@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,1956 @@
1
+ # Tree
2
+
3
+ > A tree view component presents a hierarchical list.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/navigation/tree/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Tree } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ By default, tree is in single select mode and each item is selectable.
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { Tree } from '@fibrae/semi-ui-svelte';
24
+
25
+ const treeData = [
26
+ {
27
+ label: '亚洲',
28
+ value: 'Asia',
29
+ key: '0',
30
+ children: [
31
+ {
32
+ label: '中国',
33
+ value: 'China',
34
+ key: '0-0',
35
+ children: [
36
+ {
37
+ label: '北京',
38
+ value: 'Beijing',
39
+ key: '0-0-0',
40
+ },
41
+ {
42
+ label: '上海',
43
+ value: 'Shanghai',
44
+ key: '0-0-1',
45
+ },
46
+ ],
47
+ },
48
+ ],
49
+ },
50
+ {
51
+ label: '北美洲',
52
+ value: 'North America',
53
+ key: '1',
54
+ },
55
+ ];
56
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
57
+ </script>
58
+
59
+ <Tree defaultExpandAll {style} {treeData} />
60
+ ```
61
+
62
+ ### Multi-choice
63
+
64
+ You could use `multiple` to set mode to multi-choice. When all child items are selected, the parent item will be selected.
65
+
66
+ ```svelte
67
+ <script lang="ts">
68
+ import { Tree } from '@fibrae/semi-ui-svelte';
69
+
70
+ const treeData = [
71
+ {
72
+ label: 'Asia',
73
+ value: 'Asia',
74
+ key: '0',
75
+ children: [
76
+ {
77
+ label: 'China',
78
+ value: 'China',
79
+ key: '0-0',
80
+ children: [
81
+ { label: 'Beijing', value: 'Beijing', key: '0-0-0' },
82
+ { label: 'Shanghai', value: 'Shanghai', key: '0-0-1' },
83
+ { label: 'Chengdu', value: 'Chengdu', key: '0-0-2' },
84
+ ],
85
+ },
86
+ {
87
+ label: 'Japan',
88
+ value: 'Japan',
89
+ key: '0-1',
90
+ children: [{ label: 'Osaka', value: 'Osaka', key: '0-1-0' }],
91
+ },
92
+ ],
93
+ },
94
+ {
95
+ label: 'North America',
96
+ value: 'North America',
97
+ key: '1',
98
+ children: [
99
+ { label: 'United States', value: 'United States', key: '1-0' },
100
+ { label: 'Canada', value: 'Canada', key: '1-1' },
101
+ ],
102
+ },
103
+ ];
104
+
105
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
106
+ </script>
107
+
108
+ <Tree defaultExpandAll multiple {style} {treeData} />
109
+ ```
110
+
111
+ ### Searchable
112
+
113
+ Use `filterTreeNode` to support search input. By default it searches the `label` property of the data. You can use `treeNodeFilterProp` to set another property to search or pass in a function to `filterTreeNode` to customize search behavior.
114
+
115
+ You could also use `showFilteredOnly` if you prefer to display filtered results only.
116
+
117
+ ```svelte
118
+ <script lang="ts">
119
+ import { Switch, Tree } from '@fibrae/semi-ui-svelte';
120
+
121
+ let showFilteredOnly = $state(false);
122
+
123
+ const treeData = [
124
+ {
125
+ label: 'Asia',
126
+ value: 'Asia',
127
+ key: '0',
128
+ children: [
129
+ {
130
+ label: 'China',
131
+ value: 'China',
132
+ key: '0-0',
133
+ children: [
134
+ { label: 'Beijing', value: 'Beijing', key: '0-0-0' },
135
+ { label: 'Shanghai', value: 'Shanghai', key: '0-0-1' },
136
+ ],
137
+ },
138
+ {
139
+ label: 'Japan',
140
+ value: 'Japan',
141
+ key: '0-1',
142
+ children: [{ label: 'Osaka', value: 'Osaka', key: '0-1-0' }],
143
+ },
144
+ ],
145
+ },
146
+ {
147
+ label: 'North America',
148
+ value: 'North America',
149
+ key: '1',
150
+ children: [
151
+ { label: 'United States', value: 'United States', key: '1-0' },
152
+ { label: 'Canada', value: 'Canada', key: '1-1' },
153
+ ],
154
+ },
155
+ ];
156
+
157
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
158
+ </script>
159
+
160
+ <span id="tree-searchable-filtered-only">showFilteredOnly</span>
161
+ <Switch aria-labelledby="tree-searchable-filtered-only" bind:checked={showFilteredOnly} size="small" />
162
+ <br />
163
+ <Tree filterTreeNode multiple {showFilteredOnly} {style} {treeData} />
164
+ ```
165
+
166
+ After setting the `filterTreeNode` property to enable search, you can customize the search box with the `search` snippet, whose arguments are `class`, `value`, `placeholder`, `showClear` and `onChange`. `search={false}` hides the search box.
167
+
168
+ ```svelte
169
+ <script lang="ts">
170
+ import { Input, Tree } from '@fibrae/semi-ui-svelte';
171
+
172
+ const treeData = [
173
+ {
174
+ label: 'Asia',
175
+ value: 'Asia',
176
+ key: '0',
177
+ children: [
178
+ {
179
+ label: 'China',
180
+ value: 'China',
181
+ key: '0-0',
182
+ children: [
183
+ { label: 'Beijing', value: 'Beijing', key: '0-0-0' },
184
+ { label: 'Shanghai', value: 'Shanghai', key: '0-0-1' },
185
+ ],
186
+ },
187
+ {
188
+ label: 'Japan',
189
+ value: 'Japan',
190
+ key: '0-1',
191
+ children: [{ label: 'Osaka', value: 'Osaka', key: '0-1-0' }],
192
+ },
193
+ ],
194
+ },
195
+ {
196
+ label: 'North America',
197
+ value: 'North America',
198
+ key: '1',
199
+ children: [
200
+ { label: 'United States', value: 'United States', key: '1-0' },
201
+ { label: 'Canada', value: 'Canada', key: '1-1' },
202
+ ],
203
+ },
204
+ ];
205
+ </script>
206
+
207
+ <Tree filterTreeNode {treeData}>
208
+ {#snippet search(searchProps)}
209
+ <Input class={searchProps.class} onChange={searchProps.onChange} placeholder={searchProps.placeholder} showClear={searchProps.showClear} value={searchProps.value}>
210
+ {#snippet prefix()}Search{/snippet}
211
+ </Input>
212
+ {/snippet}
213
+ </Tree>
214
+ ```
215
+
216
+ ### Trigger search manually
217
+
218
+ Use `bind:this` to get the Tree instance, and call its `search` method to trigger search manually. Note that you need to set `filterTreeNode` to enable search at the same time. If the search box is outside the Tree, you can hide the search box inside it with `search={false}`.
219
+
220
+ ```svelte
221
+ <script lang="ts">
222
+ import { Input, Tree, type TreeHandle } from '@fibrae/semi-ui-svelte';
223
+
224
+ let tree = $state<TreeHandle>();
225
+
226
+ const treeData = [
227
+ {
228
+ label: 'Asia',
229
+ value: 'Asia',
230
+ key: '0',
231
+ children: [
232
+ {
233
+ label: 'China',
234
+ value: 'China',
235
+ key: '0-0',
236
+ children: [
237
+ { label: 'Beijing', value: 'Beijing', key: '0-0-0' },
238
+ { label: 'Shanghai', value: 'Shanghai', key: '0-0-1' },
239
+ ],
240
+ },
241
+ {
242
+ label: 'Japan',
243
+ value: 'Japan',
244
+ key: '0-1',
245
+ children: [{ label: 'Osaka', value: 'Osaka', key: '0-1-0' }],
246
+ },
247
+ ],
248
+ },
249
+ {
250
+ label: 'North America',
251
+ value: 'North America',
252
+ key: '1',
253
+ children: [
254
+ { label: 'United States', value: 'United States', key: '1-0' },
255
+ { label: 'Canada', value: 'Canada', key: '1-1' },
256
+ ],
257
+ },
258
+ ];
259
+ </script>
260
+
261
+ <div>
262
+ <Input aria-label="filter tree" onChange={(value) => tree?.search(value)} showClear>
263
+ {#snippet prefix()}Search{/snippet}
264
+ </Input>
265
+ <div style="margin-top: 20px">搜索结果如下:</div>
266
+ <Tree bind:this={tree} blockNode={false} filterTreeNode search={false} {treeData} />
267
+ </div>
268
+ ```
269
+
270
+ ### JSON TreeData
271
+
272
+ You could use `treeDataSimpleJson` to pass in `treeNodes` data in JSON format. In this case, key will be used as `key` and `label`, and value will be used as `value` correspondingly. Return value includes JSON data in selected nodes.
273
+
274
+ ```svelte
275
+ <script lang="ts">
276
+ import { Tree } from '@fibrae/semi-ui-svelte';
277
+
278
+ const json = {
279
+ Node1: {
280
+ 'Child Node1': '0-0-1',
281
+ 'Child Node2': '0-0-2',
282
+ },
283
+ Node2: '0-1',
284
+ };
285
+
286
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
287
+ </script>
288
+
289
+ <Tree multiple onChange={(value) => console.log('当前所有选中项: ', value)} onSelect={(key) => console.log('当前选项: ', key)} {style} treeDataSimpleJson={json} />
290
+ ```
291
+
292
+ ### BlockNode
293
+
294
+ You could use `blockNode` to set node to display as a row. In this case, styles for hovering and selected state take effects on the entire row. By default, it is set to `true`. When it is set to `false`, only label will be highlighted.
295
+
296
+ ```svelte
297
+ <script lang="ts">
298
+ import { Tree } from '@fibrae/semi-ui-svelte';
299
+
300
+ const treeData = [
301
+ {
302
+ label: 'Asia',
303
+ value: 'Asia',
304
+ key: '0',
305
+ children: [
306
+ {
307
+ label: 'China',
308
+ value: 'China',
309
+ key: '0-0',
310
+ children: [
311
+ {
312
+ label: 'Beijing',
313
+ value: 'Beijing',
314
+ key: '0-0-0',
315
+ },
316
+ {
317
+ label: 'Shanghai',
318
+ value: 'Shanghai',
319
+ key: '0-0-1',
320
+ },
321
+ ],
322
+ },
323
+ {
324
+ label: 'Japan',
325
+ value: 'Japan',
326
+ key: '0-1',
327
+ children: [
328
+ {
329
+ label: 'Osaka',
330
+ value: 'Osaka',
331
+ key: '0-1-0',
332
+ },
333
+ ],
334
+ },
335
+ ],
336
+ },
337
+ {
338
+ label: 'North America',
339
+ value: 'North America',
340
+ key: '1',
341
+ children: [
342
+ {
343
+ label: 'United States',
344
+ value: 'United States',
345
+ key: '1-0',
346
+ },
347
+ {
348
+ label: 'Canada',
349
+ value: 'Canada',
350
+ key: '1-1',
351
+ },
352
+ ],
353
+ },
354
+ ];
355
+ </script>
356
+
357
+ <div>
358
+ <Tree blockNode={false} {treeData} value="Shanghai" />
359
+ <br />
360
+ <Tree blockNode={false} multiple {treeData} value="Shanghai" />
361
+ </div>
362
+ ```
363
+
364
+ ### Custom TreeNode Label
365
+
366
+ The `label` of `TreeNodeData` accepts only a string or a number. Custom node content comes from the `label` snippet, whose arguments are `item` (the node data), `label` and `searchWord` (the current search word). Search by `filterTreeNode` still matches the `label` text in `treeData`.
367
+
368
+ Node content is best kept for display. Buttons and links in a node can be reached with Tab (see [Accessibility](#accessibility)), but screen readers read them as part of the node's name and arrow-key browsing skips them. Put actions on a node outside the tree, for example in a menu opened by `onContextMenu` or in a toolbar next to the tree.
369
+
370
+ ```svelte
371
+ <script lang="ts">
372
+ import { Tag, Tree } from '@fibrae/semi-ui-svelte';
373
+
374
+ // Node content is display-only: focus stays on the tree, so buttons and links inside are keyboard-unreachable
375
+ const treeData = [
376
+ {
377
+ label: '亚洲',
378
+ value: 'yazhou',
379
+ key: 'yazhou',
380
+ children: [
381
+ {
382
+ label: '中国',
383
+ value: 'zhongguo',
384
+ key: 'zhongguo',
385
+ },
386
+ {
387
+ label: '日本',
388
+ value: 'riben',
389
+ key: 'riben',
390
+ },
391
+ ],
392
+ },
393
+ ];
394
+ const labelStyle = 'display: flex; justify-content: space-between; align-items: center';
395
+ const treeStyle = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
396
+ </script>
397
+
398
+ <Tree style={treeStyle} {treeData}>
399
+ {#snippet label(labelProps)}
400
+ <div style={labelStyle}>
401
+ <span>{labelProps.label}</span>
402
+ <Tag size="small">{labelProps.item.children ? '大洲' : '国家'}</Tag>
403
+ </div>
404
+ {/snippet}
405
+ </Tree>
406
+ ```
407
+
408
+ Ellipsis for long labels. Truncate overlong text with an ellipsis inside the `label` snippet.
409
+
410
+ ```svelte
411
+ <script lang="ts">
412
+ import { Tree, Typography } from '@fibrae/semi-ui-svelte';
413
+
414
+ const treeData = [
415
+ {
416
+ label: '亚洲亚洲亚洲亚洲亚洲亚洲亚洲亚洲亚洲亚洲亚洲亚洲',
417
+ value: 'yazhou',
418
+ key: 'yazhou',
419
+ children: [
420
+ {
421
+ label: '中国中国中国中国中国中国中国中国中国中国中国中国',
422
+ value: 'zhongguo',
423
+ key: 'zhongguo',
424
+ },
425
+ {
426
+ label: '日本日本日本日本日本日本日本日本日本日本日本日本',
427
+ value: 'riben',
428
+ key: 'riben',
429
+ },
430
+ ],
431
+ },
432
+ ];
433
+ const treeStyle = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
434
+ </script>
435
+
436
+ <Tree style={treeStyle} {treeData}>
437
+ {#snippet label(labelProps)}
438
+ <Typography.Text ellipsis={{ showTooltip: true }} style="width: 100%">{labelProps.label}</Typography.Text>
439
+ {/snippet}
440
+ </Tree>
441
+ ```
442
+
443
+ ### Custom Icon
444
+
445
+ Use the `icon` snippet to add a customized icon. Its arguments are `item`, `level`, `expanded`, `isLeaf`, `loading`, `selected`, `checked` and `halfChecked`, so the icon can differ by node. `TreeNodeData` has no `icon` field.
446
+
447
+ ```svelte
448
+ <script lang="ts">
449
+ import { IconMapPin } from '@fibrae/semi-icons-svelte';
450
+ import { Tree } from '@fibrae/semi-ui-svelte';
451
+
452
+ const treeData = [
453
+ {
454
+ label: 'Asia',
455
+ value: 'Asia',
456
+ key: '0',
457
+ children: [
458
+ {
459
+ label: 'China',
460
+ value: 'China',
461
+ key: '0-0',
462
+ },
463
+ {
464
+ label: 'Japan',
465
+ value: 'Japan',
466
+ key: '0-1',
467
+ },
468
+ ],
469
+ },
470
+ ];
471
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
472
+ </script>
473
+
474
+ <Tree {style} {treeData}>
475
+ {#snippet icon()}
476
+ <IconMapPin style="color: var(--semi-color-text-2)" />
477
+ {/snippet}
478
+ </Tree>
479
+ ```
480
+
481
+ ### Directory
482
+
483
+ You could use `directory` to display tree as a directory with default icons. Also, the icon could be overwritten by custom Icon.
484
+
485
+ ```svelte
486
+ <script lang="ts">
487
+ import { Tree } from '@fibrae/semi-ui-svelte';
488
+
489
+ const treeData = [
490
+ {
491
+ label: 'Asia',
492
+ value: 'Asia',
493
+ key: '0',
494
+ children: [
495
+ {
496
+ label: 'China',
497
+ value: 'China',
498
+ key: '0-0',
499
+ children: [
500
+ {
501
+ label: 'Beijing',
502
+ value: 'Beijing',
503
+ key: '0-0-0',
504
+ },
505
+ {
506
+ label: 'Shanghai',
507
+ value: 'Shanghai',
508
+ key: '0-0-1',
509
+ },
510
+ ],
511
+ },
512
+ {
513
+ label: 'Japan',
514
+ value: 'Japan',
515
+ key: '0-1',
516
+ children: [
517
+ {
518
+ label: 'Osaka',
519
+ value: 'Osaka',
520
+ key: '0-1-0',
521
+ },
522
+ ],
523
+ },
524
+ ],
525
+ },
526
+ {
527
+ label: 'North America',
528
+ value: 'North America',
529
+ key: '1',
530
+ children: [
531
+ {
532
+ label: 'United States',
533
+ value: 'United States',
534
+ key: '1-0',
535
+ },
536
+ {
537
+ label: 'Canada',
538
+ value: 'Canada',
539
+ key: '1-1',
540
+ },
541
+ ],
542
+ },
543
+ ];
544
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
545
+ </script>
546
+
547
+ <Tree directory {style} {treeData} />
548
+ ```
549
+
550
+ ### Disabled
551
+
552
+ You can use `disableStrictly` to set whether 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.
553
+
554
+ ```svelte
555
+ <script lang="ts">
556
+ import { Tree } from '@fibrae/semi-ui-svelte';
557
+
558
+ const treeData = [
559
+ {
560
+ label: 'Asia',
561
+ value: 'Asia',
562
+ key: '0',
563
+ children: [
564
+ {
565
+ label: 'China',
566
+ value: 'China',
567
+ key: '0-0',
568
+ children: [
569
+ {
570
+ label: 'Beijing',
571
+ value: 'Beijing',
572
+ key: '0-0-0',
573
+ disabled: true,
574
+ },
575
+ {
576
+ label: 'Shanghai',
577
+ value: 'Shanghai',
578
+ key: '0-0-1',
579
+ disabled: true,
580
+ },
581
+ ],
582
+ },
583
+ {
584
+ label: 'Japan',
585
+ value: 'Japan',
586
+ key: '0-1',
587
+ children: [
588
+ {
589
+ label: 'Osaka',
590
+ value: 'Osaka',
591
+ key: '0-1-0',
592
+ },
593
+ ],
594
+ },
595
+ ],
596
+ },
597
+ {
598
+ label: 'North America',
599
+ value: 'North America',
600
+ key: '1',
601
+ children: [
602
+ {
603
+ label: 'United States',
604
+ value: 'United States',
605
+ key: '1-0',
606
+ },
607
+ {
608
+ label: 'Canada',
609
+ value: 'Canada',
610
+ key: '1-1',
611
+ },
612
+ ],
613
+ },
614
+ ];
615
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
616
+ </script>
617
+
618
+ <Tree disableStrictly multiple {style} {treeData} value="Shanghai" />
619
+ ```
620
+
621
+ ### Checked RelationShip
622
+
623
+ When multiple selections are made, `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.
624
+
625
+ ```svelte
626
+ <script lang="ts">
627
+ import { Tree } from '@fibrae/semi-ui-svelte';
628
+
629
+ const treeData = [
630
+ {
631
+ label: 'Asia',
632
+ value: 'Asia',
633
+ key: '0',
634
+ children: [
635
+ {
636
+ label: 'China',
637
+ value: 'China',
638
+ key: '0-0',
639
+ children: [
640
+ {
641
+ label: 'Beijing',
642
+ value: 'Beijing',
643
+ key: '0-0-0',
644
+ },
645
+ {
646
+ label: 'Shanghai',
647
+ value: 'Shanghai',
648
+ key: '0-0-1',
649
+ },
650
+ {
651
+ label: 'Chengdu',
652
+ value: 'Chengdu',
653
+ key: '0-0-2',
654
+ },
655
+ ],
656
+ },
657
+ {
658
+ label: 'Japan',
659
+ value: 'Japan',
660
+ key: '0-1',
661
+ children: [
662
+ {
663
+ label: 'Osaka',
664
+ value: 'Osaka',
665
+ key: '0-1-0',
666
+ },
667
+ ],
668
+ },
669
+ ],
670
+ },
671
+ {
672
+ label: 'North America',
673
+ value: 'North America',
674
+ key: '1',
675
+ children: [
676
+ {
677
+ label: 'United States',
678
+ value: 'United States',
679
+ key: '1-0',
680
+ },
681
+ {
682
+ label: 'Canada',
683
+ value: 'Canada',
684
+ key: '1-1',
685
+ },
686
+ ],
687
+ },
688
+ ];
689
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
690
+ </script>
691
+
692
+ <Tree checkRelation="unRelated" defaultExpandAll multiple {style} {treeData} />
693
+ ```
694
+
695
+ ### Default Expand All
696
+
697
+ Both `defaultExpandAll` and `expandAll` can set the default expanded/collapsed state of `Tree`. The difference between the two is that `defaultExpandAll` only takes effect at initialization, while `expandAll` will not only take effect at initialization, but also when the data (`treeData`/`treeDataSimpleJson`) is dynamically updated, `expandAll` will still take effect.
698
+
699
+ In the demo below, after clicking the button to update `TreeData`, `defaultExpandAll` becomes invalid, and `expandAll` still takes effect.
700
+
701
+ ```svelte
702
+ <script lang="ts">
703
+ import { Button, Tree, type TreeProps } from '@fibrae/semi-ui-svelte';
704
+
705
+ const json = {
706
+ Node1: {
707
+ 'Child Node1': '0-0-1',
708
+ 'Child Node2': '0-0-2',
709
+ },
710
+ Node2: '0-1',
711
+ };
712
+ const json2 = {
713
+ Node3: {
714
+ 'Child Node1': '0-0-1',
715
+ 'Child Node2': '0-0-2',
716
+ 'Child Node3': '0-0-3',
717
+ 'Child Node4': '0-0-4',
718
+ },
719
+ Node2: '0-1',
720
+ };
721
+ const style = 'margin-right: 20px; width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
722
+ let tree = $state<TreeProps['treeDataSimpleJson']>(json);
723
+ </script>
724
+
725
+ <Button style="margin-bottom: 10px" onclick={() => (tree = json2)}>点击更新 TreeData</Button>
726
+ <div style="display: flex">
727
+ <div>
728
+ <span>defaultExpandAll</span>
729
+ <Tree defaultExpandAll {style} treeDataSimpleJson={tree} />
730
+ </div>
731
+ <div>
732
+ <span>expandAll</span>
733
+ <Tree expandAll {style} treeDataSimpleJson={tree} />
734
+ </div>
735
+ </div>
736
+ ```
737
+
738
+ ### Controlled Expansion with Search
739
+
740
+ Bind the expanded nodes with `bind:expandedKeys`, or use it along with `onExpand`. `bind:expandedKeys={get, set}` makes the expansion fully controlled; unbound, the given `expandedKeys` is only the initially expanded nodes. When the expansion is controlled, if you enable `filterTreeNode` and search, the node will not be automatically expanded. At this time, the expansion of the node is completely controlled by `expandedKeys`. You can use the second parameter `filteredExpandedKeys` of `onSearch` to realize the search expansion effect when the expansion is controlled.
741
+
742
+ ```svelte
743
+ <script lang="ts">
744
+ import { Tree } from '@fibrae/semi-ui-svelte';
745
+
746
+ let expandedKeys = $state<string[]>([]);
747
+ const treeData = [
748
+ {
749
+ label: '亚洲',
750
+ value: 'Asia',
751
+ key: '0',
752
+ children: [
753
+ {
754
+ label: '中国',
755
+ value: 'China',
756
+ key: '0-0',
757
+ children: [
758
+ {
759
+ label: '北京',
760
+ value: 'Beijing',
761
+ key: '0-0-0',
762
+ },
763
+ {
764
+ label: '上海',
765
+ value: 'Shanghai',
766
+ key: '0-0-1',
767
+ },
768
+ ],
769
+ },
770
+ {
771
+ label: '日本',
772
+ value: 'Japan',
773
+ key: '0-1',
774
+ },
775
+ ],
776
+ },
777
+ {
778
+ label: '北美洲',
779
+ value: 'North America',
780
+ key: '1',
781
+ },
782
+ ];
783
+
784
+ const handleSearch = (_inputValue: string, filteredExpandedKeys: string[]) => {
785
+ expandedKeys = [...filteredExpandedKeys];
786
+ };
787
+ </script>
788
+
789
+ <Tree bind:expandedKeys filterTreeNode onSearch={handleSearch} style="width: 300px" {treeData} />
790
+ ```
791
+
792
+ ### Controlled Component
793
+
794
+ Bind `value` with `bind:value`, or use it along with `onChange`. `bind:value={get, set}` makes it fully controlled. Unbound, the given `value` is only the initial selection.
795
+
796
+ ```svelte
797
+ <script lang="ts">
798
+ import { Tree, type TreeValue } from '@fibrae/semi-ui-svelte';
799
+
800
+ const treeData = [
801
+ {
802
+ label: '亚洲',
803
+ value: 'Asia',
804
+ key: '0',
805
+ children: [
806
+ {
807
+ label: '中国',
808
+ value: 'China',
809
+ key: '0-0',
810
+ children: [
811
+ {
812
+ label: '北京',
813
+ value: 'Beijing',
814
+ key: '0-0-0',
815
+ },
816
+ {
817
+ label: '上海',
818
+ value: 'Shanghai',
819
+ key: '0-0-1',
820
+ },
821
+ ],
822
+ },
823
+ ],
824
+ },
825
+ {
826
+ label: '北美洲',
827
+ value: 'North America',
828
+ key: '1',
829
+ },
830
+ ];
831
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
832
+ let value = $state<TreeValue>('Shanghai');
833
+ </script>
834
+
835
+ <Tree bind:value {style} {treeData} />
836
+ ```
837
+
838
+ ### Auto Expand Parent
839
+
840
+ In the case of controlled expansion, when `autoExpandParent` is turned on, if you want to collapse the parent element, you need to collapse all its child elements. By default, `autoExpandParent` is false, that is, the collapse of the parent element is not affected by the child element.
841
+
842
+ ```svelte
843
+ <script lang="ts">
844
+ import { Tree } from '@fibrae/semi-ui-svelte';
845
+
846
+ const treeData = [
847
+ {
848
+ label: '亚洲',
849
+ value: 'Asia',
850
+ key: '0',
851
+ children: [
852
+ {
853
+ label: '中国',
854
+ value: 'China',
855
+ key: '0-0',
856
+ children: [
857
+ {
858
+ label: '北京',
859
+ value: 'Beijing',
860
+ key: '0-0-0',
861
+ },
862
+ {
863
+ label: '上海',
864
+ value: 'Shanghai',
865
+ key: '0-0-1',
866
+ },
867
+ ],
868
+ },
869
+ ],
870
+ },
871
+ {
872
+ label: '北美洲',
873
+ value: 'North America',
874
+ key: '1',
875
+ },
876
+ ];
877
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
878
+ let expandedKeys = $state(['0', '0-0']);
879
+ </script>
880
+
881
+ <div>需要先将“中国”节点收起后,才能够收起“亚洲”节点</div>
882
+ <br />
883
+ <Tree autoExpandParent bind:expandedKeys {style} {treeData} />
884
+ ```
885
+
886
+ ### Custom expansion icon
887
+
888
+ The expansion Icon can be customized through the `expandIcon` snippet, whose arguments are `onClick`, `class` and `expanded`. Put `class` and `onclick` on the element it renders.
889
+
890
+ ```svelte
891
+ <Tree {treeData}>
892
+ {#snippet expandIcon({ expanded, onClick, class: className })}
893
+ {#if expanded}
894
+ <IconMinus class={className} onclick={onClick} />
895
+ {:else}
896
+ <IconPlus class={className} onclick={onClick} />
897
+ {/if}
898
+ {/snippet}
899
+ </Tree>
900
+ ```
901
+
902
+ Examples are as follows:
903
+
904
+ ```svelte
905
+ <script lang="ts">
906
+ import { IconChevronDown, IconMinus, IconPlus } from '@fibrae/semi-icons-svelte';
907
+ import { Tree } from '@fibrae/semi-ui-svelte';
908
+
909
+ const treeData = [
910
+ {
911
+ label: '亚洲',
912
+ key: 'yazhou',
913
+ children: [
914
+ {
915
+ label: '中国',
916
+ key: 'zhongguo',
917
+ children: [
918
+ {
919
+ label: '北京',
920
+ key: 'beijing',
921
+ },
922
+ {
923
+ label: '上海',
924
+ key: 'shanghai',
925
+ },
926
+ ],
927
+ },
928
+ {
929
+ label: '日本',
930
+ key: 'riben',
931
+ },
932
+ ],
933
+ },
934
+ {
935
+ label: '北美洲',
936
+ key: 'beimeizhou',
937
+ },
938
+ ];
939
+ const style = 'width: 260px; height: 200px; border: 1px solid var(--semi-color-border)';
940
+ </script>
941
+
942
+ <p>expandIcon 是固定的图标</p>
943
+ <Tree expandedKeys={['yazhou']} multiple {style} {treeData}>
944
+ {#snippet expandIcon()}
945
+ <IconChevronDown class="testCls" size="small" />
946
+ {/snippet}
947
+ </Tree>
948
+ <br />
949
+ <p>expandIcon 随展开状态变化</p>
950
+ <Tree expandedKeys={['yazhou']} multiple {style} {treeData}>
951
+ {#snippet expandIcon(iconProps)}
952
+ {#if iconProps.expanded}
953
+ <IconMinus class={iconProps.class} size="small" onclick={iconProps.onClick} />
954
+ {:else}
955
+ <IconPlus class={iconProps.class} size="small" onclick={iconProps.onClick} />
956
+ {/if}
957
+ {/snippet}
958
+ </Tree>
959
+ ```
960
+
961
+ ### Tree with line
962
+
963
+ Set the line between nodes through `showLine`, the default is false.
964
+
965
+ ```svelte
966
+ <script lang="ts">
967
+ import { Switch, Tree } from '@fibrae/semi-ui-svelte';
968
+
969
+ let show = $state(true);
970
+
971
+ const treeData = [
972
+ {
973
+ label: 'parent-0',
974
+ key: 'parent-0',
975
+ children: [
976
+ {
977
+ label: 'leaf-0-0',
978
+ key: 'leaf-0-0',
979
+ children: [
980
+ { label: 'leaf-0-0-0', key: 'leaf-0-0-0' },
981
+ { label: 'leaf-0-0-1', key: 'leaf-0-0-1' },
982
+ { label: 'leaf-0-0-2', key: 'leaf-0-0-2' },
983
+ ],
984
+ },
985
+ { label: 'leaf-0-1', key: 'leaf-0-1' },
986
+ ],
987
+ },
988
+ { label: 'parent-1', key: 'parent-1' },
989
+ ];
990
+
991
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
992
+ </script>
993
+
994
+ <div style="display: flex; align-items: center; column-gap: 5px; margin-bottom: 5px">
995
+ <strong id="tree-line-show-line">showLine </strong>
996
+ <Switch aria-labelledby="tree-line-show-line" bind:checked={show} />
997
+ </div>
998
+ <Tree defaultExpandAll showLine={show} {style} {treeData} />
999
+ ```
1000
+
1001
+ ### Virtualized Tree
1002
+
1003
+ If you need to render large sets of tree structured data, you could use virtualized tree. In virtualized mode, animation / motion is disabled for better performance.
1004
+
1005
+ The property `virtualize` is an object consisting of the following values:
1006
+
1007
+ - height: Height of the tree, If passed in as a string, computed height should not be zero for render purpose, in other words, parent node should have offsetHeight
1008
+ - width: Width of the tree.
1009
+ - itemSize: Height for each line of treeNode, required
1010
+
1011
+ If tree is searchable, you could also turn on `showFilteredOnly` to reduce time of rendering for results.
1012
+
1013
+ ```svelte
1014
+ <script lang="ts">
1015
+ import { Button, Tree, type TreeNodeData } from '@fibrae/semi-ui-svelte';
1016
+
1017
+ const style = 'width: 260px; border: 1px solid var(--semi-color-border)';
1018
+
1019
+ const virtualize = {
1020
+ // A set Tree height fills the remaining space
1021
+ height: 300,
1022
+ itemSize: 28,
1023
+ };
1024
+
1025
+ const generateData = (x = 5, y = 4, z = 3, data: TreeNodeData[] = []) => {
1026
+ // x: nodes per level. y: nodes with children per level. z: depth (0 is one level)
1027
+ const fill = (level: number, preKey: string, nodes: TreeNodeData[]) => {
1028
+ const parents: string[] = [];
1029
+ for (let i = 0; i < x; i++) {
1030
+ const key = `${preKey}-${i}`;
1031
+ nodes.push({ label: `${key}-标签`, key: `${key}-key`, value: `${key}-value` });
1032
+ if (i < y) {
1033
+ parents.push(key);
1034
+ }
1035
+ }
1036
+ if (level < 0) {
1037
+ return;
1038
+ }
1039
+ parents.forEach((key, index) => {
1040
+ const children: TreeNodeData[] = [];
1041
+ nodes[index].children = children;
1042
+ fill(level - 1, key, children);
1043
+ });
1044
+ };
1045
+ fill(z, '0', data);
1046
+
1047
+ let total = 0;
1048
+ for (let n = z + 1; n >= 0; n--) {
1049
+ total += x * y ** n;
1050
+ }
1051
+ return { gData: data, total };
1052
+ };
1053
+
1054
+ let gData = $state.raw<TreeNodeData[]>([]);
1055
+ let total = $state(0);
1056
+
1057
+ const onGen = () => {
1058
+ const data = generateData();
1059
+ gData = data.gData;
1060
+ total = data.total;
1061
+ };
1062
+ </script>
1063
+
1064
+ <div style="padding: 0 20px">
1065
+ <Button onclick={onGen}>生成数据:</Button>
1066
+ <span>共 {total} 个节点</span>
1067
+ <br />
1068
+ <br />
1069
+ {#if gData.length}
1070
+ <Tree filterTreeNode showFilteredOnly {style} treeData={gData} {virtualize} />
1071
+ {/if}
1072
+ </div>
1073
+ ```
1074
+
1075
+ ### Dynamic Update of Data
1076
+
1077
+ `treeData` is replaced as a whole: only a new array updates the tree, while changes made in place to the array or a node are not seen. Declare the data with `$state.raw` and assign a new array after changing it.
1078
+
1079
+ ```svelte
1080
+ <script lang="ts">
1081
+ import { Button, Tree, type TreeNodeData } from '@fibrae/semi-ui-svelte';
1082
+
1083
+ const style = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
1084
+
1085
+ let treeData = $state.raw<TreeNodeData[]>([
1086
+ {
1087
+ key: '0',
1088
+ label: 'item-0',
1089
+ value: '0',
1090
+ },
1091
+ ]);
1092
+
1093
+ const add = () => {
1094
+ const itemLength = Math.floor(Math.random() * 5) + 1;
1095
+ treeData = Array.from({ length: itemLength }).map((_, i) => {
1096
+ const length = Math.floor(Math.random() * 3);
1097
+ const children = Array.from({ length }).map((_, ci) => ({
1098
+ key: `${i}-${ci}`,
1099
+ label: `Leaf-${i}-${ci}`,
1100
+ value: `${i}-${ci}`,
1101
+ }));
1102
+ return {
1103
+ key: `${i}`,
1104
+ label: `Item-${i}`,
1105
+ value: `${i}`,
1106
+ children,
1107
+ };
1108
+ });
1109
+ };
1110
+ </script>
1111
+
1112
+ <div {style}>
1113
+ <Tree {treeData} />
1114
+ <br />
1115
+ <Button style="margin: 20px" onclick={add}>动态改变数据</Button>
1116
+ </div>
1117
+ ```
1118
+
1119
+ ### Load Data Asynchronously
1120
+
1121
+ You could use `loadData` to load treeData asynchronously on node expansion. Notice `isLeaf` is required to mark node as leaf in treeData.
1122
+
1123
+ ```svelte
1124
+ <script lang="ts">
1125
+ import { Tree, type TreeNodeData } from '@fibrae/semi-ui-svelte';
1126
+
1127
+ let treeData = $state.raw<TreeNodeData[]>([
1128
+ { label: 'Expand to load', value: '0', key: '0' },
1129
+ { label: 'Expand to load', value: '1', key: '1' },
1130
+ { label: 'Leaf Node', value: '2', key: '2', isLeaf: true },
1131
+ ]);
1132
+
1133
+ const updateTreeData = (list: TreeNodeData[], key: string | undefined, children: TreeNodeData[]): TreeNodeData[] => {
1134
+ return list.map((node) => {
1135
+ if (node.key === key) {
1136
+ return { ...node, children };
1137
+ }
1138
+ if (node.children) {
1139
+ return { ...node, children: updateTreeData(node.children, key, children) };
1140
+ }
1141
+ return node;
1142
+ });
1143
+ };
1144
+
1145
+ const onLoadData = (treeNode?: TreeNodeData) => {
1146
+ const key = treeNode?.key;
1147
+ return new Promise<void>((resolve) => {
1148
+ if (treeNode?.children) {
1149
+ resolve();
1150
+ return;
1151
+ }
1152
+ setTimeout(() => {
1153
+ treeData = updateTreeData(treeData, key, [
1154
+ { label: 'Child Node', key: `${key}-0` },
1155
+ { label: 'Child Node', key: `${key}-1` },
1156
+ ]);
1157
+ resolve();
1158
+ }, 1000);
1159
+ });
1160
+ };
1161
+ </script>
1162
+
1163
+ <Tree loadData={onLoadData} {treeData} />
1164
+ ```
1165
+
1166
+ ### Draggable Tree
1167
+
1168
+ You could use `draggable` along with `onDrop` to achieve a draggable Tree.
1169
+
1170
+ > **Notice**
1171
+ >
1172
+ > Simultaneous use with virtualization is currently not supported
1173
+
1174
+ The argument of each drag callback is one object with the following fields:
1175
+
1176
+ ```
1177
+ - onDragEnd: { event, node: TreeDragNode }
1178
+ - onDragEnter: { event, node: TreeDragNode, expandedKeys?: string[] }
1179
+ - onDragLeave: { event, node: TreeDragNode }
1180
+ - onDragOver: { event, node: TreeDragNode }
1181
+ - onDragStart: { event, node: TreeDragNode }
1182
+ - onDrop: { event, node: TreeDragNode, dragNode: TreeDragNode, dragNodesKeys: string[], dropPosition: number, dropToGap: boolean }
1183
+ ```
1184
+
1185
+ The data type TreeDragNode, in addition to all the attributes of TreeNodeData, also includes expanded and pos attributes,
1186
+
1187
+ ```
1188
+ TreeDragNode {
1189
+ expanded: boolean,
1190
+ pos: string
1191
+ value?: string | number;
1192
+ label?: string | number;
1193
+ disabled?: boolean;
1194
+ isLeaf?: boolean;
1195
+ [key: string]: any;
1196
+ }
1197
+ ```
1198
+
1199
+ - `pos` refers to the positional relationship of the current node in the entire treeData, such as the 0th node of the 2nd node of the 1st node of the 0th layer: '0-1-2-0'
1200
+ - `dropPosition` refers to the position where the dragged node is dropped in the current hierarchy. If it is inserted before the 0th node of the same level, it will be -1, and after the 0th node, it will be 1, and it will fall on it. is 0, and so on. With dropToGap, a more complete judgment can be obtained.
1201
+ - `dropToGap` refers to whether the dragged node is dropped between nodes, if false, it is dropped above a node
1202
+
1203
+ ```svelte
1204
+ <script lang="ts">
1205
+ import { Tree, type TreeNodeData, type TreeOnDragProps } from '@fibrae/semi-ui-svelte';
1206
+
1207
+ type LoopCallback = (item: TreeNodeData, ind: number, arr: TreeNodeData[]) => void;
1208
+
1209
+ let treeData = $state.raw<TreeNodeData[]>([
1210
+ {
1211
+ label: 'Asia',
1212
+ value: 'Asia',
1213
+ key: '0',
1214
+ children: [
1215
+ {
1216
+ label: 'China',
1217
+ value: 'China',
1218
+ key: '0-0',
1219
+ children: [
1220
+ {
1221
+ label: 'Beijing',
1222
+ value: 'Beijing',
1223
+ key: '0-0-0',
1224
+ },
1225
+ {
1226
+ label: 'Shanghai',
1227
+ value: 'Shanghai',
1228
+ key: '0-0-1',
1229
+ },
1230
+ ],
1231
+ },
1232
+ {
1233
+ label: 'Japan',
1234
+ value: 'Japan',
1235
+ key: '0-1',
1236
+ children: [
1237
+ {
1238
+ label: 'Osaka',
1239
+ value: 'Osaka',
1240
+ key: '0-1-0',
1241
+ },
1242
+ ],
1243
+ },
1244
+ ],
1245
+ },
1246
+ {
1247
+ label: 'North America',
1248
+ value: 'North America',
1249
+ key: '1',
1250
+ children: [
1251
+ {
1252
+ label: 'United States',
1253
+ value: 'United States',
1254
+ key: '1-0',
1255
+ },
1256
+ {
1257
+ label: 'Canada',
1258
+ value: 'Canada',
1259
+ key: '1-1',
1260
+ },
1261
+ ],
1262
+ },
1263
+ {
1264
+ label: 'Europe',
1265
+ value: 'Europe',
1266
+ key: '2',
1267
+ },
1268
+ ]);
1269
+
1270
+ const onDrop = (info: TreeOnDragProps) => {
1271
+ const { dropToGap, node, dragNode } = info;
1272
+ const dropKey = node.key;
1273
+ const dragKey = dragNode.key;
1274
+ const dropPos = node.pos.split('-');
1275
+ const dropPosition = info.dropPosition - Number(dropPos[dropPos.length - 1]);
1276
+
1277
+ const data = [...treeData];
1278
+ const loop = (data: TreeNodeData[], key: string | undefined, callback: LoopCallback) => {
1279
+ data.forEach((item, ind, arr) => {
1280
+ if (item.key === key) return callback(item, ind, arr);
1281
+ if (item.children) return loop(item.children, key, callback);
1282
+ });
1283
+ };
1284
+ let dragObj: TreeNodeData = {};
1285
+ loop(data, dragKey, (item, ind, arr) => {
1286
+ arr.splice(ind, 1);
1287
+ dragObj = item;
1288
+ });
1289
+
1290
+ if (!dropToGap) {
1291
+ loop(data, dropKey, (item) => {
1292
+ item.children ||= [];
1293
+ item.children.push(dragObj);
1294
+ });
1295
+ } else if (dropPosition === 1 && node.children && node.expanded) {
1296
+ // Expanded with children and dropped in the bottom gap: insert at the top
1297
+ loop(data, dropKey, (item) => {
1298
+ item.children ||= [];
1299
+ item.children.unshift(dragObj);
1300
+ });
1301
+ } else {
1302
+ let dropNodeInd = 0;
1303
+ let dropNodePosArr: TreeNodeData[] = [];
1304
+ loop(data, dropKey, (_item, ind, arr) => {
1305
+ dropNodePosArr = arr;
1306
+ dropNodeInd = ind;
1307
+ });
1308
+ if (dropPosition === -1) {
1309
+ dropNodePosArr.splice(dropNodeInd, 0, dragObj);
1310
+ } else {
1311
+ dropNodePosArr.splice(dropNodeInd + 1, 0, dragObj);
1312
+ }
1313
+ }
1314
+ treeData = data;
1315
+ };
1316
+ </script>
1317
+
1318
+ <Tree draggable {onDrop} {treeData} />
1319
+ ```
1320
+
1321
+ ### Advanced FullRender
1322
+
1323
+ You could use the `fullLabel` snippet for advanced rendering to render the content of the entire row on your own.
1324
+
1325
+ The row element (`li`) carrying the `id`, `role="treeitem"` and the row state is provided by Tree itself, and so is the positioning style of a virtualized tree; the snippet holds only what is inside the row. Bind the `class` argument to the content element and it gets the same indentation, selection and focus styles and the same inline padding as a built-in row. The keyboard is handled by Tree, so a click inside the row is only a pointer shortcut.
1326
+
1327
+ The snippet argument types are as follows:
1328
+
1329
+ ```ts
1330
+ type TreeFullLabelSnippetProps = {
1331
+ /* The original data of the row */
1332
+ data: TreeNodeData;
1333
+ /* The level of the line can be used to customize the indentation value */
1334
+ level: number;
1335
+ /* Class name, including built-in styles such as indentation, selection, focus and drag state */
1336
+ class: string;
1337
+ /* The built-in expand button, rendered with {@render expandIcon()} */
1338
+ expandIcon: Snippet;
1339
+ /* Selected state */
1340
+ checkStatus: {
1341
+ /* Whether to select in the multi-select state */
1342
+ checked: boolean;
1343
+ /* Whether to half-select in the multi-select state */
1344
+ halfChecked: boolean;
1345
+ };
1346
+ /* Expand status */
1347
+ expandStatus: {
1348
+ /* Has it been expanded */
1349
+ expanded: boolean;
1350
+ /* Is it unfolding */
1351
+ loading: boolean;
1352
+ };
1353
+ /* Whether the node meets the search conditions */
1354
+ filtered: boolean;
1355
+ /* Current search box input */
1356
+ searchWord: string;
1357
+ /* Click the callback of the entire row: selects it, or checks it in a multiple tree */
1358
+ onClick: (event: MouseEvent) => void;
1359
+ /* Multi-select click callback */
1360
+ onCheck: (event: MouseEvent) => void;
1361
+ /* expand callback */
1362
+ onExpand: (event: MouseEvent) => void;
1363
+ /* Right-click the callback for the entire row */
1364
+ onContextmenu: (event: MouseEvent) => void;
1365
+ /* Double-click the entire line of callback */
1366
+ onDblclick: (event: MouseEvent) => void;
1367
+ };
1368
+ ```
1369
+
1370
+ ```svelte
1371
+ <Tree {treeData}>
1372
+ {#snippet fullLabel({ data, class: className, onClick })}
1373
+ <div class={className} onclick={onClick} role="presentation">{data.label}</div>
1374
+ {/snippet}
1375
+ </Tree>
1376
+ ```
1377
+
1378
+ Here are some demos.
1379
+
1380
+ First is to render Parent node as separator and only allow leaf nodes to be selected.\
1381
+ `fullLabel` only takes care of the UI rendering and won't affect inside data logic. But you could choose info to your needs and use it with controlled mode for advanced usage.
1382
+
1383
+ ```svelte
1384
+ <script lang="ts">
1385
+ import { Checkbox, Tree } from '@fibrae/semi-ui-svelte';
1386
+
1387
+ const treeData = [
1388
+ {
1389
+ label: 'Asia',
1390
+ value: 'Asia',
1391
+ key: '0',
1392
+ children: [
1393
+ {
1394
+ label: 'China',
1395
+ value: 'China',
1396
+ key: '0-0',
1397
+ children: [
1398
+ {
1399
+ label: 'Beijing',
1400
+ value: 'Beijing',
1401
+ key: '0-0-0',
1402
+ },
1403
+ {
1404
+ label: 'Shanghai',
1405
+ value: 'Shanghai',
1406
+ key: '0-0-1',
1407
+ },
1408
+ ],
1409
+ },
1410
+ {
1411
+ label: 'Japan',
1412
+ value: 'Japan',
1413
+ key: '0-1',
1414
+ children: [
1415
+ {
1416
+ label: 'Osaka',
1417
+ value: 'Osaka',
1418
+ key: '0-1-0',
1419
+ },
1420
+ ],
1421
+ },
1422
+ ],
1423
+ },
1424
+ {
1425
+ label: 'North America',
1426
+ value: 'North America',
1427
+ key: '1',
1428
+ children: [
1429
+ {
1430
+ label: 'United States',
1431
+ value: 'United States',
1432
+ key: '1-0',
1433
+ },
1434
+ {
1435
+ label: 'Canada',
1436
+ value: 'Canada',
1437
+ key: '1-1',
1438
+ },
1439
+ ],
1440
+ },
1441
+ ];
1442
+
1443
+ const treeStyle = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
1444
+ </script>
1445
+
1446
+ <Tree leafOnly multiple style={treeStyle} {treeData}>
1447
+ <!-- Focus stays on the tree (arrows expand, Enter/Space check), so the inline checkbox is display-only -->
1448
+ {#snippet fullLabel(row)}
1449
+ <div class={row.class} role="presentation" onclick={row.data.children?.length ? row.onExpand : row.onCheck}>
1450
+ {#if row.data.children?.length}
1451
+ {@render row.expandIcon()}
1452
+ {:else}
1453
+ <Checkbox aria-hidden="true" checked={row.checkStatus.checked} indeterminate={row.checkStatus.halfChecked} style="margin-right: 8px" tabindex={-1} />
1454
+ {/if}
1455
+ <span>{row.data.label}</span>
1456
+ </div>
1457
+ {/snippet}
1458
+ </Tree>
1459
+ ```
1460
+
1461
+ The second is for the scenario of "I hope that only leaf nodes can be single-selected, and the parent node only plays a role in grouping".
1462
+
1463
+ - You only need to click on the parent node without triggering the selection, click on the leaf node to trigger.
1464
+
1465
+ ```svelte
1466
+ <script lang="ts">
1467
+ import { Tree } from '@fibrae/semi-ui-svelte';
1468
+
1469
+ const treeData = [
1470
+ {
1471
+ label: 'Asia',
1472
+ value: 'Asia',
1473
+ key: '0',
1474
+ children: [
1475
+ {
1476
+ label: 'China',
1477
+ value: 'China',
1478
+ key: '0-0',
1479
+ children: [
1480
+ { label: 'Beijing', value: 'Beijing', key: '0-0-0' },
1481
+ { label: 'Shanghai', value: 'Shanghai', key: '0-0-1' },
1482
+ ],
1483
+ },
1484
+ {
1485
+ label: 'Japan',
1486
+ value: 'Japan',
1487
+ key: '0-1',
1488
+ children: [{ label: 'Osaka', value: 'Osaka', key: '0-1-0' }],
1489
+ },
1490
+ ],
1491
+ },
1492
+ {
1493
+ label: 'North America',
1494
+ value: 'North America',
1495
+ key: '1',
1496
+ children: [
1497
+ { label: 'United States', value: 'United States', key: '1-0' },
1498
+ { label: 'Canada', value: 'Canada', key: '1-1' },
1499
+ ],
1500
+ },
1501
+ ];
1502
+
1503
+ const treeStyle = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
1504
+ </script>
1505
+
1506
+ <Tree onChange={(...args) => console.log('change', ...args)} style={treeStyle} {treeData}>
1507
+ {#snippet fullLabel(row)}
1508
+ <div class={row.class} role="presentation" onclick={row.data.children?.length ? row.onExpand : row.onClick}>
1509
+ {@render row.expandIcon()}
1510
+ <span>{row.data.label}</span>
1511
+ </div>
1512
+ {/snippet}
1513
+ </Tree>
1514
+ ```
1515
+
1516
+ Third is for the scenario when selecting Parent node also highlighting child node.
1517
+
1518
+ ```svelte
1519
+ <script lang="ts">
1520
+ import type { Component } from 'svelte';
1521
+ import { IconAbsoluteStroked, IconComponentStroked, IconFixedStroked, IconInnerSectionStroked, IconSectionStroked } from '@fibrae/semi-icons-svelte';
1522
+ import { Tree, type TreeNodeData } from '@fibrae/semi-ui-svelte';
1523
+
1524
+ const icons: Record<string, Component<{ style?: string }>> = {
1525
+ 'fix-btn-0': IconFixedStroked,
1526
+ 'module-0': IconSectionStroked,
1527
+ 'free-compo-0': IconAbsoluteStroked,
1528
+ 'split-col-0': IconInnerSectionStroked,
1529
+ 'btn-0': IconComponentStroked,
1530
+ 'btn-1': IconComponentStroked,
1531
+ 'module-1': IconSectionStroked,
1532
+ 'cus-0': IconComponentStroked,
1533
+ };
1534
+ const iconStyle = 'margin-right: 8px; color: var(--semi-color-text-2)';
1535
+
1536
+ let selected = $state.raw(new Set<string | undefined>());
1537
+ let selectedThroughParent = $state.raw(new Set<string | undefined>());
1538
+ const treeData = [
1539
+ {
1540
+ label: '黑色固定按钮',
1541
+ key: 'fix-btn-0',
1542
+ },
1543
+ {
1544
+ label: '模块',
1545
+ key: 'module-0',
1546
+ children: [
1547
+ {
1548
+ label: '可自由摆放的组件',
1549
+ key: 'free-compo-0',
1550
+ },
1551
+ {
1552
+ label: '分栏容器',
1553
+ key: 'split-col-0',
1554
+ children: [
1555
+ {
1556
+ label: '按钮组件',
1557
+ key: 'btn-0',
1558
+ },
1559
+ {
1560
+ label: '按钮组件',
1561
+ key: 'btn-1',
1562
+ },
1563
+ ],
1564
+ },
1565
+ ],
1566
+ },
1567
+ {
1568
+ label: '模块',
1569
+ key: 'module-1',
1570
+ children: [
1571
+ {
1572
+ label: '自定义组件',
1573
+ key: 'cus-0',
1574
+ },
1575
+ ],
1576
+ },
1577
+ ];
1578
+
1579
+ const findDescendantKeys = (node: TreeNodeData) => {
1580
+ const res = [node.key];
1581
+ const findChild = (item?: TreeNodeData) => {
1582
+ if (!item) return;
1583
+ const { children } = item;
1584
+
1585
+ if (children && children.length) {
1586
+ children.forEach((child) => {
1587
+ res.push(child.key);
1588
+ findChild(child);
1589
+ });
1590
+ }
1591
+ };
1592
+ findChild(node);
1593
+ return res;
1594
+ };
1595
+
1596
+ const handleSelect = (key: string, _bool: boolean, node: TreeNodeData) => {
1597
+ selected = new Set([key]);
1598
+ selectedThroughParent = new Set(findDescendantKeys(node));
1599
+ };
1600
+
1601
+ const rowBackground = (key?: string) => {
1602
+ if (selected.has(key)) return 'var(--semi-blue-0)';
1603
+ if (selectedThroughParent.has(key)) return 'color-mix(in srgb, var(--semi-blue-0) 50%, transparent)';
1604
+ return 'transparent';
1605
+ };
1606
+
1607
+ const treeStyle = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
1608
+ </script>
1609
+
1610
+ <Tree defaultExpandAll onSelect={handleSelect} style={treeStyle} {treeData}>
1611
+ {#snippet fullLabel(row)}
1612
+ {@const Icon = icons[row.data.key ?? '']}
1613
+ <!-- the tree handles the keyboard: the row is a pointer shortcut -->
1614
+ <div class={row.class} role="presentation" style:background-color={rowBackground(row.data.key)} onclick={row.onClick}>
1615
+ {#if !row.data.children?.length}
1616
+ <span style="width: 24px"></span>
1617
+ {:else}
1618
+ {@render row.expandIcon()}
1619
+ {/if}
1620
+ <Icon style={iconStyle} />
1621
+ <span>{row.data.label}</span>
1622
+ </div>
1623
+ {/snippet}
1624
+ </Tree>
1625
+ ```
1626
+
1627
+ ### Advanced FullRender with Draggable
1628
+
1629
+ Draggable (`draggable`) and advanced customization (`fullLabel`) can be used at the same time.
1630
+
1631
+ ```svelte
1632
+ <script lang="ts">
1633
+ import type { Component } from 'svelte';
1634
+ import { IconAbsoluteStroked, IconComponentStroked, IconFixedStroked, IconSectionStroked } from '@fibrae/semi-icons-svelte';
1635
+ import { Tree, type TreeNodeData, type TreeOnDragProps } from '@fibrae/semi-ui-svelte';
1636
+
1637
+ type LoopCallback = (item: TreeNodeData, ind: number, arr: TreeNodeData[]) => void;
1638
+
1639
+ const icons: Record<string, Component<{ style?: string }>> = {
1640
+ 'fix-btn-0': IconFixedStroked,
1641
+ 'module-0': IconSectionStroked,
1642
+ 'free-compo-0': IconAbsoluteStroked,
1643
+ 'split-col-0': IconSectionStroked,
1644
+ 'btn-0': IconComponentStroked,
1645
+ 'btn-1': IconComponentStroked,
1646
+ 'module-1': IconSectionStroked,
1647
+ 'cus-0': IconComponentStroked,
1648
+ };
1649
+ const iconStyle = 'margin-right: 8px; color: var(--semi-color-text-2)';
1650
+
1651
+ let selected = $state.raw(new Set<string | undefined>());
1652
+ let selectedThroughParent = $state.raw(new Set<string | undefined>());
1653
+ let treeData = $state.raw<TreeNodeData[]>([
1654
+ {
1655
+ label: '黑色固定按钮',
1656
+ key: 'fix-btn-0',
1657
+ },
1658
+ {
1659
+ label: '模块',
1660
+ key: 'module-0',
1661
+ children: [
1662
+ {
1663
+ label: '可自由摆放的组件',
1664
+ key: 'free-compo-0',
1665
+ },
1666
+ {
1667
+ label: '分栏容器',
1668
+ key: 'split-col-0',
1669
+ children: [
1670
+ {
1671
+ label: '按钮组件',
1672
+ key: 'btn-0',
1673
+ },
1674
+ {
1675
+ label: '按钮组件',
1676
+ key: 'btn-1',
1677
+ },
1678
+ ],
1679
+ },
1680
+ ],
1681
+ },
1682
+ {
1683
+ label: '模块',
1684
+ key: 'module-1',
1685
+ children: [
1686
+ {
1687
+ label: '自定义组件',
1688
+ key: 'cus-0',
1689
+ },
1690
+ ],
1691
+ },
1692
+ ]);
1693
+
1694
+ const onDrop = (info: TreeOnDragProps) => {
1695
+ const { dropToGap, node, dragNode } = info;
1696
+ const dropKey = node.key;
1697
+ const dragKey = dragNode.key;
1698
+ const dropPos = node.pos.split('-');
1699
+ const dropPosition = info.dropPosition - Number(dropPos[dropPos.length - 1]);
1700
+
1701
+ const data = [...treeData];
1702
+ const loop = (data: TreeNodeData[], key: string | undefined, callback: LoopCallback) => {
1703
+ data.forEach((item, ind, arr) => {
1704
+ if (item.key === key) return callback(item, ind, arr);
1705
+ if (item.children) return loop(item.children, key, callback);
1706
+ });
1707
+ };
1708
+
1709
+ let dragObj: TreeNodeData = {};
1710
+ loop(data, dragKey, (item, ind, arr) => {
1711
+ arr.splice(ind, 1);
1712
+ dragObj = item;
1713
+ });
1714
+
1715
+ if (!dropToGap) {
1716
+ loop(data, dropKey, (item) => {
1717
+ item.children ||= [];
1718
+ item.children.push(dragObj);
1719
+ });
1720
+ } else if (dropPosition === 1 && node.children && node.expanded) {
1721
+ loop(data, dropKey, (item) => {
1722
+ item.children ||= [];
1723
+ item.children.unshift(dragObj);
1724
+ });
1725
+ } else {
1726
+ let dropNodeInd = 0;
1727
+ let dropNodePosArr: TreeNodeData[] = [];
1728
+ loop(data, dropKey, (_item, ind, arr) => {
1729
+ dropNodePosArr = arr;
1730
+ dropNodeInd = ind;
1731
+ });
1732
+ if (dropPosition === -1) {
1733
+ dropNodePosArr.splice(dropNodeInd, 0, dragObj);
1734
+ } else {
1735
+ dropNodePosArr.splice(dropNodeInd + 1, 0, dragObj);
1736
+ }
1737
+ }
1738
+ treeData = data;
1739
+ };
1740
+
1741
+ const findDescendantKeys = (node: TreeNodeData) => {
1742
+ const res = [node.key];
1743
+ const findChild = (item?: TreeNodeData) => {
1744
+ if (!item) return;
1745
+ const { children } = item;
1746
+
1747
+ if (children && children.length) {
1748
+ children.forEach((child) => {
1749
+ res.push(child.key);
1750
+ findChild(child);
1751
+ });
1752
+ }
1753
+ };
1754
+ findChild(node);
1755
+ return res;
1756
+ };
1757
+
1758
+ const handleSelect = (key: string, _bool: boolean, node: TreeNodeData) => {
1759
+ selected = new Set([key]);
1760
+ selectedThroughParent = new Set(findDescendantKeys(node));
1761
+ };
1762
+
1763
+ const rowBackground = (key?: string) => {
1764
+ if (selected.has(key)) return 'var(--semi-blue-0)';
1765
+ if (selectedThroughParent.has(key)) return 'color-mix(in srgb, var(--semi-blue-0) 50%, transparent)';
1766
+ return 'transparent';
1767
+ };
1768
+
1769
+ const treeStyle = 'width: 260px; height: 420px; border: 1px solid var(--semi-color-border)';
1770
+ </script>
1771
+
1772
+ <Tree defaultExpandAll draggable {onDrop} onSelect={handleSelect} style={treeStyle} {treeData}>
1773
+ {#snippet fullLabel(row)}
1774
+ {@const Icon = icons[row.data.key ?? '']}
1775
+ <!-- the tree handles the keyboard: the row is a pointer shortcut -->
1776
+ <div class={row.class} role="presentation" style:background-color={rowBackground(row.data.key)} onclick={row.onClick}>
1777
+ {#if !row.data.children?.length}
1778
+ <span style="width: 24px"></span>
1779
+ {:else}
1780
+ {@render row.expandIcon()}
1781
+ {/if}
1782
+ <Icon style={iconStyle} />
1783
+ <span>{row.data.label}</span>
1784
+ </div>
1785
+ {/snippet}
1786
+ </Tree>
1787
+ ```
1788
+
1789
+ ## API Reference
1790
+
1791
+ ### Tree
1792
+
1793
+ **Props**
1794
+
1795
+ | Property | Description | Type | Default |
1796
+ | - | - | - | - |
1797
+ | autoExpandParent | Whether the parents of the nodes in expandedKeys expand automatically when expandedKeys changes; they always do on mount. When on, a controlled tree collapses a parent only after its expanded children are collapsed. | `boolean` | `false` |
1798
+ | autoExpandWhenDragEnter | Whether dragging over a collapsed node expands it. | `boolean` | `true` |
1799
+ | autoMergeValue | When a parent is selected the value leaves out its descendants; applies when leafOnly is false. | `boolean` | `true` |
1800
+ | blockNode | Shows each node as a whole row, highlighting the row on hover and selection; when off only the label is highlighted. | `boolean` | `true` |
1801
+ | checkRelation | How the checked states of nodes relate in a multiple tree: related links parents and children, unRelated keeps them independent. | `CheckRelation` | `"related"` |
1802
+ | classNames | Class names of the inner parts, keyed by search (the search box container); values take anything class takes (string, array or object) and merge with the built-in classes. | `Partial<Record<TreePart, ClassValue>>` | - |
1803
+ | defaultExpandAll | Expands every node on mount. Later changes of treeData or treeDataSimpleJson do not affect it; use expandAll for that. | `boolean` | `false` |
1804
+ | directory | Directory mode with built-in folder icons, which the icon snippet can replace. | `boolean` | `false` |
1805
+ | disabled | Disables the whole tree. A node with disabled: false does not lift it. | `boolean` | `false` |
1806
+ | disableStrictly | Strict disabling: a disabled node cannot change state through the selection of its parent or children. | `boolean` | `false` |
1807
+ | draggable | Whether nodes can be dragged, used together with onDrop. It cannot be combined with virtualize. | `boolean` | `false` |
1808
+ | emptyContent | Content shown when there are no nodes, or when the search finds none with showFilteredOnly on. | `Snippet` | - |
1809
+ | expandAction | How a node expands: false only through the arrow, click on a click, doubleClick on a double click. The keyboard does not use it. | `ExpandAction` | `false` |
1810
+ | expandAll | Expands every node, and keeps doing so when the data changes. | `boolean` | `false` |
1811
+ | expandedKeys | Expanded nodes, bindable with `bind:expandedKeys`. Unbound, the given value is only the initially expanded nodes, showing their direct children. `bind:expandedKeys={get, set}` makes expansion fully controlled. | `string[]` | - |
1812
+ | expandIcon | The expand icon, with `{ onClick, class, expanded }` as its argument; put `class` and `onclick` on the element it renders. | `Snippet<[TreeExpandIconSnippetProps]>` | - |
1813
+ | filterTreeNode | Whether search is on. true matches by treeNodeFilterProp; a function customizes the match, with data as the node. | `boolean \| ((inputValue: string, treeNodeString: string, data?: TreeNodeData) => boolean)` | `false` |
1814
+ | fullLabel | Content of the whole row. Its argument holds `class`, `data`, `level`, `expandIcon`, `checkStatus`, `expandStatus`, `filtered`, `searchWord` and `onClick`, `onCheck`, `onExpand`, `onContextmenu`, `onDblclick`. Tree provides the row element carrying the id, role and state, and virtualized positioning; the snippet holds only what is inside. | `Snippet<[TreeFullLabelSnippetProps]>` | - |
1815
+ | hideDraggingNode | Hides the drag image of the node being dragged. | `boolean` | `false` |
1816
+ | icon | A node's icon. Its argument holds `item`, `level`, `expanded`, `isLeaf`, `loading`, `selected`, `checked` and `halfChecked`, so it can differ by node; empty output keeps the directory icon. | `Snippet<[TreeIconSnippetProps]>` | - |
1817
+ | keyMaps | Custom field names for key, label and value in a node. When label is mapped and search is on, set treeNodeFilterProp to one of the keys in treeData or provide filterTreeNode. | `TreeKeyMapProps` | - |
1818
+ | label | Content of a node's label, with `{ item, label, searchWord }` as its argument. Search still matches the label text in treeData. | `Snippet<[TreeLabelSnippetProps]>` | - |
1819
+ | labelEllipsis | Whether an overflowing label is truncated; on by default for a virtualized tree. | `boolean` | - |
1820
+ | leafOnly | In a multiple tree, the value and the payload of onChange hold leaf nodes only. | `boolean` | `false` |
1821
+ | loadData | Loads the children of a node and returns a Promise. Mark leaves with isLeaf in the data; a node without isLeaf shows the expand arrow while this is set. | `(treeNode?: TreeNodeData) => Promise<void>` | - |
1822
+ | loadedKeys | Nodes already loaded, used with loadData and bindable with `bind:loadedKeys`. | `string[]` | - |
1823
+ | motion | Whether expanding and collapsing are animated; animation is off for a virtualized tree. | `boolean` | `true` |
1824
+ | multiple | Whether several nodes can be selected. A parent is checked automatically once all its children are. | `boolean` | `false` |
1825
+ | onChange | Called when the selection changes, with the current value. | `(value: TreeValue) => void` | - |
1826
+ | onChangeWithObject | When true the argument of onChange is the node object with value, label and other fields instead of the value; a controlled value must then be objects with a value. | `boolean` | `false` |
1827
+ | onContextMenu | Called on a right click on a node, with the event and the node data. | `(event: MouseEvent, node: TreeNodeData) => void` | - |
1828
+ | onDoubleClick | Called on a double click on a node, with the event and the node data. | `(event: MouseEvent, node: TreeNodeData) => void` | - |
1829
+ | onDragEnd | Called when a drag ends. | `(info: TreeDragProps) => void` | - |
1830
+ | onDragEnter | Called when a drag enters a node; the argument holds expandedKeys when that expanded a collapsed node. | `(info: TreeDragEnterProps) => void` | - |
1831
+ | onDragLeave | Called when a drag leaves a node. | `(info: TreeDragProps) => void` | - |
1832
+ | onDragOver | Called while a drag is over a node. | `(info: TreeDragProps) => void` | - |
1833
+ | onDragStart | Called when a node starts to be dragged. | `(info: TreeDragProps) => void` | - |
1834
+ | onDrop | Called when a node is dropped; the argument holds node, dragNode, dragNodesKeys, dropPosition and dropToGap. | `(info: TreeOnDragProps) => void` | - |
1835
+ | onExpand | Called when a node expands or collapses, with the array of expanded keys and an info object holding expanded and node. | `(expandedKeys: string[], info: TreeExpandedOtherProps) => void` | - |
1836
+ | onLoad | Called when a node has loaded, with the set of loaded nodes and the node just loaded. | `(loadedKeys: Set<string>, node: TreeNodeData) => void` | - |
1837
+ | onSearch | Called when the search input changes; filteredExpandedKeys are the nodes expanded by the search or by value, which controlled expansion can use to show the results. | `(input: string, filteredExpandedKeys: string[]) => void` | - |
1838
+ | onSelect | Called when a node is selected or deselected, with its key, whether it is selected and its data. | `(selectedKey: string, selected: boolean, node: TreeNodeData) => void` | - |
1839
+ | renderDraggingNode | The element the browser shows while a node is dragged, with the node element nodeInstance and the node data node as arguments; on dragstart the snippet is rendered into a detached container and used as the drag image, so only app-level context reaches it. | `Snippet<[TreeDraggingNodeSnippetProps]>` | - |
1840
+ | search | Replaces the search box, with `class`, `value`, `placeholder`, `showClear` and `onChange` as its argument; false hides the box while filterTreeNode still filters. | `Snippet<[TreeSearchSnippetProps]> \| false` | - |
1841
+ | searchPlaceholder | Placeholder of the search box. | `string` | - |
1842
+ | showClear | Whether the search box shows a clear button. | `boolean` | `true` |
1843
+ | showFilteredOnly | Shows only the filtered nodes while searching. | `boolean` | `false` |
1844
+ | showLine | Shows connecting lines between nodes. | `boolean` | `false` |
1845
+ | styles | Style strings of the inner parts, keyed like classNames. | `Partial<Record<TreePart, string>>` | - |
1846
+ | treeData | Node data; keys are unique across the tree. Only a new array updates the tree, changes made in place are not seen. A node's icon is drawn by the icon snippet, and its label is a string or number. | `TreeNodeData[]` | - |
1847
+ | treeDataSimpleJson | Node data as a plain JSON object; the value is a JSON object holding the selected nodes. | `TreeDataSimpleJson` | - |
1848
+ | treeNodeFilterProp | The node field matched against the search input, label by default. | `string` | `"label"` |
1849
+ | value | Value of the selected node (its key when it has no value), bindable with `bind:value`; an array when multiple. Unbound, the given value is only the initial selection; `bind:value={get, set}` makes it fully controlled. | `TreeValue` | - |
1850
+ | virtualize | List virtualization for many nodes: height, width and itemSize (required). Animation is off once enabled. | `TreeVirtualize` | - |
1851
+
1852
+ **Methods**
1853
+
1854
+ | Method | Description | Type |
1855
+ | - | - | - |
1856
+ | scrollTo | In a virtualized tree, scrolls an expanded node into view; align is center by default. | `(scrollData: TreeScrollData) => void` |
1857
+ | search | Searches as if the value were typed into the search box; filterTreeNode must be set. | `(input: string) => void` |
1858
+
1859
+ The Svelte Tree has no `className` property: undeclared attributes such as `class`, `style` and `data-*` land on the root element `.semi-tree-wrapper`, and `aria-*` and `tabindex` land on the `role="tree"` element. The empty state has no `role="tree"` element, so `aria-*` attributes are dropped there.
1860
+
1861
+ ### TreeNodeData
1862
+
1863
+ > **Key for `TreeNodeData` is required and must be unique**, `label` can be duplicated. Value is not required; without it, the value property in `onChange`, `value` and `onChangeWithObject` points to the key property. To ensure everything behave as expected, keep a consistency of whether to have value or not to have value.
1864
+
1865
+ | Properties | Instructions | Type | Default |
1866
+ | - | - | - | - |
1867
+ | value | Value | string\|number | - |
1868
+ | label | Displayed label; custom content comes from the `label` snippet | string\|number | - |
1869
+ | disabled | Disabled. When the Tree's `disabled` is true the whole tree is disabled, and a node's `disabled: false` does not lift it | boolean | false |
1870
+ | key | Required and must be unique | string | - |
1871
+ | isLeaf | Toggle whether node is leaf node, only takes effect in async load data with `loadData` | boolean | - |
1872
+
1873
+ ### Virtualize Object
1874
+
1875
+ > `itemSize` is required to render virtualized tree。
1876
+
1877
+ | Properties | Instructions | Type | Default |
1878
+ | - | - | - | - |
1879
+ | height | Height. If passed as a string, computed height should not be 0 for render purpose, in other words, parent node should have offsetHeight | number\|string | '100%' |
1880
+ | itemSize | Height for each line of treeNode, required | number | - |
1881
+ | width | Width | number\|string | '100%' |
1882
+
1883
+ ## Methods
1884
+
1885
+ Tree exposes `search` and `scrollTo` through `bind:this`, typed as `TreeHandle`; see the Methods part of the Tree table above.
1886
+
1887
+ ```svelte
1888
+ <script lang="ts">
1889
+ import { Tree, type TreeHandle } from '@fibrae/semi-ui-svelte';
1890
+
1891
+ let tree = $state<TreeHandle>();
1892
+ const search = (value: string) => tree?.search(value);
1893
+ </script>
1894
+
1895
+ <Tree bind:this={tree} filterTreeNode {treeData} />
1896
+ ```
1897
+
1898
+ ## Accessibility
1899
+
1900
+ ### ARIA
1901
+
1902
+ - Tree supports passing in `aria-label`, `aria-labelledby` and `aria-describedby` to name and describe the Tree; they are all set on the `role="tree"` element;
1903
+ - Tree sets `aria-level`, `aria-setsize`, `aria-posinset` and `aria-disabled` on each node, and `aria-expanded` on nodes that can expand; a single-choice tree marks the selected node with `aria-selected`, a multi-choice tree marks checked nodes with `aria-checked` (`mixed` when half checked);
1904
+ - Tree will set `role` to `tree` and `treeitem` for corresponding parts.
1905
+
1906
+ * The content of `fullLabel` is wrapped in Tree's own `li`, which carries the `id`, `role="treeitem"` and the states above.
1907
+
1908
+ - The expand arrow and the checkbox in front of a node only picture its state: they are hidden from screen readers and take no focus.
1909
+
1910
+ ### Keyboard Interaction
1911
+
1912
+ Tree follows the [WAI-ARIA Tree View](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) pattern: the whole tree is one Tab stop, focus stays on the tree, `aria-activedescendant` points at the current node, and the current node shows the focus ring.
1913
+
1914
+ - `ArrowDown`, `ArrowUp`: move to the next or previous visible node; `Home`, `End`: move to the first or last visible node
1915
+ - `ArrowRight`: expand a collapsed node; on an expanded node, move to its first child (swapped with `ArrowLeft` in RTL)
1916
+ - `ArrowLeft`: collapse an expanded node; otherwise move to the parent
1917
+ - `Enter`, `Space`: select the current node, or check and uncheck it in a multi-choice tree; disabled nodes do not respond
1918
+ - Typing characters: move to the next node whose text starts with them
1919
+
1920
+ A node that is selected, checked, expanded, right-clicked or double-clicked with the pointer becomes the current node of the keyboard, and the arrow keys continue from it.
1921
+
1922
+ The keyboard does not trigger `expandAction`; the arrow keys expand and collapse.
1923
+
1924
+ Buttons and links inside a node (for example a control in the `label` snippet) can be reached with Tab. While one of them has focus, keys are handled by that control and the tree does not respond.
1925
+
1926
+ Demo:
1927
+
1928
+ ```svelte
1929
+ <Tree aria-label="example tree" {treeData} />
1930
+ ```
1931
+
1932
+ ## Content Guidelines
1933
+
1934
+ - Try to use phrases, capitalize the first letter
1935
+ - Keep the same form of terminology between levels, such as all place names or country names
1936
+
1937
+ ## Design Tokens
1938
+
1939
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/navigation/tree/>
1940
+
1941
+ ## Changes from Semi Design
1942
+
1943
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
1944
+
1945
+ - 破坏性:删除 `searchClassName`、`searchStyle`,改用 `classNames.search`、`styles.search`,落在搜索框容器上。
1946
+ - 行为变化:Tree 与 TreeSelect 的派生状态由同一份 `deriveTreeState` 计算。`treeData`、`treeDataSimpleJson` 异步到达或结构变化后,Tree 不再按 `value` 自动展开到所在节点,保留原有展开状态(与 TreeSelect、rc-tree 一致);非受控单选在节点删除后不再残留 `selectedKeys`;非受控 `defaultValue` 在 `treeData` 晚到时不再丢失;`onChangeWithObject` 下对象值首次渲染能展开到父节点。
1947
+ - 破坏性(样式钩子):节点数据的 `active` 字段不再生成 `-active` 类,`BasicTreeNodeProps.active` 与 `&-active` 规则删除。`TreeProps.expandIcon` 放宽为 `ReactNode | ((props) => ReactNode)`;删除 `preventScroll`;拖拽回调的 `event` 改为 `DragEvent`;ref 改为 `TreeHandle { search, scrollTo }`。
1948
+ - 键盘按 APG Tree View:整棵树是一个 Tab 停靠点,焦点留在 `role="tree"` 上并用 `aria-activedescendant` 指向当前节点;展开箭头与复选框不可聚焦,多选不再有 `role="group"` 层,传给 Tree 的 `tabIndex` 与 `aria-label` 等落在 `role="tree"` 元素上。节点内容里可聚焦元素的 `click` 仍冒泡触发 `onSelect`,需自行 `stopPropagation`。
1949
+ - 节点数据中与行状态同名的字段(`expanded`、`checked`、`level`、`empty` 等)不再覆盖内部状态;树外拖入不再触发 `onDrop`,需要时在容器上监听原生 `drop`;默认搜索只匹配字符串与数字 `label`,元素 `label` 请用 `treeNodeFilterProp` 或自定义 `filterTreeNode`;多选 `related` 下全选的父节点不再同时半选。
1950
+ - 没有 `treeData` 时把 `treeDataSimpleJson` 改为 `undefined` 不再抛 `TypeError`,树变为空(TreeSelect 同)。
1951
+ - Solid 破坏性(类型):`TreeNodeData.label` 收紧为 `string | number`,`TreeNodeData.icon` 为 `never`(不再读取,`keyMaps.icon` 随之无效);节点内容用 `renderLabel`(参数 `label` 为 `string | number | undefined`),图标用 Tree 的 `icon`,按节点区分时传函数(同 Vue 的 `#label`、`#icon`)。`icon` 只在插入它的行里读取,`renderFullLabel` 接管整行时不创建。
1952
+ - Svelte:`value`、`expandedKeys`、`loadedKeys` 可绑定;没有 `defaultValue`、`defaultExpandedKeys`,保留 `defaultExpandAll`。
1953
+ - Svelte:自定义内容用 snippet,名字同 Vue 插槽:`label`、`icon`、`expandIcon`、`fullLabel`、`search`、`emptyContent`、`renderDraggingNode`;`search={false}` 隐藏搜索框;`expandIcon` 收到 `class`、`onClick`、`expanded`,由使用方挂到自己的元素上,`fullLabel` 收到的 `expandIcon` 是 snippet;传了 `icon`、`search` 就一律替换内置内容;`renderDraggingNode` 渲染的拖拽图像能读到 Tree 的 context。
1954
+ - Svelte:`search()`、`scrollTo()` 经 `bind:this` 调用;`class`、`style` 落在外层 wrapper 上,`aria-*` 与 `tabindex` 落在 `role="tree"` 元素上。
1955
+ - Svelte:`bind:value` 的值被父组件改回 `undefined` 时清空选中与勾选(同 TreeSelect)。
1956
+ - `onChange` 取节点数据时检查 `keyEntities[key].key === key`,名为 `constructor` 这类原型属性名的 key 不再误取到原型上的值。