x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/select.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Select AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Select`；模型：v-model、v-model:popup-visible；已核对事件：change、popupVisibleChange。
+先读 [通用接入](../core.md)。公开导出：`Select, SelectDropdown, SelectOption, SelectOptionGroup`；主要模型：v-model、v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./select-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/form-select`（包含 base.css、empty.css、form-checkbox.css、form-select.css、scrollbar-v2.css、spin.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/select)。`v-model` 返回选项的 `value`；单选通常为标量，多选为数组，也支持对象值。`multiple=false`、`allowClear=false`；单选搜索默认关闭，多选默认开启。`options` 是选项对象数组，常用字段是 `label`、`value`、`disabled`。静态数组可直接传入；动态选项用 `ref` / `reactive` 等响应式状态更新，支持替换数组，不要求原地修改；公开类型不接受 readonly 数组时先复制成普通数组。
 
 `change(value)` 返回新值，`clear(event)` 返回 `Event`；单选清空通常为 `''`，多选为 `[]`，已选禁用项可能保留。`v-model:popup-visible` 控制弹层，`option` / `empty` / `header` / `footer` 等插槽见组件文档。
@@ -35,4 +37,639 @@ function changed(value: unknown) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/select.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./select-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于从选项集合中选择单个或多个值，适合枚举、状态、人员、城市、分类等字段。
+
+
+### 何时使用
+
+候选项有限且需要保证值来自集合时使用 Select；多选适合成员、标签等集合字段。远程候选项用 `allowSearch`、`filterOption=false` 和 `search` 事件组合；自由文本用 Input，层级选择用 Cascader / TreeSelect。
+
+
+### 基础用法
+
+右侧共用一个操作位置：未选择时是展开 / 收起图标；选中且 `allowClear` 时是 ×，无需悬浮。点击文字仍能展开，点击 × 只清空并保留当前面板状态；禁用项不可清空，加载时优先显示加载图标。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select, SelectOption } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('pending');
+const clearCount = ref(0);
+</script>
+<template>
+<Select v-model="value" placeholder="请选择" allow-clear @clear="clearCount++">
+    <SelectOption value="pending">待处理</SelectOption>
+    <SelectOption value="processing">处理中</SelectOption>
+    <SelectOption value="done">已完成</SelectOption>
+    <SelectOption value="disabled" disabled>禁用项</SelectOption>
+  </Select>
+  <p>当前值：{{ value || '未选择' }}，清除次数：{{ clearCount }}</p>
+</template>
+```
+
+### 多选
+
+点击已选项可取消选择；标签关闭按钮或空输入时的 Backspace 删除可关闭项。清空保留禁用项。`maxTagCount` 只折叠展示，不限制选择数量；数量限制使用 `limit`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select, SelectOption } from 'x-next';
+import { ref } from 'vue';
+
+const values = ref(['design', 'frontend']);
+</script>
+<template>
+<Select
+    v-model="values"
+    multiple
+    allow-clear
+    :max-tag-count="2"
+    placeholder="请选择成员"
+  >
+    <SelectOption value="design" :tag-props="{ color: 'blue' }">设计</SelectOption>
+    <SelectOption value="frontend" :tag-props="{ color: 'green' }">前端</SelectOption>
+    <SelectOption value="backend">后端</SelectOption>
+    <SelectOption value="qa">测试</SelectOption>
+  </Select>
+</template>
+```
+
+### 搜索和自定义过滤
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select } from 'x-next';
+import { ref } from 'vue';
+
+const city = ref('');
+const cities = [
+  { label: '北京 Beijing', value: 'beijing' },
+  { label: '上海 Shanghai', value: 'shanghai' },
+  { label: '广州 Guangzhou', value: 'guangzhou' },
+  { label: '深圳 Shenzhen', value: 'shenzhen' },
+];
+
+const filterCity = (input: string, option: { label?: string }) =>
+  option.label?.toLowerCase().includes(input.toLowerCase()) ?? false;
+</script>
+<template>
+<Select
+    v-model="city"
+    allow-search
+    :options="cities"
+    :filter-option="filterCity"
+    placeholder="搜索城市"
+  />
+</template>
+```
+
+### 允许创建
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select, SelectOption } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['vue']);
+</script>
+<template>
+<Select v-model="tags" multiple allow-create placeholder="输入后选择新标签">
+    <SelectOption value="vue">Vue</SelectOption>
+    <SelectOption value="typescript">TypeScript</SelectOption>
+    <SelectOption value="vite">Vite</SelectOption>
+  </Select>
+</template>
+```
+
+### 选择数量限制
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select } from 'x-next';
+import { ref } from 'vue';
+
+const members = ref(['pm']);
+const message = ref('');
+const memberOptions = [
+  { label: '产品', value: 'pm' },
+  { label: '设计', value: 'design' },
+  { label: '前端', value: 'frontend' },
+  { label: '后端', value: 'backend' },
+];
+</script>
+<template>
+<Select
+    v-model="members"
+    multiple
+    :limit="2"
+    :options="memberOptions"
+    placeholder="最多选择 2 项"
+    @exceed-limit="message = '最多只能选择 2 项'"
+  />
+  <p>{{ message }}</p>
+</template>
+```
+
+### 通过 options 渲染
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('beijing');
+const options = [
+  { label: '北京', value: 'beijing' },
+  { label: '上海', value: 'shanghai' },
+  { label: '禁用项', value: 'disabled', disabled: true },
+];
+</script>
+<template>
+<Select v-model="value" :options="options" placeholder="请选择城市" />
+</template>
+```
+
+### 自定义字段名
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select } from 'x-next';
+import { ref } from 'vue';
+
+const city = ref('bj');
+const options = [
+  { id: 'bj', name: '北京' },
+  { id: 'sh', name: '上海' },
+  { id: 'gz', name: '广州', locked: true },
+];
+</script>
+<template>
+<Select
+    v-model="city"
+    :options="options"
+    :field-names="{ value: 'id', label: 'name', disabled: 'locked' }"
+    placeholder="请选择城市"
+  />
+</template>
+```
+
+### 选项分组
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select, SelectOptionGroup, SelectOption } from 'x-next';
+import { ref } from 'vue';
+
+const city = ref('');
+</script>
+<template>
+<Select v-model="city" placeholder="请选择城市">
+    <SelectOptionGroup label="华北">
+      <template #label><strong>华北 · 2 个城市</strong></template>
+      <SelectOption value="beijing">北京</SelectOption>
+      <SelectOption value="tianjin">天津</SelectOption>
+    </SelectOptionGroup>
+    <SelectOptionGroup label="华东">
+      <SelectOption value="shanghai">上海</SelectOption>
+      <SelectOption value="hangzhou">杭州</SelectOption>
+    </SelectOptionGroup>
+  </Select>
+</template>
+```
+
+### 状态和尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Select } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+const options = [
+  { label: '选项 A', value: 'a' },
+  { label: '选项 B', value: 'b' },
+];
+</script>
+<template>
+<Space direction="vertical">
+    <Select v-model="value" size="small" :options="options" placeholder="小尺寸" />
+    <Select v-model="value" :options="options" disabled placeholder="禁用状态" />
+    <Select v-model="value" :options="options" error placeholder="错误状态" />
+    <Select v-model="value" :options="options" loading placeholder="加载中" />
+    <Select v-model="value" :options="options" :bordered="false" placeholder="无边框" />
+  </Space>
+</template>
+```
+
+### 自定义内容和插槽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select, SelectOption } from 'x-next';
+import { ref } from 'vue';
+import { Icon } from 'x-next';
+
+const value = ref('pending');
+</script>
+<template>
+<Select v-model="value" placeholder="请选择">
+    <template #prefix>状态</template>
+    <template #header>
+      <div style="padding: 8px 12px">常用状态</div>
+    </template>
+    <template #footer>
+      <div style="padding: 8px 12px">没有合适选项时可联系管理员</div>
+    </template>
+    <template #label="{ data }">
+      {{ data.label }} / {{ data.value }}
+    </template>
+    <SelectOption value="pending" label="待处理">
+      待处理
+      <template #icon><Icon name="clock" /></template>
+      <template #suffix>3</template>
+    </SelectOption>
+    <SelectOption value="done" label="已完成">
+      已完成
+      <template #suffix>8</template>
+    </SelectOption>
+  </Select>
+</template>
+```
+
+### 虚拟列表和滚动事件
+
+虚拟与非虚拟列表共用 `scrollbar` 配置，并触发相同的滚动事件；传 `scrollbar=false` 可使用原生滚动条。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+const reached = ref(false);
+const options = Array.from({ length: 100 }, (_, index) => ({
+  label: `选项 ${index + 1}`,
+  value: index + 1,
+}));
+</script>
+<template>
+<Select
+    v-model="value"
+    :options="options"
+    :virtual-list-props="{ height: 200 }"
+    placeholder="大量数据"
+    @dropdown-reach-bottom="reached = true"
+  />
+  <p>{{ reached ? '已滚动到底部' : '继续滚动查看更多' }}</p>
+</template>
+```
+
+### 局部容器滚动
+
+打开下拉后滚动下面的容器：默认跟随触发器。开启「滚动关闭」后，从打开时的位置滚动 24px 即收起；不需要同时设置 `updateAtScroll`。若需要固定在原位置，可传 `triggerProps: { updateAtScroll: false }`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Select, Switch } from 'x-next';
+
+const value = ref('a');
+const popup = ref(false);
+const closeOnScroll = ref(false);
+const host = ref<HTMLElement>();
+const switchAttrs = { 'aria-label': '滚动关闭' };
+const options = [{ label: '选项 A', value: 'a' }, { label: '选项 B', value: 'b' }];
+</script>
+<template>
+<section class="scroll-scope">
+    <Switch v-model="closeOnScroll" v-bind="switchAttrs" />
+    <span>{{ popup ? '下拉已打开' : '下拉已关闭' }}</span>
+    <div class="scroll-region">
+      <div class="scroll-content">
+        <Select
+          v-if="host"
+          v-model="value"
+          v-model:popup-visible="popup"
+          :options="options"
+          :popup-container="host"
+          :trigger-props="{ scrollToClose: closeOnScroll, scrollToCloseDistance: 24 }"
+          style="width: 220px"
+        />
+      </div>
+    </div>
+    <div ref="host" class="scroll-overlay" />
+  </section>
+</template>
+<style scoped>
+.scroll-region { height: 200px; overflow: auto; }
+.scroll-content { min-height: 480px; padding: 80px 16px 0; }
+.scroll-overlay { position: fixed; inset: 0; pointer-events: none; }
+</style>
+```
+
+### 键盘、焦点与父级 Escape
+
+用 `Tab` 聚焦下面的选择器，再按 `↓` / `↑` 打开面板。没有已选的启用项时，`↓` 激活首个启用项，`↑` 激活最后一个启用项；已有选中项时优先激活该项。展开后上下键跳过禁用项并循环，`Enter` 选择活动项。通过方向键打开时会激活选项，即使设置了 `defaultActiveFirstOption=false`。
+
+`Enter` 单选或 `Esc` 关闭面板后，焦点保留在选择器上。展开时第一次 `Esc` 只关闭选项面板，继续按 `Esc` 才到达父级；闭合选择器不会拦截 `Esc`，可供外层 Dialog 关闭。`Tab` / `Shift+Tab` 关闭面板并保留浏览器的焦点移动，点击外部也可正常转移焦点。禁用状态和输入法组合输入期间不执行上述键盘操作；加载期间不通过 Enter 或上下键选择 / 移动选项，仍可用 Escape 或 Tab 关闭已打开面板。
+
+默认触发器会自动关联 `combobox`、`listbox` 和 `option` 的 ARIA 状态。使用 `trigger` 自定义触发器时，插槽提供 `onKeydown` 键盘代理和对应的 ARIA 状态，完整示例见下方「自定义触发器与方法」。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Select, Button } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('');
+const popupVisible = ref(false);
+const focused = ref(false);
+const keyboardInputAttrs = { 'aria-label': '键盘选择城市' };
+const parentEscapeCount = ref(0);
+const options = [
+  { label: '不可用的起始项', value: 'disabled-first', disabled: true },
+  { label: '北京', value: 'beijing' },
+  { label: '上海', value: 'shanghai' },
+  { label: '不可用的末尾项', value: 'disabled-last', disabled: true },
+];
+const handleParentEscape = (event: KeyboardEvent) => {
+  if (event.key === 'Escape' && !event.isComposing && event.keyCode !== 229) {
+    parentEscapeCount.value++;
+  }
+};
+</script>
+<template>
+<div @keydown="handleParentEscape">
+    <Select
+      v-model="value"
+      v-model:popup-visible="popupVisible"
+      :options="options"
+      v-bind="keyboardInputAttrs"
+      placeholder="Tab 聚焦后按 ↑ / ↓"
+      @focus="focused = true"
+      @blur="focused = false"
+    />
+    <Button>下一个焦点目标</Button>
+    <p role="status">
+      当前值：{{ value || '未选择' }}；面板：{{ popupVisible ? '展开' : '关闭' }}；
+      Select 聚焦：{{ focused ? '是' : '否' }}；父级收到 Escape：{{ parentEscapeCount }} 次
+    </p>
+  </div>
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Select, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive<{ city: string | undefined }>({ city: undefined });
+const formRules: Record<string, FieldRule[]> = {
+  city: [{ required: true, message: '请选择城市' }],
+};
+const formRef = ref<FormInstance>();
+const validateResult = ref('');
+const cityOptions = [
+  { value: 'beijing', label: '北京 Beijing' },
+  { value: 'shanghai', label: '上海 Shanghai' },
+  { value: 'guangzhou', label: '广州 Guangzhou' },
+  { value: 'shenzhen', label: '深圳 Shenzhen' },
+];
+
+const handleValidate = async () => {
+  const errors = await formRef.value!.validate();
+  validateResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleReset = () => {
+  formRef.value!.resetFields();
+  validateResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formState" :rules="formRules">
+    <FormItem field="city" label="城市">
+      <Select v-model="formState.city" :options="cityOptions" placeholder="请选择城市" allow-clear />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleValidate">校验</Button>
+        <Button @click="handleReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ validateResult }}</p>
+</template>
+```
+
+### 对象值与缺失选项回显
+
+对象值使用 `valueKey` 指定稳定、唯一的键。候选项因分页或搜索暂时消失时，`fallbackOption` 可继续显示已选值；`showExtraOptions=false` 只隐藏下拉中的兜底项，不隐藏回显。设置 `fallbackOption=false` 会隐藏缺失项的标签，但多选更新仍保留其原始值。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Select, Button } from 'x-next';
+import type { SelectOptionValue } from 'x-next';
+
+const value = ref<SelectOptionValue>({ id: 2, name: '林悦' });
+const visible = ref(true);
+const people = [{ id: 1, name: '陈晨' }, { id: 2, name: '林悦' }];
+const options = people.map(person => ({ value: person, label: person.name }));
+const fallback = (value: SelectOptionValue) => ({
+  value, label: typeof value === 'object' ? String(value.name) : String(value),
+});
+</script>
+<template>
+<Select
+    v-model="value" :options="visible ? options : []" value-key="id"
+    :fallback-option="fallback" :show-extra-options="false" allow-clear
+    placeholder="选择成员"
+  />
+  <Button @click="visible = !visible">{{ visible ? '移除候选数据' : '恢复候选数据' }}</Button>
+  <p>选中对象：{{ JSON.stringify(value) }}</p>
+</template>
+```
+
+### 远程搜索与受控输入
+
+这个示例模拟网络延迟，使用三组受控状态：选中值、搜索输入和面板显示。`filterOption=false` 把结果筛选交给业务；`searchDelay` 只延迟 `search` 事件，输入更新立即发生。业务需取消旧请求或校验请求序号，避免旧响应覆盖新关键词。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { onBeforeUnmount, ref, watch } from 'vue';
+import { Select } from 'x-next';
+import type { SelectOptionData } from 'x-next';
+
+const value = ref('');
+const input = ref('');
+const popup = ref(false);
+const loading = ref(false);
+const options = ref<SelectOptionData[]>([]);
+const cities = [
+  { value: 'beijing', label: '北京 Beijing' },
+  { value: 'shanghai', label: '上海 Shanghai' },
+];
+let revision = 0;
+let timer: ReturnType<typeof setTimeout> | undefined;
+const cancel = () => {
+  revision++;
+  clearTimeout(timer);
+  loading.value = false;
+};
+watch(input, cancel, { flush: 'sync' });
+onBeforeUnmount(cancel);
+const search = (query: string) => {
+  cancel();
+  const current = revision;
+  if (!query.trim()) {
+    options.value = [];
+    return;
+  }
+  loading.value = true;
+  timer = setTimeout(() => {
+    if (current !== revision || query !== input.value) return;
+    options.value = cities.filter(city => city.label.toLowerCase().includes(query.toLowerCase()));
+    loading.value = false;
+  }, 400);
+};
+</script>
+<template>
+<Select
+    v-model="value" v-model:input-value="input" v-model:popup-visible="popup"
+    :options="options" :loading="loading" allow-search allow-clear
+    :filter-option="false" :search-delay="120" :show-extra-options="false"
+    show-header-on-empty show-footer-on-empty placeholder="输入城市名搜索" @search="search"
+  >
+    <template #header>模拟远程城市服务</template>
+    <template #empty>没有匹配城市，试试「北京」</template>
+    <template #footer>结果由业务返回，不做二次过滤</template>
+  </Select>
+  <p>选中：{{ value || '未选择' }}；输入：{{ input || '空' }}</p>
+</template>
+```
+
+### 自定义触发器与方法
+
+将插槽提供的 `onKeydown` 绑定到触发节点，即可复用方向键、Enter、Escape、Tab 和 Home / End。Home / End 在面板展开且搜索输入为空时定位首 / 末启用项；有输入时保留光标移动。自定义节点需要设置可聚焦状态和 ARIA；`focus()` / `blur()` 用于默认输入触发器。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Select, Button } from 'x-next';
+import type { SelectInstance } from 'x-next';
+
+const value = ref('');
+const popup = ref(false);
+const select = ref<SelectInstance>();
+const options = [{ value: 'beijing', label: '北京' }, { value: 'shanghai', label: '上海' }];
+</script>
+<template>
+<Select v-model="value" v-model:popup-visible="popup" :options="options">
+    <template #trigger="{ popupVisible, disabled, listboxId, activeDescendant, onKeydown }">
+      <button
+        type="button" role="combobox" :disabled="disabled" aria-label="自定义城市选择"
+        aria-haspopup="listbox" :aria-expanded="popupVisible" :aria-controls="listboxId"
+        :aria-activedescendant="activeDescendant" @keydown="onKeydown"
+      >{{ value || '选择城市' }}</button>
+    </template>
+  </Select>
+  <Select ref="select" :options="options" />
+  <Button @click="select?.focus()">聚焦</Button>
+  <Button @click="select?.blur()">失焦</Button>
+  <p>当前值：{{ value }}；面板：{{ popup }}</p>
+</template>
+```
+
+### 自定义渲染与状态图标
+
+`options.render` 自定义候选项，`option` 插槽存在时优先使用插槽；标签使用 `label` 插槽或 `formatLabel`。图标优先级为：加载 > 可清空的选中值 > 展开搜索图标 > 箭头。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { h, ref } from 'vue';
+import { Select, Button, Icon } from 'x-next';
+
+const value = ref('a');
+const input = ref('');
+const loading = ref(false);
+const options = [
+  { value: 'a', label: '产品方案', render: () => h('strong', '产品方案 · 推荐') },
+  { value: 'b', label: '研发计划', render: () => h('span', '研发计划 · 进行中') },
+];
+</script>
+<template>
+<Select
+    v-model="value" v-model:input-value="input" :options="options" :loading="loading"
+    allow-search allow-clear :format-label="data => `已选：${data.label}`"
+  >
+    <template #prefix>方案</template>
+    <template #arrow-icon><Icon name="chevron-down" /></template>
+    <template #search-icon><Icon name="search" /></template>
+    <template #loading-icon><Icon name="loader-circle" spin /></template>
+  </Select>
+  <Button @click="loading = !loading">{{ loading ? '结束加载' : '模拟加载' }}</Button>
+  <Select v-model="value" :options="options">
+    <template #option="{ data }"><Icon name="check-circle" /> {{ data.label }} · 插槽渲染</template>
+  </Select>
+  <p>值：{{ value }}；加载：{{ loading }}</p>
+</template>
+```
+
+### 交互与数据边界
+
+- `modelValue`、`inputValue`、`popupVisible` 分别控制选中值、输入和面板。只传 prop 时上层必须处理对应更新事件；`default*` 仅初始化非受控值。
+- 单选清空为 `''`；若候选项包含值 `''`，清空为 `undefined`，以区分「空字符串选项」和「未选择」。多选清空为数组，保留禁用项。`0`、`false` 是有效值。
+- 候选值 / 对象 `valueKey` 必须唯一；插槽选项动态改变顺序时，可用 `index` 明确键盘顺序。默认标签取正文，不含 `icon` / `suffix`。
+- 虚拟列表使用 `options` 数据，分组会逐行虚拟化。存在默认选项插槽时退回普通列表，避免插槽选项丢失；`itemKey` 由 Select 管理。
+- 未开启搜索时，默认输入是只读的选择触发器；Select 目前没有独立 `readonly` 业务态。查看态可展示标签，禁止操作使用 `disabled`。
+- 原生 `id`、`name`、`tabindex`、`autocomplete` 和 `aria-*` 落在实际输入上；`class`、`style`、`data-*` 落在外层。原生输入值是搜索文本，提交选中值应读取 `v-model`；必填校验使用 FormItem 的 `required` 规则，Select 不提供原生表单选中值提交和 constraint validation。
+
+
+### 选项数据
+
+`SelectOptionData` 和 `SelectOptionGroupData` 可从根入口导入。自定义字段名只映射选项数据，分组结构仍使用 `isGroup`、`label`、`options`。
+
+| 字段 | 说明 | 类型 |
+| --- | --- | --- |
+| `value` | 选项值；对象值需配合 `valueKey` | `string \| number \| boolean \| object` |
+| `label` | 用于回显和默认搜索的纯文本 | `string` |
+| `disabled` | 禁止选择 / 取消 / 删除 / 清空此项 | `boolean` |
+| `tagProps` | 多选标签属性；`closable=false` 隐藏此标签的删除入口，不代替选项禁用 | `object` |
+| `render` | 选项渲染函数，不改变搜索文本或回显 label | `RenderFunction` |
+
+分组为 `{ isGroup: true, label: string, options: [...] }`。`fieldNames` 可映射 `value`、`label`、`disabled`、`tagProps`、`render`，未传的字段使用同名默认字段。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./select-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。