@apexhub/apex-ui-react 0.0.0-stage → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +37 -2
  3. package/dist/en_US.d.ts +191 -0
  4. package/dist/index.cjs +40727 -0
  5. package/dist/index.d.ts +6873 -0
  6. package/dist/index.mjs +40711 -0
  7. package/dist/llm/alert.tokens.txt +44 -0
  8. package/dist/llm/alert.txt +167 -0
  9. package/dist/llm/apex-provider.txt +369 -0
  10. package/dist/llm/auto-complete.tokens.txt +77 -0
  11. package/dist/llm/auto-complete.txt +373 -0
  12. package/dist/llm/avatar.tokens.txt +38 -0
  13. package/dist/llm/avatar.txt +199 -0
  14. package/dist/llm/breadcrumb.tokens.txt +143 -0
  15. package/dist/llm/breadcrumb.txt +251 -0
  16. package/dist/llm/button.tokens.txt +470 -0
  17. package/dist/llm/button.txt +270 -0
  18. package/dist/llm/card.tokens.txt +29 -0
  19. package/dist/llm/card.txt +118 -0
  20. package/dist/llm/cascader.tokens.txt +261 -0
  21. package/dist/llm/cascader.txt +917 -0
  22. package/dist/llm/checkbox.tokens.txt +36 -0
  23. package/dist/llm/checkbox.txt +343 -0
  24. package/dist/llm/collapse.tokens.txt +84 -0
  25. package/dist/llm/collapse.txt +330 -0
  26. package/dist/llm/date-picker.tokens.txt +171 -0
  27. package/dist/llm/date-picker.txt +428 -0
  28. package/dist/llm/divider.tokens.txt +22 -0
  29. package/dist/llm/divider.txt +161 -0
  30. package/dist/llm/drawer.tokens.txt +71 -0
  31. package/dist/llm/drawer.txt +369 -0
  32. package/dist/llm/dropdown.tokens.txt +59 -0
  33. package/dist/llm/dropdown.txt +420 -0
  34. package/dist/llm/form.tokens.txt +28 -0
  35. package/dist/llm/form.txt +341 -0
  36. package/dist/llm/grid.txt +419 -0
  37. package/dist/llm/image.tokens.txt +28 -0
  38. package/dist/llm/image.txt +428 -0
  39. package/dist/llm/input-number.tokens.txt +159 -0
  40. package/dist/llm/input-number.txt +491 -0
  41. package/dist/llm/input.tokens.txt +136 -0
  42. package/dist/llm/input.txt +424 -0
  43. package/dist/llm/layout.tokens.txt +29 -0
  44. package/dist/llm/layout.txt +298 -0
  45. package/dist/llm/menu.tokens.txt +100 -0
  46. package/dist/llm/menu.txt +687 -0
  47. package/dist/llm/message.tokens.txt +25 -0
  48. package/dist/llm/message.txt +301 -0
  49. package/dist/llm/modal.tokens.txt +96 -0
  50. package/dist/llm/modal.txt +584 -0
  51. package/dist/llm/notification.tokens.txt +79 -0
  52. package/dist/llm/notification.txt +383 -0
  53. package/dist/llm/pagination.tokens.txt +35 -0
  54. package/dist/llm/pagination.txt +217 -0
  55. package/dist/llm/popover.tokens.txt +18 -0
  56. package/dist/llm/popover.txt +233 -0
  57. package/dist/llm/progress.tokens.txt +83 -0
  58. package/dist/llm/progress.txt +279 -0
  59. package/dist/llm/radio.tokens.txt +26 -0
  60. package/dist/llm/radio.txt +385 -0
  61. package/dist/llm/rate.tokens.txt +20 -0
  62. package/dist/llm/rate.txt +241 -0
  63. package/dist/llm/select.tokens.txt +160 -0
  64. package/dist/llm/select.txt +831 -0
  65. package/dist/llm/skeleton.tokens.txt +15 -0
  66. package/dist/llm/skeleton.txt +275 -0
  67. package/dist/llm/spin.tokens.txt +21 -0
  68. package/dist/llm/spin.txt +294 -0
  69. package/dist/llm/steps.tokens.txt +30 -0
  70. package/dist/llm/steps.txt +300 -0
  71. package/dist/llm/switch.tokens.txt +38 -0
  72. package/dist/llm/switch.txt +216 -0
  73. package/dist/llm/table.tokens.txt +94 -0
  74. package/dist/llm/table.txt +1049 -0
  75. package/dist/llm/tabs.tokens.txt +78 -0
  76. package/dist/llm/tabs.txt +306 -0
  77. package/dist/llm/tag.tokens.txt +75 -0
  78. package/dist/llm/tag.txt +304 -0
  79. package/dist/llm/tooltip.tokens.txt +22 -0
  80. package/dist/llm/tooltip.txt +304 -0
  81. package/dist/llm/tree-select.tokens.txt +175 -0
  82. package/dist/llm/tree-select.txt +772 -0
  83. package/dist/llm/tree.tokens.txt +34 -0
  84. package/dist/llm/tree.txt +501 -0
  85. package/dist/llm/typography.tokens.txt +60 -0
  86. package/dist/llm/typography.txt +413 -0
  87. package/dist/llm/upload.tokens.txt +205 -0
  88. package/dist/llm/upload.txt +708 -0
  89. package/dist/llms-full.txt +16826 -0
  90. package/dist/llms-theme.txt +32 -0
  91. package/dist/llms.txt +59 -0
  92. package/dist/locale/en_US.cjs +160 -0
  93. package/dist/locale/en_US.d.ts +4 -0
  94. package/dist/locale/en_US.mjs +161 -0
  95. package/dist/locale/zh_CN.cjs +160 -0
  96. package/dist/locale/zh_CN.d.ts +4 -0
  97. package/dist/locale/zh_CN.mjs +161 -0
  98. package/dist/style.css +20095 -0
  99. package/dist/zh_CN.d.ts +191 -0
  100. package/llms-full.txt +16826 -0
  101. package/llms-theme.txt +32 -0
  102. package/llms.txt +59 -0
  103. package/package.json +118 -3
  104. package/src/alert/llm.txt +167 -0
  105. package/src/alert/tokens.txt +44 -0
  106. package/src/apex-provider/llm.txt +369 -0
  107. package/src/auto-complete/llm.txt +373 -0
  108. package/src/auto-complete/tokens.txt +77 -0
  109. package/src/avatar/llm.txt +199 -0
  110. package/src/avatar/tokens.txt +38 -0
  111. package/src/breadcrumb/llm.txt +251 -0
  112. package/src/breadcrumb/tokens.txt +143 -0
  113. package/src/button/llm.txt +270 -0
  114. package/src/button/tokens.txt +470 -0
  115. package/src/card/llm.txt +118 -0
  116. package/src/card/tokens.txt +29 -0
  117. package/src/cascader/llm.txt +917 -0
  118. package/src/cascader/tokens.txt +261 -0
  119. package/src/checkbox/llm.txt +343 -0
  120. package/src/checkbox/tokens.txt +36 -0
  121. package/src/collapse/llm.txt +330 -0
  122. package/src/collapse/tokens.txt +84 -0
  123. package/src/date-picker/llm.txt +428 -0
  124. package/src/date-picker/tokens.txt +171 -0
  125. package/src/divider/llm.txt +161 -0
  126. package/src/divider/tokens.txt +22 -0
  127. package/src/drawer/llm.txt +369 -0
  128. package/src/drawer/tokens.txt +71 -0
  129. package/src/dropdown/llm.txt +420 -0
  130. package/src/dropdown/tokens.txt +59 -0
  131. package/src/form/llm.txt +341 -0
  132. package/src/form/tokens.txt +28 -0
  133. package/src/grid/llm.txt +419 -0
  134. package/src/image/llm.txt +428 -0
  135. package/src/image/tokens.txt +28 -0
  136. package/src/input/llm.txt +424 -0
  137. package/src/input/tokens.txt +136 -0
  138. package/src/input-number/llm.txt +491 -0
  139. package/src/input-number/tokens.txt +159 -0
  140. package/src/layout/llm.txt +298 -0
  141. package/src/layout/tokens.txt +29 -0
  142. package/src/menu/llm.txt +687 -0
  143. package/src/menu/tokens.txt +100 -0
  144. package/src/message/llm.txt +301 -0
  145. package/src/message/tokens.txt +25 -0
  146. package/src/modal/llm.txt +584 -0
  147. package/src/modal/tokens.txt +96 -0
  148. package/src/notification/llm.txt +383 -0
  149. package/src/notification/tokens.txt +79 -0
  150. package/src/pagination/llm.txt +217 -0
  151. package/src/pagination/tokens.txt +35 -0
  152. package/src/popover/llm.txt +233 -0
  153. package/src/popover/tokens.txt +18 -0
  154. package/src/progress/llm.txt +279 -0
  155. package/src/progress/tokens.txt +83 -0
  156. package/src/radio/llm.txt +385 -0
  157. package/src/radio/tokens.txt +26 -0
  158. package/src/rate/llm.txt +241 -0
  159. package/src/rate/tokens.txt +20 -0
  160. package/src/select/llm.txt +831 -0
  161. package/src/select/tokens.txt +160 -0
  162. package/src/skeleton/llm.txt +275 -0
  163. package/src/skeleton/tokens.txt +15 -0
  164. package/src/spin/llm.txt +294 -0
  165. package/src/spin/tokens.txt +21 -0
  166. package/src/steps/llm.txt +300 -0
  167. package/src/steps/tokens.txt +30 -0
  168. package/src/switch/llm.txt +216 -0
  169. package/src/switch/tokens.txt +38 -0
  170. package/src/table/llm.txt +1049 -0
  171. package/src/table/tokens.txt +94 -0
  172. package/src/tabs/llm.txt +306 -0
  173. package/src/tabs/tokens.txt +78 -0
  174. package/src/tag/llm.txt +304 -0
  175. package/src/tag/tokens.txt +75 -0
  176. package/src/tooltip/llm.txt +304 -0
  177. package/src/tooltip/tokens.txt +22 -0
  178. package/src/tree/llm.txt +501 -0
  179. package/src/tree/tokens.txt +34 -0
  180. package/src/tree-select/llm.txt +772 -0
  181. package/src/tree-select/tokens.txt +175 -0
  182. package/src/typography/llm.txt +413 -0
  183. package/src/typography/tokens.txt +60 -0
  184. package/src/upload/llm.txt +708 -0
  185. package/src/upload/tokens.txt +205 -0
@@ -0,0 +1,831 @@
1
+ # Select
2
+
3
+ > Select:选项来自预设列表,需要从其中选择一个或多个值时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Select`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Select } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ const options = [
19
+ { label: '选项 A', value: 'a' },
20
+ { label: '选项 B', value: 'b' },
21
+ { label: '选项 C', value: 'c' },
22
+ ]
23
+
24
+ export default () => <Select placeholder="请选择" options={options} />
25
+ ```
26
+
27
+ ## 何时使用
28
+
29
+ - 选项来自预设列表,需要从其中选择一个或多个值时。
30
+ - 选项较多、需要搜索过滤、分组展示,或需要 tags 模式输入新选项时。
31
+ - 若选项极少(2–3 个)且互斥,可考虑 Radio;自由文本输入请使用 Input 或 AutoComplete。
32
+
33
+ ## API
34
+
35
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
36
+
37
+ ### Select
38
+
39
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
40
+ | --- | --- | --- | --- | --- |
41
+ | mode | 此字段随模式变化,见下方判别联合与分支类型。 | `(undefined) \| ("multiple" \| "tags")` | 否 | — |
42
+ | value | 当前选中值(受控) | `(SelectSingleValue) \| (SelectMultiValue)` | 否 | — |
43
+ | defaultValue | 初始选中值(非受控) | `(SelectSingleValue) \| (SelectMultiValue)` | 否 | — |
44
+ | onChange | 此字段随模式变化,见下方判别联合与分支类型。 | `((value: SelectSingleValue \| undefined, option?: SelectOptionType) => void) \| ((value: SelectMultiValue, option?: SelectOptionType[]) => void)` | 否 | — |
45
+ | variant | 输入框表面变体,与 Input 一致。 | `"default" \| "elevated"` | 否 | `'default'` |
46
+ | allowClear | 自定义清除按钮;`true` 使用默认图标 | `boolean \| SelectAllowClear` | 否 | `false` |
47
+ | className | 外层根节点 className(`data-slot="select"` 的 `<div>`)<br>注:底层 Radix `Popover.Root` 是 Context Provider,不渲染 DOM;<br>`className` 落到外层 `data-slot="select"` 的 `<div>` 上,与 `<Input>` 等组件一致。 | `string` | 否 | — |
48
+ | style | 外层根节点内联样式(`data-slot="select"` 的 `<div>`);与 `styles.root` 合并,同名字段以本 prop 为准 | `React.CSSProperties` | 否 | — |
49
+ | classNames | 为各语义子结构自定义 `className`,支持对象或函数 | `Partial<Record<SelectSemanticDOM, string>> \| ((info: { props: Readonly<SelectProps> }) => Partial<Record<SelectSemanticDOM, string>>)` | 否 | — |
50
+ | defaultActiveFirstOption | 键盘/程序展开或搜索时,无匹配的选中项则按此配置激活首个可选项。<br>鼠标/触摸点击展开不自动激活首项;已有匹配的选中项时始终激活该项。 | `boolean` | 否 | `true` |
51
+ | defaultOpen | 下拉初始是否展开(非受控) | `boolean` | 否 | — |
52
+ | disabled | 是否禁用 | `boolean` | 否 | `false` |
53
+ | readOnly | 只读:不可打开下拉、不可改值,无 hover 交互态,仅展示。与 `disabled` 正交。 | `boolean` | 否 | `false` |
54
+ | fieldNames | 自定义 `label` / `value` / `options` / `groupLabel` 字段名 | `SelectFieldNames` | 否 | `{ label: 'label', value: 'value', options: 'options', groupLabel: 'label' }` |
55
+ | getPopupContainer | 已弃用:浮层统一挂载 `[data-slot="overlay-root"]`,该 prop 不再生效。 | `(triggerNode: HTMLElement) => HTMLElement` | 否 | — |
56
+ | maxCount | 最多可选数量,仅 `mode` 为 `multiple` 或 `tags` 时生效 | `number` | 否 | — |
57
+ | maxTagCount | 多选时输入框内最多展示的 tag 数量(可见 tag 数,不含 +N)。<br>- `number`:固定展示 N 个,其余折叠为 +M<br>- `'responsive'`:按 trigger 宽度自适应(推荐表单场景)<br>- `undefined`:展示全部(默认) | `MaxTagCount` | 否 | — |
58
+ | maxTagPlaceholder | 超出 `maxTagCount` 时的占位内容;Popover 仍内建(可用 `maxTagPopover={false}` 关闭) | `React.ReactNode \| ((omittedValues: SelectLabeledValue[]) => React.ReactNode)` | 否 | — |
59
+ | maxTagPopover | 溢出 tag(+M)的 Popover 行为;默认开启并预览全部已选项(hover + top) | `boolean \| MaxTagPopoverConfig<string \| number>` | 否 | — |
60
+ | size | 触发器尺寸 | `"small" \| "medium" \| "large"` | 否 | `'medium'` |
61
+ | notFoundContent | 无匹配结果时的展示内容 | `React.ReactNode` | 否 | `'Not Found'` |
62
+ | open | 下拉是否展开(受控) | `boolean` | 否 | — |
63
+ | closeOnScroll | 触发器的滚动祖先滚动时关闭;选项列表及无关区域滚动不受影响。<br>默认跟随滚动;触发器完全被裁剪或失效时始终请求关闭。 | `boolean` | 否 | `false` |
64
+ | optionLabelProp | 选中后展示文案取自 option 的哪个字段 | `string` | 否 | `'label'` |
65
+ | options | 选项数据;性能优于手写 JSX 子项 | `SelectBaseOptionType[]` | 否 | — |
66
+ | optionRender | 自定义下拉选项渲染 | `(option: SelectFlattenOptionData, info: { index: number }) => React.ReactNode` | 否 | — |
67
+ | placeholder | 未选中时的占位内容 | `React.ReactNode` | 否 | — |
68
+ | placement | 下拉弹出位置 | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight"` | 否 | `'bottomLeft'` |
69
+ | prefix | 选择框前缀 | `React.ReactNode` | 否 | — |
70
+ | removeIcon | 多选 / tags 模式下自定义移除图标 | `React.ReactNode` | 否 | — |
71
+ | showSearch | 是否可搜索;单选默认 `false`,多选默认 `true`;<br>传对象可内联配置所有搜索相关参数 | `boolean \| SelectShowSearchOption` | 否 | — |
72
+ | autoClearSearchValue | 选中后是否清空搜索框内容(仅 `multiple` / `tags` 模式生效) | `boolean` | 否 | `true` |
73
+ | filterOption | 客户端过滤逻辑;`false` 禁用(适合异步搜索);函数自定义匹配 | `boolean \| ((inputValue: string, option: SelectBaseOptionType) => boolean)` | 否 | `true` |
74
+ | filterSort | 搜索结果排序(`info.searchValue` 为当前输入值) | `( optionA: SelectBaseOptionType, optionB: SelectBaseOptionType, info: { searchValue: string }, ) => number` | 否 | — |
75
+ | optionFilterProp | 用于客户端过滤的 option 字段;设置了 `options` 时建议设为 `'label'`;<br>传数组则多字段 OR 匹配 | `string \| string[]` | 否 | `'value'` |
76
+ | searchValue | 搜索框当前文本(受控) | `string` | 否 | — |
77
+ | onSearch | 搜索输入变化时触发(常用于异步拉取 `options`) | `(value: string) => void` | 否 | — |
78
+ | searchIcon | 自定义搜索图标 | `React.ReactNode` | 否 | — |
79
+ | styles | 为各语义子结构自定义内联样式(仅允许 CSS Token 等变量赋值,禁止业务硬编码色值) | `Partial<Record<SelectSemanticDOM, React.CSSProperties>> \| ((info: { props: Readonly<SelectProps> }) => Partial<Record<SelectSemanticDOM, React.CSSProperties>>)` | 否 | — |
80
+ | status | 设置校验 / 状态样式(与 `Input` 一致) | `"error" \| "completed" \| "loading"` | 否 | — |
81
+ | suffixIcon | 后缀图标;自定义图标默认不响应点击打开,可用 `pointer-events: none` 绕过 | `React.ReactNode` | 否 | — |
82
+ | tagRender | 自定义标签渲染,仅 `mode` 为 `multiple` 或 `tags` | `(props: SelectTagRenderProps) => React.ReactNode` | 否 | — |
83
+ | labelRender | 自定义已选标签展示 | `(props: SelectLabelRenderProps) => React.ReactNode` | 否 | — |
84
+ | onActive | 键盘或鼠标交互激活某选项时 | `(value: string \| number \| SelectLabeledValue) => void` | 否 | — |
85
+ | onBlur | 失焦 | `React.FocusEventHandler<HTMLElement>` | 否 | — |
86
+ | onClear | 点击清除时 | `() => void` | 否 | — |
87
+ | onDeselect | 取消选中某值,仅 `multiple` / `tags` | `(value: string \| number \| SelectLabeledValue) => void` | 否 | — |
88
+ | onOpenChange | 下拉展开状态变化 | `(open: boolean) => void` | 否 | — |
89
+ | onFocus | 聚焦 | `React.FocusEventHandler<HTMLElement>` | 否 | — |
90
+ | onInputKeyDown | 输入框按键 | `React.KeyboardEventHandler<HTMLElement>` | 否 | — |
91
+ | virtual | 是否启用虚拟滚动;大量 `options` 时仅渲染可视窗口以提升性能 | `boolean` | 否 | `true` |
92
+ | listHeight | 下拉列表可视高度(px);虚拟滚动时作为滚动容器高度上限 | `number` | 否 | `256` |
93
+ | listItemHeight | 单个选项初始预估高度(px);真实高度会通过 `measureElement` 动态校正,<br>自定义 `optionRender` 可使用不同高度 | `number` | 否 | `32` |
94
+ | onPopupScroll | 下拉列表滚动 | `React.UIEventHandler<HTMLElement>` | 否 | — |
95
+ | onSelect | 选中某一选项时(与 `onChange` 并存;`option` 为对应项) | `(value: string \| number \| SelectLabeledValue, option: SelectOptionType) => void` | 否 | — |
96
+ | ref | 转发到焦点目标:`showSearch=true` 时为 `<input>`;否则为 trigger 容器 `<div>` | `React.Ref<HTMLInputElement \| HTMLDivElement>` | 否 | — |
97
+
98
+ ### 模式与类型约束
99
+
100
+ 主 API 表汇总各模式字段;实际可用组合以以下判别联合及各分支类型为准。
101
+
102
+ ```typescript
103
+ export type SelectProps = SelectSingleProps | SelectMultiProps
104
+ ```
105
+
106
+ ### SelectSemanticDOM
107
+
108
+ Select 子结构语义,用于 `classNames` / `styles` 分段定制
109
+
110
+ ```typescript
111
+ type SelectSemanticDOM = | 'root'
112
+ | 'selector'
113
+ | 'selection'
114
+ | 'placeholder'
115
+ | 'prefix'
116
+ | 'suffix'
117
+ | 'clear'
118
+ | 'popup'
119
+ | 'list'
120
+ | 'option'
121
+ ```
122
+
123
+ ### SelectLabeledValue
124
+
125
+ 带展示文案的选项值
126
+
127
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
128
+ | --- | --- | --- | --- | --- |
129
+ | value | — | `string \| number` | 是 | — |
130
+ | label | — | `React.ReactNode` | 否 | — |
131
+
132
+ ### SelectSingleValue
133
+
134
+ 单选模式下的值类型
135
+
136
+ ```typescript
137
+ type SelectSingleValue = string | number | SelectLabeledValue
138
+ ```
139
+
140
+ ### SelectMultiValue
141
+
142
+ 多选 / tags 模式下的值类型
143
+
144
+ ```typescript
145
+ type SelectMultiValue = string[] | number[] | SelectLabeledValue[]
146
+ ```
147
+
148
+ ### SelectValue
149
+
150
+ 兼容历史的宽 union 类型;新代码请优先使用 `SelectSingleValue` / `SelectMultiValue`
151
+
152
+ ```typescript
153
+ type SelectValue = SelectSingleValue | SelectMultiValue
154
+ ```
155
+
156
+ ### SelectBaseOptionType
157
+
158
+ `options` / `fieldNames` 下的选项结构(不对外提供已废弃的 `Select.Option` 子组件)
159
+
160
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
161
+ | --- | --- | --- | --- | --- |
162
+ | key | 展示行的唯一、稳定身份;可为字符串或数字。value 仍是业务选中值。 | `string \| number` | 否 | — |
163
+ | label | — | `React.ReactNode` | 否 | — |
164
+ | value | 选项值;搜索过滤、选中比较均依赖此字段 | `string \| number` | 否 | — |
165
+ | disabled | 是否禁用该选项 | `boolean` | 否 | `false` |
166
+ | className | 选项根节点额外 className | `string` | 否 | — |
167
+ | title | 原生 `title`(悬停提示) | `string` | 否 | — |
168
+ | options | 分组子选项 | `SelectBaseOptionType[]` | 否 | — |
169
+ | groupLabel | 分组标题(与 `fieldNames.groupLabel` 对应) | `React.ReactNode` | 否 | — |
170
+
171
+ ### SelectFlattenOptionData
172
+
173
+ 泛型参数:`<OptionType extends SelectBaseOptionType = SelectBaseOptionType>`。
174
+
175
+ `optionRender` 入参:拍平后的选项数据
176
+
177
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
178
+ | --- | --- | --- | --- | --- |
179
+ | key | 展示行的唯一、稳定身份;可为字符串或数字。value 仍是业务选中值。 | `string \| number` | 否 | — |
180
+ | label | — | `React.ReactNode` | 否 | — |
181
+ | value | 选项值;搜索过滤、选中比较均依赖此字段 | `string \| number` | 否 | — |
182
+ | disabled | 是否禁用该选项 | `boolean` | 否 | `false` |
183
+ | className | 选项根节点额外 className | `string` | 否 | — |
184
+ | title | 原生 `title`(悬停提示) | `string` | 否 | — |
185
+ | options | 分组子选项 | `SelectBaseOptionType[]` | 否 | — |
186
+ | groupLabel | 分组标题(与 `fieldNames.groupLabel` 对应) | `React.ReactNode` | 否 | — |
187
+ | level | 在列表中的层级(0 为顶层) | `number` | 否 | — |
188
+ | isGroupOption | 是否为分组标题行 | `boolean` | 否 | — |
189
+
190
+ ### SelectFieldNames
191
+
192
+ `fieldNames` 自定义字段名
193
+
194
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
195
+ | --- | --- | --- | --- | --- |
196
+ | label | — | `string` | 否 | — |
197
+ | value | — | `string` | 否 | — |
198
+ | options | — | `string` | 否 | — |
199
+ | groupLabel | — | `string` | 否 | — |
200
+
201
+ ### SelectAllowClear
202
+
203
+ `allowClear` 为对象时的配置
204
+
205
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
206
+ | --- | --- | --- | --- | --- |
207
+ | clearIcon | — | `React.ReactNode` | 否 | — |
208
+
209
+ ### SelectShowSearchOption
210
+
211
+ `showSearch` 为对象时的内联配置(所有字段与同名顶层 prop 含义相同)
212
+
213
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
214
+ | --- | --- | --- | --- | --- |
215
+ | autoClearSearchValue | 选中后是否清空搜索框内容(仅 `multiple` / `tags` 模式生效) | `boolean` | 否 | `true` |
216
+ | filterOption | 客户端过滤逻辑;`false` 禁用客户端过滤(适合异步搜索) | `boolean \| ((inputValue: string, option: SelectBaseOptionType) => boolean)` | 否 | `true` |
217
+ | filterSort | 搜索结果排序(`info.searchValue` 为当前输入值) | `( optionA: SelectBaseOptionType, optionB: SelectBaseOptionType, info: { searchValue: string }, ) => number` | 否 | — |
218
+ | optionFilterProp | 用于客户端过滤的 option 字段;设置了 `options` 时建议设为 `'label'`;<br>传数组则多字段 OR 匹配 | `string \| string[]` | 否 | `'value'` |
219
+ | searchValue | 搜索框当前文本(受控) | `string` | 否 | — |
220
+ | onSearch | 搜索输入变化时触发 | `(value: string) => void` | 否 | — |
221
+ | searchIcon | 自定义搜索图标 | `React.ReactNode` | 否 | — |
222
+
223
+ ### SelectTagRenderProps
224
+
225
+ `tagRender` 入参(`mode` 为 `multiple` / `tags`)
226
+
227
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
228
+ | --- | --- | --- | --- | --- |
229
+ | label | — | `React.ReactNode` | 是 | — |
230
+ | value | — | `string \| number` | 是 | — |
231
+ | disabled | — | `boolean` | 否 | — |
232
+ | onClose | — | `(event?: React.MouseEvent<HTMLElement>) => void` | 否 | — |
233
+ | closable | — | `boolean` | 否 | — |
234
+
235
+ ### SelectLabelRenderProps
236
+
237
+ `labelRender` 入参
238
+
239
+ **类型别名**:`SelectLabelRenderProps` 即 `SelectLabeledValue`,字段见上文 `### SelectLabeledValue`。
240
+
241
+ 等价写法:`SelectLabelRenderProps` ≡ `SelectLabeledValue`
242
+
243
+ ### SelectOptionType
244
+
245
+ `onChange` / `onSelect` 的 option 参数
246
+
247
+ **类型别名**:`SelectOptionType` 即 `SelectBaseOptionType`,字段见上文 `### SelectBaseOptionType`。
248
+
249
+ 等价写法:`SelectOptionType` ≡ `SelectBaseOptionType`
250
+
251
+ ### SelectSize
252
+
253
+ 触发器尺寸(消费 `.apex-sm/md/lg-input` 上的 `--input-height`)
254
+
255
+ ```typescript
256
+ type SelectSize = 'small' | 'medium' | 'large'
257
+ ```
258
+
259
+ ### SelectStatus
260
+
261
+ 校验 / 状态展示(与 `Input` 一致:复用 `--input-*-error|completed|loading` token)
262
+
263
+ ```typescript
264
+ type SelectStatus = 'error' | 'completed' | 'loading'
265
+ ```
266
+
267
+ ### SelectBaseProps
268
+
269
+ Select 公共 Props(不含与 `mode` 判别相关的 `value` / `defaultValue` / `onChange`)
270
+
271
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
272
+ | --- | --- | --- | --- | --- |
273
+ | variant | 输入框表面变体,与 Input 一致。 | `"default" \| "elevated"` | 否 | `'default'` |
274
+ | allowClear | 自定义清除按钮;`true` 使用默认图标 | `boolean \| SelectAllowClear` | 否 | `false` |
275
+ | className | 外层根节点 className(`data-slot="select"` 的 `<div>`)<br>注:底层 Radix `Popover.Root` 是 Context Provider,不渲染 DOM;<br>`className` 落到外层 `data-slot="select"` 的 `<div>` 上,与 `<Input>` 等组件一致。 | `string` | 否 | — |
276
+ | style | 外层根节点内联样式(`data-slot="select"` 的 `<div>`);与 `styles.root` 合并,同名字段以本 prop 为准 | `React.CSSProperties` | 否 | — |
277
+ | classNames | 为各语义子结构自定义 `className`,支持对象或函数 | `Partial<Record<SelectSemanticDOM, string>> \| ((info: { props: Readonly<SelectProps> }) => Partial<Record<SelectSemanticDOM, string>>)` | 否 | — |
278
+ | defaultActiveFirstOption | 键盘/程序展开或搜索时,无匹配的选中项则按此配置激活首个可选项。<br>鼠标/触摸点击展开不自动激活首项;已有匹配的选中项时始终激活该项。 | `boolean` | 否 | `true` |
279
+ | defaultOpen | 下拉初始是否展开(非受控) | `boolean` | 否 | — |
280
+ | disabled | 是否禁用 | `boolean` | 否 | `false` |
281
+ | readOnly | 只读:不可打开下拉、不可改值,无 hover 交互态,仅展示。与 `disabled` 正交。 | `boolean` | 否 | `false` |
282
+ | fieldNames | 自定义 `label` / `value` / `options` / `groupLabel` 字段名 | `SelectFieldNames` | 否 | `{ label: 'label', value: 'value', options: 'options', groupLabel: 'label' }` |
283
+ | getPopupContainer | 已弃用:浮层统一挂载 `[data-slot="overlay-root"]`,该 prop 不再生效。 | `(triggerNode: HTMLElement) => HTMLElement` | 否 | — |
284
+ | maxCount | 最多可选数量,仅 `mode` 为 `multiple` 或 `tags` 时生效 | `number` | 否 | — |
285
+ | maxTagCount | 多选时输入框内最多展示的 tag 数量(可见 tag 数,不含 +N)。<br>- `number`:固定展示 N 个,其余折叠为 +M<br>- `'responsive'`:按 trigger 宽度自适应(推荐表单场景)<br>- `undefined`:展示全部(默认) | `MaxTagCount` | 否 | — |
286
+ | maxTagPlaceholder | 超出 `maxTagCount` 时的占位内容;Popover 仍内建(可用 `maxTagPopover={false}` 关闭) | `React.ReactNode \| ((omittedValues: SelectLabeledValue[]) => React.ReactNode)` | 否 | — |
287
+ | maxTagPopover | 溢出 tag(+M)的 Popover 行为;默认开启并预览全部已选项(hover + top) | `boolean \| MaxTagPopoverConfig<string \| number>` | 否 | — |
288
+ | size | 触发器尺寸 | `"small" \| "medium" \| "large"` | 否 | `'medium'` |
289
+ | notFoundContent | 无匹配结果时的展示内容 | `React.ReactNode` | 否 | `'Not Found'` |
290
+ | open | 下拉是否展开(受控) | `boolean` | 否 | — |
291
+ | closeOnScroll | 触发器的滚动祖先滚动时关闭;选项列表及无关区域滚动不受影响。<br>默认跟随滚动;触发器完全被裁剪或失效时始终请求关闭。 | `boolean` | 否 | `false` |
292
+ | optionLabelProp | 选中后展示文案取自 option 的哪个字段 | `string` | 否 | `'label'` |
293
+ | options | 选项数据;性能优于手写 JSX 子项 | `SelectBaseOptionType[]` | 否 | — |
294
+ | optionRender | 自定义下拉选项渲染 | `(option: SelectFlattenOptionData, info: { index: number }) => React.ReactNode` | 否 | — |
295
+ | placeholder | 未选中时的占位内容 | `React.ReactNode` | 否 | — |
296
+ | placement | 下拉弹出位置 | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight"` | 否 | `'bottomLeft'` |
297
+ | prefix | 选择框前缀 | `React.ReactNode` | 否 | — |
298
+ | removeIcon | 多选 / tags 模式下自定义移除图标 | `React.ReactNode` | 否 | — |
299
+ | showSearch | 是否可搜索;单选默认 `false`,多选默认 `true`;<br>传对象可内联配置所有搜索相关参数 | `boolean \| SelectShowSearchOption` | 否 | — |
300
+ | autoClearSearchValue | 选中后是否清空搜索框内容(仅 `multiple` / `tags` 模式生效) | `boolean` | 否 | `true` |
301
+ | filterOption | 客户端过滤逻辑;`false` 禁用(适合异步搜索);函数自定义匹配 | `boolean \| ((inputValue: string, option: SelectBaseOptionType) => boolean)` | 否 | `true` |
302
+ | filterSort | 搜索结果排序(`info.searchValue` 为当前输入值) | `( optionA: SelectBaseOptionType, optionB: SelectBaseOptionType, info: { searchValue: string }, ) => number` | 否 | — |
303
+ | optionFilterProp | 用于客户端过滤的 option 字段;设置了 `options` 时建议设为 `'label'`;<br>传数组则多字段 OR 匹配 | `string \| string[]` | 否 | `'value'` |
304
+ | searchValue | 搜索框当前文本(受控) | `string` | 否 | — |
305
+ | onSearch | 搜索输入变化时触发(常用于异步拉取 `options`) | `(value: string) => void` | 否 | — |
306
+ | searchIcon | 自定义搜索图标 | `React.ReactNode` | 否 | — |
307
+ | styles | 为各语义子结构自定义内联样式(仅允许 CSS Token 等变量赋值,禁止业务硬编码色值) | `Partial<Record<SelectSemanticDOM, React.CSSProperties>> \| ((info: { props: Readonly<SelectProps> }) => Partial<Record<SelectSemanticDOM, React.CSSProperties>>)` | 否 | — |
308
+ | status | 设置校验 / 状态样式(与 `Input` 一致) | `"error" \| "completed" \| "loading"` | 否 | — |
309
+ | suffixIcon | 后缀图标;自定义图标默认不响应点击打开,可用 `pointer-events: none` 绕过 | `React.ReactNode` | 否 | — |
310
+ | tagRender | 自定义标签渲染,仅 `mode` 为 `multiple` 或 `tags` | `(props: SelectTagRenderProps) => React.ReactNode` | 否 | — |
311
+ | labelRender | 自定义已选标签展示 | `(props: SelectLabelRenderProps) => React.ReactNode` | 否 | — |
312
+ | onActive | 键盘或鼠标交互激活某选项时 | `(value: string \| number \| SelectLabeledValue) => void` | 否 | — |
313
+ | onBlur | 失焦 | `React.FocusEventHandler<HTMLElement>` | 否 | — |
314
+ | onClear | 点击清除时 | `() => void` | 否 | — |
315
+ | onDeselect | 取消选中某值,仅 `multiple` / `tags` | `(value: string \| number \| SelectLabeledValue) => void` | 否 | — |
316
+ | onOpenChange | 下拉展开状态变化 | `(open: boolean) => void` | 否 | — |
317
+ | onFocus | 聚焦 | `React.FocusEventHandler<HTMLElement>` | 否 | — |
318
+ | onInputKeyDown | 输入框按键 | `React.KeyboardEventHandler<HTMLElement>` | 否 | — |
319
+ | virtual | 是否启用虚拟滚动;大量 `options` 时仅渲染可视窗口以提升性能 | `boolean` | 否 | `true` |
320
+ | listHeight | 下拉列表可视高度(px);虚拟滚动时作为滚动容器高度上限 | `number` | 否 | `256` |
321
+ | listItemHeight | 单个选项初始预估高度(px);真实高度会通过 `measureElement` 动态校正,<br>自定义 `optionRender` 可使用不同高度 | `number` | 否 | `32` |
322
+ | onPopupScroll | 下拉列表滚动 | `React.UIEventHandler<HTMLElement>` | 否 | — |
323
+ | onSelect | 选中某一选项时(与 `onChange` 并存;`option` 为对应项) | `(value: string \| number \| SelectLabeledValue, option: SelectOptionType) => void` | 否 | — |
324
+ | ref | 转发到焦点目标:`showSearch=true` 时为 `<input>`;否则为 trigger 容器 `<div>` | `React.Ref<HTMLInputElement \| HTMLDivElement>` | 否 | — |
325
+
326
+ ### SelectSingleProps
327
+
328
+ 继承:`SelectBaseProps`;本节列出新增或重声明字段。
329
+
330
+ 单选模式 Props(`mode` 未设或不为 `'multiple'` / `'tags'`)
331
+
332
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
333
+ | --- | --- | --- | --- | --- |
334
+ | mode | 选择模式(单选) | `undefined` | 否 | — |
335
+ | value | 当前选中值(受控) | `SelectSingleValue` | 否 | — |
336
+ | defaultValue | 初始选中值(非受控) | `SelectSingleValue` | 否 | — |
337
+ | onChange | 选中值变化(`(value, option)`);清除时 `value` 为 `undefined` | `(value: SelectSingleValue \| undefined, option?: SelectOptionType) => void` | 否 | — |
338
+
339
+ ### SelectMultiProps
340
+
341
+ 继承:`SelectBaseProps`;本节列出新增或重声明字段。
342
+
343
+ 多选 / Tags 模式 Props(`mode: 'multiple' | 'tags'`)
344
+
345
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
346
+ | --- | --- | --- | --- | --- |
347
+ | mode | 选择模式 | `"multiple" \| "tags"` | 是 | — |
348
+ | value | 当前选中值(受控) | `SelectMultiValue` | 否 | — |
349
+ | defaultValue | 初始选中值(非受控) | `SelectMultiValue` | 否 | — |
350
+ | onChange | 选中值变化;清除 / 反选最后一项时 `value` 为 `[]` | `(value: SelectMultiValue, option?: SelectOptionType[]) => void` | 否 | — |
351
+
352
+ ### MaxTagCount
353
+
354
+ 展示层最多渲染的 tag 数量;超出部分合并为溢出 tag
355
+
356
+ ```typescript
357
+ type MaxTagCount = number | 'responsive'
358
+ ```
359
+
360
+ ### MaxTagPopoverConfig
361
+
362
+ 泛型参数:`<TValue = string | number>`。
363
+
364
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
365
+ | --- | --- | --- | --- | --- |
366
+ | trigger | — | `"hover" \| "click"` | 否 | `'hover'` |
367
+ | placement | — | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight" \| "top" \| "left" \| "right" \| "bottom" \| "leftTop" \| "leftBottom" \| "rightTop" \| "rightBottom"` | 否 | `'top'` |
368
+ | overlaySelector | 是否覆盖在选择器上展开;设为 false 时使用普通 Popover 定位。@default true | `boolean` | 否 | — |
369
+ | disabled | 禁用 Popover,仅展示 +N | `boolean` | 否 | — |
370
+ | contentRender | 自定义完整已选项预览内容 | `(values: LabeledValue<TValue>[]) => React.ReactNode` | 否 | — |
371
+
372
+ ### LabeledValue
373
+
374
+ 泛型参数:`<TValue = string | number>`。
375
+
376
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
377
+ | --- | --- | --- | --- | --- |
378
+ | value | — | `TValue` | 是 | — |
379
+ | label | — | `React.ReactNode` | 是 | — |
380
+
381
+ 其他组件的类型不在此展开:`InputVariant` 见 `../input/llm.txt`、`PopoverPlacement` 见 `../popover/llm.txt`。
382
+
383
+ ### 导出类型
384
+
385
+ 另可从 `@apexhub/apex-ui-react` 导入:`SelectAllowClear`、`SelectBaseOptionType`、`SelectFieldNames`、`SelectFlattenOptionData`、`SelectLabeledValue`、`SelectLabelRenderProps`、`SelectOptionType`、`SelectProps`、`SelectSemanticDOM`、`SelectShowSearchOption`、`SelectStatus`、`SelectTagRenderProps`、`SelectValue`(与上文子类型配合使用)。
386
+
387
+ ## 代码演示
388
+
389
+ ### 尺寸
390
+
391
+ 支持 `large`、`medium`(默认)、`small` 三种尺寸。示例选中值并开启清除:large/medium 的下拉箭头为 16px,small 为 14px,清除按钮均为 14px。
392
+
393
+ ```tsx
394
+ import { Select } from '@apexhub/apex-ui-react'
395
+
396
+ const options = [
397
+ { label: 'React', value: 'react' },
398
+ { label: 'Vue', value: 'vue' },
399
+ ]
400
+
401
+ export default () => (
402
+ <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
403
+ <Select size="large" defaultValue="react" allowClear options={options} />
404
+ <Select size="medium" defaultValue="react" allowClear options={options} />
405
+ <Select size="small" defaultValue="react" allowClear options={options} />
406
+ </div>
407
+ )
408
+ ```
409
+
410
+ ### 禁用状态
411
+
412
+ 可禁用整个 Select,也可以禁用单个选项。
413
+
414
+ ```tsx
415
+ import { Select } from '@apexhub/apex-ui-react'
416
+
417
+ const options = [
418
+ { label: '可选项', value: 'enabled' },
419
+ { label: '禁用项', value: 'disabled', disabled: true },
420
+ ]
421
+
422
+ export default () => (
423
+ <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
424
+ <Select placeholder="包含禁用项" options={options} />
425
+ <Select disabled defaultValue="enabled" options={options} />
426
+ </div>
427
+ )
428
+ ```
429
+
430
+ ### 只读
431
+
432
+ `readOnly` 不可打开下拉、不可改值;视觉使用禁用配色,但仍可聚焦。示例包含空值、单选和多选。
433
+
434
+ ```tsx
435
+ import { Select } from '@apexhub/apex-ui-react'
436
+
437
+ const options = [
438
+ { label: '选项 A', value: 'a' },
439
+ { label: '选项 B', value: 'b' },
440
+ { label: '选项 C', value: 'c' },
441
+ ]
442
+
443
+ export default () => (
444
+ <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
445
+ <Select readOnly placeholder="只读空值" options={options} style={{ minWidth: 160 }} />
446
+ <Select readOnly defaultValue="a" options={options} />
447
+ <Select
448
+ mode="multiple"
449
+ readOnly
450
+ defaultValue={['a', 'b']}
451
+ options={options}
452
+ style={{ minWidth: 200 }}
453
+ />
454
+ </div>
455
+ )
456
+ ```
457
+
458
+ ### 状态
459
+
460
+ 通过 `status` 展示错误、完成和加载状态。
461
+
462
+ ```tsx
463
+ import { Select } from '@apexhub/apex-ui-react'
464
+
465
+ const options = [
466
+ { label: '选项 A', value: 'a' },
467
+ { label: '选项 B', value: 'b' },
468
+ ]
469
+
470
+ export default () => (
471
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 12, maxWidth: 280 }}>
472
+ <Select status="error" placeholder="错误状态" options={options} />
473
+ <Select status="completed" placeholder="完成状态" options={options} />
474
+ <Select status="loading" placeholder="加载状态" options={options} />
475
+ </div>
476
+ )
477
+ ```
478
+
479
+ ### 可清除
480
+
481
+ `allowClear` 展示清除按钮,清除后单选值变为 `undefined`,多选值变为空数组。
482
+
483
+ ```tsx
484
+ import { Select } from '@apexhub/apex-ui-react'
485
+
486
+ import { useState } from 'react'
487
+
488
+ const options = [
489
+ { label: '杭州', value: 'hangzhou' },
490
+ { label: '上海', value: 'shanghai' },
491
+ { label: '北京', value: 'beijing' },
492
+ ]
493
+
494
+ export default () => {
495
+ const [value, setValue] = useState<string | number | undefined>('hangzhou')
496
+
497
+ return (
498
+ <Select
499
+ allowClear
500
+ value={value}
501
+ placeholder="请选择城市"
502
+ options={options}
503
+ onChange={(next) => setValue(typeof next === 'object' ? next?.value : next)}
504
+ onClear={() => setValue(undefined)}
505
+ />
506
+ )
507
+ }
508
+ ```
509
+
510
+ ### 搜索
511
+
512
+ `showSearch` 开启搜索;可通过 `optionFilterProp` 指定过滤字段。
513
+
514
+ ```tsx
515
+ import { Select } from '@apexhub/apex-ui-react'
516
+
517
+ const options = [
518
+ { label: 'TypeScript', value: 'ts' },
519
+ { label: 'JavaScript', value: 'js' },
520
+ { label: 'Python', value: 'py' },
521
+ { label: 'Rust', value: 'rust' },
522
+ ]
523
+
524
+ export default () => (
525
+ <Select showSearch allowClear optionFilterProp="label" placeholder="搜索语言" options={options} />
526
+ )
527
+ ```
528
+
529
+ ### 虚拟滚动
530
+
531
+ 大量 `options` 时默认启用 `virtual`,使用上下 spacer 与动态测高,仅渲染可视窗口内的选项;可通过 `listHeight` 调整列表高度,`listItemHeight` 仅作为首次布局预估,自定义选项的真实高度会自动校正。
532
+
533
+ ```tsx
534
+ import { Select } from '@apexhub/apex-ui-react'
535
+
536
+ const options = Array.from({ length: 10_000 }, (_, index) => ({
537
+ label: `选项 ${index + 1}`,
538
+ value: String(index + 1),
539
+ }))
540
+
541
+ export default () => (
542
+ <Select
543
+ placeholder="打开下拉浏览大量选项"
544
+ options={options}
545
+ showSearch
546
+ virtual
547
+ listHeight={256}
548
+ listItemHeight={32}
549
+ style={{ width: 240 }}
550
+ />
551
+ )
552
+ ```
553
+
554
+ ### 多选
555
+
556
+ `mode="multiple"` 支持选择多个值,`maxCount` 可限制最多可选数量。
557
+
558
+ ```tsx
559
+ import { Select } from '@apexhub/apex-ui-react'
560
+
561
+ import { useState } from 'react'
562
+
563
+ const options = [
564
+ { label: 'Apple', value: 'apple' },
565
+ { label: 'Banana', value: 'banana' },
566
+ { label: 'Cherry', value: 'cherry' },
567
+ { label: 'Durian', value: 'durian' },
568
+ ]
569
+
570
+ export default () => {
571
+ const [value, setValue] = useState<string[]>(['apple'])
572
+
573
+ return (
574
+ <Select
575
+ style={{ width: '330px' }}
576
+ mode="multiple"
577
+ allowClear
578
+ maxTagCount={3}
579
+ value={value}
580
+ placeholder="请选择水果"
581
+ options={options}
582
+ onChange={(next) => setValue(next as string[])}
583
+ />
584
+ )
585
+ }
586
+ ```
587
+
588
+ ### 标签模式
589
+
590
+ `mode="tags"` 支持从输入内容创建新标签。
591
+
592
+ ```tsx
593
+ import { Select } from '@apexhub/apex-ui-react'
594
+
595
+ import { useState } from 'react'
596
+
597
+ const options = [
598
+ { label: 'Design', value: 'design' },
599
+ { label: 'React', value: 'react' },
600
+ { label: 'Docs', value: 'docs' },
601
+ ]
602
+
603
+ export default () => {
604
+ const [value, setValue] = useState<string[]>(['react'])
605
+
606
+ return (
607
+ <Select
608
+ style={{ width: '250px' }}
609
+ mode="tags"
610
+ value={value}
611
+ placeholder="输入后按 Enter 创建标签"
612
+ options={options}
613
+ onChange={(next) => setValue(next as string[])}
614
+ />
615
+ )
616
+ }
617
+ ```
618
+
619
+ ### 分组选项与字段映射
620
+
621
+ 通过嵌套 `options` 表达分组,也可以用 `fieldNames` 适配后端字段。
622
+
623
+ ```tsx
624
+ import { Select } from '@apexhub/apex-ui-react'
625
+
626
+ const options = [
627
+ {
628
+ name: '前端',
629
+ children: [
630
+ { name: 'React', id: 'react' },
631
+ { name: 'Vue', id: 'vue' },
632
+ ],
633
+ },
634
+ {
635
+ name: '后端',
636
+ children: [
637
+ { name: 'Node.js', id: 'node' },
638
+ { name: 'Python', id: 'python' },
639
+ ],
640
+ },
641
+ ]
642
+
643
+ export default () => (
644
+ <Select
645
+ placeholder="请选择技术栈"
646
+ options={options}
647
+ fieldNames={{ label: 'name', value: 'id', options: 'children', groupLabel: 'name' }}
648
+ />
649
+ )
650
+ ```
651
+
652
+ ### 自定义渲染
653
+
654
+ 通过 `optionRender`、`labelRender` 和 `tagRender` 定制下拉项、已选展示和标签。
655
+
656
+ ```tsx
657
+ import type { SelectTagRenderProps } from '@apexhub/apex-ui-react'
658
+
659
+ import { Button, Select } from '@apexhub/apex-ui-react'
660
+
661
+ const options = [
662
+ { label: 'React', value: 'react', description: 'UI library' },
663
+ { label: 'TypeScript', value: 'ts', description: 'Typed JavaScript' },
664
+ { label: 'Vite', value: 'vite', description: 'Build tool' },
665
+ ]
666
+
667
+ const tagRender = ({ label, onClose, closable }: SelectTagRenderProps) => (
668
+ <span
669
+ style={{
670
+ display: 'inline-flex',
671
+ alignItems: 'center',
672
+ gap: 4,
673
+ paddingInline: 'var(--apex-spacing-8)',
674
+ border: 'var(--apex-border-1) solid var(--apex-stroke-neutral-quinary)',
675
+ borderRadius: '7px',
676
+ }}
677
+ >
678
+ {label}
679
+ {closable ? (
680
+ <Button
681
+ type="text"
682
+ size="small"
683
+ style={{
684
+ display: 'flex',
685
+ alignItems: 'center',
686
+ justifyContent: 'center',
687
+ width: 14,
688
+ height: 14,
689
+ opacity: 0.8,
690
+ lineHeight: 0,
691
+ padding: 0,
692
+ }}
693
+ onClick={onClose}
694
+ aria-label={`移除 ${String(label)}`}
695
+ >
696
+ ×
697
+ </Button>
698
+ ) : null}
699
+ </span>
700
+ )
701
+
702
+ export default () => (
703
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 12, maxWidth: 320 }}>
704
+ <Select
705
+ style={{ width: '250px' }}
706
+ defaultValue="react"
707
+ options={options}
708
+ labelRender={({ label, value }) => `${label ?? value} 已选`}
709
+ optionRender={(option) => (
710
+ <div style={{ display: 'flex', justifyContent: 'space-between', gap: 12, width: '100%' }}>
711
+ <span>{option.label}</span>
712
+ <span style={{ color: 'var(--apex-text-neutral-secondary)' }}>
713
+ {String(option.description ?? '')}
714
+ </span>
715
+ </div>
716
+ )}
717
+ />
718
+ <Select
719
+ style={{ width: '250px' }}
720
+ mode="multiple"
721
+ defaultValue={['react']}
722
+ options={options}
723
+ tagRender={tagRender}
724
+ placeholder="自定义标签"
725
+ />
726
+ </div>
727
+ )
728
+ ```
729
+
730
+ ### 受控展开
731
+
732
+ 通过 `open` 与 展开变化事件 控制下拉展开状态。
733
+
734
+ ```tsx
735
+ import { Button, Select } from '@apexhub/apex-ui-react'
736
+
737
+ import { useState } from 'react'
738
+
739
+ const options = [
740
+ { label: '选项 A', value: 'a' },
741
+ { label: '选项 B', value: 'b' },
742
+ ]
743
+
744
+ export default () => {
745
+ const [open, setOpen] = useState(false)
746
+
747
+ return (
748
+ <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
749
+ <Select open={open} onOpenChange={setOpen} placeholder="受控展开" options={options} />
750
+ <Button onClick={() => setOpen((current) => !current)}>
751
+ {open ? '关闭下拉' : '打开下拉'}
752
+ </Button>
753
+ </div>
754
+ )
755
+ }
756
+ ```
757
+
758
+ ### 自定义语义结构
759
+
760
+ 通过 `classNames` 和 `styles` 定制各语义节点样式。
761
+
762
+ ```tsx
763
+ import type { SelectProps } from '@apexhub/apex-ui-react'
764
+
765
+ import { Select } from '@apexhub/apex-ui-react'
766
+
767
+ const options = [
768
+ { label: 'Alpha', value: 'alpha' },
769
+ { label: 'Beta', value: 'beta' },
770
+ { label: 'Gamma', value: 'gamma' },
771
+ ]
772
+
773
+ const styles: SelectProps['styles'] = {
774
+ selector: {
775
+ minWidth: 220,
776
+ },
777
+ popup: {
778
+ minWidth: 220,
779
+ },
780
+ option: {
781
+ letterSpacing: 0.2,
782
+ },
783
+ }
784
+
785
+ export default () => (
786
+ <Select
787
+ defaultValue="alpha"
788
+ options={options}
789
+ classNames={{
790
+ root: 'custom-select-root',
791
+ selector: 'custom-select-selector',
792
+ option: 'custom-select-option',
793
+ }}
794
+ styles={styles}
795
+ />
796
+ )
797
+ ```
798
+
799
+ ## DOM 结构
800
+
801
+ 源码声明的静态 `data-slot`:`select-virtual-spacer`、`select-virtual-holder`、`select-option-check`、`select`、`selector`、`input-clear`、`popup`、`list`。具体节点随模式和状态出现,不表示固定嵌套顺序。
802
+
803
+ ## 样式定制
804
+
805
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
806
+
807
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
808
+
809
+ ## FAQ
810
+
811
+ ### 为什么没有 `Select.Option` 子组件?
812
+
813
+ 选项统一通过 `options` 配置,性能更好。
814
+
815
+
816
+ ### 异步搜索怎么实现?
817
+
818
+ 设置 `filterOption={false}`,在 `onSearch` 中请求数据并更新 `options`;需要受控搜索文本时配合 `searchValue`。
819
+
820
+ 单选和多选都会保留已选项数据:更换关键词或清空 `options` 不会让已选名称退回 ID,多选 `onChange` 的选项参数也会保留已选项的业务字段。新结果包含同一 value 时,采用新结果的数据;取消选择或清空后释放对应缓存。缓存不会把旧选项追加到下拉搜索结果。
821
+
822
+ 编辑回显时,可以先传入 `{ value, label }`(多选为数组),或先加载已选项到 `options`。只有 ID 且从未加载名称时仍显示 ID。`onChange` 的值参数仍为原始 ID(多选为 ID 数组)。请求、防抖、乱序保护和错误处理由业务负责;加载状态使用 `status="loading"`。
823
+
824
+
825
+ ### `tags` 模式下如何创建新标签?
826
+
827
+ 输入搜索文本后按 Enter;若无匹配项,将把当前输入创建为新标签。
828
+
829
+ ### `readOnly` 和 `disabled` 有什么区别?
830
+
831
+ `disabled` 不可交互;`readOnly` 同样使用禁用配色且不可打开下拉或改值,但保留可聚焦语义,适合表单只读场景。