# 如何制作可选择的简单列表

> 使用 ListView（SINGLE 或 MULTIPLE）显示文本列表并捕获选择。

Source: https://crossfly.dev/zh/docs/cookbook/lists/lista-simples — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 如何制作可选择的简单列表

**目的。** 显示一个可滚动的文本项列表，并在用户选择一个（SINGLE）或多个（MULTIPLE）时做出响应。
`ListView` 是一个可嵌入的 `Component`：你可以将其添加到任何布局，无需窗口。

## 使用的 API
- `new ListView(String[] items, ListView.ItemType type)` — 从文本数组创建列表。
- `new ListView(String title, String[] items, ListView.ItemType type)` — 相同，带标题头部。
- `ListView.ItemType.SINGLE` / `ListView.ItemType.MULTIPLE` — 枚举仅有的两个值。`SINGLE` = 点击选择并触发 `onConfirm`；`MULTIPLE` = 复选框 + "确认"按钮。
- `ListView.onConfirm(Component.Action action)` — 确认时触发的回调。接收 `ListView` 本身作为事件源。
- `ListView.getSelectedText()` / `getSelectedIndex()` — 第一个被选中的项（文本/索引），或 `null`/`-1`。
- `ListView.getSelectedTexts()` / `getSelectedIndices()` — 所有被选中的项（在 MULTIPLE 中有用）。
- `ListView.confirmText(String)` — 确认按钮的文本（默认 `"Confirmar"`，仅在 MULTIPLE 中）。

## 完整示例（复制、粘贴并运行）
```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[] frutas = {"Maçã", "Banana", "Laranja", "Uva"};

      // SINGLE：点按即选中并触发 onConfirm
      ListView lista = new ListView("Escolha uma fruta", frutas, ListView.ItemType.SINGLE);
      lista.onConfirm(e ->
      {
         String texto = lista.getSelectedText();   // 例如："Banana"
         int idx = lista.getSelectedIndex();       // 例如：1
         Debug.log("Selecionado: " + texto + " (#" + idx + ")");
         return null;
      });
      add(LAY_FILL, lista);   // ListView 是一个 Component：直接进入布局
   }
}
```

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

## 最小片段
```java
// 已在源码核实：ListView.java
String[] frutas = {"Maçã", "Banana", "Laranja", "Uva"};

// SINGLE：点按即选中并触发 onConfirm
ListView lista = new ListView("Escolha uma fruta", frutas, ListView.ItemType.SINGLE);
lista.onConfirm(e ->
{
   String texto = lista.getSelectedText();   // 例如："Banana"
   int idx = lista.getSelectedIndex();       // 例如：1
   Debug.log("Selecionado: " + texto + " (#" + idx + ")");
   return null;
});
layout.add(.9f, lista);   // ListView 是一个 Component：直接进入布局
```

```java
// MULTIPLE：复选框；onConfirm 仅在点按 "Confirmar" 按钮时触发
ListView multi = new ListView("Selecione ingredientes", frutas, ListView.ItemType.MULTIPLE);
multi.confirmText("Adicionar");
multi.onConfirm(e ->
{
   String[] escolhidas = multi.getSelectedTexts();   // 所有被勾选的项
   return null;
});
layout.add(.9f, multi);
```

## 深入了解
- 需要模态弹窗而非嵌入式？参见 [popup-de-selecao.md](/docs/cookbook/lists/popup-de-selecao)。
- 数千个项目？不要使用 `ListView`（它会实例化所有项）；参见 [lista-virtual-grande.md](/docs/cookbook/lists/lista-virtual-grande)。
- 组件指南：[ListView](/docs/ui/widgets/listview) · 权威来源：第 15 章