@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,392 @@
1
+ # JsonViewer
2
+
3
+ > Used for displaying and editing JSON data
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/plus/json-viewer/
6
+
7
+ ## When to use
8
+
9
+ The JsonViewer component can be used for the display and editing of JSON data.
10
+
11
+ Semi mainly referred to the design concept of the `text-buffer` data structure of [VS Code](https://github.com/microsoft/vscode), reused some utilities and data type definitions (Token parsing, language services, etc.), and implemented the JsonViewer component in combination with our functional/style customization requirements. Visually, it will be more coordinated with other components within the Semi Design Next system, and it will be more convenient for customized rendering and customization of specific data types.
12
+
13
+ Compared with directly using MonacoEditor, Semi JsonViewer has additional processing in engineering construction, is simpler to use, and there is no need to pay attention to complex configurations such as Webpack plugins and worker loaders. At the same time, since we only focus on the JSON data format, it is more lightweight. While being ready to use out of the box, it has a smaller size **(📦-96%)**, a more extreme loading speed **(🚀 -53.5%)**, and less memory occupation **(⬇️71.6% reduction)**. For data with five million lines and below, data loading and parsing can be completed within 1 second.
14
+
15
+ Detailed comparison data can be referred to in the [Performance](#Performance) section.
16
+
17
+ - If you only need to preview/edit JSON and don't need to modify other more complex programming languages, we recommend that you choose `JsonViewer`.
18
+ - If you also need to handle data/code files in other formats and the full capabilities of a code editor (syntax highlighting, code completion, error prompts, complex editing, etc.) are essential and the build product size is not a key concern, we recommend that you choose `Monaco Editor`.
19
+
20
+ ## Demos
21
+
22
+ ### How to import
23
+
24
+ ```svelte
25
+ <script lang="ts">
26
+ import { JsonViewer } from '@fibrae/semi-ui-svelte';
27
+ </script>
28
+ ```
29
+
30
+ ### Basic Usage
31
+
32
+ Basic usage of JsonViewer. Pass `height` and `width` to set the height and width of the component, and pass the JSON string through `value` as the initial value. `onChange` is called with the editor's current text when the content changes. `value` can be bound with `bind:value`; the editor is re-created only when `value` becomes different from the editor's current content, so echoing the same content back keeps the caret; without a binding the editor keeps what the user typed. To read the value, call `getValue()` through `bind:this` (type `JsonViewerHandle`), please refer to [Methods](#Methods) for details.
33
+
34
+ ```svelte
35
+ <script lang="ts">
36
+ import { JsonViewer } from '@fibrae/semi-ui-svelte';
37
+
38
+ const data = `{
39
+ "name": "Semi",
40
+ "version": "0.0.0"
41
+ }`;
42
+ </script>
43
+
44
+ <div style="margin-bottom: 16px">
45
+ <JsonViewer height={100} value={data} width={700} />
46
+ </div>
47
+ ```
48
+
49
+ ### Different lineHeight
50
+
51
+ Configure the `lineHeight` parameter of `options` to set a fixed line height (unit: px, default 20).
52
+
53
+ ```svelte
54
+ <script lang="ts">
55
+ import { JsonViewer } from '@fibrae/semi-ui-svelte';
56
+
57
+ const data = `{
58
+ "name": "Semi",
59
+ "version": "0.0.0"
60
+ }`;
61
+ const wrapperStyle = 'margin-bottom: 12px; overflow: hidden';
62
+ </script>
63
+
64
+ <div>
65
+ <div style={wrapperStyle}>
66
+ <JsonViewer height={100} options={{ lineHeight: 20 }} value={data} width={700} />
67
+ </div>
68
+ <div style={wrapperStyle}>
69
+ <JsonViewer height={120} options={{ lineHeight: 24 }} value={data} width={700} />
70
+ </div>
71
+ <div style={wrapperStyle}>
72
+ <JsonViewer height={120} options={{ lineHeight: 26 }} value={data} width={700} />
73
+ </div>
74
+ </div>
75
+ ```
76
+
77
+ ### Autowrap
78
+
79
+ Configure the `autoWrap` parameter of `options`. When it is set to `true`, the component will automatically wrap lines according to the length of the content.
80
+
81
+ ```svelte
82
+ <script lang="ts">
83
+ import { JsonViewer } from '@fibrae/semi-ui-svelte';
84
+
85
+ const data = `{
86
+ "name": "Semi",
87
+ "version": "0.0.0",
88
+ "description": "Semi Design is a design system that defines a set of mid_back design and front_end basic components."
89
+ }`;
90
+ const options = { autoWrap: true };
91
+ </script>
92
+
93
+ <div style="margin-bottom: 16px">
94
+ <JsonViewer height={120} {options} value={data} width={700} />
95
+ </div>
96
+ ```
97
+
98
+ ### Format options
99
+
100
+ Configure `options.formatOptions` to set the formatting configuration of the component.
101
+
102
+ - tabSize: number,set the indent size to 4, which means each level of indentation is 4 spaces.
103
+ - insertSpaces: boolean,when it is true, it means using spaces for indentation, and when it is false, it means using tabs.
104
+ - eol: string,set the line break character, which can be `\n`,`\r\n`,
105
+
106
+ ```svelte
107
+ <script lang="ts">
108
+ import { Button, JsonViewer, type JsonViewerHandle } from '@fibrae/semi-ui-svelte';
109
+
110
+ const data = `{
111
+ "name": "Semi",
112
+ "version": "0.0.0"
113
+ }`;
114
+ const options = { formatOptions: { tabSize: 4, insertSpaces: true, eol: '\n' } };
115
+
116
+ let jsonviewer = $state<JsonViewerHandle>();
117
+ </script>
118
+
119
+ <div>
120
+ <Button onclick={() => jsonviewer?.format()}>格式化</Button>
121
+ <div style="margin-bottom: 16px; margin-top: 16px">
122
+ <JsonViewer bind:this={jsonviewer} height={100} {options} value={data} width={700} />
123
+ </div>
124
+ </div>
125
+ ```
126
+
127
+ ### Custom Render Rules
128
+
129
+ By configuring the `options.customRenderRule` parameter, you can customize how JSON content is rendered (Note: only works in read-only mode).
130
+
131
+ > **Behavior notes**
132
+ >
133
+ > `path` in `customRenderRule` is computed more accurately: **the key token and the value token of the same key-value pair share the same `path`** (they both map to the property path, e.g. `root.<key>`).
134
+ >
135
+ > As a result, rules that only rely on `path` (such as `path === 'root.<key>'`) may match both the key and the value, which can change which rule “wins” compared to previous versions.
136
+ >
137
+ > If you want to match only the key or only the value, use the third argument `tokenType` of function match:
138
+ >
139
+ > ```ts
140
+ > const targetPath = 'root.<key>';
141
+ > // Key only
142
+ > match: (_value, path, tokenType) => tokenType === 'key' && path === targetPath;
143
+ > // Value only
144
+ > match: (value, path, tokenType) => tokenType === 'value' && path === targetPath;
145
+ > ```
146
+
147
+ `customRenderRule` is an array of rules that hold data only: `match` is the matching condition, and the optional `name` tells rules apart in the `customRender` snippet. The content of a matched token is drawn by `{#snippet customRender({ item, index, content })}`, where `item` is the matched rule and `index` is its position in `customRenderRule`.
148
+
149
+ - `match`: Matching condition, can be one of three types:
150
+ - String: Exact match
151
+ - Regular expression: Match by regex
152
+ - Function: Custom matching logic, with signature `(value: string | number | boolean | null, path: string, tokenType: 'key' | 'value') => boolean`
153
+ - `value`: Value to match (JSON key or value). When `match` is a function, `value` will be passed as the parsed primitive when possible (number / boolean / null / string), so strict comparisons like `===` work; when `match` is a string or RegExp, matching is still based on textual content (string tokens are unquoted)
154
+ - `path`: Current matching path, format is `root.key1.key2.key3[0].key4`
155
+ - `tokenType`: Current token type, `'key'` for JSON property name, `'value'` for JSON value. Useful for distinguishing between key and value matching
156
+
157
+ * `name`: Optional rule name; use `item.name` in the `customRender` snippet to tell rules apart
158
+ * `customRender` snippet: the arguments are `{ item, index, content }`
159
+ - `content`: Matched content. For string values, includes double quotes (e.g., `"name"`, `"Semi"`)
160
+ - Without the snippet, or when it draws nothing, custom rendering is skipped and the token keeps its text
161
+
162
+ ```svelte
163
+ <script lang="ts">
164
+ import { Image, JsonViewer, Popover, Rating, Tag, type JsonViewerOptions } from '@fibrae/semi-ui-svelte';
165
+
166
+ const data = `{
167
+ "name": "Semi",
168
+ "version": "2.7.4",
169
+ "rating": 5,
170
+ "tags": ["design", "react", "ui"],
171
+ "image": "/assets/root-web-sites/abstract.jpg"
172
+ }`;
173
+
174
+ // A rule holds data only; the customRender snippet draws the token and tells the rules apart by name
175
+ const options: JsonViewerOptions = {
176
+ formatOptions: { tabSize: 4, insertSpaces: true, eol: '\n' },
177
+ customRenderRule: [
178
+ { name: 'popover', match: 'Semi' },
179
+ { name: 'rating', match: (value) => value == 5 },
180
+ {
181
+ name: 'tag',
182
+ match: (_value, path) => path === 'root.tags[0]' || path === 'root.tags[1]' || path === 'root.tags[2]',
183
+ },
184
+ { name: 'image', match: /^http/ },
185
+ ],
186
+ readOnly: true,
187
+ autoWrap: true,
188
+ };
189
+
190
+ // content is the raw string token with its quotes; without them it is a valid URL
191
+ const unquote = (content: string) => content.replace(/^"|"$/g, '');
192
+ </script>
193
+
194
+ {#snippet imagePreview(src: string)}
195
+ <Image height={100} {src} width={100} />
196
+ {/snippet}
197
+
198
+ <div>
199
+ <div style="margin-bottom: 16px; margin-top: 16px">
200
+ <JsonViewer height={200} {options} showSearch={false} value={data} width={600}>
201
+ {#snippet customRender({ item, content: text })}
202
+ {#if item.name === 'popover'}
203
+ <Popover showArrow trigger="hover">
204
+ {#snippet content()}我是用户自定义的渲染{/snippet}
205
+ <span>{text}</span>
206
+ </Popover>
207
+ {:else if item.name === 'rating'}
208
+ <Rating disabled size={10} value={Number(text)} />
209
+ {:else if item.name === 'tag'}
210
+ <Tag shape="circle" size="small">{text}</Tag>
211
+ {:else}
212
+ <Popover showArrow trigger="hover">
213
+ {#snippet content()}{@render imagePreview(unquote(text))}{/snippet}
214
+ <span>{text}</span>
215
+ </Popover>
216
+ {/if}
217
+ {/snippet}
218
+ </JsonViewer>
219
+ </div>
220
+ </div>
221
+ ```
222
+
223
+ ### Custom Search Button
224
+
225
+ Use the `searchButton` snippet to customize the rendering of the search button, enabling fixed positioning, custom styles, and more. Providing the snippet replaces the default button as a whole; `defaultButton` is the default button's snippet, drawn with `{@render defaultButton()}`. When `showSearch` is `false`, neither is rendered.
226
+
227
+ ```svelte
228
+ <script lang="ts">
229
+ import { IconSearch } from '@fibrae/semi-icons-svelte';
230
+ import { Button, JsonViewer } from '@fibrae/semi-ui-svelte';
231
+
232
+ const data = `{
233
+ "name": "Semi",
234
+ "version": "0.0.0"
235
+ }`;
236
+ </script>
237
+
238
+ <div style="margin-bottom: 16px">
239
+ <JsonViewer height={200} value={data} width={700}>
240
+ {#snippet searchButton({ defaultButton, showSearchBar, onToggleSearchBar })}
241
+ <div style="position: absolute; top: 10px; right: 10px; z-index: 10">
242
+ {#if !showSearchBar}
243
+ <Button onclick={onToggleSearchBar}>
244
+ {#snippet icon()}
245
+ <IconSearch />
246
+ {/snippet}
247
+ 搜索
248
+ </Button>
249
+ {:else}
250
+ {@render defaultButton()}
251
+ {/if}
252
+ </div>
253
+ {/snippet}
254
+ </JsonViewer>
255
+ </div>
256
+ ```
257
+
258
+ ## API Reference
259
+
260
+ ### JsonViewer
261
+
262
+ **Props**
263
+
264
+ | Property | Description | Type | Default |
265
+ | - | - | - | - |
266
+ | customRender | Replaces the content of a token matched by options.customRenderRule, with the matched rule item, its index and the token text content as snippet arguments. A snippet that draws nothing leaves the token's text in place. Only takes effect in read-only mode. | `Snippet<[JsonViewerCustomRenderArgs]>` | - |
267
+ | height | Height. A number is taken as px; a string is used as is. | `number \| string` | `400` |
268
+ | limitSearchButtonBounds | Whether to limit the search button drag bounds within the component container. | `boolean` | `false` |
269
+ | onChange | Called when the content changes, with the editor's current text. | `(value: string) => void` | - |
270
+ | options | Editor options; see JsonViewerOptions for the fields. The defaults of ariaLabel, readOnly and autoWrap merge per key, so passing some fields keeps the defaults of the others. A deep change re-creates the editor; mutating a nested object such as formatOptions or customRenderRule in place goes unnoticed, so replace it with a new object. | `JsonViewerOptions` | - |
271
+ | searchButton | Replaces the default search button as a whole. defaultButton is the default button's snippet, drawn with `{@render defaultButton()}`; the other arguments build a custom search UI. Not rendered when showSearch is false. | `Snippet<[JsonViewerSearchButtonArgs]>` | - |
272
+ | showSearch | Whether to show the search button. | `boolean` | `true` |
273
+ | value | Text of the editor, used with bind:value. A value different from the editor's current content re-creates the editor; echoing the current content back keeps the caret. Without it the editor starts empty. | `string` | - |
274
+ | width | Width. A number is taken as px; a string is used as is. | `number \| string` | `400` |
275
+
276
+ **Methods**
277
+
278
+ | Method | Description | Type |
279
+ | - | - | - |
280
+ | format | Formats the content with formatOptions. | `() => void` |
281
+ | getSearchResults | Returns the current search results. | `() => FindMatch[] \| null \| undefined` |
282
+ | getStyle | Returns the current width and height. | `() => { width: string \| number; height: string \| number; }` |
283
+ | getValue | Returns the editor's current text. | `() => string` |
284
+ | nextSearch | Moves to the next search result, with an optional step. | `(step?: number) => void` |
285
+ | prevSearch | Moves to the previous search result, with an optional step. | `(step?: number) => void` |
286
+ | replace | Replaces the current search match. An empty string deletes the match; without a match it does nothing. | `(replaceText: string) => void` |
287
+ | replaceAll | Replaces all search matches. An empty string deletes them. | `(replaceText: string) => void` |
288
+ | search | Searches for text; the optional parameters control case sensitivity, whole word and regular expression. | `(searchText: string, caseSensitive?: boolean, wholeWord?: boolean, regex?: boolean) => void` |
289
+
290
+ `class`, `style` and native attributes fall on the root element. The editor owns the root's content, so there is no `children`. When the root has no `role` and `aria-label` or `aria-labelledby` is passed, the root gets `role="group"`; an explicit `role` wins.
291
+
292
+ ### JsonViewerOptions
293
+
294
+ | Attribute | Description | Type | Default |
295
+ | - | - | - | - |
296
+ | lineHeight | Height of each line of content, unit:px | number | 20 |
297
+ | autoWrap | Whether to wrap lines automatically. | boolean | true |
298
+ | readOnly | Whether to be read-only. | boolean | false |
299
+ | customRenderRule | Custom render rules | CustomRenderRule\[] | - |
300
+ | formatOptions | Content format setting | FormattingOptions | - |
301
+ | completionOptions | Auto-completion setting | CompletionOptions | - |
302
+ | ariaLabel | Accessible name of the content area (the read-only scroll region, or the editable textbox) | string | locale `JsonViewer.content` |
303
+
304
+ ### CustomRenderRule
305
+
306
+ The type is named `JsonViewerCustomRenderRule`. A rule holds data only; the content of a matched token is drawn by the `customRender` snippet.
307
+
308
+ | Attribute | Description | Type | Default |
309
+ | - | - | - | - |
310
+ | match | Matching rule | string \| RegExp \| (value: string \| number \| boolean \| null, path: string, tokenType: 'key' \| 'value') => boolean | - |
311
+ | name | Rule name, to tell rules apart in the `customRender` snippet | string | - |
312
+
313
+ ### FormattingOptions
314
+
315
+ | Attribute | Description | Type | Default |
316
+ | - | - | - | - |
317
+ | tabSize | Indent size | number | 4 |
318
+ | insertSpaces | Whether to use spaces for indentation | boolean | true |
319
+ | eol | Line break character | string | '\n' |
320
+
321
+ ### CompletionOptions
322
+
323
+ | Attribute | Description | Type | Default |
324
+ | - | - | - | - |
325
+ | staticCompletions | Static completion items. They are appended only after the candidates inferred from the document structure, and are not offered when nothing can be inferred; an item whose `label` matches an existing candidate is not added again. Only `label`, `insertText` (falling back to `label`) and `documentation` of each item are read | CompletionItem\[] | - |
326
+
327
+ ### SearchControls
328
+
329
+ With the `searchButton` snippet, the arguments (type `JsonViewerSearchButtonArgs`) contain the following properties besides `defaultButton`:
330
+
331
+ | Attribute | Description | Type |
332
+ | - | - | - |
333
+ | showSearchBar | Whether the search bar is currently visible | boolean |
334
+ | onToggleSearchBar | Toggle search bar visibility | () => void |
335
+ | onSearch | Execute search | (text: string, caseSensitive?: boolean, wholeWord?: boolean, regex?: boolean) => void |
336
+ | onPrevSearch | Navigate to previous search result | () => void |
337
+ | onNextSearch | Navigate to next search result | () => void |
338
+ | onReplace | Replace current search match | (text: string) => void |
339
+ | onReplaceAll | Replace all search matches | (text: string) => void |
340
+
341
+ ## Methods
342
+
343
+ Methods exported by the component can be called through `bind:this` (type `JsonViewerHandle`), for example `jsonviewer?.format()`.
344
+
345
+ | Method | Description |
346
+ | - | - |
347
+ | getValue() | Get current value |
348
+ | format() | Format current content |
349
+ | search(searchText: string, caseSensitive?: boolean, wholeWord?: boolean, regex?: boolean) | Search for text with optional parameters |
350
+ | getSearchResults() | Get current search results |
351
+ | prevSearch(step?: number) | Navigate to previous search result, with optional step size |
352
+ | nextSearch(step?: number) | Navigate to next search result, with optional step size |
353
+ | replace(replaceText: string) | Replace current search match |
354
+ | replaceAll(replaceText: string) | Replace all search matches |
355
+ | getStyle() | Get the current width and height |
356
+
357
+ ### Performance
358
+
359
+ #### Bundle Size
360
+
361
+ | Libs Name | Size | Size (Gzip) |
362
+ | - | - | - |
363
+ | JsonViewer | 203.14kb | 51.23kb |
364
+ | MonacoEditor | 5102.0 KB | 1322.7 KB |
365
+
366
+ #### Time for rendering data of different magnitudes.
367
+
368
+ > For details on the generation method of the test data, please refer to [URL](https://github.com/DouyinFE/semi-design/blob/main/packages/semi-ui-react/jsonViewer/_story/jsonViewer.stories.jsx)\
369
+ > When the data volume exceeds 500,000 lines, ReactMonacoEditor turns off highlighting and other behaviors by default, and the data comparison does not follow the principle of a single variable.
370
+
371
+ | Libs Name | 1k lines | 5k lines | 10 thousand lines | 100 thousand lines | 500 thousand lines | 1 million lines | 3 million lines |
372
+ | - | - | - | - | - | - | - | - |
373
+ | JsonViewer | 30.42ms | 30.66ms | 36.87ms | 52.73ms | 111.02ms | 178.81ms | 506.25ms |
374
+ | ReactMonacoEditor | 72.01ms | 73.76ms | 76.64ms | 97.89ms | 133.31ms | 202.79ms | 495.53ms |
375
+ | Performance improvement | 57.70% | 58.41% | 51.87% | 46.11% | - | - | - |
376
+
377
+ ## Changes from Semi Design
378
+
379
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
380
+
381
+ - 破坏性(类型):`JsonViewerProps` 不再接受 `children`、`dangerouslySetInnerHTML`,删除从未生效的 `renderTooltip`;`value`、`width`、`height` 改为可选;`ref` 为 `JsonViewerHandle` 而非类实例;`options` 默认值按键合并,只传部分选项时 `autoWrap` 仍为 `true`;`customRenderRule` 的 `render` 返回 `null`、`undefined`、`false` 时保留 token 原文。
382
+ - 搜索栏容器由 `div` 改为原生 `search` 元素(类名不变,`div.semi-json-viewer-search-bar-container` 选择器需改),大小写、正则、全词选项改为按钮,自定义语言包需补 `JsonViewer.caseSensitive`、`JsonViewer.regex`、`JsonViewer.wholeWord`、`JsonViewer.replaceWith`;替换输入框的可访问名称改用 `replaceWith`(中文「替换为」、英文「Replace with」),不再与「替换」按钮同名。Vue:`value` 改名 `modelValue` 配合 `v-model`;`customRenderRule[].render` 改为 `#customRender="{ item, index, content }"` 插槽;`renderSearchButton` 改为 `#searchButton`。
383
+ - 构建插件配置了 `prefixCls` 时,悬停字符串值同样触发 `hoverNode`(原来判断写死了 `semi-` 类名,自定义前缀下悬停字符串值没有反应)。
384
+ - Svelte:`value` 可绑定(`bind:`、函数绑定、单向、不传),变化同时触发 `onChange`;`customRender`、`searchButton` 为同名 snippet,参数分别是 `{ item, index, content }` 与 `{ defaultButton, showSearchBar, onToggleSearchBar, onSearch, onPrevSearch, onNextSearch, onReplace, onReplaceAll }`,`defaultButton` 是 snippet,用 `{@render}` 渲染。
385
+ - Svelte:实例方法 `getValue`、`format`、`search`、`getSearchResults`、`prevSearch`、`nextSearch`、`replace`、`replaceAll`、`getStyle` 经 `bind:this` 调用。
386
+ - 补全列表在下一次请求返回空结果后关闭,不再留着旧列表,此时上下方向键不会再把选中下标算成 `NaN`。
387
+ - `getValue()`、`format()` 在编辑器不存在(挂载前、隐藏后)时返回 `''` 或什么也不做,不抛错。
388
+ - 折叠区域超过 65535 个时不再抛错。
389
+ - `options` 按内容比较,内容未变且 `value` 与编辑器文本一致时不重建编辑器。
390
+ - 可编辑的编辑器只在内容区已有焦点时恢复光标:搜索、切换搜索选项、上一个或下一个匹配、替换、全部替换和滚动不再把焦点移到内容区,焦点留在原控件上;点击补全建议项时焦点留在内容区。
391
+ - `getSearchResults` 的返回类型写为 `FindMatch[] | null | undefined`,`FindMatch` 从 `@fibrae/semi-json-viewer-core` 与 foundation 的 `json-viewer/foundation` 导出。
392
+ - worker 首次回复前就编辑不再抛 TypeError、丢失重绘;补全建议变少后按 Enter 不再抛错。
@@ -0,0 +1,176 @@
1
+ # Lottie Animation
2
+
3
+ > Display Lottie animation on the web page
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/plus/lottie/
6
+
7
+ ## When to use
8
+
9
+ The Lottie component can render Lottie animations conveniently and simply, and provides a way to obtain global Lottie and animation instances to meet a wider range of configuration needs. `lottie-web` is used internally to render Lottie animations. Compared to using `lottie-web` directly, use the Semi Lottie component
10
+
11
+ - No need to worry about the creation and destruction of animation containers
12
+ - No need to worry about the life cycle of the animation itself
13
+
14
+ * Easier to use with Svelte projects
15
+
16
+ ## Demos
17
+
18
+ ### How to import
19
+
20
+ ```svelte
21
+ <script lang="ts">
22
+ import { Lottie } from '@fibrae/semi-ui-svelte';
23
+ </script>
24
+ ```
25
+
26
+ ### Basic Usage
27
+
28
+ **When the Lottie animation resource JSON is on CDN**
29
+
30
+ Pass path=your lottie json URL to the `params` props
31
+
32
+ ```svelte
33
+ <script lang="ts">
34
+ import { Lottie } from '@fibrae/semi-ui-svelte';
35
+
36
+ const jsonURL = '/assets/root-web-sites/lottie-demo.json';
37
+ </script>
38
+
39
+ <div>
40
+ <Lottie height="300px" params={{ path: jsonURL }} width="300px" />
41
+ </div>
42
+ ```
43
+
44
+ **When Lottie animation resource JSON needs to be packaged into the website code**
45
+
46
+ Pass animationData=your lottie json object into the `params` props (the Demo request JSON below is only for demonstration. In actual projects, json should be manually imported instead of obtained through network requests, so that JSON animation resources can be packaged into the website code)
47
+
48
+ ```svelte
49
+ <script lang="ts">
50
+ import { onMount } from 'svelte';
51
+ import { Lottie } from '@fibrae/semi-ui-svelte';
52
+
53
+ const jsonURL = '/assets/root-web-sites/lottie-demo.json';
54
+
55
+ // large animation data is held in $state.raw so it is not made deeply reactive
56
+ let data = $state.raw<object | string>('');
57
+ // params reloads the animation when it is replaced, so it is derived from the data instead of mutated
58
+ const params = $derived({ animationData: data });
59
+
60
+ onMount(() => {
61
+ void fetch(jsonURL)
62
+ .then((resp) => resp.json())
63
+ .then((json: object) => {
64
+ data = json;
65
+ });
66
+ });
67
+ </script>
68
+
69
+ <div>
70
+ <Lottie height="300px" {params} width="300px" />
71
+ </div>
72
+ ```
73
+
74
+ ### Params Other common parameters
75
+
76
+ `params` will be passed to `lottie.loadAnimation` of `lottie-web` by the component. Please refer to `lottie-web` [documentation](https://github.com/airbnb/lottie-web?tab=readme-ov-file#usage)
77
+
78
+ Common parameters
79
+
80
+ ```json
81
+ //params
82
+ {
83
+ container: element, // Rendering container, if not passed, Semi Lottie component will automatically configure and generate
84
+ renderer: 'svg', // Rendering mode, default SVG; SVG uses the light build of lottie-web, which does not support expressions. Set 'canvas' or 'html' for animations that use expressions, which loads the full build
85
+ loop: true, // Whether to open loop, default true
86
+ autoplay: true, // Whether to play automatically, default true, when set to false, you need to manually play through the play method on the animation instance
87
+ path: 'data.json' // URL path of animation JSON file (mutually exclusive with animationData)
88
+ animationData: {/*...*/} // JSON object of animation (mutually exclusive with animationData)
89
+ /*...*/
90
+ }
91
+ ```
92
+
93
+ ### Get the current animation instance
94
+
95
+ Pass a callback to the `getAnimationInstance` prop to get the animation instance of the currently playing animation. The instance contains many methods for adjusting various parameters of the animation, such as playing and pausing, getting the current frame number, adjusting the playback speed, etc. It is called once per animation created, including every reload.
96
+
97
+ For more information about the methods contained in the animation instance, please refer to the `lottie-web` [documentation](https://github.com/airbnb/lottie-web?tab=readme-ov-file#usage)
98
+
99
+ ```svelte
100
+ <script lang="ts">
101
+ import { Lottie } from '@fibrae/semi-ui-svelte';
102
+
103
+ const jsonURL = '/assets/root-web-sites/lottie-demo.json';
104
+ </script>
105
+
106
+ <div>
107
+ <Lottie
108
+ getAnimationInstance={(animation) => {
109
+ console.log(animation);
110
+ }}
111
+ height="300px"
112
+ params={{ path: jsonURL }}
113
+ width="300px"
114
+ />
115
+ </div>
116
+ ```
117
+
118
+ ### Get global Lottie
119
+
120
+ Pass a callback to the `getLottie` prop to get global lottie, or use the static method `Lottie.getLottie` on the Semi Lottie component to get global lottie
121
+
122
+ `lottie-web` is large, so Semi loads it on demand when an animation needs to be created. The `getLottie` prop is called once it has loaded and the animation is created, once per mount. The static method `Lottie.getLottie()` is asynchronous and returns a `Promise` that resolves to lottie (use `await` or `.then`). The component renders no animation until `lottie-web` has loaded, and if it unmounts before that, no animation is created.
123
+
124
+ For more information about the methods on the global lottie, please refer to the `lottie-web` [documentation](https://github.com/airbnb/lottie-web?tab=readme-ov-file#usage)
125
+
126
+ ```svelte
127
+ <script lang="ts">
128
+ import { onMount } from 'svelte';
129
+ import { Lottie } from '@fibrae/semi-ui-svelte';
130
+
131
+ const jsonURL = '/assets/root-web-sites/lottie-demo.json';
132
+
133
+ onMount(() => {
134
+ void Lottie.getLottie().then((lottie) => console.log('lottie', lottie));
135
+ });
136
+ </script>
137
+
138
+ <div>
139
+ <Lottie getLottie={(lottie) => console.log('lottie', lottie)} height="300px" params={{ path: jsonURL }} width="300px" />
140
+ </div>
141
+ ```
142
+
143
+ ### API
144
+
145
+ **Props**
146
+
147
+ | Property | Description | Type | Default |
148
+ | - | - | - | - |
149
+ | getAnimationInstance | Called once per animation created, including every reload, with the AnimationItem of the animation. | `(animation: LottieAnimation) => void` | - |
150
+ | getLottie | Called once per mount after lottie-web has loaded, with the global Lottie. | `(lottie: LottieModule) => void` | - |
151
+ | height | Container height, with a unit such as 300px. | `string` | - |
152
+ | params | Options passed to lottie-web's loadAnimation. It reloads when the content changes (mutating a `$state` in place counts too); a snapshot is taken before it reaches lottie-web, and large animation data is best held in `$state.raw`. | `LottieParams` | - |
153
+ | width | Container width, with a unit such as 300px. | `string` | - |
154
+
155
+ `class`, `style` (a string) and native attributes (such as `data-*` and `aria-*`) land on the container `div`. `params` reloads whenever its content changes, mutating a `$state` in place included, and a snapshot is taken before it reaches `lottie-web`; hold large animation data in `$state.raw`. When `params.container` is set the component renders nothing, so these attributes have nowhere to land.
156
+
157
+ ### Static methods
158
+
159
+ | Method | Description | Type |
160
+ | - | - | - |
161
+ | `Lottie.getLottie` | Get the global Lottie asynchronously; `lottie-web` is loaded on the first call. The full build is loaded for `canvas` or `html`, the light build otherwise | (renderer?: 'svg' \| 'canvas' \| 'html') => Promise\<Lottie> |
162
+
163
+ ## Accessibility
164
+
165
+ - An animation with `aria-label` or `aria-labelledby` is a named image, and its container gets `role="img"`; an animation without a name is decoration, and its container gets `aria-hidden="true"`. A `role` or `aria-*` you pass wins
166
+ - With `prefers-reduced-motion: reduce` set in the system, the animation does not autoplay, and it pauses or plays as the setting changes while running; an explicit `params.autoplay` takes precedence
167
+
168
+ ## Design Tokens
169
+
170
+ ## Changes from Semi Design
171
+
172
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
173
+
174
+ - 破坏性:默认的 SVG 渲染器改用 lottie-web 的 light 构建(只含 SVG 渲染器、不执行表达式,不需要 CSP `unsafe-eval`);`params.renderer` 为 `canvas` 或 `html` 时加载完整版。用了表达式的动画在默认渲染器下表达式失效,需要时把 `params.renderer` 设为 `canvas`;开发环境下 `animationData` 含表达式会告警(`params.path` 加载的数据不检查)。`Lottie.getLottie(renderer?)` 新增可选参数,`canvas`、`html` 返回完整版,其余返回 light 版;`getLottie` 回调拿到的对象随渲染器而定,类型不变。
175
+ - 破坏性:`Lottie.getLottie()` 改为异步,返回解析为 lottie-web 的 `Promise`;lottie-web 按需导入,`getLottie`、`getAnimationInstance` 回调在其加载完成后调用;系统开启「减少动态效果」时不自动播放(显式传 `params.autoplay` 则以其为准)。
176
+ - Svelte:`getAnimationInstance`、`getLottie` 为函数 prop;`params` 内容变化即重载(原地修改 `$state` 也会),交给 lottie-web 前做快照;使用方的 `aria-hidden`、`role` 覆盖默认值。