@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,772 @@
1
+ # TreeSelect
2
+
3
+ > TreeSelect:表单中需要从层级数据里选取一个或多个节点时(部门、分类、地区等)。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`TreeSelect`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { TreeSelect } from '@apexhub/apex-ui-react'
15
+
16
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
17
+
18
+ import '@apexhub/apex-ui-react/style.css'
19
+
20
+ const TREE_SELECT_DATA: TreeSelectDataNode[] = [
21
+ {
22
+ value: '0-0',
23
+ title: '父节点 0',
24
+ children: [
25
+ { value: '0-0-0', title: '叶子 0-0' },
26
+ { value: '0-0-1', title: '叶子 0-0-1' },
27
+ ],
28
+ },
29
+ {
30
+ value: '0-1',
31
+ title: '父节点 1',
32
+ children: [{ value: '0-1-0', title: '叶子 0-1-0' }],
33
+ },
34
+ ]
35
+
36
+ export default () => (
37
+ <TreeSelect treeData={TREE_SELECT_DATA} treeDefaultExpandAll placeholder="请选择" />
38
+ )
39
+ ```
40
+
41
+ ## 何时使用
42
+
43
+ - 表单中需要从层级数据里选取一个或多个节点时(部门、分类、地区等)。
44
+ - 勾选多节点并回填标签时,配合 `treeCheckable` 与 `showCheckedStrategy` 使用。
45
+ - 若仅需展示或操作树形数据而非选取值,请使用 Tree 组件。
46
+
47
+ ## API
48
+
49
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
50
+
51
+ ### TreeSelect
52
+
53
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
54
+ | --- | --- | --- | --- | --- |
55
+ | treeData | 树形数据(推荐) | `TreeSelectDataNode[]` | 否 | — |
56
+ | treeDataSimpleMode | 扁平树数据模式 | `boolean \| TreeDataSimpleMode` | 否 | `false` |
57
+ | fieldNames | — | `TreeSelectFieldNames` | 否 | — |
58
+ | value | 当前值(受控) | `TreeSelectValue` | 否 | — |
59
+ | defaultValue | 初始值(非受控) | `TreeSelectValue` | 否 | — |
60
+ | placeholder | — | `string` | 否 | — |
61
+ | disabled | — | `boolean` | 否 | `false` |
62
+ | readOnly | 只读:不可打开下拉、不可改值,无 hover 交互态,仅展示。与 `disabled` 正交。 | `boolean` | 否 | `false` |
63
+ | allowClear | — | `boolean \| TreeSelectAllowClear` | 否 | `false` |
64
+ | multiple | 是否多选;`treeCheckable` 时通常为 true | `boolean` | 否 | `false` |
65
+ | treeCheckable | 下拉树是否显示 Checkbox | `boolean` | 否 | `false` |
66
+ | treeCheckStrictly | 父子勾选不关联;为 true 时等价于启用 `labelInValue` 语义 | `boolean` | 否 | `false` |
67
+ | labelInValue | 值是否携带 label 对象 | `boolean` | 否 | `false` |
68
+ | showCheckedStrategy | 多选勾选时输入框内展示策略 | `"SHOW_ALL" \| "SHOW_PARENT" \| "SHOW_CHILD"` | 否 | `TreeSelect.SHOW_CHILD` |
69
+ | showSearch | 是否可搜索;默认单选 false、多选 true(实现层默认,可被显式 prop 覆盖) | `boolean \| TreeSelectSearchConfig` | 否 | — |
70
+ | open | 受控下拉展开 | `boolean` | 否 | — |
71
+ | closeOnScroll | 外部滚动祖先滚动时关闭;内部列表滚动不关闭。触发器完全不可见时始终请求关闭。 | `boolean` | 否 | `false` |
72
+ | defaultOpen | 初始是否展开下拉 | `boolean` | 否 | — |
73
+ | placement | — | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight"` | 否 | `'bottomLeft'` |
74
+ | size | — | `"small" \| "medium" \| "large"` | 否 | `'medium'` |
75
+ | variant | 输入框表面变体,与 Input 一致。 | `"default" \| "elevated"` | 否 | `'default'` |
76
+ | status | — | `"error" \| "warning"` | 否 | — |
77
+ | prefix | — | `React.ReactNode` | 否 | — |
78
+ | suffixIcon | — | `React.ReactNode` | 否 | — |
79
+ | listHeight | 下拉面板内树的可视高度(px) | `number` | 否 | `256` |
80
+ | virtual | 是否启用下拉树虚拟滚动;`popupMatchSelectWidth={false}` 时自动关闭。 | `boolean` | 否 | `true` |
81
+ | popupMatchSelectWidth | 弹层宽度:`true` 时至少与选择框同宽,可随树内容变宽;`false` 同宽策略并关闭虚拟滚动;<br>传入 `number` 时固定为该像素宽度。 | `boolean \| number` | 否 | `true` |
82
+ | popupRender | — | `(originNode: React.ReactNode, info: { props: TreeSelectProps }) => React.ReactNode` | 否 | — |
83
+ | loadData | 异步加载子节点;搜索过滤时不调用 | `(node: TreeSelectDataNode) => void` | 否 | — |
84
+ | treeLoadedKeys | — | `TreeSelectNodeValue[]` | 否 | `[]` |
85
+ | treeDefaultExpandAll | — | `boolean` | 否 | `false` |
86
+ | treeDefaultExpandedKeys | — | `TreeSelectNodeValue[]` | 否 | — |
87
+ | treeExpandedKeys | — | `TreeSelectNodeValue[]` | 否 | — |
88
+ | treeExpandAction | — | `TreeSelectExpandAction` | 否 | `false` |
89
+ | treeIcon | — | `boolean` | 否 | `false` |
90
+ | treeLine | 是否显示层级连接线(视觉依赖 Tree 连线 token,首期可能仅透传) | `boolean` | 否 | `false` |
91
+ | switcherIcon | — | `React.ReactNode \| ((props: TreeSelectSwitcherIconProps) => React.ReactNode)` | 否 | — |
92
+ | treeNodeLabelProp | 选中后在输入框展示的节点字段 | `string` | 否 | `'title'` |
93
+ | treeTitleRender | — | `(node: TreeSelectDataNode) => React.ReactNode` | 否 | — |
94
+ | tagRender | — | `(props: TreeSelectTagRenderProps) => React.ReactNode` | 否 | — |
95
+ | maxTagCount | 多选时输入框内最多展示的 tag 数量(可见 tag 数,不含 +N)。 | `MaxTagCount` | 否 | `undefined(展示全部)` |
96
+ | maxCount | 最多可选数量(`treeCheckable` + 多选) | `number` | 否 | — |
97
+ | maxTagPlaceholder | — | `React.ReactNode \| ((omittedValues: TreeSelectLabeledValue[]) => React.ReactNode)` | 否 | — |
98
+ | maxTagPopover | 溢出 tag(+M)的 Popover 行为;默认开启并预览全部已选项(hover + top) | `boolean \| MaxTagPopoverConfig<TreeSelectNodeValue>` | 否 | — |
99
+ | notFoundContent | — | `React.ReactNode` | 否 | `'Not Found'` |
100
+ | className | — | `string` | 否 | — |
101
+ | styles | 为各语义子结构自定义内联样式(仅允许 CSS Token 等变量赋值,禁止业务硬编码色值) | `Partial<Record<TreeSelectSemanticDOM, React.CSSProperties>> \| ((info: { props: Readonly<TreeSelectProps> }) => Partial<Record<TreeSelectSemanticDOM, React.CSSProperties>>)` | 否 | — |
102
+ | onChange | — | `( value: TreeSelectValue, label: React.ReactNode \| React.ReactNode[], extra: TreeSelectChangeExtra, ) => void` | 否 | — |
103
+ | onSelect | — | `( value: TreeSelectNodeValue, node: TreeSelectDataNode, extra: TreeSelectChangeExtra, ) => void` | 否 | — |
104
+ | onOpenChange | — | `(open: boolean) => void` | 否 | — |
105
+ | onTreeExpand | — | `(expandedKeys: TreeSelectNodeValue[]) => void` | 否 | — |
106
+ | onPopupScroll | — | `React.UIEventHandler<HTMLDivElement>` | 否 | — |
107
+ | ref | 实例方法 ref:`focus` / `blur` / `nativeElement` | `React.Ref<TreeSelectRef>` | 否 | — |
108
+
109
+ ### TreeSelectNodeValue
110
+
111
+ 节点 `value` 字段类型(要求全树唯一)
112
+
113
+ ```typescript
114
+ type TreeSelectNodeValue = string
115
+ ```
116
+
117
+ ### TreeSelectCheckedStrategy
118
+
119
+ 勾选展示策略(挂到 `TreeSelect.SHOW_*`)
120
+
121
+ ```typescript
122
+ type TreeSelectCheckedStrategy = 'SHOW_ALL' | 'SHOW_PARENT' | 'SHOW_CHILD'
123
+ ```
124
+
125
+ ### TreeSelectPlacement
126
+
127
+ 弹出位置
128
+
129
+ ```typescript
130
+ type TreeSelectPlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight'
131
+ ```
132
+
133
+ ### TreeSelectSize
134
+
135
+ 触发器尺寸
136
+
137
+ ```typescript
138
+ type TreeSelectSize = 'small' | 'medium' | 'large'
139
+ ```
140
+
141
+ ### TreeSelectSemanticDOM
142
+
143
+ 子结构语义,用于 `styles` 分段定制
144
+
145
+ ```typescript
146
+ type TreeSelectSemanticDOM = 'popup'
147
+ ```
148
+
149
+ ### TreeSelectStatus
150
+
151
+ 校验态
152
+
153
+ ```typescript
154
+ type TreeSelectStatus = 'error' | 'warning'
155
+ ```
156
+
157
+ ### TreeSelectExpandAction
158
+
159
+ 点击标题时的展开行为
160
+
161
+ ```typescript
162
+ type TreeSelectExpandAction = false | 'click' | 'doubleClick'
163
+ ```
164
+
165
+ ### TreeSelectLabeledValue
166
+
167
+ `labelInValue` 为 true 时的值结构
168
+
169
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
170
+ | --- | --- | --- | --- | --- |
171
+ | value | — | `TreeSelectNodeValue` | 是 | — |
172
+ | label | — | `React.ReactNode` | 是 | — |
173
+ | halfChecked | 半选父节点(`treeCheckStrictly` 场景) | `boolean` | 否 | — |
174
+
175
+ ### TreeSelectValue
176
+
177
+ 受控/非受控值:单选或多选;是否带 label 由 `labelInValue` / `treeCheckStrictly` 决定
178
+
179
+ ```typescript
180
+ type TreeSelectValue = | TreeSelectNodeValue
181
+ | TreeSelectNodeValue[]
182
+ | TreeSelectLabeledValue
183
+ | TreeSelectLabeledValue[]
184
+ ```
185
+
186
+ ### TreeSelectFieldNames
187
+
188
+ `treeData` 字段映射
189
+
190
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
191
+ | --- | --- | --- | --- | --- |
192
+ | label | — | `string` | 否 | — |
193
+ | value | — | `string` | 否 | — |
194
+ | children | — | `string` | 否 | — |
195
+
196
+ ### TreeDataSimpleMode
197
+
198
+ `treeDataSimpleMode` 为对象时的 id / pId 配置
199
+
200
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
201
+ | --- | --- | --- | --- | --- |
202
+ | id | — | `string` | 否 | — |
203
+ | pId | — | `string` | 否 | — |
204
+ | rootPId | — | `TreeSelectNodeValue` | 否 | — |
205
+
206
+ ### TreeSelectDataNode
207
+
208
+ 树节点数据(推荐 `treeData`;)
209
+
210
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
211
+ | --- | --- | --- | --- | --- |
212
+ | value | 节点值,全树唯一 | `TreeSelectNodeValue` | 是 | — |
213
+ | title | 展示标题(默认字段名;可用 `fieldNames.label` 指向 `title`) | `React.ReactNode` | 否 | — |
214
+ | children | 子节点 | `TreeSelectDataNode[]` | 否 | — |
215
+ | disabled | — | `boolean` | 否 | — |
216
+ | disableCheckbox | — | `boolean` | 否 | — |
217
+ | selectable | — | `boolean` | 否 | — |
218
+ | checkable | — | `boolean` | 否 | — |
219
+ | isLeaf | — | `boolean` | 否 | — |
220
+
221
+ ### TreeSelectSwitcherIconProps
222
+
223
+ `switcherIcon` 渲染上下文
224
+
225
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
226
+ | --- | --- | --- | --- | --- |
227
+ | expanded | — | `boolean` | 是 | — |
228
+ | isLeaf | — | `boolean` | 是 | — |
229
+ | loading | — | `boolean` | 否 | — |
230
+ | data | — | `TreeSelectDataNode` | 是 | — |
231
+
232
+ ### TreeSelectAllowClear
233
+
234
+ `allowClear` 对象配置
235
+
236
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
237
+ | --- | --- | --- | --- | --- |
238
+ | clearIcon | — | `React.ReactNode` | 否 | — |
239
+
240
+ ### TreeSelectSearchConfig
241
+
242
+ `showSearch` 为对象时的配置
243
+
244
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
245
+ | --- | --- | --- | --- | --- |
246
+ | autoClearSearchValue | 多选勾选后是否清空搜索框 | `boolean` | 否 | `true` |
247
+ | filterTreeNode | 是否根据输入过滤树节点 | `boolean \| ((inputValue: string, treeNode: TreeSelectDataNode) => boolean)` | 否 | — |
248
+ | treeNodeFilterProp | 默认用于过滤的节点字段 | `string` | 否 | `'value'` |
249
+ | searchValue | 受控搜索文本 | `string` | 否 | — |
250
+ | onSearch | 搜索文本变化 | `(search: string) => void` | 否 | — |
251
+
252
+ ### TreeSelectTagRenderProps
253
+
254
+ `tagRender` 入参;默认实现使用 Apex `Tag`
255
+
256
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
257
+ | --- | --- | --- | --- | --- |
258
+ | label | — | `React.ReactNode` | 是 | — |
259
+ | value | — | `TreeSelectNodeValue` | 是 | — |
260
+ | disabled | — | `boolean` | 否 | — |
261
+ | closable | — | `boolean` | 否 | — |
262
+ | onClose | — | `(event?: React.MouseEvent<HTMLElement>) => void` | 否 | — |
263
+
264
+ ### TreeSelectChangeExtra
265
+
266
+ `onChange` / `onSelect` 的 extra 信息
267
+
268
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
269
+ | --- | --- | --- | --- | --- |
270
+ | triggerValue | 触发来源等,apply 阶段与 rc 对齐后细化 | `TreeSelectNodeValue` | 否 | — |
271
+ | selected | — | `boolean` | 否 | — |
272
+ | preValue | — | `TreeSelectLabeledValue[]` | 否 | — |
273
+ | allCheckedNodes | — | `TreeSelectDataNode[]` | 否 | — |
274
+
275
+ ### TreeSelectRef
276
+
277
+ TreeSelect 实例方法(通过 `ref` 获取)
278
+
279
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
280
+ | --- | --- | --- | --- | --- |
281
+ | nativeElement | 触发器 DOM(`role="combobox"`) | `HTMLDivElement \| null` | 是 | — |
282
+ | focus | 聚焦选择框(有搜索时聚焦输入框) | `() => void` | 是 | — |
283
+ | blur | 移除焦点 | `() => void` | 是 | — |
284
+
285
+ ### TreeSelectTreeNodeProps
286
+
287
+ 不推荐手写;请用 `treeData`。。
288
+
289
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
290
+ | --- | --- | --- | --- | --- |
291
+ | value | — | `TreeSelectNodeValue` | 否 | — |
292
+ | title | — | `React.ReactNode` | 否 | — |
293
+ | key | — | `string` | 否 | — |
294
+ | disabled | — | `boolean` | 否 | — |
295
+ | disableCheckbox | — | `boolean` | 否 | — |
296
+ | selectable | — | `boolean` | 否 | — |
297
+ | checkable | — | `boolean` | 否 | — |
298
+ | isLeaf | — | `boolean` | 否 | — |
299
+ | children | — | `React.ReactNode` | 否 | — |
300
+
301
+ ### TreeSelectStaticProps
302
+
303
+ 挂到 `TreeSelect` 函数对象的静态常量
304
+
305
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
306
+ | --- | --- | --- | --- | --- |
307
+ | SHOW_ALL | — | `"SHOW_ALL" \| "SHOW_PARENT" \| "SHOW_CHILD"` | 是 | — |
308
+ | SHOW_PARENT | — | `"SHOW_ALL" \| "SHOW_PARENT" \| "SHOW_CHILD"` | 是 | — |
309
+ | SHOW_CHILD | — | `"SHOW_ALL" \| "SHOW_PARENT" \| "SHOW_CHILD"` | 是 | — |
310
+
311
+ ### MaxTagCount
312
+
313
+ 展示层最多渲染的 tag 数量;超出部分合并为溢出 tag
314
+
315
+ ```typescript
316
+ type MaxTagCount = number | 'responsive'
317
+ ```
318
+
319
+ ### MaxTagPopoverConfig
320
+
321
+ 泛型参数:`<TValue = string | number>`。
322
+
323
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
324
+ | --- | --- | --- | --- | --- |
325
+ | trigger | — | `"click" \| "hover"` | 否 | `'hover'` |
326
+ | placement | — | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight" \| "top" \| "left" \| "right" \| "bottom" \| "leftTop" \| "leftBottom" \| "rightTop" \| "rightBottom"` | 否 | `'top'` |
327
+ | overlaySelector | 是否覆盖在选择器上展开;设为 false 时使用普通 Popover 定位。@default true | `boolean` | 否 | — |
328
+ | disabled | 禁用 Popover,仅展示 +N | `boolean` | 否 | — |
329
+ | contentRender | 自定义完整已选项预览内容 | `(values: LabeledValue<TValue>[]) => React.ReactNode` | 否 | — |
330
+
331
+ ### LabeledValue
332
+
333
+ 泛型参数:`<TValue = string | number>`。
334
+
335
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
336
+ | --- | --- | --- | --- | --- |
337
+ | value | — | `TValue` | 是 | — |
338
+ | label | — | `React.ReactNode` | 是 | — |
339
+
340
+ 其他组件的类型不在此展开:`InputVariant` 见 `../input/llm.txt`、`PopoverPlacement` 见 `../popover/llm.txt`。
341
+
342
+ ### 导出类型
343
+
344
+ 另可从 `@apexhub/apex-ui-react` 导入:`TreeDataSimpleMode`、`TreeSelectAllowClear`、`TreeSelectChangeExtra`、`TreeSelectCheckedStrategy`、`TreeSelectDataNode`、`TreeSelectExpandAction`、`TreeSelectFieldNames`、`TreeSelectLabeledValue`、`TreeSelectNodeValue`、`TreeSelectPlacement`、`TreeSelectProps`、`TreeSelectRef`、`TreeSelectSearchConfig`、`TreeSelectSize`、`TreeSelectStaticProps`、`TreeSelectStatus`、`TreeSelectSwitcherIconProps`、`TreeSelectTagRenderProps`、`TreeSelectTreeNodeProps`、`TreeSelectValue`(与上文子类型配合使用)。
345
+
346
+ ## 代码演示
347
+
348
+ ### 受控用法
349
+
350
+ 传入 `value` 与 变更事件 由外部控制选中值。
351
+
352
+ ```tsx
353
+ import { TreeSelect } from '@apexhub/apex-ui-react'
354
+
355
+ import { useState } from 'react'
356
+
357
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
358
+
359
+ const TREE_SELECT_DATA: TreeSelectDataNode[] = [
360
+ {
361
+ value: '0-0',
362
+ title: '父节点 0',
363
+ children: [
364
+ { value: '0-0-0', title: '叶子 0-0' },
365
+ { value: '0-0-1', title: '叶子 0-0-1' },
366
+ ],
367
+ },
368
+ {
369
+ value: '0-1',
370
+ title: '父节点 1',
371
+ children: [{ value: '0-1-0', title: '叶子 0-1-0' }],
372
+ },
373
+ ]
374
+
375
+ export default () => {
376
+ const [value, setValue] = useState<string | undefined>('0-0-0')
377
+
378
+ return (
379
+ <TreeSelect
380
+ treeData={TREE_SELECT_DATA}
381
+ value={value}
382
+ onChange={(v) => setValue(v as string)}
383
+ treeDefaultExpandAll
384
+ placeholder="受控"
385
+ />
386
+ )
387
+ }
388
+ ```
389
+
390
+ ### 多选
391
+
392
+ 设置 `multiple` 开启多选,选中项以标签形式展示在输入框内。
393
+
394
+ ```tsx
395
+ import { TreeSelect } from '@apexhub/apex-ui-react'
396
+
397
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
398
+
399
+ const TREE_SELECT_DATA: TreeSelectDataNode[] = [
400
+ {
401
+ value: '0-0',
402
+ title: '父节点 0',
403
+ children: [
404
+ { value: '0-0-0', title: '叶子 0-0' },
405
+ { value: '0-0-1', title: '叶子 0-0-1' },
406
+ ],
407
+ },
408
+ {
409
+ value: '0-1',
410
+ title: '父节点 1',
411
+ children: [{ value: '0-1-0', title: '叶子 0-1-0' }],
412
+ },
413
+ ]
414
+
415
+ export default () => (
416
+ <TreeSelect
417
+ style={{ width: '100%' }}
418
+ multiple
419
+ maxTagCount={3}
420
+ treeData={TREE_SELECT_DATA}
421
+ treeDefaultExpandAll
422
+ defaultValue={['0-0-0']}
423
+ placeholder="多选"
424
+ />
425
+ )
426
+ ```
427
+
428
+ ### 勾选
429
+
430
+ `treeCheckable` 与 `multiple` 配合,通过复选框选择多个节点。示例预选一个子节点,可观察父节点半选;悬停一行时,行背景与该行复选框共同显示悬停态。点击父节点只勾选可用子节点,禁用子节点保持未选。
431
+
432
+ ```tsx
433
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
434
+
435
+ import { TreeSelect } from '@apexhub/apex-ui-react'
436
+
437
+ const treeData: TreeSelectDataNode[] = [
438
+ {
439
+ value: 'team',
440
+ title: '项目组',
441
+ children: [
442
+ { value: 'design', title: '设计' },
443
+ { value: 'engineering', title: '研发' },
444
+ { value: 'archived', title: '已归档', disabled: true },
445
+ ],
446
+ },
447
+ ]
448
+
449
+ export default () => (
450
+ <TreeSelect
451
+ style={{ width: '250px' }}
452
+ treeCheckable
453
+ multiple
454
+ treeData={treeData}
455
+ treeDefaultExpandAll
456
+ defaultValue={['design']}
457
+ placeholder="选择团队"
458
+ />
459
+ )
460
+ ```
461
+
462
+ ### 搜索
463
+
464
+ 通过 `showSearch` 在下拉面板内过滤树节点。
465
+
466
+ ```tsx
467
+ import { TreeSelect } from '@apexhub/apex-ui-react'
468
+
469
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
470
+
471
+ const TREE_SELECT_DATA: TreeSelectDataNode[] = [
472
+ {
473
+ value: '0-0',
474
+ title: '父节点 0',
475
+ children: [
476
+ { value: '0-0-0', title: '叶子 0-0' },
477
+ { value: '0-0-1', title: '叶子 0-0-1' },
478
+ ],
479
+ },
480
+ {
481
+ value: '0-1',
482
+ title: '父节点 1',
483
+ children: [{ value: '0-1-0', title: '叶子 0-1-0' }],
484
+ },
485
+ ]
486
+
487
+ export default () => (
488
+ <TreeSelect showSearch treeData={TREE_SELECT_DATA} treeDefaultExpandAll placeholder="可搜索" />
489
+ )
490
+ ```
491
+
492
+ ### 尺寸
493
+
494
+ 支持 `large`、`medium`(默认)、`small` 三种触发器尺寸;弹层选项高度随尺寸档位对齐。示例选中值并开启清除,以便对照 large/medium 的 16px 箭头、small 的 14px 箭头与各档 14px 清除按钮。
495
+
496
+ ```tsx
497
+ import { TreeSelect } from '@apexhub/apex-ui-react'
498
+
499
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
500
+
501
+ const TREE_SELECT_DATA: TreeSelectDataNode[] = [
502
+ {
503
+ value: '0-0',
504
+ title: '父节点 0',
505
+ children: [
506
+ { value: '0-0-0', title: '叶子 0-0' },
507
+ { value: '0-0-1', title: '叶子 0-0-1' },
508
+ ],
509
+ },
510
+ {
511
+ value: '0-1',
512
+ title: '父节点 1',
513
+ children: [{ value: '0-1-0', title: '叶子 0-1-0' }],
514
+ },
515
+ ]
516
+
517
+ export default () => (
518
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
519
+ <TreeSelect
520
+ size="large"
521
+ treeData={TREE_SELECT_DATA}
522
+ defaultValue="0-0-0"
523
+ allowClear
524
+ treeDefaultExpandAll
525
+ />
526
+ <TreeSelect
527
+ size="medium"
528
+ treeData={TREE_SELECT_DATA}
529
+ defaultValue="0-0-0"
530
+ allowClear
531
+ treeDefaultExpandAll
532
+ />
533
+ <TreeSelect
534
+ size="small"
535
+ treeData={TREE_SELECT_DATA}
536
+ defaultValue="0-0-0"
537
+ allowClear
538
+ treeDefaultExpandAll
539
+ />
540
+ </div>
541
+ )
542
+ ```
543
+
544
+ ### 禁用状态
545
+
546
+ `disabled` 时禁止展开下拉与选择操作。
547
+
548
+ ```tsx
549
+ import { TreeSelect } from '@apexhub/apex-ui-react'
550
+
551
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
552
+
553
+ const TREE_SELECT_DATA: TreeSelectDataNode[] = [
554
+ {
555
+ value: '0-0',
556
+ title: '父节点 0',
557
+ children: [
558
+ { value: '0-0-0', title: '叶子 0-0' },
559
+ { value: '0-0-1', title: '叶子 0-0-1' },
560
+ ],
561
+ },
562
+ {
563
+ value: '0-1',
564
+ title: '父节点 1',
565
+ children: [{ value: '0-1-0', title: '叶子 0-1-0' }],
566
+ },
567
+ ]
568
+
569
+ export default () => (
570
+ <TreeSelect treeData={TREE_SELECT_DATA} disabled treeDefaultExpandAll placeholder="禁用" />
571
+ )
572
+ ```
573
+
574
+ ### 只读
575
+
576
+ `readOnly` 为 true 时不可打开下拉、不可清除或修改;视觉使用禁用配色,但仍可聚焦。示例对照空值、单选和多选。
577
+
578
+ ```tsx
579
+ import { TreeSelect } from '@apexhub/apex-ui-react'
580
+
581
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
582
+
583
+ const TREE_SELECT_DATA: TreeSelectDataNode[] = [
584
+ {
585
+ value: '0-0',
586
+ title: '父节点 0',
587
+ children: [
588
+ { value: '0-0-0', title: '叶子 0-0' },
589
+ { value: '0-0-1', title: '叶子 0-0-1' },
590
+ ],
591
+ },
592
+ {
593
+ value: '0-1',
594
+ title: '父节点 1',
595
+ children: [{ value: '0-1-0', title: '叶子 0-1-0' }],
596
+ },
597
+ ]
598
+
599
+ export default () => (
600
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 320 }}>
601
+ <TreeSelect treeData={TREE_SELECT_DATA} defaultValue="0-0-0" placeholder="可编辑" allowClear />
602
+ <TreeSelect treeData={TREE_SELECT_DATA} readOnly placeholder="只读空值" />
603
+ <TreeSelect treeData={TREE_SELECT_DATA} defaultValue="0-0-0" readOnly placeholder="只读" />
604
+ <TreeSelect
605
+ treeData={TREE_SELECT_DATA}
606
+ multiple
607
+ defaultValue={['0-0-0', '0-0-1']}
608
+ readOnly
609
+ placeholder="只读多选"
610
+ />
611
+ </div>
612
+ )
613
+ ```
614
+
615
+ ### 标签折叠(maxTagCount)
616
+
617
+ 多选场景下可用 `maxTagCount` 限制输入框内可见 tag 数,超出部分合并为 `+N`;`maxTagCount="responsive"` 按容器宽度自适应。
618
+
619
+ ```tsx
620
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
621
+
622
+ import { TreeSelect } from '@apexhub/apex-ui-react'
623
+
624
+ const treeData: TreeSelectDataNode[] = [
625
+ {
626
+ value: 'asia',
627
+ title: 'Asia',
628
+ children: [
629
+ { value: 'cn', title: 'China' },
630
+ { value: 'jp', title: 'Japan' },
631
+ { value: 'kr', title: 'Korea' },
632
+ { value: 'in', title: 'India' },
633
+ ],
634
+ },
635
+ {
636
+ value: 'eu',
637
+ title: 'Europe',
638
+ children: [
639
+ { value: 'de', title: 'Germany' },
640
+ { value: 'fr', title: 'France' },
641
+ ],
642
+ },
643
+ ]
644
+
645
+ export default () => (
646
+ <div style={{ width: 360, padding: 24 }}>
647
+ <TreeSelect
648
+ style={{ width: '100%' }}
649
+ treeData={treeData}
650
+ treeDefaultExpandAll
651
+ multiple
652
+ treeCheckable
653
+ maxTagCount="responsive"
654
+ defaultValue={['cn', 'jp', 'kr', 'de', 'fr']}
655
+ placeholder="选择国家/地区"
656
+ />
657
+ </div>
658
+ )
659
+ ```
660
+
661
+ ### 溢出预览(maxTagPopover)
662
+
663
+ 设置 `maxTagCount` 后默认 hover `+N` 可在 Popover 中查看并删除剩余项;`maxTagPopover` 设为 `false` 可关闭。默认预览内容按需创建,超过 100 项时自动使用分块虚拟化;块内 Tag 按内容宽度自然换行,间距与 TagGroup Token 保持一致,全选万级叶子后也不会挂载全部 Tag。
664
+
665
+ ```tsx
666
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
667
+
668
+ import { TreeSelect } from '@apexhub/apex-ui-react'
669
+
670
+ const treeData: TreeSelectDataNode[] = [
671
+ {
672
+ value: 'skills',
673
+ title: 'Skills',
674
+ children: [
675
+ { value: 'react', title: 'React' },
676
+ { value: 'vue', title: 'Vue' },
677
+ { value: 'node', title: 'Node.js' },
678
+ { value: 'go', title: 'Go' },
679
+ ],
680
+ },
681
+ ]
682
+
683
+ export default () => (
684
+ <div style={{ width: 320, padding: 24 }}>
685
+ <TreeSelect
686
+ style={{ width: '100%' }}
687
+ treeData={treeData}
688
+ treeDefaultExpandAll
689
+ multiple
690
+ maxTagCount={1}
691
+ maxTagPopover
692
+ defaultValue={['react', 'vue', 'node', 'go']}
693
+ placeholder="目标技能"
694
+ />
695
+ </div>
696
+ )
697
+ ```
698
+
699
+ ### 大数据虚拟滚动
700
+
701
+ 万级节点场景默认启用虚拟滚动,`listHeight` 控制树的最大可视高度,短列表按内容高度收起;配合搜索、级联勾选与 `maxTagCount="responsive"` 可保持下拉和触发器 DOM 有界。级联全选/半选状态采用 O(n) 聚合计算,不会因父节点状态查询退化为 O(n²)。
702
+
703
+ ```tsx
704
+ import type { TreeSelectDataNode } from '@apexhub/apex-ui-react'
705
+
706
+ import { TreeSelect } from '@apexhub/apex-ui-react'
707
+
708
+ const treeData: TreeSelectDataNode[] = [
709
+ {
710
+ value: 'all-devices',
711
+ title: 'All Devices',
712
+ children: Array.from({ length: 17_239 }, (_, index) => ({
713
+ value: `device-${index}`,
714
+ title: `Device ${String(index).padStart(5, '0')}`,
715
+ })),
716
+ },
717
+ ]
718
+
719
+ export default () => (
720
+ <TreeSelect
721
+ treeData={treeData}
722
+ treeCheckable
723
+ multiple
724
+ showCheckedStrategy="SHOW_CHILD"
725
+ treeDefaultExpandAll
726
+ showSearch
727
+ virtual
728
+ listHeight={320}
729
+ maxTagCount="responsive"
730
+ placeholder="搜索或选择设备"
731
+ style={{ width: 400 }}
732
+ />
733
+ )
734
+ ```
735
+
736
+ ## DOM 结构
737
+
738
+ 源码声明的静态 `data-slot`:`tree`、`tree-select`、`selector`、`input-clear`、`popup`。具体节点随模式和状态出现,不表示固定嵌套顺序。
739
+
740
+ ## 样式定制
741
+
742
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
743
+
744
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
745
+
746
+ ## FAQ
747
+
748
+ ### 搜索相关的 prop 为什么都挂在 `showSearch` 下?
749
+
750
+ `filterTreeNode`、`treeNodeFilterProp`、`searchValue`、`onSearch`、`autoClearSearchValue` 仅作为 `showSearch` 对象子项提供,不提供顶层同名 prop。
751
+
752
+
753
+
754
+ ### `treeCheckStrictly` 和 `labelInValue` 什么关系?
755
+
756
+ `treeCheckStrictly` 为 `true` 时父子勾选不联动,并强制 `labelInValue` 语义,`value` / `onChange` 携带 `{ value, label, halfChecked? }` 对象。
757
+
758
+
759
+
760
+ ### `showCheckedStrategy` 可以用静态常量吗?
761
+
762
+ 可以。组件挂载了 `TreeSelect.SHOW_ALL`、`TreeSelect.SHOW_PARENT`、`TreeSelect.SHOW_CHILD`,与字符串字面量等价,例如 `showCheckedStrategy={TreeSelect.SHOW_CHILD}`。
763
+
764
+
765
+ ### 为什么没有 `getPopupContainer`?
766
+
767
+ v1 不提供该 prop;弹层通过 Portal 挂载到 `document.body`。若需在滚动容器内挂载,请评估业务是否可改用 Select / Cascader / DatePicker 等已支持 `getPopupContainer` 的组件。
768
+
769
+
770
+ ### 万级节点为什么还会卡顿?
771
+
772
+ 请确认没有设置 `virtual={false}` 或 `popupMatchSelectWidth={false}`,两者都会让下拉树完整渲染。`treeDefaultExpandAll` 与万级数据组合时应保持虚拟滚动,并在多选全选场景使用 `maxTagCount="responsive"`,避免触发器一次挂载全部 Tag。默认 `maxTagPopover` 已对大列表虚拟化;若配置 `contentRender`,它会收到完整选中数组,自定义内容也需要自行分页或虚拟化。