@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,285 @@
1
+ # Cropper
2
+
3
+ > Freely crop pictures
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/cropper/
6
+
7
+ ## When to use
8
+
9
+ Cropper is used to crop pictures. It supports custom cropping box styles. The positions of the cropping box, cropped image can be adjusted by dragging. It can zoom and rotate the cropped pictures.
10
+
11
+ ## Demos
12
+
13
+ ### How to import
14
+
15
+ ```svelte
16
+ <script lang="ts">
17
+ import { Cropper } from '@fibrae/semi-ui-svelte';
18
+ </script>
19
+ ```
20
+
21
+ ### Basic usage
22
+
23
+ Use `src` to set the cropped image; use `shape` to set the shape of the cropping box, which defaults to square.
24
+
25
+ ```svelte
26
+ <script lang="ts">
27
+ import { Button, Cropper, Radio, RadioGroup, type CropperShape, type RadioValue } from '@fibrae/semi-ui-svelte';
28
+
29
+ const containerStyle = 'width: 550px; height: 300px; margin: 20px';
30
+
31
+ let cropper = $state<ReturnType<typeof Cropper>>();
32
+ let shape = $state<RadioValue | undefined>('rect');
33
+ let cropperUrl = $state('');
34
+
35
+ const onButtonClick = () => {
36
+ const canvas = cropper?.getCropperCanvas();
37
+ if (canvas) cropperUrl = canvas.toDataURL();
38
+ };
39
+ </script>
40
+
41
+ <RadioGroup aria-label="裁切框形状" bind:value={shape}>
42
+ <Radio value="rect">rect</Radio>
43
+ <Radio value="round">round</Radio>
44
+ <Radio value="roundRect">roundRect</Radio>
45
+ </RadioGroup>
46
+ <Cropper bind:this={cropper} shape={shape as CropperShape} src="/assets/other/image.png" style={containerStyle} />
47
+ <Button onclick={onButtonClick}>裁切</Button>
48
+ <br />
49
+ <br />
50
+ {#if cropperUrl}
51
+ <img alt="裁切结果" src={cropperUrl} style="height: 400px" />
52
+ {/if}
53
+ ```
54
+
55
+ ### Customize crop box ratio
56
+
57
+ The initial crop box ratio can be passed through `defaultAspectRatio` (default is 1). A fixed crop box ratio can be set via `aspectRatio`.
58
+
59
+ Setting `defaultAspectRatio` only takes effect on the initial crop box ratio. When dragging, the crop box ratio will change with dragging.
60
+
61
+ When setting `aspectRatio`, the crop box ratio is fixed, and the crop box will change according to this ratio when dragging. When `aspectRatio` changes after the image has loaded, the crop box is laid out again at the new ratio: its height is kept, its width follows the ratio, it shrinks to fit the container when it would overflow, and its center stays where it is as far as possible. When `aspectRatio` becomes `undefined` the box is not laid out again.
62
+
63
+ ```svelte
64
+ <script lang="ts">
65
+ import { Button, Cropper } from '@fibrae/semi-ui-svelte';
66
+
67
+ const containerStyle = 'width: 550px; height: 300px; margin: 20px';
68
+
69
+ let cropper = $state<ReturnType<typeof Cropper>>();
70
+ let cropperUrl = $state('');
71
+
72
+ const onButtonClick = () => {
73
+ const canvas = cropper?.getCropperCanvas();
74
+ if (canvas) cropperUrl = canvas.toDataURL();
75
+ };
76
+ </script>
77
+
78
+ <Cropper aspectRatio={3 / 4} bind:this={cropper} src="/assets/other/image.png" style={containerStyle} />
79
+ <Button onclick={onButtonClick}>裁切</Button>
80
+ <br />
81
+ <br />
82
+ {#if cropperUrl}
83
+ <img alt="裁切结果" src={cropperUrl} style="height: 400px" />
84
+ {/if}
85
+ ```
86
+
87
+ ### Controlled rotation/zooming of images
88
+
89
+ Control image rotation and zoom through `rotate` and `zoom`. `zoom` can be bound with `bind:zoom`, a function binding `bind:zoom={get, set}`, or passed one-way as `zoom={x}`; wheel zooming also calls `onZoomChange(zoom)`. `rotate` is one-way only: the component never changes it. `zoom` does not read the global default.
90
+
91
+ ```svelte
92
+ <script lang="ts">
93
+ import { Button, Cropper, Slider } from '@fibrae/semi-ui-svelte';
94
+
95
+ const containerStyle = 'width: 550px; height: 300px; margin: 20px';
96
+ const actionStyle = 'margin-block-start: 20px; display: flex; align-items: center; justify-content: center; width: fit-content';
97
+
98
+ let rotate = $state(0);
99
+ let zoom = $state(1);
100
+ let cropper = $state<ReturnType<typeof Cropper>>();
101
+ let cropperUrl = $state('');
102
+
103
+ const onSliderChange = (value: number | number[]) => {
104
+ if (typeof value === 'number') rotate = value;
105
+ };
106
+
107
+ const onZoomSliderChange = (value: number | number[]) => {
108
+ if (typeof value === 'number') zoom = value;
109
+ };
110
+
111
+ const onButtonClick = () => {
112
+ const canvas = cropper?.getCropperCanvas();
113
+ if (canvas) cropperUrl = canvas.toDataURL();
114
+ };
115
+ </script>
116
+
117
+ <div id="cropper-container">
118
+ <Cropper bind:this={cropper} bind:zoom {rotate} src="/assets/other/image.png" style={containerStyle} />
119
+ <div style={actionStyle}>
120
+ <span id="cropper-rotate-zoom-rotate">旋转</span>
121
+ <Slider aria-labelledby="cropper-rotate-zoom-rotate" max={360} min={-360} onChange={onSliderChange} step={1} style="width: 500px" value={rotate} />
122
+ </div>
123
+ <div style={actionStyle}>
124
+ <span id="cropper-rotate-zoom-zoom">缩放</span>
125
+ <Slider aria-labelledby="cropper-rotate-zoom-zoom" max={3} min={0.1} onChange={onZoomSliderChange} step={0.1} style="width: 500px" value={zoom} />
126
+ </div>
127
+ <br />
128
+ <Button onclick={onButtonClick}>裁切</Button>
129
+ <br />
130
+ <br />
131
+ {#if cropperUrl}
132
+ <img alt="裁切结果" src={cropperUrl} style="height: 400px" />
133
+ {/if}
134
+ </div>
135
+ ```
136
+
137
+ ### Crop box settings
138
+
139
+ The crop box style can be customized through `classNames.cropperBox` and `styles.cropperBox`. You can use `showResizeBox` to set whether to display the adjustment blocks at the corners of the crop box.
140
+
141
+ ```svelte
142
+ <script lang="ts">
143
+ import { Button, Cropper } from '@fibrae/semi-ui-svelte';
144
+
145
+ const containerStyle = 'width: 550px; height: 300px; margin: 20px';
146
+
147
+ let cropper = $state<ReturnType<typeof Cropper>>();
148
+ let cropperUrl = $state('');
149
+
150
+ const onButtonClick = () => {
151
+ const canvas = cropper?.getCropperCanvas();
152
+ if (canvas) cropperUrl = canvas.toDataURL();
153
+ };
154
+ </script>
155
+
156
+ <strong>showResizeBox = false,并修改边框颜色</strong>
157
+ <Cropper bind:this={cropper} showResizeBox={false} src="/assets/other/image.png" style={containerStyle} styles={{ cropperBox: 'outline-color: var(--semi-color-bg-0)' }} />
158
+ <Button onclick={onButtonClick}>裁切</Button>
159
+ <br />
160
+ <br />
161
+ {#if cropperUrl}
162
+ <img alt="裁切结果" src={cropperUrl} style="height: 400px" />
163
+ {/if}
164
+ ```
165
+
166
+ ### Live preview
167
+
168
+ Use `preview` to specify a container that previews the crop result in real time. `preview` is a function returning the container DOM; it may return `null` or `undefined` while the container is not mounted yet.
169
+
170
+ ```svelte
171
+ <script lang="ts">
172
+ import { Button, Cropper, Slider } from '@fibrae/semi-ui-svelte';
173
+
174
+ const containerStyle = 'width: 550px; height: 300px; margin: 20px';
175
+ const actionStyle = 'margin-block-start: 20px; display: flex; align-items: center; justify-content: center; width: fit-content';
176
+
177
+ let rotate = $state(0);
178
+ let zoom = $state(1);
179
+ let cropperUrl = $state('');
180
+ let cropper = $state<ReturnType<typeof Cropper>>();
181
+ let previewWrapper = $state<HTMLDivElement>();
182
+
183
+ const onSliderChange = (value: number | number[]) => {
184
+ if (typeof value === 'number') rotate = value;
185
+ };
186
+
187
+ const onZoomSliderChange = (value: number | number[]) => {
188
+ if (typeof value === 'number') zoom = value;
189
+ };
190
+
191
+ const onButtonClick = () => {
192
+ const canvas = cropper?.getCropperCanvas();
193
+ if (canvas) cropperUrl = canvas.toDataURL();
194
+ };
195
+
196
+ // a function so the cropper reads the wrapper when it needs it; the element is undefined until it has mounted
197
+ const preview = () => previewWrapper;
198
+ </script>
199
+
200
+ <div>
201
+ <Cropper bind:this={cropper} bind:zoom {preview} {rotate} src="/assets/root-web-sites/abstract.jpg" style={containerStyle} />
202
+ <div style={actionStyle}>
203
+ <span id="cropper-preview-rotate">旋转</span>
204
+ <Slider aria-labelledby="cropper-preview-rotate" max={360} min={-360} onChange={onSliderChange} step={1} style="width: 500px" value={rotate} />
205
+ </div>
206
+ <div style={actionStyle}>
207
+ <span id="cropper-preview-zoom">缩放</span>
208
+ <Slider aria-labelledby="cropper-preview-zoom" max={3} min={0.1} onChange={onZoomSliderChange} step={0.1} style="width: 500px" value={zoom} />
209
+ </div>
210
+ <br />
211
+ <div style="display: flex">
212
+ <div style="width: 50%; flex-grow: 1">
213
+ <strong>实时预览</strong>
214
+ <div bind:this={previewWrapper} style="height: 300px; margin-block-start: 8px"></div>
215
+ </div>
216
+ <div style="width: 50%; flex-grow: 1; padding-inline-start: 10px">
217
+ <Button onclick={onButtonClick}>裁切</Button>
218
+ <br />
219
+ <br />
220
+ {#if cropperUrl}
221
+ <img alt="裁切结果" src={cropperUrl} style="width: 90%" />
222
+ {/if}
223
+ </div>
224
+ </div>
225
+ </div>
226
+ ```
227
+
228
+ ### API
229
+
230
+ **Props**
231
+
232
+ | Property | Description | Type | Default |
233
+ | - | - | - | - |
234
+ | aspectRatio | Fixed aspect ratio of the crop box. When it changes after loading, the box is laid out again at the new ratio. | `number` | - |
235
+ | classNames | Class names of the inner parts, keyed by `cropperBox` (the crop box); merged with the built-in classes. | `Partial<Record<CropperPart, ClassValue>>` | - |
236
+ | defaultAspectRatio | Initial aspect ratio of the crop box, which changes while dragging. | `number` | `1` |
237
+ | fill | Fill color of the parts of the result that are not the image. | `string` | `"rgba(0, 0, 0, 0)"` |
238
+ | imgProps | Attributes passed to the img element being cropped. src and the layout style belong to the component; class and style are merged with its own, and onload is called after the component has handled it. alt defaults to an empty string and crossorigin to anonymous; both can be overridden. | `HTMLImgAttributes` | - |
239
+ | maxZoom | Maximum zoom factor. | `number` | `3` |
240
+ | minZoom | Minimum zoom factor. | `number` | `0.1` |
241
+ | onZoomChange | Called by wheel zooming, with the new zoom. | `(zoom: number) => void` | - |
242
+ | preview | Function returning the DOM element that mirrors the cropped area live. It may return null while the element is not mounted yet. | `() => HTMLElement \| null \| undefined` | - |
243
+ | rotate | Image rotation angle. It is one-way: the component never changes it. | `number` | - |
244
+ | shape | Shape of the crop box. | `CropperShape` | `"rect"` |
245
+ | showResizeBox | Whether to show the resize handles on the corners of the crop box. | `boolean` | `true` |
246
+ | src | Address of the image to crop. | `string` | - |
247
+ | styles | Style strings of the inner parts, keyed like classNames; `cropperBox` is merged with the size and offset the component computes, and the size and offset win. | `Partial<Record<CropperPart, string>>` | - |
248
+ | zoom | Zoom, applied on top of the initial scaling that fits the image into the cropper; use `bind:zoom`, a function binding or a one-way value. Wheel zooming updates the bound value and calls `onZoomChange`. | `number` | - |
249
+ | zoomStep | Zoom change per wheel step. | `number` | `0.1` |
250
+
251
+ **Methods**
252
+
253
+ | Method | Description | Type |
254
+ | - | - | - |
255
+ | getCropperCanvas | Draws the area inside the crop box at the image's own resolution onto a new canvas and returns it. It throws when called before the image has loaded. | `() => HTMLCanvasElement` |
256
+
257
+ `class`, `style` and native attributes and events (such as `id`, `data-*`, `aria-*` and `onkeydown`) land on the root `<div>`; `role` can be overridden. Call `getCropperCanvas()` on the component instance obtained through `bind:this`.
258
+
259
+ ## Accessibility
260
+
261
+ - With `aria-label` or `aria-labelledby` and no `role` on the root, the root gets `role="group"`; a `role` you pass wins
262
+ - The crop box is a focusable named group (`role="group"`, with its name and role description from the locale, and `aria-describedby` pointing to the usage hint). It becomes focusable once the image has loaded. The `img` being cropped is decorative: its `alt` defaults to an empty string and can be overridden through `imgProps`
263
+ - Only a mouse press with the primary button, or a touch or pen contact, starts dragging the crop box, a resize handle or the image; a middle or right mouse press does not
264
+
265
+ ### Keyboard and focus
266
+
267
+ - The crop box is the only tab stop in the component, and is focusable only after the image has loaded
268
+ - With focus on the crop box, each arrow key moves the box by 10px, and the box stays inside the container
269
+ - Shift + arrow keys move the bottom right corner of the box by 10px to resize it, within the container; when `aspectRatio` is set the ratio is kept (a horizontal change is converted to height). This works only while `showResizeBox` is true (the handles are shown); with false, Shift + arrow keys do nothing
270
+ - Zoom and rotation have no built-in keyboard control; provide a keyboard-operable control for them (such as the Slider in the demos)
271
+
272
+ ## Design Token
273
+
274
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/cropper/>
275
+
276
+ ## Changes from Semi Design
277
+
278
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
279
+
280
+ - 破坏性:删除 `cropperBoxCls`、`cropperBoxStyle`,改用 `classNames.cropperBox`、`styles.cropperBox`,落在裁切框上,宽高与位移以组件计算值为准。
281
+ - 裁剪框最小边长 10px 对指针拖拽同样生效;加载后改变 `aspectRatio`,裁剪框按新比例重排;滚轮缩放末步停在 `maxZoom`、`minZoom`;图片未加载时 `getCropperCanvas` 抛错;ref 为 `CropperHandle`,只有 `getCropperCanvas`。
282
+ - Svelte:`zoom` 可绑定(`bind:zoom`、函数绑定或单向传值),滚轮缩放同时调 `onZoomChange(zoom)`,`zoom` 不读全局默认值;`imgProps` 为 `HTMLImgAttributes`(加载回调用 `onload`),`style` 与 `styles` 的值只接受字符串;`getCropperCanvas()` 经 `bind:this` 调用。
283
+ - 换图后保持当前 zoom,图片尺寸与 zoom 一致。切换 `aspectRatio` 时结束进行中的角点与裁剪框拖动。
284
+ - React、Vue、Solid:服务端渲染的图片在 hydration 前已加载完成时,hydration 后补发 load 并初始化裁剪框(原来裁剪框保持 0 尺寸)。
285
+ - RTL 下裁剪器内部固定为 `direction: ltr`,裁剪框、图片与 `preview` 容器里的预览图都从左上角定位,与 LTR 一致(原来三者错位);预览图带内联 `float: left`。
@@ -0,0 +1,325 @@
1
+ # Description
2
+
3
+ > The description list is used to render key-value pairs.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/descriptions/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Descriptions } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ Svelte has no `Descriptions.Item`; declare data with `data` only.
18
+
19
+ ### Basic Usage
20
+
21
+ Data can be passed in as an array of key-value pairs `{ key: value }` through `data`.
22
+
23
+ The key and value in `data` only accept strings or numbers. To customize the rendering, use the `itemKey` and `value` snippets, whose parameter is `{ item, index }`; `index` is the position of the item in `data`, including `hidden` items.
24
+
25
+ ```svelte
26
+ <script lang="ts">
27
+ import { IconArrowUp } from '@fibrae/semi-icons-svelte';
28
+ import { Descriptions, Tag } from '@fibrae/semi-ui-svelte';
29
+
30
+ const data = [
31
+ { key: '实际用户数量', value: '1,480,000' },
32
+ { key: '7天留存', value: '98%' },
33
+ { key: '安全等级', value: '3级' },
34
+ { key: '垂类标签', value: '电商' },
35
+ { key: '认证状态', value: '未认证' },
36
+ ];
37
+ </script>
38
+
39
+ <Descriptions {data}>
40
+ {#snippet value({ item, index })}
41
+ {#if index === 1}
42
+ <div>
43
+ 98%
44
+ <IconArrowUp size="small" style="color: var(--semi-color-success); margin-inline-start: 2px" />
45
+ </div>
46
+ {:else if index === 3}
47
+ <Tag style="margin: 0">电商</Tag>
48
+ {:else}
49
+ {item.value}
50
+ {/if}
51
+ {/snippet}
52
+ </Descriptions>
53
+ ```
54
+
55
+ ### Alignment
56
+
57
+ You can use `align` to set alignment of key-value. Supporting values including: `center`(default), `justify`, `left`, and `plain`. When `row` is true, this configuration is invalid\
58
+ `left` means the start side: in RTL it mirrors to the right, like `center` and `justify`
59
+
60
+ ```svelte
61
+ <script lang="ts">
62
+ import { Card, Descriptions, Tag } from '@fibrae/semi-ui-svelte';
63
+
64
+ const data = [
65
+ { key: '实际用户数量', value: '1,480,000' },
66
+ { key: '7天留存', value: '98%' },
67
+ { key: '安全等级', value: '3级' },
68
+ { key: '垂类标签', value: '电商' },
69
+ { key: '认证状态', value: '未认证' },
70
+ ];
71
+ const aligns = ['center', 'justify', 'left', 'plain'] as const;
72
+ const style = 'margin: 10px';
73
+ </script>
74
+
75
+ <div style="display: flex; flex-wrap: wrap">
76
+ {#each aligns as align (align)}
77
+ <Card shadows="always" {style}>
78
+ <Descriptions {align} {data}>
79
+ {#snippet value({ item, index })}
80
+ {#if index === 3}
81
+ <Tag style="margin: 0">电商</Tag>
82
+ {:else}
83
+ {item.value}
84
+ {/if}
85
+ {/snippet}
86
+ </Descriptions>
87
+ </Card>
88
+ {/each}
89
+ </div>
90
+ ```
91
+
92
+ ### Descriptions Using Descriptions.Item
93
+
94
+ Svelte has no `Descriptions.Item`: write the data in `data` only, and customize the content with `{#snippet itemKey({ item, index })}...{/snippet}` and `{#snippet value({ item, index })}...{/snippet}`, which gives the same result as the demo below.
95
+
96
+ ```svelte
97
+ <script lang="ts">
98
+ import { Descriptions } from '@fibrae/semi-ui-svelte';
99
+
100
+ const data = [
101
+ { key: '实际用户数量', value: '1,480,000' },
102
+ { key: '7天留存', value: '98%' },
103
+ { key: '安全等级', value: '3级' },
104
+ { key: '垂类标签', value: '电商' },
105
+ { key: '认证状态', value: '未认证' },
106
+ ];
107
+ </script>
108
+
109
+ <Descriptions {data}>
110
+ {#snippet itemKey({ item })}{item.key}{/snippet}
111
+ {#snippet value({ item })}{item.value}{/snippet}
112
+ </Descriptions>
113
+ ```
114
+
115
+ ### Set layout mode
116
+
117
+ The layout mode can be set through `layout`. Default is `vertical`.
118
+
119
+ ```svelte
120
+ <script lang="ts">
121
+ import { Descriptions, Space, Tag } from '@fibrae/semi-ui-svelte';
122
+
123
+ const data = [
124
+ { key: '短视频号', value: 'SemiDesign' },
125
+ { key: '主播类型', value: '自由主播' },
126
+ { key: '安全等级', value: '3级' },
127
+ { key: '垂类标签', value: '互联网资讯 编程' },
128
+ { key: '作品数量', value: '88888888' },
129
+ { key: '认证状态', value: '这是一个很长很长很长很长很长很长很长很长很长的值', span: 3 },
130
+ ];
131
+ </script>
132
+
133
+ <Descriptions align="plain" column={4} {data} layout="vertical">
134
+ {#snippet value({ item, index })}
135
+ {#if index === 3}
136
+ <Space>
137
+ <Tag color="amber" shape="circle" size="small">互联网资讯</Tag>
138
+ <Tag color="violet" shape="circle" size="small">编程</Tag>
139
+ </Space>
140
+ {:else}
141
+ {item.value}
142
+ {/if}
143
+ {/snippet}
144
+ </Descriptions>
145
+ ```
146
+
147
+ Set `layout` to `horizontal` for horizontal layout. When horizontal is set, column can be used to specify the maximum number of columns per row.
148
+
149
+ ```svelte
150
+ <script lang="ts">
151
+ import { Descriptions, Tag } from '@fibrae/semi-ui-svelte';
152
+
153
+ const data = [
154
+ { key: '短视频号', value: 'SemiDesign' },
155
+ { key: '主播类型', value: '自由主播' },
156
+ { key: '安全等级', value: '3级' },
157
+ { key: '垂类标签', value: '编程' },
158
+ { key: '作品数量', value: '88888888' },
159
+ { key: '认证状态', value: '这是一个很长很长很长很长很长很长很长很长很长的值', span: 3 },
160
+ { key: '上次直播时间', value: '2024-05-01 12:00:00', span: 3 },
161
+ ];
162
+ </script>
163
+
164
+ <Descriptions align="plain" column={5} {data} layout="horizontal">
165
+ {#snippet value({ item, index })}
166
+ {#if index === 3}
167
+ <Tag color="violet" shape="circle" size="small">编程</Tag>
168
+ {:else}
169
+ {item.value}
170
+ {/if}
171
+ {/snippet}
172
+ </Descriptions>
173
+ ```
174
+
175
+ ### Row Display
176
+
177
+ Set `row` to display the data to two-row, supporting three sizes: `small`, `medium`(default), and `large`. The `align` configuration no longer takes effect.
178
+
179
+ ```svelte
180
+ <script lang="ts">
181
+ import { IconArrowUp } from '@fibrae/semi-icons-svelte';
182
+ import { Descriptions } from '@fibrae/semi-ui-svelte';
183
+
184
+ const data = [
185
+ { key: '实际用户数量', value: '1,480,000' },
186
+ { key: '7天留存', value: '98%' },
187
+ { key: '安全等级', value: '3级' },
188
+ ];
189
+ const style = 'box-shadow: var(--semi-shadow-elevated); background-color: var(--semi-color-bg-2); border-radius: 4px; padding: 10px; margin-inline-end: 20px; width: 600px';
190
+ </script>
191
+
192
+ <div>
193
+ <Descriptions {data} row size="small" {style}>
194
+ {#snippet value({ item, index })}
195
+ {#if index === 1}
196
+ <span>
197
+ 98%
198
+ <IconArrowUp size="small" style="color: red; margin-inline-start: 4px" />
199
+ </span>
200
+ {:else}
201
+ {item.value}
202
+ {/if}
203
+ {/snippet}
204
+ </Descriptions>
205
+ <br />
206
+ <Descriptions {data} row {style}>
207
+ {#snippet value({ item, index })}
208
+ {#if index === 1}
209
+ <span>
210
+ 98%
211
+ <IconArrowUp size="small" style="color: red; margin-inline-start: 4px" />
212
+ </span>
213
+ {:else}
214
+ {item.value}
215
+ {/if}
216
+ {/snippet}
217
+ </Descriptions>
218
+ <br />
219
+ <Descriptions {data} row size="large" {style}>
220
+ {#snippet value({ item, index })}
221
+ {#if index === 1}
222
+ <span>
223
+ 98%
224
+ <IconArrowUp size="small" style="color: red; margin-inline-start: 4px" />
225
+ </span>
226
+ {:else}
227
+ {item.value}
228
+ {/if}
229
+ {/snippet}
230
+ </Descriptions>
231
+ </div>
232
+ ```
233
+
234
+ ### Custom Key Style
235
+
236
+ You can customize the style of key through `styles.key`, such as setting a fixed width to achieve alignment. This property supports all CSS styles, such as `width`, `maxWidth`, `textAlign`, `color`, etc.
237
+
238
+ ```svelte
239
+ <script lang="ts">
240
+ import { Descriptions, type DescriptionsData } from '@fibrae/semi-ui-svelte';
241
+
242
+ const keyStyle = 'width: 100px; text-align: right';
243
+ const styles = { key: keyStyle };
244
+ const data: DescriptionsData[] = [
245
+ { key: '用户名', value: '张三', styles },
246
+ { key: '电子邮箱', value: 'zhangsan@example.com', styles },
247
+ { key: '联系电话', value: '138-0000-0000', styles },
248
+ { key: '地址', value: '北京市朝阳区', styles },
249
+ ];
250
+ </script>
251
+
252
+ <Descriptions align="center" {data} />
253
+ ```
254
+
255
+ You can also use it with the `itemKey` and `value` snippets:
256
+
257
+ ```svelte
258
+ <script lang="ts">
259
+ import { Descriptions, type DescriptionsData } from '@fibrae/semi-ui-svelte';
260
+
261
+ const keyStyle = 'width: 120px; color: var(--semi-color-primary)';
262
+ const styles = { key: keyStyle };
263
+ const data: DescriptionsData[] = [
264
+ { key: '姓名', value: '李四', styles },
265
+ { key: '年龄', value: '28', styles },
266
+ { key: '职业', value: '前端工程师', styles },
267
+ ];
268
+ </script>
269
+
270
+ <Descriptions align="center" {data}>
271
+ {#snippet itemKey({ item })}{item.key}{/snippet}
272
+ {#snippet value({ item })}{item.value}{/snippet}
273
+ </Descriptions>
274
+ ```
275
+
276
+ ## API Reference
277
+
278
+ ### Descriptions
279
+
280
+ **Props**
281
+
282
+ | Property | Description | Type | Default |
283
+ | - | - | - | - |
284
+ | align | Alignment: center, justify, left or plain; ignored when row is true. | `DescriptionsAlign` | `"center"` |
285
+ | column | Total number of columns per row in the horizontal layout. | `number` | `3` |
286
+ | data | Data to display, each item a `DescriptionsData`. | `DescriptionsData[]` | `[]` |
287
+ | itemKey | Snippet for the key of each data item, with the parameter `{ item, index }`, where `index` is the position in `data` (hidden items included); renders item.key by default. | `Snippet<[DescriptionsSnippetArgs]>` | - |
288
+ | layout | Layout mode: vertical or horizontal. | `DescriptionsLayout` | `"vertical"` |
289
+ | row | Whether to display key and value in two rows. | `boolean` | `false` |
290
+ | size | Size in two-row mode: small, medium or large. | `DescriptionsSize` | `"medium"` |
291
+ | value | Snippet for the value of each data item, with the parameter `{ item, index }`, where `index` is the position in `data` (hidden items included); renders item.value by default. | `Snippet<[DescriptionsSnippetArgs]>` | - |
292
+
293
+ `class`, `style` and native attributes (such as `id`, `data-*` and `aria-*`) land on the root `div` element of Descriptions.
294
+
295
+ ### DataItem
296
+
297
+ | Properties | Instructions | type | Default |
298
+ | - | - | - | - |
299
+ | key | Key value; use the `itemKey` snippet to customize rendering | string \| number | - |
300
+ | value | Data value; use the `value` snippet to customize rendering | string \| number | - |
301
+ | hidden | Toggle whether the data should be displayed | boolean | - |
302
+ | span | The number of columns the cell should span | number | 1 |
303
+ | classNames | Part class names, key `key`, appended after the built-in class names | `Partial<Record<'key', ClassValue>>` | - |
304
+ | styles | Part styles, key `key`, can be used to set width, alignment, etc. | `Partial<Record<'key', string>>` | - |
305
+
306
+ ### Descriptions.Item
307
+
308
+ Svelte has no `Descriptions.Item`; declare data items with `DataItem` in `data` only.
309
+
310
+ ## Content Guidelines
311
+
312
+ - Field names and values ​​are written in upper and lower case according to the Sentence case principle
313
+
314
+ ## Design Tokens
315
+
316
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/descriptions/>
317
+
318
+ ## Changes from Semi Design
319
+
320
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
321
+
322
+ - 破坏性:`Descriptions.Item` 与 `data` 项删除 `keyStyle`,改用 `classNames.key`、`styles.key`,落在 key 的 span 上;`data` 项上的同名字段由 Descriptions 下发给 Item。
323
+ - 横向布局只把 `Descriptions.Item`(含 Fragment 里的)当作列,非元素子节点不再占列位;`align="left"` 在 RTL 下镜像。
324
+ - Solid 破坏性(类型):`data` 项的 `key`、`value` 只接受 `string | number`(不再接受 JSX 与函数),自定义内容用 `renderKey(item, index)`、`renderValue(item, index)`,`index` 是该项在 `data` 中的位置(含 `hidden` 项);隐藏项不调用它们。`Descriptions.Item` 的 `itemKey`、`children` 不变。
325
+ - Svelte 破坏性:不提供 `Descriptions.Item`,只用 `data`;自定义内容用 `itemKey`、`value` snippet(参数 `{ item, index }`,`index` 含隐藏项);`styles` 的值只接受字符串。