# Choices 选项框组件 API 文档

本文档由 `DeepSeek R1` 模型生成并微调。

---

## 组件特性

-   **多选一机制**：从多个选项中选择一项
-   **自动分页**：通过 `maxHeight` 控制分页
-   **灵活样式**：支持图片背景/纯色背景 + 自定义字体
-   **键盘导航**：方向键选择 + Enter 确认
-   **动态内容**：支持异步加载选项数据

---

## Props 属性说明

```mermaid
graph LR
    ConfirmBoxProps --> TextContentProps

    click TextContentProps "./组件%20TextContent"
```

本组件完全继承 `TextContent` 组件的参数，参考 [组件 TextContent](./组件%20TextContent.md)

| 属性名      | 类型             | 默认值   | 描述                                  |
| ----------- | ---------------- | -------- | ------------------------------------- |
| `choices`   | `ChoiceItem[]`   | 必填     | 选项数组，格式为 `[key, text]` 的元组 |
| `loc`       | `ElementLocator` | 必填     | 定位配置（需包含 x,y 坐标及锚点）     |
| `width`     | `number`         | 必填     | 选项框宽度（像素）                    |
| `maxHeight` | `number`         | `360`    | 最大高度（超过时自动分页）            |
| `text`      | `string`         | -        | 主说明文本（显示在标题下方）          |
| `title`     | `string`         | -        | 标题文本                              |
| `winskin`   | `ImageIds`       | -        | 背景图片资源 ID（与 color 互斥）      |
| `color`     | `CanvasStyle`    | `#333`   | 背景颜色（未设置 winskin 时生效）     |
| `border`    | `CanvasStyle`    | `gold`   | 边框颜色/样式                         |
| `selFont`   | `Font`           | 系统默认 | 选项文本字体                          |
| `selFill`   | `CanvasStyle`    | `#fff`   | 选项文本颜色                          |
| `titleFont` | `Font`           | 系统默认 | 标题字体                              |
| `titleFill` | `CanvasStyle`    | `gold`   | 标题颜色                              |
| `interval`  | `number`         | `16`     | 选项间垂直间距（像素）                |

---

## Events 事件说明

| 事件名   | 参数             | 触发时机               |
| -------- | ---------------- | ---------------------- |
| `choose` | `key: ChoiceKey` | 用户选择任意选项时触发 |

---

## 使用示例

### 基础用法 - 系统设置

```tsx
import { defineComponent } from 'vue';
import { Choices, ChoiceItem } from '@user/client-modules';

export const MyCom = defineComponent(() => {
    const options: ChoiceItem[] = [
        ['low', '低画质'],
        ['medium', '中画质'],
        ['high', '高画质']
    ];

    return () => (
        <Choices
            choices={options}
            loc={[208, 208, void 0, void 0, 0.5, 0.5]}
            width={208}
            title="图形质量设置"
            text="请选择适合您设备的画质等级"
            // key 在这里是每个选项的第一个元素，即 low, medium, high
            onChoose={key => console.log(`Choose ${key}.`)}
        />
    );
});
```

### 分页处理 - 角色选择

```tsx
import { defineComponent } from 'vue';
import { Choices, ChoiceItem } from '@user/client-modules';

export const MyCom = defineComponent(() => {
    // 生成 50 个角色选项
    const characters: ChoiceItem[] = Array.from(
        { length: 50 },
        (_, i) => [`char_${i}`, `角色 ${i + 1}`] as ChoiceItem
    );

    return () => (
        <Choices
            choices={characters}
            loc={[208, 208, void 0, void 0, 0.5, 0.5]}
            width={208}
            maxHeight={400} // 高度超过 400px 自动分页
            interval={12}
            winskin="winskin.png"
            // 粗体，20px 大小的 Verdana 字体
            titleFont={new Font('Verdana', 20, 'px', 700)}
            selFill="#4CAF50"
        />
    );
});
```

### 动态内容 + 自定义样式

```tsx
import { defineComponent } from 'vue';
import { Choices, ChoiceItem } from '@user/client-modules';
import { onTick } from '@motajs/render';

export const MyCom = defineComponent(() => {
    const dynamicOptions = ref<ChoiceItem[]>([]);

    onTick(() => {
        // 每帧生成随机选项名称
        dynamicOptions.value = Array.from(
            { length: 50 },
            (_, i) =>
                [
                    `char_${i}`,
                    `随机数 ${Math.random().toFixed(8)}`
                ] as ChoiceItem
        );
    });

    return () => (
        <Choices
            choices={dynamicOptions.value}
            loc={[208, 208, void 0, void 0, 0.5, 0.5]}
            width={208}
            color="rgba(30,30,30,0.9)"
            border="#607D8B"
            title="选择随机数"
            titleFill="#B2EBF2"
        />
    );
});
```

---

## 注意事项

1. **选项键值唯一性**  
   每个选项的 `key` 必须唯一，否则可能引发不可预期行为

2. **分页计算规则**  
   分页依据 `maxHeight` 和字体大小自动计算，需确保字体大小一致

3. **使用更方便的函数**：多数情况下，你不需要使用本组件，使用包装好的函数往往会更加方便，参考 [`getChoice`](./functions.md#getchoice)