@apexhub/apex-ui-react 0.0.0-stage → 1.2.0
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.
- package/LICENSE +21 -0
- package/README.md +37 -2
- package/dist/en_US.d.ts +191 -0
- package/dist/index.cjs +40692 -0
- package/dist/index.d.ts +6869 -0
- package/dist/index.mjs +40676 -0
- package/dist/llm/alert.tokens.txt +44 -0
- package/dist/llm/alert.txt +167 -0
- package/dist/llm/apex-provider.txt +368 -0
- package/dist/llm/auto-complete.tokens.txt +77 -0
- package/dist/llm/auto-complete.txt +373 -0
- package/dist/llm/avatar.tokens.txt +38 -0
- package/dist/llm/avatar.txt +199 -0
- package/dist/llm/breadcrumb.tokens.txt +193 -0
- package/dist/llm/breadcrumb.txt +251 -0
- package/dist/llm/button.tokens.txt +470 -0
- package/dist/llm/button.txt +262 -0
- package/dist/llm/card.tokens.txt +27 -0
- package/dist/llm/card.txt +95 -0
- package/dist/llm/cascader.tokens.txt +253 -0
- package/dist/llm/cascader.txt +898 -0
- package/dist/llm/checkbox.tokens.txt +28 -0
- package/dist/llm/checkbox.txt +332 -0
- package/dist/llm/collapse.tokens.txt +84 -0
- package/dist/llm/collapse.txt +330 -0
- package/dist/llm/date-picker.tokens.txt +171 -0
- package/dist/llm/date-picker.txt +424 -0
- package/dist/llm/divider.tokens.txt +22 -0
- package/dist/llm/divider.txt +161 -0
- package/dist/llm/drawer.tokens.txt +71 -0
- package/dist/llm/drawer.txt +369 -0
- package/dist/llm/dropdown.tokens.txt +59 -0
- package/dist/llm/dropdown.txt +420 -0
- package/dist/llm/form.tokens.txt +26 -0
- package/dist/llm/form.txt +341 -0
- package/dist/llm/grid.txt +419 -0
- package/dist/llm/image.tokens.txt +28 -0
- package/dist/llm/image.txt +428 -0
- package/dist/llm/input-number.tokens.txt +159 -0
- package/dist/llm/input-number.txt +486 -0
- package/dist/llm/input.tokens.txt +136 -0
- package/dist/llm/input.txt +422 -0
- package/dist/llm/layout.tokens.txt +29 -0
- package/dist/llm/layout.txt +298 -0
- package/dist/llm/menu.tokens.txt +87 -0
- package/dist/llm/menu.txt +680 -0
- package/dist/llm/message.tokens.txt +25 -0
- package/dist/llm/message.txt +301 -0
- package/dist/llm/modal.tokens.txt +96 -0
- package/dist/llm/modal.txt +584 -0
- package/dist/llm/notification.tokens.txt +79 -0
- package/dist/llm/notification.txt +383 -0
- package/dist/llm/pagination.tokens.txt +33 -0
- package/dist/llm/pagination.txt +208 -0
- package/dist/llm/popover.tokens.txt +28 -0
- package/dist/llm/popover.txt +233 -0
- package/dist/llm/progress.tokens.txt +83 -0
- package/dist/llm/progress.txt +279 -0
- package/dist/llm/radio.tokens.txt +21 -0
- package/dist/llm/radio.txt +348 -0
- package/dist/llm/rate.tokens.txt +20 -0
- package/dist/llm/rate.txt +241 -0
- package/dist/llm/select.tokens.txt +160 -0
- package/dist/llm/select.txt +830 -0
- package/dist/llm/skeleton.tokens.txt +15 -0
- package/dist/llm/skeleton.txt +275 -0
- package/dist/llm/spin.tokens.txt +21 -0
- package/dist/llm/spin.txt +294 -0
- package/dist/llm/steps.tokens.txt +30 -0
- package/dist/llm/steps.txt +300 -0
- package/dist/llm/switch.tokens.txt +38 -0
- package/dist/llm/switch.txt +216 -0
- package/dist/llm/table.tokens.txt +94 -0
- package/dist/llm/table.txt +1046 -0
- package/dist/llm/tabs.tokens.txt +78 -0
- package/dist/llm/tabs.txt +306 -0
- package/dist/llm/tag.tokens.txt +76 -0
- package/dist/llm/tag.txt +305 -0
- package/dist/llm/tooltip.tokens.txt +22 -0
- package/dist/llm/tooltip.txt +304 -0
- package/dist/llm/tree-select.tokens.txt +174 -0
- package/dist/llm/tree-select.txt +762 -0
- package/dist/llm/tree.tokens.txt +36 -0
- package/dist/llm/tree.txt +505 -0
- package/dist/llm/typography.tokens.txt +60 -0
- package/dist/llm/typography.txt +413 -0
- package/dist/llm/upload.tokens.txt +201 -0
- package/dist/llm/upload.txt +706 -0
- package/dist/llms-full.txt +16689 -0
- package/dist/llms-theme.txt +32 -0
- package/dist/llms.txt +59 -0
- package/dist/locale/en_US.cjs +160 -0
- package/dist/locale/en_US.d.ts +4 -0
- package/dist/locale/en_US.mjs +161 -0
- package/dist/locale/zh_CN.cjs +160 -0
- package/dist/locale/zh_CN.d.ts +4 -0
- package/dist/locale/zh_CN.mjs +161 -0
- package/dist/style.css +19619 -0
- package/dist/zh_CN.d.ts +191 -0
- package/llms-full.txt +16689 -0
- package/llms-theme.txt +32 -0
- package/llms.txt +59 -0
- package/package.json +118 -3
- package/src/alert/llm.txt +167 -0
- package/src/alert/tokens.txt +44 -0
- package/src/apex-provider/llm.txt +368 -0
- package/src/auto-complete/llm.txt +373 -0
- package/src/auto-complete/tokens.txt +77 -0
- package/src/avatar/llm.txt +199 -0
- package/src/avatar/tokens.txt +38 -0
- package/src/breadcrumb/llm.txt +251 -0
- package/src/breadcrumb/tokens.txt +193 -0
- package/src/button/llm.txt +262 -0
- package/src/button/tokens.txt +470 -0
- package/src/card/llm.txt +95 -0
- package/src/card/tokens.txt +27 -0
- package/src/cascader/llm.txt +898 -0
- package/src/cascader/tokens.txt +253 -0
- package/src/checkbox/llm.txt +332 -0
- package/src/checkbox/tokens.txt +28 -0
- package/src/collapse/llm.txt +330 -0
- package/src/collapse/tokens.txt +84 -0
- package/src/date-picker/llm.txt +424 -0
- package/src/date-picker/tokens.txt +171 -0
- package/src/divider/llm.txt +161 -0
- package/src/divider/tokens.txt +22 -0
- package/src/drawer/llm.txt +369 -0
- package/src/drawer/tokens.txt +71 -0
- package/src/dropdown/llm.txt +420 -0
- package/src/dropdown/tokens.txt +59 -0
- package/src/form/llm.txt +341 -0
- package/src/form/tokens.txt +26 -0
- package/src/grid/llm.txt +419 -0
- package/src/image/llm.txt +428 -0
- package/src/image/tokens.txt +28 -0
- package/src/input/llm.txt +422 -0
- package/src/input/tokens.txt +136 -0
- package/src/input-number/llm.txt +486 -0
- package/src/input-number/tokens.txt +159 -0
- package/src/layout/llm.txt +298 -0
- package/src/layout/tokens.txt +29 -0
- package/src/menu/llm.txt +680 -0
- package/src/menu/tokens.txt +87 -0
- package/src/message/llm.txt +301 -0
- package/src/message/tokens.txt +25 -0
- package/src/modal/llm.txt +584 -0
- package/src/modal/tokens.txt +96 -0
- package/src/notification/llm.txt +383 -0
- package/src/notification/tokens.txt +79 -0
- package/src/pagination/llm.txt +208 -0
- package/src/pagination/tokens.txt +33 -0
- package/src/popover/llm.txt +233 -0
- package/src/popover/tokens.txt +28 -0
- package/src/progress/llm.txt +279 -0
- package/src/progress/tokens.txt +83 -0
- package/src/radio/llm.txt +348 -0
- package/src/radio/tokens.txt +21 -0
- package/src/rate/llm.txt +241 -0
- package/src/rate/tokens.txt +20 -0
- package/src/select/llm.txt +830 -0
- package/src/select/tokens.txt +160 -0
- package/src/skeleton/llm.txt +275 -0
- package/src/skeleton/tokens.txt +15 -0
- package/src/spin/llm.txt +294 -0
- package/src/spin/tokens.txt +21 -0
- package/src/steps/llm.txt +300 -0
- package/src/steps/tokens.txt +30 -0
- package/src/switch/llm.txt +216 -0
- package/src/switch/tokens.txt +38 -0
- package/src/table/llm.txt +1046 -0
- package/src/table/tokens.txt +94 -0
- package/src/tabs/llm.txt +306 -0
- package/src/tabs/tokens.txt +78 -0
- package/src/tag/llm.txt +305 -0
- package/src/tag/tokens.txt +76 -0
- package/src/tooltip/llm.txt +304 -0
- package/src/tooltip/tokens.txt +22 -0
- package/src/tree/llm.txt +505 -0
- package/src/tree/tokens.txt +36 -0
- package/src/tree-select/llm.txt +762 -0
- package/src/tree-select/tokens.txt +174 -0
- package/src/typography/llm.txt +413 -0
- package/src/typography/tokens.txt +60 -0
- package/src/upload/llm.txt +706 -0
- package/src/upload/tokens.txt +201 -0
|
@@ -0,0 +1,830 @@
|
|
|
1
|
+
# Select
|
|
2
|
+
|
|
3
|
+
> Select:选项来自预设列表,需要从其中选择一个或多个值时。
|
|
4
|
+
|
|
5
|
+
包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
|
|
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`(32px)、`medium`(默认,28px)、`small`(24px)三种尺寸。
|
|
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" placeholder="large" options={options} />
|
|
404
|
+
<Select size="medium" placeholder="medium" options={options} />
|
|
405
|
+
<Select size="small" placeholder="small" 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` 不可打开下拉、不可改值,仅展示已选内容;与 `disabled` 正交,适合表单只读态。
|
|
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 defaultValue="a" options={options} />
|
|
446
|
+
<Select
|
|
447
|
+
mode="multiple"
|
|
448
|
+
readOnly
|
|
449
|
+
defaultValue={['a', 'b']}
|
|
450
|
+
options={options}
|
|
451
|
+
style={{ minWidth: 200 }}
|
|
452
|
+
/>
|
|
453
|
+
</div>
|
|
454
|
+
)
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
### 状态
|
|
458
|
+
|
|
459
|
+
通过 `status` 展示错误、完成和加载状态。
|
|
460
|
+
|
|
461
|
+
```tsx
|
|
462
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
463
|
+
|
|
464
|
+
const options = [
|
|
465
|
+
{ label: '选项 A', value: 'a' },
|
|
466
|
+
{ label: '选项 B', value: 'b' },
|
|
467
|
+
]
|
|
468
|
+
|
|
469
|
+
export default () => (
|
|
470
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 12, maxWidth: 280 }}>
|
|
471
|
+
<Select status="error" placeholder="错误状态" options={options} />
|
|
472
|
+
<Select status="completed" placeholder="完成状态" options={options} />
|
|
473
|
+
<Select status="loading" placeholder="加载状态" options={options} />
|
|
474
|
+
</div>
|
|
475
|
+
)
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
### 可清除
|
|
479
|
+
|
|
480
|
+
`allowClear` 展示清除按钮,清除后单选值变为 `undefined`,多选值变为空数组。
|
|
481
|
+
|
|
482
|
+
```tsx
|
|
483
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
484
|
+
|
|
485
|
+
import { useState } from 'react'
|
|
486
|
+
|
|
487
|
+
const options = [
|
|
488
|
+
{ label: '杭州', value: 'hangzhou' },
|
|
489
|
+
{ label: '上海', value: 'shanghai' },
|
|
490
|
+
{ label: '北京', value: 'beijing' },
|
|
491
|
+
]
|
|
492
|
+
|
|
493
|
+
export default () => {
|
|
494
|
+
const [value, setValue] = useState<string | number | undefined>('hangzhou')
|
|
495
|
+
|
|
496
|
+
return (
|
|
497
|
+
<Select
|
|
498
|
+
allowClear
|
|
499
|
+
value={value}
|
|
500
|
+
placeholder="请选择城市"
|
|
501
|
+
options={options}
|
|
502
|
+
onChange={(next) => setValue(typeof next === 'object' ? next?.value : next)}
|
|
503
|
+
onClear={() => setValue(undefined)}
|
|
504
|
+
/>
|
|
505
|
+
)
|
|
506
|
+
}
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
### 搜索
|
|
510
|
+
|
|
511
|
+
`showSearch` 开启搜索;可通过 `optionFilterProp` 指定过滤字段。
|
|
512
|
+
|
|
513
|
+
```tsx
|
|
514
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
515
|
+
|
|
516
|
+
const options = [
|
|
517
|
+
{ label: 'TypeScript', value: 'ts' },
|
|
518
|
+
{ label: 'JavaScript', value: 'js' },
|
|
519
|
+
{ label: 'Python', value: 'py' },
|
|
520
|
+
{ label: 'Rust', value: 'rust' },
|
|
521
|
+
]
|
|
522
|
+
|
|
523
|
+
export default () => (
|
|
524
|
+
<Select showSearch allowClear optionFilterProp="label" placeholder="搜索语言" options={options} />
|
|
525
|
+
)
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
### 虚拟滚动
|
|
529
|
+
|
|
530
|
+
大量 `options` 时默认启用 `virtual`,使用上下 spacer 与动态测高,仅渲染可视窗口内的选项;可通过 `listHeight` 调整列表高度,`listItemHeight` 仅作为首次布局预估,自定义选项的真实高度会自动校正。
|
|
531
|
+
|
|
532
|
+
```tsx
|
|
533
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
534
|
+
|
|
535
|
+
const options = Array.from({ length: 10_000 }, (_, index) => ({
|
|
536
|
+
label: `选项 ${index + 1}`,
|
|
537
|
+
value: String(index + 1),
|
|
538
|
+
}))
|
|
539
|
+
|
|
540
|
+
export default () => (
|
|
541
|
+
<Select
|
|
542
|
+
placeholder="打开下拉浏览大量选项"
|
|
543
|
+
options={options}
|
|
544
|
+
showSearch
|
|
545
|
+
virtual
|
|
546
|
+
listHeight={256}
|
|
547
|
+
listItemHeight={32}
|
|
548
|
+
style={{ width: 240 }}
|
|
549
|
+
/>
|
|
550
|
+
)
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
### 多选
|
|
554
|
+
|
|
555
|
+
`mode="multiple"` 支持选择多个值,`maxCount` 可限制最多可选数量。
|
|
556
|
+
|
|
557
|
+
```tsx
|
|
558
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
559
|
+
|
|
560
|
+
import { useState } from 'react'
|
|
561
|
+
|
|
562
|
+
const options = [
|
|
563
|
+
{ label: 'Apple', value: 'apple' },
|
|
564
|
+
{ label: 'Banana', value: 'banana' },
|
|
565
|
+
{ label: 'Cherry', value: 'cherry' },
|
|
566
|
+
{ label: 'Durian', value: 'durian' },
|
|
567
|
+
]
|
|
568
|
+
|
|
569
|
+
export default () => {
|
|
570
|
+
const [value, setValue] = useState<string[]>(['apple'])
|
|
571
|
+
|
|
572
|
+
return (
|
|
573
|
+
<Select
|
|
574
|
+
style={{ width: '330px' }}
|
|
575
|
+
mode="multiple"
|
|
576
|
+
allowClear
|
|
577
|
+
maxTagCount={3}
|
|
578
|
+
value={value}
|
|
579
|
+
placeholder="请选择水果"
|
|
580
|
+
options={options}
|
|
581
|
+
onChange={(next) => setValue(next as string[])}
|
|
582
|
+
/>
|
|
583
|
+
)
|
|
584
|
+
}
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
### 标签模式
|
|
588
|
+
|
|
589
|
+
`mode="tags"` 支持从输入内容创建新标签。
|
|
590
|
+
|
|
591
|
+
```tsx
|
|
592
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
593
|
+
|
|
594
|
+
import { useState } from 'react'
|
|
595
|
+
|
|
596
|
+
const options = [
|
|
597
|
+
{ label: 'Design', value: 'design' },
|
|
598
|
+
{ label: 'React', value: 'react' },
|
|
599
|
+
{ label: 'Docs', value: 'docs' },
|
|
600
|
+
]
|
|
601
|
+
|
|
602
|
+
export default () => {
|
|
603
|
+
const [value, setValue] = useState<string[]>(['react'])
|
|
604
|
+
|
|
605
|
+
return (
|
|
606
|
+
<Select
|
|
607
|
+
style={{ width: '250px' }}
|
|
608
|
+
mode="tags"
|
|
609
|
+
value={value}
|
|
610
|
+
placeholder="输入后按 Enter 创建标签"
|
|
611
|
+
options={options}
|
|
612
|
+
onChange={(next) => setValue(next as string[])}
|
|
613
|
+
/>
|
|
614
|
+
)
|
|
615
|
+
}
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
### 分组选项与字段映射
|
|
619
|
+
|
|
620
|
+
通过嵌套 `options` 表达分组,也可以用 `fieldNames` 适配后端字段。
|
|
621
|
+
|
|
622
|
+
```tsx
|
|
623
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
624
|
+
|
|
625
|
+
const options = [
|
|
626
|
+
{
|
|
627
|
+
name: '前端',
|
|
628
|
+
children: [
|
|
629
|
+
{ name: 'React', id: 'react' },
|
|
630
|
+
{ name: 'Vue', id: 'vue' },
|
|
631
|
+
],
|
|
632
|
+
},
|
|
633
|
+
{
|
|
634
|
+
name: '后端',
|
|
635
|
+
children: [
|
|
636
|
+
{ name: 'Node.js', id: 'node' },
|
|
637
|
+
{ name: 'Python', id: 'python' },
|
|
638
|
+
],
|
|
639
|
+
},
|
|
640
|
+
]
|
|
641
|
+
|
|
642
|
+
export default () => (
|
|
643
|
+
<Select
|
|
644
|
+
placeholder="请选择技术栈"
|
|
645
|
+
options={options}
|
|
646
|
+
fieldNames={{ label: 'name', value: 'id', options: 'children', groupLabel: 'name' }}
|
|
647
|
+
/>
|
|
648
|
+
)
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
### 自定义渲染
|
|
652
|
+
|
|
653
|
+
通过 `optionRender`、`labelRender` 和 `tagRender` 定制下拉项、已选展示和标签。
|
|
654
|
+
|
|
655
|
+
```tsx
|
|
656
|
+
import type { SelectTagRenderProps } from '@apexhub/apex-ui-react'
|
|
657
|
+
|
|
658
|
+
import { Button, Select } from '@apexhub/apex-ui-react'
|
|
659
|
+
|
|
660
|
+
const options = [
|
|
661
|
+
{ label: 'React', value: 'react', description: 'UI library' },
|
|
662
|
+
{ label: 'TypeScript', value: 'ts', description: 'Typed JavaScript' },
|
|
663
|
+
{ label: 'Vite', value: 'vite', description: 'Build tool' },
|
|
664
|
+
]
|
|
665
|
+
|
|
666
|
+
const tagRender = ({ label, onClose, closable }: SelectTagRenderProps) => (
|
|
667
|
+
<span
|
|
668
|
+
style={{
|
|
669
|
+
display: 'inline-flex',
|
|
670
|
+
alignItems: 'center',
|
|
671
|
+
gap: 4,
|
|
672
|
+
paddingInline: 'var(--apex-spacing-8)',
|
|
673
|
+
border: 'var(--apex-border-1) solid var(--apex-stroke-neutral-quinary)',
|
|
674
|
+
borderRadius: '7px',
|
|
675
|
+
}}
|
|
676
|
+
>
|
|
677
|
+
{label}
|
|
678
|
+
{closable ? (
|
|
679
|
+
<Button
|
|
680
|
+
type="text"
|
|
681
|
+
size="small"
|
|
682
|
+
style={{
|
|
683
|
+
display: 'flex',
|
|
684
|
+
alignItems: 'center',
|
|
685
|
+
justifyContent: 'center',
|
|
686
|
+
width: 14,
|
|
687
|
+
height: 14,
|
|
688
|
+
opacity: 0.8,
|
|
689
|
+
lineHeight: 0,
|
|
690
|
+
padding: 0,
|
|
691
|
+
}}
|
|
692
|
+
onClick={onClose}
|
|
693
|
+
aria-label={`移除 ${String(label)}`}
|
|
694
|
+
>
|
|
695
|
+
×
|
|
696
|
+
</Button>
|
|
697
|
+
) : null}
|
|
698
|
+
</span>
|
|
699
|
+
)
|
|
700
|
+
|
|
701
|
+
export default () => (
|
|
702
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 12, maxWidth: 320 }}>
|
|
703
|
+
<Select
|
|
704
|
+
style={{ width: '250px' }}
|
|
705
|
+
defaultValue="react"
|
|
706
|
+
options={options}
|
|
707
|
+
labelRender={({ label, value }) => `${label ?? value} 已选`}
|
|
708
|
+
optionRender={(option) => (
|
|
709
|
+
<div style={{ display: 'flex', justifyContent: 'space-between', gap: 12, width: '100%' }}>
|
|
710
|
+
<span>{option.label}</span>
|
|
711
|
+
<span style={{ color: 'var(--apex-text-neutral-secondary)' }}>
|
|
712
|
+
{String(option.description ?? '')}
|
|
713
|
+
</span>
|
|
714
|
+
</div>
|
|
715
|
+
)}
|
|
716
|
+
/>
|
|
717
|
+
<Select
|
|
718
|
+
style={{ width: '250px' }}
|
|
719
|
+
mode="multiple"
|
|
720
|
+
defaultValue={['react']}
|
|
721
|
+
options={options}
|
|
722
|
+
tagRender={tagRender}
|
|
723
|
+
placeholder="自定义标签"
|
|
724
|
+
/>
|
|
725
|
+
</div>
|
|
726
|
+
)
|
|
727
|
+
```
|
|
728
|
+
|
|
729
|
+
### 受控展开
|
|
730
|
+
|
|
731
|
+
通过 `open` 与 展开变化事件 控制下拉展开状态。
|
|
732
|
+
|
|
733
|
+
```tsx
|
|
734
|
+
import { Button, Select } from '@apexhub/apex-ui-react'
|
|
735
|
+
|
|
736
|
+
import { useState } from 'react'
|
|
737
|
+
|
|
738
|
+
const options = [
|
|
739
|
+
{ label: '选项 A', value: 'a' },
|
|
740
|
+
{ label: '选项 B', value: 'b' },
|
|
741
|
+
]
|
|
742
|
+
|
|
743
|
+
export default () => {
|
|
744
|
+
const [open, setOpen] = useState(false)
|
|
745
|
+
|
|
746
|
+
return (
|
|
747
|
+
<div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
|
|
748
|
+
<Select open={open} onOpenChange={setOpen} placeholder="受控展开" options={options} />
|
|
749
|
+
<Button onClick={() => setOpen((current) => !current)}>
|
|
750
|
+
{open ? '关闭下拉' : '打开下拉'}
|
|
751
|
+
</Button>
|
|
752
|
+
</div>
|
|
753
|
+
)
|
|
754
|
+
}
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
### 自定义语义结构
|
|
758
|
+
|
|
759
|
+
通过 `classNames` 和 `styles` 定制各语义节点样式。
|
|
760
|
+
|
|
761
|
+
```tsx
|
|
762
|
+
import type { SelectProps } from '@apexhub/apex-ui-react'
|
|
763
|
+
|
|
764
|
+
import { Select } from '@apexhub/apex-ui-react'
|
|
765
|
+
|
|
766
|
+
const options = [
|
|
767
|
+
{ label: 'Alpha', value: 'alpha' },
|
|
768
|
+
{ label: 'Beta', value: 'beta' },
|
|
769
|
+
{ label: 'Gamma', value: 'gamma' },
|
|
770
|
+
]
|
|
771
|
+
|
|
772
|
+
const styles: SelectProps['styles'] = {
|
|
773
|
+
selector: {
|
|
774
|
+
minWidth: 220,
|
|
775
|
+
},
|
|
776
|
+
popup: {
|
|
777
|
+
minWidth: 220,
|
|
778
|
+
},
|
|
779
|
+
option: {
|
|
780
|
+
letterSpacing: 0.2,
|
|
781
|
+
},
|
|
782
|
+
}
|
|
783
|
+
|
|
784
|
+
export default () => (
|
|
785
|
+
<Select
|
|
786
|
+
defaultValue="alpha"
|
|
787
|
+
options={options}
|
|
788
|
+
classNames={{
|
|
789
|
+
root: 'custom-select-root',
|
|
790
|
+
selector: 'custom-select-selector',
|
|
791
|
+
option: 'custom-select-option',
|
|
792
|
+
}}
|
|
793
|
+
styles={styles}
|
|
794
|
+
/>
|
|
795
|
+
)
|
|
796
|
+
```
|
|
797
|
+
|
|
798
|
+
## DOM 结构
|
|
799
|
+
|
|
800
|
+
源码声明的静态 `data-slot`:`select-virtual-spacer`、`select-virtual-holder`、`select-option-check`、`select`、`selector`、`input-clear`、`popup`、`list`。具体节点随模式和状态出现,不表示固定嵌套顺序。
|
|
801
|
+
|
|
802
|
+
## 样式定制
|
|
803
|
+
|
|
804
|
+
优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../llms-theme.txt)。
|
|
805
|
+
|
|
806
|
+
需要定制具体样式时再读取 [Token 明细](./select.tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
|
|
807
|
+
|
|
808
|
+
## FAQ
|
|
809
|
+
|
|
810
|
+
### 为什么没有 `Select.Option` 子组件?
|
|
811
|
+
|
|
812
|
+
选项统一通过 `options` 配置,性能更好。
|
|
813
|
+
|
|
814
|
+
|
|
815
|
+
### 异步搜索怎么实现?
|
|
816
|
+
|
|
817
|
+
设置 `filterOption={false}`,在 `onSearch` 中请求数据并更新 `options`;需要受控搜索文本时配合 `searchValue`。
|
|
818
|
+
|
|
819
|
+
单选和多选都会保留已选项数据:更换关键词或清空 `options` 不会让已选名称退回 ID,多选 `onChange` 的选项参数也会保留已选项的业务字段。新结果包含同一 value 时,采用新结果的数据;取消选择或清空后释放对应缓存。缓存不会把旧选项追加到下拉搜索结果。
|
|
820
|
+
|
|
821
|
+
编辑回显时,可以先传入 `{ value, label }`(多选为数组),或先加载已选项到 `options`。只有 ID 且从未加载名称时仍显示 ID。`onChange` 的值参数仍为原始 ID(多选为 ID 数组)。请求、防抖、乱序保护和错误处理由业务负责;加载状态使用 `status="loading"`。
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
### `tags` 模式下如何创建新标签?
|
|
825
|
+
|
|
826
|
+
输入搜索文本后按 Enter;若无匹配项,将把当前输入创建为新标签。
|
|
827
|
+
|
|
828
|
+
### `readOnly` 和 `disabled` 有什么区别?
|
|
829
|
+
|
|
830
|
+
`disabled` 展示禁用态且不可交互;`readOnly` 仅展示已选值、不可打开下拉或改值,视觉更接近正常态,适合表单只读场景。二者可独立使用,一般不同时需要。
|