x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/select-api.md

@@ -0,0 +1,758 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Select 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Select API
+
+公开声明：`dist/components/form-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| multiple | 是否多选 | undefined &#124; false &#124; true | 否 | false |
+| modelValue | 绑定值 | undefined &#124; string &#124; number &#124; false &#124; true &#124; { [x: string]: any; } &#124; (string &#124; number &#124; boolean &#124; Record<string, any>)[] | 否 | undefined |
+| defaultValue | 默认值，非受控模式 | undefined &#124; string &#124; number &#124; false &#124; true &#124; { [x: string]: unknown; } &#124; (string &#124; number &#124; boolean &#124; Record<string, unknown>)[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| inputValue | 搜索输入值 | undefined &#124; string | 否 | 未声明 |
+| defaultInputValue | 默认搜索输入值 | undefined &#124; string | 否 | "" |
+| size | 选择器尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| placeholder | 占位提示 | undefined &#124; string | 否 | 未声明 |
+| loading | 是否加载中 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否错误状态 | undefined &#124; false &#124; true | 否 | false |
+| allowClear | 是否允许清空 | undefined &#124; false &#124; true | 否 | false |
+| allowSearch | 是否允许搜索 | undefined &#124; false &#124; true &#124; { retainInputValue?: boolean; } | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| allowCreate | 是否允许创建新选项 | undefined &#124; false &#124; true | 否 | false |
+| maxTagCount | 多选最多显示标签数量，0 不限制 | undefined &#124; number | 否 | 0 |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| bordered | 是否显示边框 | undefined &#124; false &#124; true | 否 | true |
+| defaultActiveFirstOption | 无有效选中项时是否默认激活首个选项；方向键展开时按方向激活首 / 末项 | undefined &#124; false &#124; true | 否 | true |
+| popupVisible | 弹出层显示状态 | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认弹出层显示状态 | undefined &#124; false &#124; true | 否 | false |
+| unmountOnClose | 关闭时是否销毁弹出层 | undefined &#124; false &#124; true | 否 | false |
+| filterOption | 是否过滤选项或自定义过滤方法 | undefined &#124; false &#124; true &#124; (inputValue: string, option: SelectOptionData) => boolean | 否 | true |
+| options | 选项数据，支持分组 | undefined &#124; (string &#124; number &#124; boolean &#124; SelectOptionData &#124; SelectOptionGroupData)[] | 否 | [] |
+| virtualListProps | 虚拟列表配置；仅使用 options 数据时开启，默认选项插槽退回普通列表 | undefined &#124; VirtualListProps | 否 | 未声明 |
+| triggerProps | 下拉触发器配置；updateAtScroll 默认开启，可显式关闭 | undefined &#124; TriggerProps | 否 | 未声明 |
+| formatLabel | 格式化显示内容 | undefined &#124; (data: SelectOptionData) => string | 否 | 未声明 |
+| fallbackOption | 自定义值不存在时的兜底选项 | undefined &#124; false &#124; true &#124; (value: string &#124; number &#124; boolean &#124; Record<string, unknown>) => SelectOptionData | 否 | true |
+| showExtraOptions | 是否显示额外选项 | undefined &#124; false &#124; true | 否 | true |
+| valueKey | 对象值的唯一键字段 | undefined &#124; string | 否 | "value" |
+| searchDelay | 搜索事件触发延迟 | undefined &#124; number | 否 | 500 |
+| limit | 多选最多选择数量，0 不限制 | undefined &#124; number | 否 | 0 |
+| fieldNames | 自定义选项字段名 | undefined &#124; { [x: string]: string &#124; undefined; value?: string &#124; undefined; label?: string &#124; undefined; disabled?: string &#124; undefined; tagProps?: string &#124; undefined; render?: string &#124; undefined; } | 否 | 未声明 |
+| scrollbar | 是否开启滚动条或滚动条配置 | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | true |
+| showHeaderOnEmpty | 空状态时是否显示 header | undefined &#124; false &#124; true | 否 | false |
+| showFooterOnEmpty | 空状态时是否显示 footer | undefined &#124; false &#124; true | 否 | false |
+| tagNowrap | 多选标签内容是否不换行 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| focus | 默认输入触发器聚焦 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 默认输入触发器失焦 | undefined &#124; (ev: FocusEvent) => any |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: string &#124; number &#124; boolean &#124; Record<string, any> &#124; (string &#124; number &#124; boolean &#124; Record<string, any>)[] &#124; undefined) => any |
+| update:inputValue | 搜索输入值更新时触发 | undefined &#124; (inputValue: string) => any |
+| update:popupVisible | 弹出层显示状态更新时触发 | undefined &#124; (visible: boolean) => any |
+| change | 值变化时触发 | undefined &#124; (value: string &#124; number &#124; boolean &#124; Record<string, any> &#124; (string &#124; number &#124; boolean &#124; Record<string, any>)[] &#124; undefined) => any |
+| inputValueChange | 输入值变化时触发 | undefined &#124; (inputValue: string) => any |
+| popupVisibleChange | 弹出层显示状态变化时触发 | undefined &#124; (visible: boolean) => any |
+| clear | 点击清除按钮时触发 | undefined &#124; (ev: Event) => any |
+| remove | 删除多选标签时触发 | undefined &#124; (removed: string &#124; number &#124; boolean &#124; Record<string, any> &#124; undefined) => any |
+| search | 用户搜索时触发 | undefined &#124; (inputValue: string) => any |
+| dropdownScroll | 下拉菜单滚动时触发 | undefined &#124; (ev: Event) => any |
+| dropdownReachBottom | 下拉菜单滚动到底部时触发 | undefined &#124; (ev: Event) => any |
+| exceedLimit | 多选超过数量限制时触发 | undefined &#124; (value: string &#124; number &#124; boolean &#124; Record<string, any> &#124; undefined, ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | SelectOption / SelectOptionGroup 选项节点 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| empty | 空状态内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| option | 自定义选项内容；参数 { data: SelectOptionData }，为原始选项数据 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| label | 自定义选择框显示内容；参数 { data: SelectOptionData }，为原始选项数据 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| header | 下拉框页头 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| footer | 下拉框页脚 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| arrow-icon | 箭头图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| loading-icon | 加载中图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| search-icon | 搜索图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| prefix | 前缀元素 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| trigger | 自定义触发元素；参数：{ popupVisible, disabled, listboxId, activeDescendant, onKeydown } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | 公开声明未细化（用法和实现已显式暴露） |
+| blur | 公开声明未细化（用法和实现已显式暴露） |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface SelectInstance {
+    focus: () => void;
+    blur: () => void;
+}
+
+interface SelectProps {
+    options?: (string | number | boolean | SelectOptionData | SelectOptionGroup)[];
+    multiple?: boolean;
+    modelValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    defaultValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    allowClear?: boolean;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowCreate?: boolean;
+    maxTagCount?: number;
+    popupContainer?: string | HTMLElement;
+    bordered?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    defaultActiveFirstOption?: boolean;
+    unmountOnClose?: boolean;
+    filterOption?: boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+    virtualListProps?: VirtualListProps;
+    triggerProps?: TriggerProps;
+    formatLabel?: (data: SelectOptionData) => string;
+    fallbackOption?: boolean | ((value: string | number | boolean | Record<string, unknown>) => SelectOptionData);
+    showExtraOptions?: boolean;
+    valueKey?: string;
+    searchDelay?: number;
+    limit?: number;
+    fieldNames?: SelectFieldNames;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+    scrollbar?: boolean | ScrollbarProps;
+    tagNowrap?: boolean;
+}
+
+type SelectOptionValue = string | number | boolean | Record<string, unknown>;
+
+interface OptionValueWithKey {
+    value: SelectOptionValue;
+    key: string;
+}
+
+type SelectFieldNames = FieldString<SelectOptionData>;
+
+interface SelectOptionData {
+    /**
+     * @zh 选项值
+     * @en Option Value
+     */
+    value?: string | number | boolean | Record<string, unknown>;
+    /**
+     * @zh 选项内容
+     * @en Option content
+     */
+    label?: string;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+    /**
+     * @zh 选项对应的多选标签的属性
+     * @en Props of the multi-select label corresponding to the option
+     */
+    tagProps?: any;
+    /**
+     * @zh 自定义渲染
+     * @en Custom Render
+     */
+    render?: RenderFunction;
+    [other: string]: any;
+}
+
+interface SelectOptionGroup {
+    /**
+     * @zh 是否为选项组
+     * @en Whether it is an option group
+     */
+    isGroup: true;
+    /**
+     * @zh 选项组标题
+     * @en Option group title
+     */
+    label: string;
+    /**
+     * @zh 选项组中的选项
+     * @en Options in the option group
+     */
+    options: SelectOption[];
+    [other: string]: any;
+}
+
+type SelectOption = string | number | boolean | SelectOptionData | SelectOptionGroup;
+
+interface SelectOptionInfo extends SelectOptionData {
+    raw: Record<string, unknown>;
+    key: string;
+    index?: number;
+    origin: 'slot' | 'options' | 'extraOptions';
+    value: SelectOptionValue;
+    label: string;
+}
+
+interface SelectOptionGroupInfo extends SelectOptionGroup {
+    key: string;
+    options: (SelectOptionInfo | SelectOptionGroupInfo)[];
+}
+
+type FilterOption = boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+
+interface SelectContext {
+    multiple?: boolean;
+    valueKey?: string;
+    inputValue?: string;
+    filterOption?: FilterOption;
+    component?: string;
+    valueKeys: string[];
+    activeKey?: string;
+    getOptionId: (key: string) => string;
+    onSelect: (key: string, ev: Event) => void;
+    setActiveKey: (key?: string) => void;
+    getNextSlotOptionIndex: () => number;
+    addSlotOptionInfo: (id: number, optionInfo: SelectOptionInfo) => void;
+    removeSlotOptionInfo: (id: number) => void;
+}
+```
+
+
+## SelectDropdown API
+
+公开声明：`dist/components/form-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| id | 见场景用法与类型 | undefined &#124; string | 否 | 未声明 |
+| multiple | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| loading | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| empty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| virtualList | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| bottomOffset | 见场景用法与类型 | undefined &#124; number | 否 | 0 |
+| scrollbar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | true |
+| onScroll | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) | 否 | 未声明 |
+| onReachBottom | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) | 否 | 未声明 |
+| showHeaderOnEmpty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| showFooterOnEmpty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| scroll | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) |
+| reachBottom | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface SelectInstance {
+    focus: () => void;
+    blur: () => void;
+}
+
+interface SelectProps {
+    options?: (string | number | boolean | SelectOptionData | SelectOptionGroup)[];
+    multiple?: boolean;
+    modelValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    defaultValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    allowClear?: boolean;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowCreate?: boolean;
+    maxTagCount?: number;
+    popupContainer?: string | HTMLElement;
+    bordered?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    defaultActiveFirstOption?: boolean;
+    unmountOnClose?: boolean;
+    filterOption?: boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+    virtualListProps?: VirtualListProps;
+    triggerProps?: TriggerProps;
+    formatLabel?: (data: SelectOptionData) => string;
+    fallbackOption?: boolean | ((value: string | number | boolean | Record<string, unknown>) => SelectOptionData);
+    showExtraOptions?: boolean;
+    valueKey?: string;
+    searchDelay?: number;
+    limit?: number;
+    fieldNames?: SelectFieldNames;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+    scrollbar?: boolean | ScrollbarProps;
+    tagNowrap?: boolean;
+}
+
+type SelectOptionValue = string | number | boolean | Record<string, unknown>;
+
+interface OptionValueWithKey {
+    value: SelectOptionValue;
+    key: string;
+}
+
+type SelectFieldNames = FieldString<SelectOptionData>;
+
+interface SelectOptionData {
+    /**
+     * @zh 选项值
+     * @en Option Value
+     */
+    value?: string | number | boolean | Record<string, unknown>;
+    /**
+     * @zh 选项内容
+     * @en Option content
+     */
+    label?: string;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+    /**
+     * @zh 选项对应的多选标签的属性
+     * @en Props of the multi-select label corresponding to the option
+     */
+    tagProps?: any;
+    /**
+     * @zh 自定义渲染
+     * @en Custom Render
+     */
+    render?: RenderFunction;
+    [other: string]: any;
+}
+
+interface SelectOptionGroup {
+    /**
+     * @zh 是否为选项组
+     * @en Whether it is an option group
+     */
+    isGroup: true;
+    /**
+     * @zh 选项组标题
+     * @en Option group title
+     */
+    label: string;
+    /**
+     * @zh 选项组中的选项
+     * @en Options in the option group
+     */
+    options: SelectOption[];
+    [other: string]: any;
+}
+
+type SelectOption = string | number | boolean | SelectOptionData | SelectOptionGroup;
+
+interface SelectOptionInfo extends SelectOptionData {
+    raw: Record<string, unknown>;
+    key: string;
+    index?: number;
+    origin: 'slot' | 'options' | 'extraOptions';
+    value: SelectOptionValue;
+    label: string;
+}
+
+interface SelectOptionGroupInfo extends SelectOptionGroup {
+    key: string;
+    options: (SelectOptionInfo | SelectOptionGroupInfo)[];
+}
+
+type FilterOption = boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+
+interface SelectContext {
+    multiple?: boolean;
+    valueKey?: string;
+    inputValue?: string;
+    filterOption?: FilterOption;
+    component?: string;
+    valueKeys: string[];
+    activeKey?: string;
+    getOptionId: (key: string) => string;
+    onSelect: (key: string, ev: Event) => void;
+    setActiveKey: (key?: string) => void;
+    getNextSlotOptionIndex: () => number;
+    addSlotOptionInfo: (id: number, optionInfo: SelectOptionInfo) => void;
+    removeSlotOptionInfo: (id: number) => void;
+}
+```
+
+
+## SelectOption API
+
+公开声明：`dist/components/form-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| value | 选项值，不填时从内容获取 | undefined &#124; string &#124; number &#124; false &#124; true &#124; { [x: string]: any; } | 否 | undefined |
+| label | 选项标签，不填时从内容获取 | undefined &#124; string | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| tagProps | 多选时展示标签的属性 | undefined &#124; TagProps | 否 | 未声明 |
+| extra | 见场景用法与类型 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+| index | 手动指定选项 index | undefined &#124; number | 否 | 未声明 |
+| internal | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 选项内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| icon | 选项图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| suffix | 选项后缀 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface SelectInstance {
+    focus: () => void;
+    blur: () => void;
+}
+
+interface SelectProps {
+    options?: (string | number | boolean | SelectOptionData | SelectOptionGroup)[];
+    multiple?: boolean;
+    modelValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    defaultValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    allowClear?: boolean;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowCreate?: boolean;
+    maxTagCount?: number;
+    popupContainer?: string | HTMLElement;
+    bordered?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    defaultActiveFirstOption?: boolean;
+    unmountOnClose?: boolean;
+    filterOption?: boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+    virtualListProps?: VirtualListProps;
+    triggerProps?: TriggerProps;
+    formatLabel?: (data: SelectOptionData) => string;
+    fallbackOption?: boolean | ((value: string | number | boolean | Record<string, unknown>) => SelectOptionData);
+    showExtraOptions?: boolean;
+    valueKey?: string;
+    searchDelay?: number;
+    limit?: number;
+    fieldNames?: SelectFieldNames;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+    scrollbar?: boolean | ScrollbarProps;
+    tagNowrap?: boolean;
+}
+
+type SelectOptionValue = string | number | boolean | Record<string, unknown>;
+
+interface OptionValueWithKey {
+    value: SelectOptionValue;
+    key: string;
+}
+
+type SelectFieldNames = FieldString<SelectOptionData>;
+
+interface SelectOptionData {
+    /**
+     * @zh 选项值
+     * @en Option Value
+     */
+    value?: string | number | boolean | Record<string, unknown>;
+    /**
+     * @zh 选项内容
+     * @en Option content
+     */
+    label?: string;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+    /**
+     * @zh 选项对应的多选标签的属性
+     * @en Props of the multi-select label corresponding to the option
+     */
+    tagProps?: any;
+    /**
+     * @zh 自定义渲染
+     * @en Custom Render
+     */
+    render?: RenderFunction;
+    [other: string]: any;
+}
+
+interface SelectOptionGroup {
+    /**
+     * @zh 是否为选项组
+     * @en Whether it is an option group
+     */
+    isGroup: true;
+    /**
+     * @zh 选项组标题
+     * @en Option group title
+     */
+    label: string;
+    /**
+     * @zh 选项组中的选项
+     * @en Options in the option group
+     */
+    options: SelectOption[];
+    [other: string]: any;
+}
+
+type SelectOption = string | number | boolean | SelectOptionData | SelectOptionGroup;
+
+interface SelectOptionInfo extends SelectOptionData {
+    raw: Record<string, unknown>;
+    key: string;
+    index?: number;
+    origin: 'slot' | 'options' | 'extraOptions';
+    value: SelectOptionValue;
+    label: string;
+}
+
+interface SelectOptionGroupInfo extends SelectOptionGroup {
+    key: string;
+    options: (SelectOptionInfo | SelectOptionGroupInfo)[];
+}
+
+type FilterOption = boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+
+interface SelectContext {
+    multiple?: boolean;
+    valueKey?: string;
+    inputValue?: string;
+    filterOption?: FilterOption;
+    component?: string;
+    valueKeys: string[];
+    activeKey?: string;
+    getOptionId: (key: string) => string;
+    onSelect: (key: string, ev: Event) => void;
+    setActiveKey: (key?: string) => void;
+    getNextSlotOptionIndex: () => number;
+    addSlotOptionInfo: (id: number, optionInfo: SelectOptionInfo) => void;
+    removeSlotOptionInfo: (id: number) => void;
+}
+```
+
+
+## SelectOptionGroup API
+
+公开声明：`dist/components/form-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| label | 选项组标题 | undefined &#124; string | 否 | 未声明 |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 选项组内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| label | 自定义选项组标题 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface SelectInstance {
+    focus: () => void;
+    blur: () => void;
+}
+
+interface SelectProps {
+    options?: (string | number | boolean | SelectOptionData | SelectOptionGroup)[];
+    multiple?: boolean;
+    modelValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    defaultValue?: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[];
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    allowClear?: boolean;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowCreate?: boolean;
+    maxTagCount?: number;
+    popupContainer?: string | HTMLElement;
+    bordered?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    defaultActiveFirstOption?: boolean;
+    unmountOnClose?: boolean;
+    filterOption?: boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+    virtualListProps?: VirtualListProps;
+    triggerProps?: TriggerProps;
+    formatLabel?: (data: SelectOptionData) => string;
+    fallbackOption?: boolean | ((value: string | number | boolean | Record<string, unknown>) => SelectOptionData);
+    showExtraOptions?: boolean;
+    valueKey?: string;
+    searchDelay?: number;
+    limit?: number;
+    fieldNames?: SelectFieldNames;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+    scrollbar?: boolean | ScrollbarProps;
+    tagNowrap?: boolean;
+}
+
+type SelectOptionValue = string | number | boolean | Record<string, unknown>;
+
+interface OptionValueWithKey {
+    value: SelectOptionValue;
+    key: string;
+}
+
+type SelectFieldNames = FieldString<SelectOptionData>;
+
+interface SelectOptionData {
+    /**
+     * @zh 选项值
+     * @en Option Value
+     */
+    value?: string | number | boolean | Record<string, unknown>;
+    /**
+     * @zh 选项内容
+     * @en Option content
+     */
+    label?: string;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+    /**
+     * @zh 选项对应的多选标签的属性
+     * @en Props of the multi-select label corresponding to the option
+     */
+    tagProps?: any;
+    /**
+     * @zh 自定义渲染
+     * @en Custom Render
+     */
+    render?: RenderFunction;
+    [other: string]: any;
+}
+
+interface SelectOptionGroup {
+    /**
+     * @zh 是否为选项组
+     * @en Whether it is an option group
+     */
+    isGroup: true;
+    /**
+     * @zh 选项组标题
+     * @en Option group title
+     */
+    label: string;
+    /**
+     * @zh 选项组中的选项
+     * @en Options in the option group
+     */
+    options: SelectOption[];
+    [other: string]: any;
+}
+
+type SelectOption = string | number | boolean | SelectOptionData | SelectOptionGroup;
+
+interface SelectOptionInfo extends SelectOptionData {
+    raw: Record<string, unknown>;
+    key: string;
+    index?: number;
+    origin: 'slot' | 'options' | 'extraOptions';
+    value: SelectOptionValue;
+    label: string;
+}
+
+interface SelectOptionGroupInfo extends SelectOptionGroup {
+    key: string;
+    options: (SelectOptionInfo | SelectOptionGroupInfo)[];
+}
+
+type FilterOption = boolean | ((inputValue: string, option: SelectOptionData) => boolean);
+
+interface SelectContext {
+    multiple?: boolean;
+    valueKey?: string;
+    inputValue?: string;
+    filterOption?: FilterOption;
+    component?: string;
+    valueKeys: string[];
+    activeKey?: string;
+    getOptionId: (key: string) => string;
+    onSelect: (key: string, ev: Event) => void;
+    setActiveKey: (key?: string) => void;
+    getNextSlotOptionIndex: () => number;
+    addSlotOptionInfo: (id: number, optionInfo: SelectOptionInfo) => void;
+    removeSlotOptionInfo: (id: number) => void;
+}
+```
+
+
+返回 [Select 用法](./select.md)。