# 如何使用选择下拉框

> 打开下拉列表、响应用户的选择，并取回选中的那一项，适合表单里的枚举字段。

Source: https://crossfly.dev/zh/docs/cookbook/ui/dropdown-selecao — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 如何使用选择下拉框

**用途。** 从项目列表中提供单项选择，显示为一个带箭头的按钮，点击时打开弹出框（`ListViewWindow`）。选择后，下拉框的文本会显示选中的项。适用于在少量或中等数量的选项中进行选择，而不占用屏幕上的固定空间。

## 用到的 API
- `new Dropdown(String placeholder, String[] items)` — 使用占位符文本和项数组创建下拉框。
- `new Dropdown(String[] items)` — 变体，使用默认占位符 `"Select..."`。
- `dropdown.onSelect(Component.Action action)` — 在用户于弹出框中确认选择**之后**触发的回调。
- `dropdown.getSelectedIndex()` — 选中项的索引，若无则为 `-1`。
- `dropdown.getSelectedText()` — 选中项的文本，若无则为 `null`。
- `dropdown.setSelectedIndex(int index)` — 以编程方式选中并更新显示的文本。
- `dropdown.popupHeightRatio(float)` / `dropdown.popupWidthRatio(float)` — 相对于屏幕调整弹出框的大小。

## 完整示例（复制、粘贴并运行）
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      String[] estados = { "Acre", "Bahia", "São Paulo", "Paraná" };

      Dropdown uf = new Dropdown("Selecione o estado", estados);

      uf.onSelect(origin ->
      {
         int i = uf.getSelectedIndex();       // 未选择时为 -1
         String texto = uf.getSelectedText(); // 未选择时为 null
         filtrarPorEstado(texto);
      });

      // 以编程方式预选（可选）
      uf.setSelectedIndex(2);   // "São Paulo"

      add(0.5f, uf);            // 占行内一半宽度（GridLayout）
   }

   private void filtrarPorEstado(String estado)
   {
      // ... 根据所选州筛选列表 ...
   }
}
```

> 下面的片段只展示**核心部分**。要运行它，请将其放入上面的 `MainWindow` 骨架中。

## 最小片段
```java
String[] estados = { "Acre", "Bahia", "São Paulo", "Paraná" };

Dropdown uf = new Dropdown("Selecione o estado", estados);

uf.onSelect(origin ->
{
   int i = uf.getSelectedIndex();       // 未选择时为 -1
   String texto = uf.getSelectedText(); // 未选择时为 null
   filtrarPorEstado(texto);
});

// 以编程方式预选（可选）
uf.setSelectedIndex(2);   // "São Paulo"

add(0.5f, uf);            // 占行内一半宽度（GridLayout）
```

> **验证说明（2026 代码）。** 已在源码中确认：`Dropdown` 继承自 `Button`；
> 构造函数 `Dropdown(String placeholder, String[] items)` 和 `Dropdown(String[] items)`；
> `onSelect(Action)`、`getSelectedIndex()`、`getSelectedText()`、`setSelectedIndex(int)`。
> 弹出框会根据屏幕上可用的空间自行决定在下拉框的**上方还是下方**打开，
> 并在点击外部时关闭。回调 `onSelect` 在 `selectedIndex`/`text` 已经更新**之后**运行，
> 因此在其中调用 `getSelectedText()` 是安全的。

## 深入了解
- 控件页面：[Dropdown](/docs/ui/widgets/dropdown) · 权威来源：第 14 章
- 带标记的单选/多选：[checkbox-e-radio.md](/docs/cookbook/ui/checkbox-e-radio)