@fibrae/semi-ui-svelte 0.9.0 → 0.10.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.
Files changed (169) hide show
  1. package/README.md +8 -4
  2. package/README.zh-CN.md +8 -4
  3. package/dist/components/anchor/interface.d.ts +14 -0
  4. package/dist/components/audio-player/interface.d.ts +5 -0
  5. package/dist/components/auto-complete/interface.d.ts +29 -0
  6. package/dist/components/avatar/interface.d.ts +24 -0
  7. package/dist/components/backtop/interface.d.ts +2 -0
  8. package/dist/components/badge/interface.d.ts +7 -0
  9. package/dist/components/banner/interface.d.ts +7 -0
  10. package/dist/components/breadcrumb/interface.d.ts +10 -0
  11. package/dist/components/button/interface.d.ts +18 -0
  12. package/dist/components/calendar/interface.d.ts +16 -0
  13. package/dist/components/card/interface.d.ts +18 -0
  14. package/dist/components/carousel/interface.d.ts +16 -0
  15. package/dist/components/cascader/cascader.svelte +1 -0
  16. package/dist/components/cascader/interface.d.ts +57 -0
  17. package/dist/components/checkbox/interface.d.ts +19 -0
  18. package/dist/components/code-highlight/interface.d.ts +3 -0
  19. package/dist/components/collapse/interface.d.ts +16 -0
  20. package/dist/components/collapsible/interface.d.ts +10 -0
  21. package/dist/components/color-picker/interface.d.ts +10 -0
  22. package/dist/components/config-provider/interface.d.ts +7 -0
  23. package/dist/components/cropper/interface.d.ts +11 -0
  24. package/dist/components/date-picker/interface.d.ts +47 -0
  25. package/dist/components/descriptions/interface.d.ts +6 -0
  26. package/dist/components/divider/interface.d.ts +4 -0
  27. package/dist/components/dropdown/interface.d.ts +8 -0
  28. package/dist/components/empty/interface.d.ts +7 -0
  29. package/dist/components/feedback/interface.d.ts +16 -0
  30. package/dist/components/float-button/interface.d.ts +14 -0
  31. package/dist/components/form/interface.d.ts +47 -0
  32. package/dist/components/form/label.svelte +2 -2
  33. package/dist/components/grid/interface.d.ts +13 -0
  34. package/dist/components/highlight/interface.d.ts +7 -0
  35. package/dist/components/hot-keys/interface.d.ts +3 -0
  36. package/dist/components/image/interface.d.ts +59 -0
  37. package/dist/components/input/interface.d.ts +67 -0
  38. package/dist/components/input-number/interface.d.ts +24 -0
  39. package/dist/components/json-viewer/interface.d.ts +7 -0
  40. package/dist/components/layout/interface.d.ts +3 -0
  41. package/dist/components/list/interface.d.ts +18 -0
  42. package/dist/components/locale/interface.d.ts +4 -0
  43. package/dist/components/lottie/interface.d.ts +2 -0
  44. package/dist/components/markdown-render/interface.d.ts +5 -0
  45. package/dist/components/modal/interface.d.ts +29 -0
  46. package/dist/components/navigation/interface.d.ts +47 -0
  47. package/dist/components/overflow-list/interface.d.ts +11 -0
  48. package/dist/components/pagination/interface.d.ts +12 -0
  49. package/dist/components/pincode/interface.d.ts +8 -0
  50. package/dist/components/popconfirm/interface.d.ts +12 -0
  51. package/dist/components/popover/interface.d.ts +30 -0
  52. package/dist/components/progress/interface.d.ts +13 -0
  53. package/dist/components/radio/interface.d.ts +22 -0
  54. package/dist/components/rating/interface.d.ts +12 -0
  55. package/dist/components/resizable/interface.d.ts +30 -0
  56. package/dist/components/scroll-list/interface.d.ts +6 -0
  57. package/dist/components/select/interface.d.ts +63 -0
  58. package/dist/components/side-sheet/interface.d.ts +19 -0
  59. package/dist/components/skeleton/interface.d.ts +7 -0
  60. package/dist/components/slider/interface.d.ts +23 -0
  61. package/dist/components/space/interface.d.ts +4 -0
  62. package/dist/components/spin/interface.d.ts +7 -0
  63. package/dist/components/steps/interface.d.ts +9 -0
  64. package/dist/components/switch/interface.d.ts +7 -0
  65. package/dist/components/table/interface.d.ts +48 -0
  66. package/dist/components/tabs/interface.d.ts +29 -0
  67. package/dist/components/tag/interface.d.ts +22 -0
  68. package/dist/components/tag-input/interface.d.ts +29 -0
  69. package/dist/components/time-picker/interface.d.ts +31 -0
  70. package/dist/components/timeline/interface.d.ts +5 -0
  71. package/dist/components/tooltip/interface.d.ts +20 -0
  72. package/dist/components/tooltip/tooltip.svelte +3 -0
  73. package/dist/components/transfer/interface.d.ts +18 -0
  74. package/dist/components/tree/interface.d.ts +45 -0
  75. package/dist/components/tree-select/interface.d.ts +55 -0
  76. package/dist/components/typography/interface.d.ts +33 -0
  77. package/dist/components/upload/interface.d.ts +64 -0
  78. package/dist/components/user-guide/interface.d.ts +15 -0
  79. package/dist/components/video-player/interface.d.ts +22 -0
  80. package/dist/styles.css +1 -1
  81. package/docs/advanced/dark-mode.md +288 -0
  82. package/docs/basic/button.md +605 -0
  83. package/docs/basic/divider.md +103 -0
  84. package/docs/basic/float-button.md +246 -0
  85. package/docs/basic/grid.md +427 -0
  86. package/docs/basic/layout.md +459 -0
  87. package/docs/basic/resizable.md +584 -0
  88. package/docs/basic/space.md +163 -0
  89. package/docs/basic/tokens.md +425 -0
  90. package/docs/basic/typography.md +615 -0
  91. package/docs/changes-from-semi.md +105 -0
  92. package/docs/ecosystem/tailwind.md +210 -0
  93. package/docs/experience/accessibility.md +82 -0
  94. package/docs/experience/content-guidelines.md +819 -0
  95. package/docs/experience/internationalization.md +7 -0
  96. package/docs/feedback/banner.md +198 -0
  97. package/docs/feedback/feedback.md +294 -0
  98. package/docs/feedback/notification.md +401 -0
  99. package/docs/feedback/popconfirm.md +243 -0
  100. package/docs/feedback/progress.md +389 -0
  101. package/docs/feedback/skeleton.md +388 -0
  102. package/docs/feedback/spin.md +172 -0
  103. package/docs/feedback/toast.md +393 -0
  104. package/docs/input/auto-complete.md +399 -0
  105. package/docs/input/cascader.md +1558 -0
  106. package/docs/input/checkbox.md +408 -0
  107. package/docs/input/color-picker.md +175 -0
  108. package/docs/input/date-picker.md +942 -0
  109. package/docs/input/form.md +2550 -0
  110. package/docs/input/input-number.md +451 -0
  111. package/docs/input/input.md +640 -0
  112. package/docs/input/pincode.md +191 -0
  113. package/docs/input/radio.md +337 -0
  114. package/docs/input/rating.md +214 -0
  115. package/docs/input/select.md +1230 -0
  116. package/docs/input/slider.md +347 -0
  117. package/docs/input/switch.md +206 -0
  118. package/docs/input/tag-input.md +465 -0
  119. package/docs/input/time-picker.md +358 -0
  120. package/docs/input/transfer.md +1061 -0
  121. package/docs/input/tree-select.md +1300 -0
  122. package/docs/input/upload.md +1811 -0
  123. package/docs/llms.txt +147 -0
  124. package/docs/navigation/anchor.md +377 -0
  125. package/docs/navigation/backtop.md +100 -0
  126. package/docs/navigation/breadcrumb.md +284 -0
  127. package/docs/navigation/navigation.md +851 -0
  128. package/docs/navigation/pagination.md +217 -0
  129. package/docs/navigation/steps.md +315 -0
  130. package/docs/navigation/tabs.md +754 -0
  131. package/docs/navigation/tree.md +1956 -0
  132. package/docs/other/config-provider.md +599 -0
  133. package/docs/other/locale.md +353 -0
  134. package/docs/plus/audio-player.md +155 -0
  135. package/docs/plus/code-highlight.md +150 -0
  136. package/docs/plus/drag-move.md +214 -0
  137. package/docs/plus/hot-keys.md +174 -0
  138. package/docs/plus/json-viewer.md +392 -0
  139. package/docs/plus/lottie.md +176 -0
  140. package/docs/plus/markdown-render.md +240 -0
  141. package/docs/plus/video-player.md +325 -0
  142. package/docs/show/avatar.md +475 -0
  143. package/docs/show/badge.md +276 -0
  144. package/docs/show/calendar.md +352 -0
  145. package/docs/show/card.md +485 -0
  146. package/docs/show/carousel.md +592 -0
  147. package/docs/show/collapse.md +289 -0
  148. package/docs/show/collapsible.md +216 -0
  149. package/docs/show/cropper.md +285 -0
  150. package/docs/show/descriptions.md +325 -0
  151. package/docs/show/dropdown.md +466 -0
  152. package/docs/show/empty.md +225 -0
  153. package/docs/show/highlight.md +144 -0
  154. package/docs/show/image.md +433 -0
  155. package/docs/show/list.md +927 -0
  156. package/docs/show/modal.md +517 -0
  157. package/docs/show/overflow-list.md +272 -0
  158. package/docs/show/popover.md +534 -0
  159. package/docs/show/scroll-list.md +156 -0
  160. package/docs/show/side-sheet.md +274 -0
  161. package/docs/show/table.md +5437 -0
  162. package/docs/show/tag.md +428 -0
  163. package/docs/show/timeline.md +277 -0
  164. package/docs/show/tooltip.md +442 -0
  165. package/docs/show/user-guide.md +419 -0
  166. package/docs/start/getting-started.md +234 -0
  167. package/docs/start/introduction.md +57 -0
  168. package/docs/start/overview.md +21 -0
  169. package/package.json +5 -4
@@ -0,0 +1,1558 @@
1
+ # Cascader
2
+
3
+ > Used to select an option under a multi-level classification.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/input/cascader/
6
+
7
+ ## Usage scenarios
8
+
9
+ Differences from TreeSelect component:
10
+
11
+ - TreeSelect: The core value lies in **target node**. The structure is to facilitate users to quickly filter out target options. The final node is what the user wants. It is commonly used in file/folder selection, organizational structure, permission allocation and other scenarios.
12
+ - Cascader: The core selection value lies in the **path**. What the user selects is not an isolated point, but a complete path from root to leaf, which is often used in scenarios such as geographical location and product classification.
13
+
14
+ ## Demos
15
+
16
+ ### How to import
17
+
18
+ ```svelte
19
+ <script lang="ts">
20
+ import { Cascader } from '@fibrae/semi-ui-svelte';
21
+ </script>
22
+ ```
23
+
24
+ ### Basic Usage
25
+
26
+ Basic usage, only leaf nodes can be selected by default.
27
+
28
+ ```svelte
29
+ <script lang="ts">
30
+ import { Cascader } from '@fibrae/semi-ui-svelte';
31
+
32
+ const treeData = [
33
+ {
34
+ label: '浙江省',
35
+ value: 'zhejiang',
36
+ children: [
37
+ {
38
+ label: '杭州市',
39
+ value: 'hangzhou',
40
+ children: [
41
+ { label: '西湖区', value: 'xihu' },
42
+ { label: '萧山区', value: 'xiaoshan' },
43
+ { label: '临安区', value: 'linan' },
44
+ ],
45
+ },
46
+ {
47
+ label: '宁波市',
48
+ value: 'ningbo',
49
+ children: [
50
+ { label: '海曙区', value: 'haishu' },
51
+ { label: '江北区', value: 'jiangbei' },
52
+ ],
53
+ },
54
+ ],
55
+ },
56
+ ];
57
+ </script>
58
+
59
+ <Cascader placeholder="请选择所在地区" style="width: 300px" {treeData} />
60
+ ```
61
+
62
+ ### Multiple
63
+
64
+ Set `multiple` to make multiple selections.
65
+
66
+ ```svelte
67
+ <script lang="ts">
68
+ import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';
69
+
70
+ // Cascader has no defaultValue: bind a state seeded with the initial selection
71
+ let value = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
72
+
73
+ const treeData = [
74
+ {
75
+ label: '浙江省',
76
+ value: 'zhejiang',
77
+ children: [
78
+ {
79
+ label: '杭州市',
80
+ value: 'hangzhou',
81
+ children: [
82
+ { label: '西湖区', value: 'xihu' },
83
+ { label: '萧山区', value: 'xiaoshan' },
84
+ { label: '临安区', value: 'linan' },
85
+ ],
86
+ },
87
+ {
88
+ label: '宁波市',
89
+ value: 'ningbo',
90
+ children: [
91
+ { label: '海曙区', value: 'haishu' },
92
+ { label: '江北区', value: 'jiangbei' },
93
+ ],
94
+ },
95
+ ],
96
+ },
97
+ ];
98
+ </script>
99
+
100
+ <Cascader bind:value multiple placeholder="请选择所在地区" style="width: 300px" {treeData} />
101
+ ```
102
+
103
+ ### Searchable
104
+
105
+ Use `filterTreeNode` to support search input.
106
+
107
+ By default, the `label` value is searched (using the includes method of the string for matching, case-insensitive). You can specify other attribute values through `treeNodeFilterProp` to search. The `label` is text only, and search still matches the `label` text when you customize the node content with the `label` snippet. To match other text, store it in another field in treeData and specify the field through `treeNodeFilterProp`.
108
+
109
+ The default search results will only display the paths of leaf nodes. If you want to display more results, you can set `filterLeafOnly` to `false`; a single Cascader can then select a non-leaf node from the search results, in both controlled and uncontrolled use.
110
+
111
+ ```svelte
112
+ <script lang="ts">
113
+ import { IconMapPinStroked } from '@fibrae/semi-icons-svelte';
114
+ import { Cascader, Typography } from '@fibrae/semi-ui-svelte';
115
+
116
+ const treeData = [
117
+ {
118
+ label: '浙江省',
119
+ value: 'zhejiang',
120
+ children: [
121
+ {
122
+ label: '杭州市',
123
+ value: 'hangzhou',
124
+ children: [
125
+ { label: '西湖区', value: 'xihu' },
126
+ { label: '萧山区', value: 'xiaoshan' },
127
+ { label: '临安区', value: 'linan' },
128
+ ],
129
+ },
130
+ {
131
+ label: '宁波市',
132
+ value: 'ningbo',
133
+ children: [
134
+ { label: '海曙区', value: 'haishu' },
135
+ { label: '江北区', value: 'jiangbei' },
136
+ ],
137
+ },
138
+ ],
139
+ },
140
+ ];
141
+
142
+ // The label snippet adds a decorative icon in the columns; labelText holds the text that search matches
143
+ const labelNodeTreeData = [
144
+ {
145
+ label: '浙江省',
146
+ labelText: '浙江省',
147
+ value: 'zhejiang',
148
+ children: [
149
+ {
150
+ label: '杭州市',
151
+ labelText: '杭州市',
152
+ value: 'hangzhou',
153
+ children: [
154
+ { label: '西湖区', labelText: '西湖区', value: 'xihu' },
155
+ { label: '萧山区', labelText: '萧山区', value: 'xiaoshan' },
156
+ { label: '临安区', labelText: '临安区', value: 'linan' },
157
+ ],
158
+ },
159
+ {
160
+ label: '宁波市',
161
+ labelText: '宁波市',
162
+ value: 'ningbo',
163
+ children: [
164
+ { label: '海曙区', labelText: '海曙区', value: 'haishu' },
165
+ { label: '江北区', labelText: '江北区', value: 'jiangbei' },
166
+ ],
167
+ },
168
+ ],
169
+ },
170
+ ];
171
+ </script>
172
+
173
+ <div>
174
+ <Cascader filterTreeNode placeholder="默认对label值进行搜索" style="width: 300px" {treeData} />
175
+ <br />
176
+ <br />
177
+ <Cascader filterTreeNode placeholder="对value值进行搜索" style="width: 300px" {treeData} treeNodeFilterProp="value" />
178
+ <br />
179
+ <br />
180
+ <Typography.Title heading={6}>filterLeafOnly=false:</Typography.Title>
181
+ <Cascader filterLeafOnly={false} filterTreeNode placeholder="filterLeafOnly=false" style="width: 300px" {treeData} />
182
+ <br />
183
+ <br />
184
+ <Typography.Title heading={6}>Label 为自定义节点,指定其他属性进行搜索</Typography.Title>
185
+ <Cascader displayProp="labelText" filterTreeNode placeholder="Search for labelText" style="width: 300px" treeData={labelNodeTreeData} treeNodeFilterProp="labelText">
186
+ {#snippet label(label)}
187
+ <span style="display: inline-flex; align-items: center; column-gap: 4px">
188
+ <IconMapPinStroked />
189
+ {label.item.label}
190
+ </span>
191
+ {/snippet}
192
+ </Cascader>
193
+ </div>
194
+ ```
195
+
196
+ ### Searchable Multiple Selection
197
+
198
+ When multiple selection and search are supported at the same time, in this scenario, you can delete the corresponding selected item by pressing the BackSpace key.
199
+
200
+ ```svelte
201
+ <script lang="ts">
202
+ import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';
203
+
204
+ let value = $state<CascaderValue>(['zhejiang', 'ningbo', 'haishu']);
205
+
206
+ const treeData = [
207
+ {
208
+ label: '浙江省',
209
+ value: 'zhejiang',
210
+ children: [
211
+ {
212
+ label: '杭州市',
213
+ value: 'hangzhou',
214
+ children: [
215
+ { label: '西湖区', value: 'xihu' },
216
+ { label: '萧山区', value: 'xiaoshan' },
217
+ { label: '临安区', value: 'linan' },
218
+ ],
219
+ },
220
+ {
221
+ label: '宁波市',
222
+ value: 'ningbo',
223
+ children: [
224
+ { label: '海曙区', value: 'haishu' },
225
+ { label: '江北区', value: 'jiangbei' },
226
+ ],
227
+ },
228
+ ],
229
+ },
230
+ ];
231
+ </script>
232
+
233
+ <Cascader bind:value filterTreeNode multiple placeholder="请选择所在地区" style="width: 300px" {treeData} />
234
+ ```
235
+
236
+ Filtered data can be sorted using `filterSorter`.
237
+
238
+ ```svelte
239
+ <script lang="ts">
240
+ import { Cascader } from '@fibrae/semi-ui-svelte';
241
+
242
+ const treeData = [
243
+ {
244
+ label: 'Product',
245
+ value: 'Product',
246
+ children: [
247
+ { label: 'Semi-Material', value: 'Semi-Material' },
248
+ { label: 'Semi-Theme', value: 'Semi-Theme' },
249
+ { label: 'Semi', value: 'Semi' },
250
+ { label: 'Semi-C2D', value: 'Semi-C2D' },
251
+ { label: 'Semi-Icons', value: 'Semi-Icons' },
252
+ ],
253
+ },
254
+ ];
255
+ </script>
256
+
257
+ <div>
258
+ <Cascader
259
+ filterSorter={(first, second, inputValue) => {
260
+ const firstData = first[first.length - 1];
261
+ const lastData = second[second.length - 1];
262
+ if (firstData.label === inputValue) {
263
+ return -1;
264
+ } else if (lastData.label === inputValue) {
265
+ return 1;
266
+ } else {
267
+ return String(firstData.label) < String(lastData.label) ? -1 : 1;
268
+ }
269
+ }}
270
+ filterTreeNode
271
+ placeholder="输入 s 查看排序效果"
272
+ style="width: 300px"
273
+ {treeData}
274
+ />
275
+ </div>
276
+ ```
277
+
278
+ If you want to customize the rendering options after the search, you can use the `filterItem` snippet to achieve custom rendering of the entire line. The snippet parameter has the type `CascaderFilterItemSnippetProps`:
279
+
280
+ ```tsx
281
+ interface CascaderFilterItemSnippetProps {
282
+ props: CascaderFilterItemDomProps; // The id, role, aria-selected, class and click handler of the option, spread it on the root element of the snippet
283
+ inputValue: string; // Search bar search content
284
+ disabled: boolean; // Whether to disable
285
+ data: CascaderData[]; // Search result data, the nodes on this path
286
+ selected: boolean; // Selected state when single selection
287
+ checkStatus: {
288
+ // Checked state when multiple selection
289
+ checked: boolean;
290
+ halfChecked: boolean;
291
+ };
292
+ onCheck: (event: CheckboxEvent) => void; // Check the option in multiple selection, bind it to the onChange of Checkbox
293
+ }
294
+ ```
295
+
296
+ Spread `props` on the root element (such as `<li {...props}>`), and clicking the row selects it in single selection. When `virtualizeInSearch` is on, `props.style` is the positioning style of the row; join your own `style` to it instead of overriding it.
297
+
298
+ The example is as follows
299
+
300
+ ```svelte
301
+ <script lang="ts">
302
+ import { Cascader, Checkbox, Typography } from '@fibrae/semi-ui-svelte';
303
+
304
+ const treeData = [
305
+ {
306
+ label: 'Semi',
307
+ value: 'Semi',
308
+ children: [
309
+ {
310
+ label: 'Semi-Material Semi-Material Semi-Material Semi-Material',
311
+ value: 'Semi-Material',
312
+ },
313
+ {
314
+ label: 'Semi-Theme Semi-Theme Semi-Theme Semi-Theme',
315
+ value: 'Semi-Theme',
316
+ },
317
+ {
318
+ label: 'Semi Design Semi Design Semi Design Semi Design',
319
+ value: 'Semi',
320
+ },
321
+ {
322
+ label: 'Semi-C2D Semi-C2D Semi-C2D Semi-C2D Semi-C2D',
323
+ value: 'Semi-C2D',
324
+ },
325
+ {
326
+ label: 'Semi-Icons Semi-Icons Semi-Icons Semi-Icons Semi-Icons ',
327
+ value: 'Semi-Icons',
328
+ },
329
+ ],
330
+ },
331
+ ];
332
+ </script>
333
+
334
+ <div>
335
+ <p>鼠标 hover 到选项可查看被省略文本完整内容</p>
336
+ <br />
337
+ <Cascader filterTreeNode placeholder="单选,输入 s 自定义搜索选项渲染结果" style="width: 320px" {treeData}>
338
+ {#snippet filterItem(item)}
339
+ <li {...item.props} style="justify-content: flex-start">
340
+ <Typography.Text ellipsis={{ showTooltip: { opts: { style: 'word-break: break-all' } } }} style={`width: 270px; ${item.selected ? 'color: var(--semi-color-primary)' : ''}`}>
341
+ {item.data.map((option) => option.label).join(' / ')}
342
+ </Typography.Text>
343
+ </li>
344
+ {/snippet}
345
+ </Cascader>
346
+ <br />
347
+ <Cascader filterTreeNode multiple placeholder="多选,输入 s 自定义搜索选项渲染结果" style="width: 320px; margin-block-start: 20px" {treeData}>
348
+ {#snippet filterItem(item)}
349
+ <li {...item.props} aria-label={item.data.map((option) => option.label).join(' / ')} style="justify-content: flex-start">
350
+ <Checkbox checked={item.checkStatus.checked} indeterminate={item.checkStatus.halfChecked} onChange={item.onCheck} tabindex={-1}>
351
+ <Typography.Text ellipsis={{ showTooltip: { opts: { style: 'word-break: break-all' } } }} style="width: 250px">
352
+ {item.data.map((option) => option.label).join(' / ')}
353
+ </Typography.Text>
354
+ </Checkbox>
355
+ </li>
356
+ {/snippet}
357
+ </Cascader>
358
+ </div>
359
+ ```
360
+
361
+ If there are a lot of options in the search results, you can optimize performance by setting virtualizeInSearch to enable the virtualization of the search result panel. virtualizeInSearch is an object containing the following values:
362
+
363
+ - height: Option list height in px (number), default 180, the same as the dropdown height
364
+ - width: Option list width value
365
+ - itemSize: The height of each row of Option
366
+
367
+ ```svelte
368
+ <script lang="ts">
369
+ import { Cascader, Checkbox, Typography } from '@fibrae/semi-ui-svelte';
370
+
371
+ const treeData = ['通用', '场景'].map((label, m) => ({
372
+ label,
373
+ value: m,
374
+ children: Array.from({ length: 100 }, (_item, n) => ({
375
+ value: `${m}-${n}`,
376
+ label: `${m}-${n} 第二级`,
377
+ children: Array.from({ length: 20 }, (_item, o) => ({
378
+ value: `${m}-${n}-${o}`,
379
+ label: `${m}-${n}-${o} 第三级详细内容`,
380
+ })),
381
+ })),
382
+ }));
383
+
384
+ const virtualize = {
385
+ // Height = default panel 180px minus 2 * 8px padding
386
+ height: 172,
387
+ width: 320,
388
+ itemSize: 36,
389
+ };
390
+ </script>
391
+
392
+ <Cascader filterTreeNode multiple placeholder="输入 通用 or 场景 进行搜索" style="width: 320px" {treeData} virtualizeInSearch={virtualize}>
393
+ {#snippet filterItem(item)}
394
+ <div {...item.props} style={`${item.props.style ?? ''}; justify-content: start; padding: 8px 16px 8px 12px; box-sizing: border-box`}>
395
+ <Checkbox checked={item.checkStatus.checked} indeterminate={item.checkStatus.halfChecked} onChange={item.onCheck} style="margin-inline-end: 8px" />
396
+ <Typography.Text ellipsis={{ showTooltip: { opts: { style: 'word-break: break-all' } } }} style="max-width: 260px">
397
+ {item.data.map((option) => option.label).join(' | ')}
398
+ </Typography.Text>
399
+ </div>
400
+ {/snippet}
401
+ </Cascader>
402
+ ```
403
+
404
+ ### Limit Tags Displayed
405
+
406
+ When multiple selections, you can use `maxTagCount` to limit the number of tags displayed, and the excess will be displayed as +N.
407
+
408
+ You can use `showRestTagsPopover` to set whether hover +N displays Popover after maxTagCount is exceeded, the default is false. And, you can also configure Popover in the `restTagsPopoverProps` property.
409
+
410
+ ```svelte
411
+ <script lang="ts">
412
+ import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';
413
+
414
+ let value = $state<CascaderValue>([
415
+ ['zhejiang', 'ningbo', 'haishu'],
416
+ ['zhejiang', 'hangzhou', 'xihu'],
417
+ ]);
418
+
419
+ const treeData = [
420
+ {
421
+ label: '浙江省',
422
+ value: 'zhejiang',
423
+ children: [
424
+ {
425
+ label: '杭州市',
426
+ value: 'hangzhou',
427
+ children: [
428
+ { label: '西湖区', value: 'xihu' },
429
+ { label: '萧山区', value: 'xiaoshan' },
430
+ { label: '临安区', value: 'linan' },
431
+ ],
432
+ },
433
+ {
434
+ label: '宁波市',
435
+ value: 'ningbo',
436
+ children: [
437
+ { label: '海曙区', value: 'haishu' },
438
+ { label: '江北区', value: 'jiangbei' },
439
+ ],
440
+ },
441
+ ],
442
+ },
443
+ ];
444
+ const restTagsPopoverProps = { position: 'top' } as const;
445
+ </script>
446
+
447
+ <Cascader bind:value maxTagCount={1} multiple placeholder="请选择所在地区" {restTagsPopoverProps} showRestTagsPopover style="width: 300px" {treeData} />
448
+ ```
449
+
450
+ ### Limit Tags Number
451
+
452
+ In a multi-selection scene, use `max` to limit the number of multi-selection selections. After `max` is exceeded, the `onExceed` callback will be triggered.
453
+
454
+ ```svelte
455
+ <script lang="ts">
456
+ import { Cascader, Toast, type CascaderEntity, type CascaderValue } from '@fibrae/semi-ui-svelte';
457
+
458
+ let value = $state<CascaderValue>([['zhejiang', 'ningbo', 'haishu']]);
459
+
460
+ const treeData = [
461
+ {
462
+ label: '浙江省',
463
+ value: 'zhejiang',
464
+ children: [
465
+ {
466
+ label: '杭州市',
467
+ value: 'hangzhou',
468
+ children: [
469
+ { label: '西湖区', value: 'xihu' },
470
+ { label: '萧山区', value: 'xiaoshan' },
471
+ { label: '临安区', value: 'linan' },
472
+ ],
473
+ },
474
+ {
475
+ label: '宁波市',
476
+ value: 'ningbo',
477
+ children: [
478
+ { label: '海曙区', value: 'haishu' },
479
+ { label: '江北区', value: 'jiangbei' },
480
+ ],
481
+ },
482
+ ],
483
+ },
484
+ ];
485
+
486
+ const onExceed = (v: CascaderEntity[]) => {
487
+ Toast.warning('exceed max');
488
+ console.log(v);
489
+ };
490
+ </script>
491
+
492
+ <Cascader bind:value max={1} multiple {onExceed} placeholder="请选择所在地区" style="width: 300px" {treeData} />
493
+ ```
494
+
495
+ ### Change on Select
496
+
497
+ In the case of single selection, you can also set `changeOnSelect` to allow the parent option to be selected.
498
+
499
+ ```svelte
500
+ <script lang="ts">
501
+ import { Cascader } from '@fibrae/semi-ui-svelte';
502
+
503
+ const treeData = [
504
+ {
505
+ label: '浙江省',
506
+ value: 'zhejiang',
507
+ children: [
508
+ {
509
+ label: '杭州市',
510
+ value: 'hangzhou',
511
+ children: [
512
+ { label: '西湖区', value: 'xihu' },
513
+ { label: '萧山区', value: 'xiaoshan' },
514
+ { label: '临安区', value: 'linan' },
515
+ ],
516
+ },
517
+ {
518
+ label: '宁波市',
519
+ value: 'ningbo',
520
+ children: [
521
+ { label: '海曙区', value: 'haishu' },
522
+ { label: '江北区', value: 'jiangbei' },
523
+ ],
524
+ },
525
+ ],
526
+ },
527
+ ];
528
+ </script>
529
+
530
+ <div>
531
+ <Cascader changeOnSelect placeholder="选择即改变" style="width: 300px" {treeData} />
532
+ <br />
533
+ <br />
534
+ <Cascader changeOnSelect filterTreeNode placeholder="可搜索的选择即改变" style="width: 300px" {treeData} />
535
+ </div>
536
+ ```
537
+
538
+ ### Custom Display Property
539
+
540
+ Set `displayProp` to select which property in the data you would like to display. By default, `label` is displayed.
541
+
542
+ ```svelte
543
+ <script lang="ts">
544
+ import { Cascader, Typography, type CascaderValue } from '@fibrae/semi-ui-svelte';
545
+
546
+ let single = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
547
+ let multiple = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
548
+
549
+ const treeData = [
550
+ {
551
+ label: '浙江省',
552
+ value: 'zhejiang',
553
+ children: [
554
+ {
555
+ label: '杭州市',
556
+ value: 'hangzhou',
557
+ children: [
558
+ { label: '西湖区', value: 'xihu' },
559
+ { label: '萧山区', value: 'xiaoshan' },
560
+ { label: '临安区', value: 'linan' },
561
+ ],
562
+ },
563
+ {
564
+ label: '宁波市',
565
+ value: 'ningbo',
566
+ children: [
567
+ { label: '海曙区', value: 'haishu' },
568
+ { label: '江北区', value: 'jiangbei' },
569
+ ],
570
+ },
571
+ ],
572
+ },
573
+ ];
574
+ </script>
575
+
576
+ <Typography.Title heading={6}>单选</Typography.Title>
577
+ <Cascader bind:value={single} displayProp="value" placeholder="回填时显示数据的value值" style="width: 300px" {treeData} />
578
+ <br />
579
+ <br />
580
+ <Typography.Title heading={6}>多选</Typography.Title>
581
+ <Cascader bind:value={multiple} displayProp="value" multiple placeholder="回填时显示数据的value值" style="width: 300px" {treeData} />
582
+ ```
583
+
584
+ `displayRender` is split into two snippets.
585
+
586
+ When single selection (`multiple` is false), use the `display` snippet to set the displayed content. Its parameter is `{ labels, path }`, where `labels` holds the `displayProp` of each node on the path and `path` holds the nodes on the path (the raw values when the value is not in treeData, as in the parameter of `onChange` with `onChangeWithObject`); empty snippet content shows the `placeholder`.
587
+
588
+ When multiple selection (`multiple` is true), use the `tag` snippet to replace each tag. Its parameter is `{ entity, index, disabled, onClose }`, where `entity` is the relevant data of the node and `onClose` unchecks the node; bind it to your own Tag when you need a close button. It works in searchable multiple selection too. The type of `entity` is `CascaderEntity`, as follows:
589
+
590
+ ```typescript
591
+ interface Entity {
592
+ children?: Entity[]; // children list
593
+ data: CascaderData; // treedata
594
+ ind: number; // index
595
+ key: string; // key
596
+ level: number; // node level
597
+ parent?: Entity; // parent data
598
+ parentKey?: string; // parent key
599
+ path: string[]; // key path
600
+ pos: string; // position of the node in treeData, such as '0-0-1'
601
+ valuePath: string[]; // value path
602
+ }
603
+ ```
604
+
605
+ The `label` of a data item is text only. To render custom content in an option of the columns, use the `label` snippet with the parameter `{ item }`, where `item` is the data of the node; the search results, the selection and the tags still show the text of the node.
606
+
607
+ ```svelte
608
+ <script lang="ts">
609
+ import { Cascader, Tag, Typography, type CascaderValue } from '@fibrae/semi-ui-svelte';
610
+
611
+ let single = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
612
+ let multiple = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
613
+
614
+ const treeData = [
615
+ {
616
+ label: '浙江省',
617
+ value: 'zhejiang',
618
+ children: [
619
+ {
620
+ label: '杭州市',
621
+ value: 'hangzhou',
622
+ children: [
623
+ { label: '西湖区', value: 'xihu' },
624
+ { label: '萧山区', value: 'xiaoshan' },
625
+ { label: '临安区', value: 'linan' },
626
+ ],
627
+ },
628
+ {
629
+ label: '宁波市',
630
+ value: 'ningbo',
631
+ children: [
632
+ { label: '海曙区', value: 'haishu' },
633
+ { label: '江北区', value: 'jiangbei' },
634
+ ],
635
+ },
636
+ ],
637
+ },
638
+ ];
639
+ </script>
640
+
641
+ <Typography.Title heading={6}>单选</Typography.Title>
642
+ <Cascader bind:value={single} placeholder="自定义回填时显示数据的格式" style="width: 300px" {treeData}>
643
+ {#snippet display(display)}
644
+ 已选择:{display.labels.join(' -> ')}
645
+ {/snippet}
646
+ </Cascader>
647
+ <br />
648
+ <br />
649
+ <Typography.Title heading={6}>多选</Typography.Title>
650
+ <Cascader bind:value={multiple} multiple placeholder="自定义回填时显示数据的格式" style="width: 300px" {treeData}>
651
+ {#snippet tag(tag)}
652
+ <Tag color="white" style="margin-inline-end: 4px">{tag.entity.data.label}</Tag>
653
+ {/snippet}
654
+ </Cascader>
655
+ ```
656
+
657
+ ### Custom Separator
658
+
659
+ You can use `separator` to set the separator, including: the separator of the content displayed in the dropdown during search and displayed in the Trigger during single selection.
660
+
661
+ ```svelte
662
+ <script lang="ts">
663
+ import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';
664
+
665
+ let value = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
666
+
667
+ const treeData = [
668
+ {
669
+ label: '浙江省',
670
+ value: 'zhejiang',
671
+ children: [
672
+ {
673
+ label: '杭州市',
674
+ value: 'hangzhou',
675
+ children: [
676
+ { label: '西湖区', value: 'xihu' },
677
+ { label: '萧山区', value: 'xiaoshan' },
678
+ { label: '临安区', value: 'linan' },
679
+ ],
680
+ },
681
+ {
682
+ label: '宁波市',
683
+ value: 'ningbo',
684
+ children: [
685
+ { label: '海曙区', value: 'haishu' },
686
+ { label: '江北区', value: 'jiangbei' },
687
+ ],
688
+ },
689
+ ],
690
+ },
691
+ ];
692
+ </script>
693
+
694
+ <Cascader bind:value filterTreeNode separator=" > " style="width: 300px" {treeData} />
695
+ ```
696
+
697
+ ### Disabled
698
+
699
+ ```svelte
700
+ <script lang="ts">
701
+ import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';
702
+
703
+ let value = $state<CascaderValue>(['zhejiang', 'hangzhou', 'xihu']);
704
+
705
+ const treeData = [
706
+ {
707
+ label: '浙江省',
708
+ value: 'zhejiang',
709
+ children: [
710
+ {
711
+ label: '杭州市',
712
+ value: 'hangzhou',
713
+ children: [
714
+ { label: '西湖区', value: 'xihu' },
715
+ { label: '萧山区', value: 'xiaoshan' },
716
+ { label: '临安区', value: 'linan' },
717
+ ],
718
+ },
719
+ ],
720
+ },
721
+ ];
722
+ </script>
723
+
724
+ <div>
725
+ <Cascader disabled placeholder="请选择所在地区" style="width: 300px" {treeData} />
726
+ <br />
727
+ <br />
728
+ <Cascader bind:value disabled filterTreeNode placeholder="请选择所在地区" style="width: 300px" {treeData} />
729
+ </div>
730
+ ```
731
+
732
+ ### Disable Strictly
733
+
734
+ You can use disableStrictly to enable strict disabling. After enabling strict disabling, when the node is disabled, the selected state cannot be changed through the relationship between the child or the parent.
735
+
736
+ Take the following demo as an example, the node "宁波市" is strictly disabled. Therefore, when we change the selected state of its parent node "浙江省", it will not affect the selected state of the node "宁波市".
737
+
738
+ ```svelte
739
+ <script lang="ts">
740
+ import { Cascader } from '@fibrae/semi-ui-svelte';
741
+
742
+ const treeData = [
743
+ {
744
+ label: '浙江省',
745
+ value: 'zhejiang',
746
+ children: [
747
+ {
748
+ label: '杭州市',
749
+ value: 'hangzhou',
750
+ children: [
751
+ { label: '西湖区', value: 'xihu' },
752
+ { label: '萧山区', value: 'xiaoshan' },
753
+ { label: '临安区', value: 'linan' },
754
+ ],
755
+ },
756
+ {
757
+ label: '宁波市',
758
+ value: 'ningbo',
759
+ disabled: true,
760
+ children: [
761
+ { label: '海曙区', value: 'haishu' },
762
+ { label: '江北区', value: 'jiangbei' },
763
+ ],
764
+ },
765
+ ],
766
+ },
767
+ ];
768
+ </script>
769
+
770
+ <Cascader disableStrictly multiple placeholder="请选择所在地区" style="width: 300px" {treeData} />
771
+ ```
772
+
773
+ ### the Way of Expand Menu
774
+
775
+ You can use `showNext` to set the time to expand the Dropdown submenu, optional: `click` (default), `hover`.
776
+
777
+ ```svelte
778
+ <script lang="ts">
779
+ import { Cascader } from '@fibrae/semi-ui-svelte';
780
+
781
+ const treeData = [
782
+ {
783
+ label: '浙江省',
784
+ value: 'zhejiang',
785
+ children: [
786
+ {
787
+ label: '杭州市',
788
+ value: 'hangzhou',
789
+ children: [
790
+ { label: '西湖区', value: 'xihu' },
791
+ { label: '萧山区', value: 'xiaoshan' },
792
+ { label: '临安区', value: 'linan' },
793
+ ],
794
+ },
795
+ ],
796
+ },
797
+ ];
798
+ </script>
799
+
800
+ <Cascader placeholder="请选择所在地区" showNext="hover" style="width: 300px" {treeData} />
801
+ ```
802
+
803
+ ### Click to Select
804
+
805
+ In multiple mode, clicking on non-leaf nodes does not trigger selection by default. You can use `clickToSelect` to enable selecting any node on click.
806
+
807
+ This API is especially useful when combined with `showNext="hover"`: hovering expands the submenu, while clicking selects the current node.
808
+
809
+ ```svelte
810
+ <script lang="ts">
811
+ import { Cascader } from '@fibrae/semi-ui-svelte';
812
+
813
+ const treeData = [
814
+ {
815
+ label: '浙江省',
816
+ value: 'zhejiang',
817
+ children: [
818
+ {
819
+ label: '杭州市',
820
+ value: 'hangzhou',
821
+ children: [
822
+ { label: '西湖区', value: 'xihu' },
823
+ { label: '萧山区', value: 'xiaoshan' },
824
+ ],
825
+ },
826
+ {
827
+ label: '宁波市',
828
+ value: 'ningbo',
829
+ children: [{ label: '海曙区', value: 'haishu' }],
830
+ },
831
+ ],
832
+ },
833
+ ];
834
+ </script>
835
+
836
+ <Cascader clickToSelect multiple placeholder="请选择所在地区" showNext="hover" style="width: 300px" {treeData} />
837
+ ```
838
+
839
+ ### Additional items
840
+
841
+ We have reserved slots at the top and bottom of the cascade selector. You can set them through the `topSlot` or `bottomSlot` snippet.
842
+
843
+ ```svelte
844
+ <script lang="ts">
845
+ import { Cascader, Typography } from '@fibrae/semi-ui-svelte';
846
+
847
+ const slotStyle = 'height: 36px; display: flex; padding: 0 32px; align-items: center; cursor: pointer; border-block-start: 1px solid var(--semi-color-border)';
848
+
849
+ const treeData = [
850
+ {
851
+ label: '浙江省',
852
+ value: 'zhejiang',
853
+ children: [
854
+ {
855
+ label: '杭州市',
856
+ value: 'hangzhou',
857
+ children: [
858
+ { label: '西湖区', value: 'xihu' },
859
+ { label: '萧山区', value: 'xiaoshan' },
860
+ { label: '临安区', value: 'linan' },
861
+ ],
862
+ },
863
+ {
864
+ label: '宁波市',
865
+ value: 'ningbo',
866
+ children: [
867
+ { label: '海曙区', value: 'haishu' },
868
+ { label: '江北区', value: 'jiangbei' },
869
+ ],
870
+ },
871
+ ],
872
+ },
873
+ ];
874
+ </script>
875
+
876
+ <Cascader placeholder="请选择所在地区" style="width: 300px" {treeData}>
877
+ {#snippet bottomSlot()}
878
+ <div style={slotStyle}>
879
+ <Typography.Text>找不到相关选项?</Typography.Text>
880
+ <Typography.Text link>去新建</Typography.Text>
881
+ </div>
882
+ {/snippet}
883
+ </Cascader>
884
+ ```
885
+
886
+ ### Controlled Component
887
+
888
+ Bind `value` with `bind:value` to use Cascader as a controlled component; `onChange` is still called. The Svelte Cascader has no `defaultValue`: to start with a selection, bind a `$state` that holds it, and leave `value` unbound for an uncontrolled Cascader; `bind:value={get, set}` makes it fully controlled.
889
+
890
+ ```svelte
891
+ <script lang="ts">
892
+ import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';
893
+
894
+ let value = $state<CascaderValue>([]);
895
+
896
+ const treeData = [
897
+ {
898
+ label: '浙江省',
899
+ value: 'zhejiang',
900
+ children: [
901
+ {
902
+ label: '杭州市',
903
+ value: 'hangzhou',
904
+ children: [
905
+ { label: '西湖区', value: 'xihu' },
906
+ { label: '萧山区', value: 'xiaoshan' },
907
+ { label: '临安区', value: 'linan' },
908
+ ],
909
+ },
910
+ {
911
+ label: '宁波市',
912
+ value: 'ningbo',
913
+ children: [
914
+ { label: '海曙区', value: 'haishu' },
915
+ { label: '江北区', value: 'jiangbei' },
916
+ ],
917
+ },
918
+ ],
919
+ },
920
+ ];
921
+ </script>
922
+
923
+ <Cascader bind:value placeholder="请选择所在地区" style="width: 300px" {treeData} />
924
+ ```
925
+
926
+ ### Auto Merge Value
927
+
928
+ In the multi-selection (multiple=true) scenario, when we select the ancestor node, if we want the value not to include its corresponding descendant nodes, we can set it by `autoMergeValue`, and the default is true. When `autoMergeValue` and `leafOnly` are turned on at the same time, the latter has a higher priority.
929
+
930
+ ```svelte
931
+ <script lang="ts">
932
+ import { Cascader, type CascaderChangeValue, type CascaderValue } from '@fibrae/semi-ui-svelte';
933
+
934
+ let value = $state<CascaderValue>([]);
935
+ const onChange = (v: CascaderChangeValue) => {
936
+ console.log(v);
937
+ };
938
+
939
+ const treeData = [
940
+ {
941
+ label: '浙江省',
942
+ value: 'zhejiang',
943
+ children: [
944
+ {
945
+ label: '杭州市',
946
+ value: 'hangzhou',
947
+ children: [
948
+ { label: '西湖区', value: 'xihu' },
949
+ { label: '萧山区', value: 'xiaoshan' },
950
+ { label: '临安区', value: 'linan' },
951
+ ],
952
+ },
953
+ {
954
+ label: '宁波市',
955
+ value: 'ningbo',
956
+ children: [
957
+ { label: '海曙区', value: 'haishu' },
958
+ { label: '江北区', value: 'jiangbei' },
959
+ ],
960
+ },
961
+ ],
962
+ },
963
+ ];
964
+ </script>
965
+
966
+ <Cascader autoMergeValue={false} bind:value multiple {onChange} placeholder="autoMergeValue 为 false" style="width: 300px" {treeData} />
967
+ ```
968
+
969
+ ### Leaf Only
970
+
971
+ In multiple selection, you can set the value to include only leaf nodes by turning on leafOnly, that is, the displayed Tag and the value of `bind:value` and `onChange` only include leaf nodes.
972
+
973
+ ```svelte
974
+ <script lang="ts">
975
+ import { Cascader, type CascaderChangeValue, type CascaderValue } from '@fibrae/semi-ui-svelte';
976
+
977
+ let value = $state<CascaderValue>([]);
978
+
979
+ const onChange = (v: CascaderChangeValue) => {
980
+ console.log(v);
981
+ };
982
+
983
+ const treeData = [
984
+ {
985
+ label: '浙江省',
986
+ value: 'zhejiang',
987
+ children: [
988
+ {
989
+ label: '杭州市',
990
+ value: 'hangzhou',
991
+ children: [
992
+ { label: '西湖区', value: 'xihu' },
993
+ { label: '萧山区', value: 'xiaoshan' },
994
+ { label: '临安区', value: 'linan' },
995
+ ],
996
+ },
997
+ {
998
+ label: '宁波市',
999
+ value: 'ningbo',
1000
+ children: [
1001
+ { label: '海曙区', value: 'haishu' },
1002
+ { label: '江北区', value: 'jiangbei' },
1003
+ ],
1004
+ },
1005
+ ],
1006
+ },
1007
+ ];
1008
+ </script>
1009
+
1010
+ <Cascader bind:value leafOnly multiple {onChange} placeholder="开启 leafOnly" style="width: 300px" {treeData} />
1011
+ ```
1012
+
1013
+ ### Checked RelationShip
1014
+
1015
+ In multiple, `checkRelation` can be used to set the type of node selection relationship, optional: 'related' (default), 'unRelated'. When the selection relationship is 'unRelated', it means that selections between nodes do not affect each other.
1016
+
1017
+ ```svelte
1018
+ <script lang="ts">
1019
+ import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';
1020
+
1021
+ let value = $state<CascaderValue>([['Asia'], ['Asia', 'China', 'Beijing']]);
1022
+
1023
+ const treeData = [
1024
+ {
1025
+ label: '亚洲',
1026
+ value: 'Asia',
1027
+ children: [
1028
+ {
1029
+ label: '中国',
1030
+ value: 'China',
1031
+ children: [
1032
+ { label: '北京', value: 'Beijing' },
1033
+ { label: '上海', value: 'Shanghai' },
1034
+ ],
1035
+ },
1036
+ ],
1037
+ },
1038
+ {
1039
+ label: '北美洲',
1040
+ value: 'North America',
1041
+ },
1042
+ ];
1043
+ </script>
1044
+
1045
+ <Cascader bind:value checkRelation="unRelated" multiple style="width: 300px" {treeData} />
1046
+ ```
1047
+
1048
+ ### Dynamic Update of Data
1049
+
1050
+ `treeData` can be replaced as a whole or changed in place in `$state` data (such as `push`, or assigning `children`); both are noticed and recalculated, and a new array with equal content keeps the expanded and selected state.
1051
+
1052
+ ```svelte
1053
+ <script lang="ts">
1054
+ import { Button, Cascader, type CascaderData } from '@fibrae/semi-ui-svelte';
1055
+
1056
+ let treeData = $state<CascaderData[]>([]);
1057
+
1058
+ const add = () => {
1059
+ const itemLength = Math.floor(Math.random() * 3) + 1;
1060
+ treeData = Array.from({ length: itemLength }, (_, i) => {
1061
+ const length = Math.floor(Math.random() * 3);
1062
+ const children = Array.from({ length }, (_, ci) => ({
1063
+ key: `${i}-${ci}`,
1064
+ label: `Item-${i}-${ci}`,
1065
+ value: `${i}-${ci}`,
1066
+ }));
1067
+ return {
1068
+ key: `${i}`,
1069
+ label: `Item-${i}`,
1070
+ value: `${i}`,
1071
+ children,
1072
+ };
1073
+ });
1074
+ };
1075
+ </script>
1076
+
1077
+ <Cascader placeholder="请选择" style="width: 300px" {treeData} />
1078
+ <br />
1079
+ <br />
1080
+ <Button onclick={add}>动态改变数据</Button>
1081
+ ```
1082
+
1083
+ ### Load Async Data
1084
+
1085
+ You could use `loadData` to load data asynchronously.
1086
+
1087
+ **Could not be used together with searching**
1088
+
1089
+ ```svelte
1090
+ <script lang="ts">
1091
+ import { Cascader, type CascaderData } from '@fibrae/semi-ui-svelte';
1092
+
1093
+ let data = $state<CascaderData[]>([
1094
+ { label: 'Node1', value: '0-0' },
1095
+ { label: 'Node2', value: '0-1' },
1096
+ { label: 'Node3', value: '0-2', isLeaf: true },
1097
+ ]);
1098
+
1099
+ const updateTreeData = (list: CascaderData[], value: CascaderData['value'], children: CascaderData[]): CascaderData[] =>
1100
+ list.map((node) => {
1101
+ if (node.value === value) {
1102
+ return { ...node, children };
1103
+ }
1104
+ if (node.children) {
1105
+ return { ...node, children: updateTreeData(node.children, value, children) };
1106
+ }
1107
+ return node;
1108
+ });
1109
+
1110
+ const onLoadData = (selectedOpt: CascaderData[]) => {
1111
+ const targetOpt = selectedOpt[selectedOpt.length - 1];
1112
+ const { label, value } = targetOpt;
1113
+ return new Promise<void>((resolve) => {
1114
+ if (targetOpt.children) {
1115
+ resolve();
1116
+ return;
1117
+ }
1118
+
1119
+ setTimeout(() => {
1120
+ data = updateTreeData(data, value, [
1121
+ {
1122
+ label: `${label} - 1`,
1123
+ value: `${label}-1`,
1124
+ isLeaf: selectedOpt.length > 1,
1125
+ },
1126
+ {
1127
+ label: `${label} - 2`,
1128
+ value: `${label}-2`,
1129
+ isLeaf: selectedOpt.length > 1,
1130
+ },
1131
+ ]);
1132
+ resolve();
1133
+ }, 1000);
1134
+ });
1135
+ };
1136
+ </script>
1137
+
1138
+ <Cascader loadData={onLoadData} placeholder="Please select" style="width: 300px" treeData={data} />
1139
+ ```
1140
+
1141
+ ### Remote Search
1142
+
1143
+ Cascader supports remote search. With `remote` enabled, search input no longer goes through local filtering; only the `onSearch` callback is called, and you are responsible for fetching `treeData` asynchronously based on the input. This mirrors Select's `remote` behavior.
1144
+
1145
+ > **Usage notes**
1146
+ >
1147
+ > You should typically handle the following yourself when using remote search:
1148
+ >
1149
+ > - **Debounce**: avoid firing a request on every keystroke; wrapping the search handler with `debounce` from `es-toolkit` (e.g. 200\~300ms) is the common approach.
1150
+ > - **Race-condition protection**: use an incrementing token or an `AbortController` to drop stale responses, otherwise an out-of-order earlier response may overwrite the latest one.
1151
+ > - **Loading hint**: show a loading state via an outer `Spin` or other indicator while the request is in flight, otherwise users may misread an in-flight state as "no data".
1152
+ > - **Empty / cleared input**: when the input is cleared, restore `treeData` to the initial state instead of querying with an empty keyword.
1153
+
1154
+ ```svelte
1155
+ <script lang="ts">
1156
+ import { debounce } from 'es-toolkit';
1157
+ import { Cascader, Spin, type CascaderData } from '@fibrae/semi-ui-svelte';
1158
+
1159
+ const fetchByKeyword = (keyword: string) =>
1160
+ new Promise<CascaderData[]>((resolve) => {
1161
+ const delay = 200 + Math.floor(Math.random() * 800);
1162
+ setTimeout(() => {
1163
+ if (!keyword) {
1164
+ resolve([]);
1165
+ return;
1166
+ }
1167
+ resolve([
1168
+ { label: `${keyword} - 选项 A`, value: `${keyword}-a` },
1169
+ { label: `${keyword} - 选项 B`, value: `${keyword}-b` },
1170
+ { label: `${keyword} - 选项 C`, value: `${keyword}-c` },
1171
+ ]);
1172
+ }, delay);
1173
+ });
1174
+
1175
+ let treeData = $state<CascaderData[]>([]);
1176
+ let loading = $state(false);
1177
+
1178
+ const latest = { token: 0 };
1179
+ const handleSearch = debounce((input: string) => {
1180
+ if (!input) {
1181
+ treeData = [];
1182
+ loading = false;
1183
+ return;
1184
+ }
1185
+ latest.token += 1;
1186
+ const token = latest.token;
1187
+ loading = true;
1188
+ void fetchByKeyword(input).then((next) => {
1189
+ // Drop stale results that arrive after a newer request
1190
+ if (token !== latest.token) {
1191
+ return;
1192
+ }
1193
+ treeData = next;
1194
+ loading = false;
1195
+ });
1196
+ }, 300);
1197
+ </script>
1198
+
1199
+ <Spin spinning={loading}>
1200
+ <Cascader filterTreeNode onChange={(v) => console.log('selected:', v)} onSearch={handleSearch} placeholder="输入关键词远程搜索" remote style="width: 300px" {treeData} />
1201
+ </Spin>
1202
+ ```
1203
+
1204
+ ### Deep & long list
1205
+
1206
+ When your data structure level is particularly deep, the Cascader drop-down menu may be at the top of the screen. At this time, we recommend setting overflow -x: auto and a suitable width for the drop-down menu (it is recommended to use a width of N+0.5 columns, the most Expand to display half a column to give users a visual cue that they can scroll in the horizontal direction)
1207
+
1208
+ ```svelte
1209
+ <script lang="ts">
1210
+ import { Cascader } from '@fibrae/semi-ui-svelte';
1211
+
1212
+ const treeData = [
1213
+ {
1214
+ label: 'A',
1215
+ value: 'A',
1216
+ children: [
1217
+ {
1218
+ label: 'B',
1219
+ value: 'B',
1220
+ children: [
1221
+ {
1222
+ label: 'C',
1223
+ value: 'C',
1224
+ children: [
1225
+ {
1226
+ label: 'D',
1227
+ value: 'D',
1228
+ children: [
1229
+ {
1230
+ label: 'E',
1231
+ value: 'E',
1232
+ children: [{ label: 'F', value: 'F' }],
1233
+ },
1234
+ ],
1235
+ },
1236
+ ],
1237
+ },
1238
+ ],
1239
+ },
1240
+ ],
1241
+ },
1242
+ ];
1243
+ </script>
1244
+
1245
+ <Cascader classNames={{ dropdown: 'components-cascader-demo' }} placeholder="请选择所在地区" style="width: 300px" {treeData} />
1246
+ ```
1247
+
1248
+ ```css
1249
+ .components-cascader-demo {
1250
+ .semi-cascader-option-lists {
1251
+ max-width: 510px;
1252
+ overflow-x: auto;
1253
+ }
1254
+ }
1255
+ ```
1256
+
1257
+ ### Custom Trigger
1258
+
1259
+ If the default trigger style cannot meet your needs, you can use the `trigger` snippet to customize the display of the select box.
1260
+
1261
+ The snippet parameter of `trigger` has the type `CascaderTriggerSnippetProps`, as follows:
1262
+
1263
+ ```typescript
1264
+ interface CascaderTriggerSnippetProps {
1265
+ /**
1266
+ * The hierarchical position of the selected node in treeData,
1267
+ * as in the following example, when "浙江省-杭州市-萧山区" is
1268
+ * selected, the value here is '0-0-1'; a Set<string> in multiple mode
1269
+ */
1270
+ value?: string | Set<string>;
1271
+ /* The search text while open; while a searchable single Cascader is closed, the display text of the selected path */
1272
+ inputValue: string;
1273
+ /* Placeholder of Cascader */
1274
+ placeholder?: string;
1275
+ /* Whether to disable Cascader */
1276
+ disabled: boolean;
1277
+ /**
1278
+ * The function used to update the value of the input box. You
1279
+ * should call this function when the value of the Input component
1280
+ * customized by trigger is updated to synchronize the
1281
+ * state with Cascader, you need to set the filterTreeNode parameter
1282
+ * to non-false when use it
1283
+ */
1284
+ onSearch: (inputValue: string) => void;
1285
+ /* Function to clear the value; pass the click event when it is bound to a control inside the trigger, so the click does not open the dropdown */
1286
+ onClear: (event?: MouseEvent) => void;
1287
+ /* Used to delete a single item, the input parameter is the hierarchical
1288
+ * position of the node in treeData (the same format as value)
1289
+ */
1290
+ onRemove: (pos: string) => void;
1291
+ }
1292
+ ```
1293
+
1294
+ ```svelte
1295
+ <script lang="ts">
1296
+ import { IconChevronDown, IconClose } from '@fibrae/semi-icons-svelte';
1297
+ import { Button, ButtonGroup, Cascader, Tag, TagInput, type CascaderData } from '@fibrae/semi-ui-svelte';
1298
+
1299
+ const treeData: CascaderData[] = [
1300
+ {
1301
+ label: '浙江省',
1302
+ value: 'zhejiang',
1303
+ children: [
1304
+ {
1305
+ label: '杭州市',
1306
+ value: 'hangzhou',
1307
+ children: [
1308
+ { label: '西湖区', value: 'xihu' },
1309
+ { label: '萧山区', value: 'xiaoshan' },
1310
+ { label: '临安区', value: 'linan' },
1311
+ ],
1312
+ },
1313
+ {
1314
+ label: '宁波市',
1315
+ value: 'ningbo',
1316
+ children: [
1317
+ { label: '海曙区', value: 'haishu' },
1318
+ { label: '江北区', value: 'jiangbei' },
1319
+ ],
1320
+ },
1321
+ ],
1322
+ },
1323
+ ];
1324
+
1325
+ const getLabelFromValue = (value: string) => {
1326
+ const [first, ...rest] = value.split('-').map((item) => Number(item));
1327
+ let node: CascaderData | undefined = treeData[first];
1328
+ rest.forEach((item) => {
1329
+ node = node?.children?.[item];
1330
+ });
1331
+ return node?.label;
1332
+ };
1333
+ </script>
1334
+
1335
+ {#snippet chevron()}
1336
+ <IconChevronDown />
1337
+ {/snippet}
1338
+
1339
+ {#snippet close()}
1340
+ <IconClose />
1341
+ {/snippet}
1342
+
1343
+ <Cascader placeholder="Custom Trigger" {treeData}>
1344
+ {#snippet trigger(trigger)}
1345
+ <!-- The clear button is a sibling of the trigger button: buttons cannot nest -->
1346
+ <ButtonGroup theme="light">
1347
+ <Button icon={chevron} iconPosition="right">
1348
+ {trigger.value ? getLabelFromValue(trigger.value as string) : trigger.placeholder}
1349
+ </Button>
1350
+ {#if trigger.value}
1351
+ <Button
1352
+ aria-label="清除"
1353
+ icon={close}
1354
+ onclick={(event) => {
1355
+ event.stopPropagation();
1356
+ trigger.onClear(event);
1357
+ }}
1358
+ />
1359
+ {/if}
1360
+ </ButtonGroup>
1361
+ {/snippet}
1362
+ </Cascader>
1363
+ <br />
1364
+ <Cascader filterTreeNode multiple placeholder="Custom Trigger" style="width: 300px" {treeData}>
1365
+ {#snippet trigger(trigger)}
1366
+ <TagInput onInputChange={trigger.onSearch} value={Array.from(trigger.value as Set<string>)}>
1367
+ {#snippet tag(tag)}
1368
+ <Tag closable onClose={() => trigger.onRemove(tag.value)} style="margin-inline-start: 2px" tagKey={tag.value}>
1369
+ {getLabelFromValue(tag.value)}
1370
+ </Tag>
1371
+ {/snippet}
1372
+ </TagInput>
1373
+ {/snippet}
1374
+ </Cascader>
1375
+ ```
1376
+
1377
+ ## API reference
1378
+
1379
+ ### Cascader
1380
+
1381
+ **Props**
1382
+
1383
+ | Property | Description | Type | Default |
1384
+ | - | - | - | - |
1385
+ | arrowIcon | Custom dropdown arrow on the right; null hides the arrow. Hovering shows the clear button first when it is visible. | `Snippet \| null` | - |
1386
+ | autoAdjustOverflow | Whether the dropdown flips its direction when an edge covers it. | `boolean` | - |
1387
+ | autoMergeValue | In multiple mode, the value leaves out the descendants of a selected parent. Changes after mount are not followed; leafOnly takes precedence when both are on. | `boolean` | `true` |
1388
+ | borderless | Whether to use the borderless style. | `boolean` | `false` |
1389
+ | bottomSlot | Extra content at the bottom of the dropdown. | `Snippet` | - |
1390
+ | changeOnSelect | Whether a non-leaf node can be selected in single mode. | `boolean` | `false` |
1391
+ | checkRelation | In multiple mode, how the checked states of the nodes relate: related links parents and children, unRelated keeps them independent. | `'related' \| 'unRelated'` | `"related"` |
1392
+ | classNames | Class names of the inner parts, keyed by dropdown; values take anything class takes (string, array or object) and merge with the built-in classes. | `Partial<Record<CascaderPart, ClassValue>>` | - |
1393
+ | clearIcon | Custom icon of the clear button, effective when showClear is true; empty content keeps the default icon. | `Snippet` | - |
1394
+ | clickToSelect | In multiple mode, clicking any node selects it. Often used with showNext set to hover: hovering expands the submenu and clicking selects the node. | `boolean` | `false` |
1395
+ | defaultOpen | Whether the dropdown is open on mount. | `boolean` | `false` |
1396
+ | disabled | Whether the Cascader is disabled. A disabled Cascader cannot be reached with Tab. | `boolean` | - |
1397
+ | disableStrictly | Whether to disable strictly. A disabled node then does not change when its parent or children are checked or unchecked. | `boolean` | `false` |
1398
+ | display | The selected path shown in single mode, with `{ labels, path }`: `labels` holds the displayProp of each node and `path` the nodes, or the raw values when the value is not in treeData. Empty content shows the placeholder. | `Snippet<[CascaderDisplaySnippetProps]>` | - |
1399
+ | displayProp | The node field shown in the trigger and the tags, label by default. | `string` | `"label"` |
1400
+ | emptyContent | Content shown when there is no data to pick or the search has no result. The default text from the locale shows when it is not given, and null hides the empty state. | `Snippet \| null` | - |
1401
+ | enableLeafClick | In multiple mode, whether clicking the option of a leaf node checks it. | `boolean` | `false` |
1402
+ | expandIcon | Custom expand icon; empty content keeps the default icon. | `Snippet` | - |
1403
+ | filterItem | Replaces a row of the search results, with `{ props, inputValue, disabled, data, checkStatus, selected, onCheck }`; spread `props` on the root element of the row. | `Snippet<[CascaderFilterItemSnippetProps]>` | - |
1404
+ | filterLeafOnly | Whether the search results only show the paths of leaf nodes. | `boolean` | `true` |
1405
+ | filterSorter | Sorts the filtered results; it receives the two result paths (the node arrays from the root to the matched node) and the input. | `(first: CascaderData[], second: CascaderData[], inputValue: string) => number` | - |
1406
+ | filterTreeNode | Whether search is on. True matches the input against the field named by treeNodeFilterProp, case-insensitively; a custom match function can be given instead. | `boolean \| ((inputValue: string, treeNodeString: string, data?: CascaderData) => boolean)` | `false` |
1407
+ | insetLabel | A label inside the select box; it is not rendered when prefix is also given. | `Snippet` | - |
1408
+ | insetLabelId | The id of the insetLabel content, used to name the combobox; the component generates one when the insetLabel snippet is used and this is not given. | `string` | - |
1409
+ | keyMaps | Custom field names for value, label, children, disabled and isLeaf in a node. | `CascaderKeyMapProps` | - |
1410
+ | label | Content of an option in the columns, with `{ item }`; the search results, the selection and the tags still show the text of the node. | `Snippet<[CascaderLabelSnippetProps]>` | - |
1411
+ | leafOnly | In multiple mode, the value and the tags shown only include leaf nodes. Changes after mount are not followed. | `boolean` | `false` |
1412
+ | loadData | Loads data asynchronously. It receives the path from the root to the current node and must return a Promise; after a rejection the node leaves the loading state and can be expanded again. Cannot be used with search. | `(selectOptions: CascaderData[]) => Promise<void>` | - |
1413
+ | max | In multiple mode, the most paths that can be selected; exceeding it calls onExceed. | `number` | - |
1414
+ | maxTagCount | In multiple mode, the most tags shown; the rest appear as +N. | `number` | - |
1415
+ | motion | Whether the dropdown animates. | `boolean` | `true` |
1416
+ | multiple | Whether several paths can be selected. It has no global default. | `boolean` | `false` |
1417
+ | onBlur | Called when the dropdown closes: a MouseEvent for a click outside, a KeyboardEvent for Esc, undefined when the close method closes it. It is not a DOM blur event. | `(event?: MouseEvent \| KeyboardEvent \| FocusEvent) => void` | - |
1418
+ | onChange | Called when the selection changes. In single mode the selected path, in multiple mode an array of the selected paths; node data with onChangeWithObject. | `(value: CascaderChangeValue) => void` | - |
1419
+ | onChangeWithObject | Whether onChange carries the data of each node instead of its value. A bound value must then be node data too, with a value. This is a boolean attribute, not a callback. | `boolean` | `false` |
1420
+ | onClear | Called when the clear button clears the selection. | `() => void` | - |
1421
+ | onDropdownVisibleChange | Called when the dropdown opens or closes, with whether it is open. | `(visible: boolean) => void` | - |
1422
+ | onExceed | Called in multiple mode when the selection goes past max, with the Entity array of the checked nodes. | `(checkedItem: CascaderEntity[]) => void` | - |
1423
+ | onFocus | Called when a click or a key opens the dropdown, with that MouseEvent or KeyboardEvent. It is not a DOM focus event and Tabbing in or out does not call it. | `(event: MouseEvent \| KeyboardEvent \| FocusEvent) => void` | - |
1424
+ | onKeyDown | Called once per key press before the Cascader handles it; calling preventDefault there does not stop the Cascader. Except for a key on the clear button or a control inside a custom trigger, it is reported in the capture phase on the trigger, so stopPropagation there keeps the key from the search input and skips the trigger's handling of it (opening the dropdown, closing it on Esc); the options still take it. | `(event: KeyboardEvent) => void` | - |
1425
+ | onListScroll | Called when a column of the tree scrolls, with the scroll event and the column. Scrolling the search results does not call it. | `(event: Event, panel: CascaderScrollPanelProps) => void` | - |
1426
+ | onLoad | Called when a node has loaded, with the set of loaded keys and the node data. | `(newLoadedKeys: Set<string>, data: CascaderData) => void` | - |
1427
+ | onSearch | Called when the search input changes, with the text. | `(value: string) => void` | - |
1428
+ | onSelect | Called when a node is selected, with the value of the node. In multiple mode, one checked node gives its value and more give an array. | `(value: string \| number \| Array<string \| number>) => void` | - |
1429
+ | placeholder | Placeholder of the select box. | `string` | - |
1430
+ | position | Direction of the dropdown, bottomLeft by default and bottomRight in RTL. | `Position` | - |
1431
+ | prefix | Prefix content. | `Snippet` | - |
1432
+ | preventScroll | Whether focusing inside the component stops the browser scrolling the document to show the focused element. | `boolean` | - |
1433
+ | remote | Whether to search remotely. Input is then not filtered locally and only calls onSearch, and the caller updates treeData asynchronously. | `boolean` | `false` |
1434
+ | restTagsPopoverProps | Configuration of the Popover of the remaining tags, such as position and trigger. See Popover. | `Omit<PopoverProps, 'child' \| 'children' \| 'content'>` | - |
1435
+ | searchPlaceholder | Placeholder of the search input; placeholder is used when it is not given. | `string` | - |
1436
+ | searchPosition | Where the search input is: trigger puts it in the trigger, custom leaves it to the caller. | `'custom' \| 'trigger'` | `"trigger"` |
1437
+ | separator | The separator of a path in the search results and in the trigger in single mode. | `string` | `" / "` |
1438
+ | showClear | Whether to show the clear button. | `boolean` | `false` |
1439
+ | showNext | When the submenu expands: on click or on hover. | `'click' \| 'hover'` | `"click"` |
1440
+ | showRestTagsPopover | Whether hovering +N shows the remaining tags in a Popover once maxTagCount is exceeded. | `boolean` | `false` |
1441
+ | size | Size of the select box. | `CascaderSize` | - |
1442
+ | stopPropagation | Whether clicks on the dropdown stop bubbling. | `boolean \| string` | `true` |
1443
+ | styles | Style strings of the inner parts, keyed like classNames. | `Partial<Record<CascaderPart, string>>` | - |
1444
+ | suffix | Suffix content. | `Snippet` | - |
1445
+ | tag | Replaces each tag in multiple mode, with `{ entity, index, disabled, onClose }`; `onClose` unchecks the node. | `Snippet<[CascaderTagSnippetProps]>` | - |
1446
+ | topSlot | Extra content at the top of the dropdown. | `Snippet` | - |
1447
+ | treeData | Node data. The label is text only, use the label snippet for node content. Changes made in place to $state data are noticed, and a new array with equal content keeps the expanded and selected state. | `CascaderData[]` | `[]` |
1448
+ | treeNodeFilterProp | The node field matched against the search input, label by default. | `string` | `"label"` |
1449
+ | trigger | Replaces the content of the trigger, with `{ value, inputValue, placeholder, disabled, onSearch, onClear, onRemove }`. | `Snippet<[CascaderTriggerSnippetProps]>` | - |
1450
+ | validateStatus | Validation status of the trigger; it only affects the style. | `ValidateStatus` | - |
1451
+ | value | The selected entry, bound with bind:value. Leave it out for an uncontrolled Cascader; to start with a selection, bind a $state that holds it. `bind:value={get, set}` makes it fully controlled. In single mode it is a node or a path, in multiple mode it can also be an array of paths. | `CascaderValue` | - |
1452
+ | virtualizeInSearch | Virtual list configuration of the search results, made of height, width and itemSize, for large result sets; height defaults to 180, the same as the dropdown height. | `CascaderVirtualize` | - |
1453
+
1454
+ **Methods**
1455
+
1456
+ | Method | Description | Type |
1457
+ | - | - | - |
1458
+ | blur | Blurs the trigger or the search input. | `() => void` |
1459
+ | close | Closes the dropdown. | `() => void` |
1460
+ | focus | Focuses the trigger or the search input. | `() => void` |
1461
+ | open | Opens the dropdown. | `() => void` |
1462
+ | search | Searches as if the keyword were typed; filterTreeNode must be set to turn search on. | `(keyword: string) => void` |
1463
+
1464
+ Cascader puts `class`, `style` and undeclared native attributes on the root element (the trigger), and `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-errormessage`, `aria-invalid` and `aria-required` on the current combobox (see [ARIA](#aria)). `onChange`, `onSelect`, `onFocus`, `onBlur` and `onKeyDown` are component callbacks and hide the native events of the same name on the root element; `onFocus` and `onBlur` are called when the dropdown opens and closes, they are not DOM focus events. `style` and each value of `styles` are CSS strings.
1465
+
1466
+ ### CascaderData
1467
+
1468
+ | Properties | Instructions | type | Default |
1469
+ | - | - | - | - |
1470
+ | children | children node | CascaderData\[] | - |
1471
+ | disabled | Disabled status | boolean | - |
1472
+ | isLeaf | leaf node | boolean | - |
1473
+ | label | Text to be displayed (required), use the `label` snippet for custom content | string\|number | - |
1474
+ | loading | loading | boolean | - |
1475
+ | value | Value property (required) | string\|number | - |
1476
+
1477
+ ## Methods
1478
+
1479
+ Cascader exposes `open()`, `close()`, `focus()`, `blur()` and `search(value)` through `export function`; call them on the instance from `bind:this`. `search` searches as if the value were typed; set `filterTreeNode` to enable search, and `searchPosition` to `custom` to customize the display search box.
1480
+
1481
+ ```svelte
1482
+ <script lang="ts">
1483
+ import { Cascader } from '@fibrae/semi-ui-svelte';
1484
+
1485
+ let cascader = $state<Cascader>();
1486
+ </script>
1487
+
1488
+ <Cascader bind:this={cascader} {treeData} />
1489
+ <button onclick={() => cascader?.open()}>Open</button>
1490
+ ```
1491
+
1492
+ ## Accessibility
1493
+
1494
+ ### ARIA
1495
+
1496
+ - Cascader supports importing `aria-label`, `aria-describedby`, `aria-errormessage`, `aria-invalid`, `aria-labelledby`, `aria-required` to indicate the relevant information of the Cascader;
1497
+
1498
+ * These `aria-*` attributes fall on the current combobox: the root element (the trigger) without search, the search input with search, and the tag input in multiple mode when the search input is in the trigger;
1499
+
1500
+ - The combobox takes its name from, in order: `aria-labelledby`, `aria-label`, the rendered insetLabel (the combobox's `aria-labelledby` points at it, with an id the component generates when `insetLabelId` is not given; with a prefix the insetLabel is not rendered and does not name it), and otherwise "Cascader" from the locale. The tree or the search-result listbox in the dropdown uses the same name source;
1501
+ - Following the ARIA 1.2 combobox pattern, exactly one element is the combobox at any time; its `aria-controls` points at the list in the dropdown, and the dropdown has the combobox's name. Without search the trigger is a select-only combobox and the selected path is its value; with search the input itself is the combobox, with `aria-autocomplete="list"`, and the trigger has no role and no Tab stop. In single mode the input appears only while searching, so the trigger is the combobox otherwise; the input is empty until the user types, so the selected path is linked to it as its description with `aria-describedby`; picking a result returns focus to the trigger;
1502
+ - The columns together are one `role="tree"`: options are `treeitem`s with `aria-level` (their column), `aria-setsize`, `aria-posinset` and `aria-disabled`, and `aria-expanded` on options that can expand; a single-choice Cascader uses `aria-selected`, a multi-choice one uses `aria-checked` (`mixed` when half checked);
1503
+
1504
+ * Search results are a `role="listbox"` of `option`s, with `aria-selected` for selected, or checked in a multi-choice Cascader. The `props` of `filterItem` carry the `id`, `role="option"` and `aria-selected` of the option, and must be spread on the root element of the snippet;
1505
+
1506
+ - The tick and the checkbox in front of an option only picture its state: they are hidden from screen readers and take no focus.
1507
+
1508
+ ### Keyboard Interaction
1509
+
1510
+ Cascader follows the [WAI-ARIA Combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) pattern: focus always stays on the trigger or the search input, `aria-activedescendant` points at the current option, and the current option shows the focus ring. There is no current option when the dropdown opens.
1511
+
1512
+ - While the dropdown is closed: `ArrowDown`, `ArrowUp` and `Enter` open it; without search, `Space` also opens it, and `Home` and `End` open it and move to the first or last option of the first column. With search, `Space`, `Home` and `End` edit the text
1513
+ - `Enter`: with a current option, act like a click on it, or check and uncheck it in a multi-choice Cascader; disabled options do not respond
1514
+ - `ArrowDown`, `ArrowUp`: move to the next or previous option in the current option's column (or in the search results); the first `ArrowDown` moves to the first option of the first column; `Home`, `End`: move to the first or last option of that column
1515
+ - `ArrowRight`: expand the current option, showing its column; once expanded, move to the first option of that column (swapped with `ArrowLeft` in RTL)
1516
+ - `ArrowLeft`: collapse the expanded current option; otherwise move to the parent option in the previous column
1517
+ - `Space`: with a current option, the same as `Enter` (it types a space in the search input)
1518
+ - Typing characters: while the dropdown is open, move to the next option after the current one, across the shown columns, whose label starts with the typed text, leaving the columns as they are; characters typed in quick succession form one search string. In the search input the characters are typed as text; a closed dropdown ignores them
1519
+ - `Esc`: close the dropdown
1520
+
1521
+ While focus is in the search input and text is typed, only `ArrowDown`, `ArrowUp` and `Enter` move and select; the other keys edit the text. The arrow keys only move the current option: unlike hovering, they do not expand the next column or trigger `loadData`, which loads when `ArrowRight` expands.
1522
+
1523
+ With `showClear`, a selected value or search text, and no `disabled`, the trigger renders a clear button. It is a native `button` named "Clear selection" from the locale, shown on hover, while the dropdown is open, or while focus is inside the Cascader. From the trigger or the search input, `Tab` moves to the clear button; `Enter` or `Space` clears, as a mouse click does, and the focus goes back to the trigger or the search input. In multiple mode `Backspace` in the search input also removes tags.
1524
+
1525
+ ## Content Guidelines
1526
+
1527
+ - Selector options
1528
+ - If there is no default option, use "Select" as the placeholder text
1529
+ - Arrange options in alphabetical order or another logical order, so that users can find them more easily
1530
+ - Write in sentence case (capitalize the first letter, lowercase the rest) and avoid ending with commas or semicolons
1531
+ - Clearly express the purpose of the choice that each option represents
1532
+
1533
+ ## Design Tokens
1534
+
1535
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/input/cascader/>
1536
+
1537
+ ## Changes from Semi Design
1538
+
1539
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
1540
+
1541
+ - 破坏性:删除 `dropdownClassName`、`dropdownStyle`,改用 `classNames.dropdown`、`styles.dropdown`,落在下拉菜单元素上,类名排在自带类名之后(原来在前)。
1542
+ - 多选选项的 checkbox 只在结束一侧留 8px 间距(原来两侧各 8px,RTL 样式漏到了 LTR),LTR 下 checkbox 起始侧少 8px。
1543
+ - 破坏性:删除 `getPopupContainer`、`zIndex`、`dropdownMargin`;不再读取未声明的 `open`(改用 `defaultOpen`)。破坏性(类型):`CascaderProps` 改为泛型 `CascaderProps<Multiple>`;单选 `displayRender` 参数改为 `ReactNode[]`;`triggerRender` 的 `inputValue` 改为 `ReactNode` 并删除 `onChange`(改用 `onSearch`);`filterSorter` 参数改为路径数组 `CascaderData[]`;`checkRelation`、`searchPosition` 收窄为字面量联合;`virtualizeInSearch.height` 收紧为 `number`;删除 `mouseEnterDelay`、`mouseLeaveDelay`。
1544
+ - 行为变化:`onFocus`、`onBlur` 与 TreeSelect 一致,成对且以整个组件(触发器、其中的搜索框与标签、下拉)为界。焦点从组件外进入时触发一次 `onFocus`(Tab、点击、脚本 `focus()` 都算,原来只有点击或按键打开下拉才触发),组件内移动不重复触发;之后每次 focus 只触发一次 `onBlur`:焦点离开到外部元素、在组件外按下鼠标、单选选中后关闭下拉(让 Form 的 `trigger="blur"` 立即校验)。Esc、多选选中、点击触发器收起下拉时焦点仍在组件内,不再触发 `onBlur`(原来关闭下拉就触发);`ref.close()` 同样不触发。打开时按 Tab 离开还会关闭下拉(APG combobox 模式)。`onFocus` 的参数可能是 `FocusEvent`,`onBlur` 的参数可能是 `FocusEvent`(Vue 为 `focus`、`blur` 事件)。
1545
+ - 行为变化:`filterLeafOnly={false}` 时,受控单选在搜索结果中选中分支后保持选中,与非受控一致(原来受控的 `value` 回写分支路径时被清空)。
1546
+ - 行为变化:`topSlot`、`bottomSlot` 带输入框时,焦点在触发器上按 ArrowUp、ArrowDown 不再把焦点送进输入框,方向键只在选项里移动,四个框架一致(原来 Vue、Solid、Svelte 会送进去)。
1547
+ - 行为变化:焦点在 `topSlot`、`bottomSlot` 的输入框里时按 Esc,关闭下拉后焦点回到触发器(原来落到 `body`);焦点在触发器上时不变。
1548
+ - 行为变化:`showNext="hover"` 时有指针宽限:鼠标从已展开的选项斜着移向下一列、途经同列其他选项时不切换;在其他选项上停留超过 300ms,或离开三角区、反向移动时,才切换到指针所在的选项(规则同 Tooltip、Popover 一节)。foundation 的 `handleItemHover(e, item)` 要求 `e` 带 `clientX`、`clientY`、`currentTarget`,`CascaderAdapter` 新增 `getColumnRect(index)`。
1549
+ - 破坏性(类型):`Entity` 删除 `_notExist`。treeData 中没有的选中值仍以占位实体保存在 `keyEntities` 中,由 foundation 内部标记,`displayRender`、`onExceed` 收到的实体不再带该字段。
1550
+ - 选项角色由 `menuitem` 改为 `treeitem`(搜索结果为 `listbox` + `option`),按 `menuitem` 查询的测试需调整;键盘按 APG combobox,焦点留在触发器或搜索框,选项 id 不再是 `cascaderItem-${key}`。清除按钮改为带名称的原生 `button`;ref 改为 `CascaderHandle { open, close, focus, blur, search }`,`ref.focus()`、`ref.blur()` 真正移动 DOM 焦点。
1551
+ - Svelte:Cascader 的 `value` 可绑定,没有 `defaultValue`;单选多选靠 `multiple` 区分,没有 `Multiple` 泛型;回调同 React:`onChange`、`onChangeWithObject`、`onSelect`、`onSearch`、`onFocus`、`onBlur`、`onDropdownVisibleChange`、`onClear`、`onExceed`、`onLoad`、`onListScroll`、`onKeyDown`(每个按键只上报一次)。
1552
+ - Svelte:插槽改为同名 snippet:`prefix`、`suffix`、`insetLabel`、`topSlot`、`bottomSlot`、`label`、`display`、`tag`、`filterItem`、`trigger`、`expandIcon`、`clearIcon`、`arrowIcon`、`emptyContent`,`emptyContent`、`arrowIcon` 传 `null` 隐藏,空 snippet 不回落默认内容;`filterItem` 收到要展开到自定义行上的 `props`(含 `id`、`role`、`class`、`onclick`,虚拟搜索结果里还带定位用的 `style`,要一起展开到行上),没有 `componentProps`,`trigger` 参数也没有 `componentProps`;`treeData` 可以是 `$state`,就地修改会重新收集选项。
1553
+ - `checkRelation="unRelated"` 多选时,自定义触发器的 `value` 是已勾选项的位置集合,不再为空。`filterTreeNode` 加远程搜索时,`treeData` 更新不再清空搜索框。
1554
+ - Svelte:不再检测绑定的 `value` 与 `keyMaps` 的原地修改,需替换整个对象;`treeData` 的原地修改仍会重新收集选项。
1555
+ - `disableStrictly` 下,被禁用键对应的标签不能再通过 `handleTagRemoveByKey`(含可搜索多选时 TagInput 的移除回调)移除,原来只有渲染层把标签显示为不可关闭。
1556
+ - 搜索框收起时焦点回到触发器:`preventScroll` 跟随组件属性(原来写死为 true),焦点原本在下拉框 slot 里的输入框时也会回到触发器,与 TreeSelect 一致。
1557
+ - 异步加载的「正在加载」判断不再依赖宿主写入 `loadedKeys` 与 `treeData` 的先后:键在 `loadingKeys` 中,或在 `loadedKeys` 中且上一轮实体没有 `children`、新实体有,都算加载中,四个框架一致。
1558
+ - Svelte 破坏性(类型):`trigger` snippet 的参数类型 `CascaderTriggerSnippetProps.value` 改为可选属性 `value?: string | Set<string>`。