@fibrae/semi-ui-svelte 0.9.1 → 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 (165) 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/interface.d.ts +57 -0
  16. package/dist/components/checkbox/interface.d.ts +19 -0
  17. package/dist/components/code-highlight/interface.d.ts +3 -0
  18. package/dist/components/collapse/interface.d.ts +16 -0
  19. package/dist/components/collapsible/interface.d.ts +10 -0
  20. package/dist/components/color-picker/interface.d.ts +10 -0
  21. package/dist/components/config-provider/interface.d.ts +7 -0
  22. package/dist/components/cropper/interface.d.ts +11 -0
  23. package/dist/components/date-picker/interface.d.ts +47 -0
  24. package/dist/components/descriptions/interface.d.ts +6 -0
  25. package/dist/components/divider/interface.d.ts +4 -0
  26. package/dist/components/dropdown/interface.d.ts +8 -0
  27. package/dist/components/empty/interface.d.ts +7 -0
  28. package/dist/components/feedback/interface.d.ts +16 -0
  29. package/dist/components/float-button/interface.d.ts +14 -0
  30. package/dist/components/form/interface.d.ts +47 -0
  31. package/dist/components/grid/interface.d.ts +13 -0
  32. package/dist/components/highlight/interface.d.ts +7 -0
  33. package/dist/components/hot-keys/interface.d.ts +3 -0
  34. package/dist/components/image/interface.d.ts +59 -0
  35. package/dist/components/input/interface.d.ts +67 -0
  36. package/dist/components/input-number/interface.d.ts +24 -0
  37. package/dist/components/json-viewer/interface.d.ts +7 -0
  38. package/dist/components/layout/interface.d.ts +3 -0
  39. package/dist/components/list/interface.d.ts +18 -0
  40. package/dist/components/locale/interface.d.ts +4 -0
  41. package/dist/components/lottie/interface.d.ts +2 -0
  42. package/dist/components/markdown-render/interface.d.ts +5 -0
  43. package/dist/components/modal/interface.d.ts +29 -0
  44. package/dist/components/navigation/interface.d.ts +47 -0
  45. package/dist/components/overflow-list/interface.d.ts +11 -0
  46. package/dist/components/pagination/interface.d.ts +12 -0
  47. package/dist/components/pincode/interface.d.ts +8 -0
  48. package/dist/components/popconfirm/interface.d.ts +12 -0
  49. package/dist/components/popover/interface.d.ts +30 -0
  50. package/dist/components/progress/interface.d.ts +13 -0
  51. package/dist/components/radio/interface.d.ts +22 -0
  52. package/dist/components/rating/interface.d.ts +12 -0
  53. package/dist/components/resizable/interface.d.ts +30 -0
  54. package/dist/components/scroll-list/interface.d.ts +6 -0
  55. package/dist/components/select/interface.d.ts +63 -0
  56. package/dist/components/side-sheet/interface.d.ts +19 -0
  57. package/dist/components/skeleton/interface.d.ts +7 -0
  58. package/dist/components/slider/interface.d.ts +23 -0
  59. package/dist/components/space/interface.d.ts +4 -0
  60. package/dist/components/spin/interface.d.ts +7 -0
  61. package/dist/components/steps/interface.d.ts +9 -0
  62. package/dist/components/switch/interface.d.ts +7 -0
  63. package/dist/components/table/interface.d.ts +48 -0
  64. package/dist/components/tabs/interface.d.ts +29 -0
  65. package/dist/components/tag/interface.d.ts +22 -0
  66. package/dist/components/tag-input/interface.d.ts +29 -0
  67. package/dist/components/time-picker/interface.d.ts +31 -0
  68. package/dist/components/timeline/interface.d.ts +5 -0
  69. package/dist/components/tooltip/interface.d.ts +20 -0
  70. package/dist/components/transfer/interface.d.ts +18 -0
  71. package/dist/components/tree/interface.d.ts +45 -0
  72. package/dist/components/tree-select/interface.d.ts +55 -0
  73. package/dist/components/typography/interface.d.ts +33 -0
  74. package/dist/components/upload/interface.d.ts +64 -0
  75. package/dist/components/user-guide/interface.d.ts +15 -0
  76. package/dist/components/video-player/interface.d.ts +22 -0
  77. package/docs/advanced/dark-mode.md +288 -0
  78. package/docs/basic/button.md +605 -0
  79. package/docs/basic/divider.md +103 -0
  80. package/docs/basic/float-button.md +246 -0
  81. package/docs/basic/grid.md +427 -0
  82. package/docs/basic/layout.md +459 -0
  83. package/docs/basic/resizable.md +584 -0
  84. package/docs/basic/space.md +163 -0
  85. package/docs/basic/tokens.md +425 -0
  86. package/docs/basic/typography.md +615 -0
  87. package/docs/changes-from-semi.md +105 -0
  88. package/docs/ecosystem/tailwind.md +210 -0
  89. package/docs/experience/accessibility.md +82 -0
  90. package/docs/experience/content-guidelines.md +819 -0
  91. package/docs/experience/internationalization.md +7 -0
  92. package/docs/feedback/banner.md +198 -0
  93. package/docs/feedback/feedback.md +294 -0
  94. package/docs/feedback/notification.md +401 -0
  95. package/docs/feedback/popconfirm.md +243 -0
  96. package/docs/feedback/progress.md +389 -0
  97. package/docs/feedback/skeleton.md +388 -0
  98. package/docs/feedback/spin.md +172 -0
  99. package/docs/feedback/toast.md +393 -0
  100. package/docs/input/auto-complete.md +399 -0
  101. package/docs/input/cascader.md +1558 -0
  102. package/docs/input/checkbox.md +408 -0
  103. package/docs/input/color-picker.md +175 -0
  104. package/docs/input/date-picker.md +942 -0
  105. package/docs/input/form.md +2550 -0
  106. package/docs/input/input-number.md +451 -0
  107. package/docs/input/input.md +640 -0
  108. package/docs/input/pincode.md +191 -0
  109. package/docs/input/radio.md +337 -0
  110. package/docs/input/rating.md +214 -0
  111. package/docs/input/select.md +1230 -0
  112. package/docs/input/slider.md +347 -0
  113. package/docs/input/switch.md +206 -0
  114. package/docs/input/tag-input.md +465 -0
  115. package/docs/input/time-picker.md +358 -0
  116. package/docs/input/transfer.md +1061 -0
  117. package/docs/input/tree-select.md +1300 -0
  118. package/docs/input/upload.md +1811 -0
  119. package/docs/llms.txt +147 -0
  120. package/docs/navigation/anchor.md +377 -0
  121. package/docs/navigation/backtop.md +100 -0
  122. package/docs/navigation/breadcrumb.md +284 -0
  123. package/docs/navigation/navigation.md +851 -0
  124. package/docs/navigation/pagination.md +217 -0
  125. package/docs/navigation/steps.md +315 -0
  126. package/docs/navigation/tabs.md +754 -0
  127. package/docs/navigation/tree.md +1956 -0
  128. package/docs/other/config-provider.md +599 -0
  129. package/docs/other/locale.md +353 -0
  130. package/docs/plus/audio-player.md +155 -0
  131. package/docs/plus/code-highlight.md +150 -0
  132. package/docs/plus/drag-move.md +214 -0
  133. package/docs/plus/hot-keys.md +174 -0
  134. package/docs/plus/json-viewer.md +392 -0
  135. package/docs/plus/lottie.md +176 -0
  136. package/docs/plus/markdown-render.md +240 -0
  137. package/docs/plus/video-player.md +325 -0
  138. package/docs/show/avatar.md +475 -0
  139. package/docs/show/badge.md +276 -0
  140. package/docs/show/calendar.md +352 -0
  141. package/docs/show/card.md +485 -0
  142. package/docs/show/carousel.md +592 -0
  143. package/docs/show/collapse.md +289 -0
  144. package/docs/show/collapsible.md +216 -0
  145. package/docs/show/cropper.md +285 -0
  146. package/docs/show/descriptions.md +325 -0
  147. package/docs/show/dropdown.md +466 -0
  148. package/docs/show/empty.md +225 -0
  149. package/docs/show/highlight.md +144 -0
  150. package/docs/show/image.md +433 -0
  151. package/docs/show/list.md +927 -0
  152. package/docs/show/modal.md +517 -0
  153. package/docs/show/overflow-list.md +272 -0
  154. package/docs/show/popover.md +534 -0
  155. package/docs/show/scroll-list.md +156 -0
  156. package/docs/show/side-sheet.md +274 -0
  157. package/docs/show/table.md +5437 -0
  158. package/docs/show/tag.md +428 -0
  159. package/docs/show/timeline.md +277 -0
  160. package/docs/show/tooltip.md +442 -0
  161. package/docs/show/user-guide.md +419 -0
  162. package/docs/start/getting-started.md +234 -0
  163. package/docs/start/introduction.md +57 -0
  164. package/docs/start/overview.md +21 -0
  165. package/package.json +5 -4
@@ -0,0 +1,276 @@
1
+ # Badge
2
+
3
+ > Badge generates a small badge to give users tips.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/badge/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Badge } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ The basic type of Badge is `count`. The `dot` property changes a badge into a small dot. The two are mutually exclusive, giving priority to rendering `dot`.
20
+
21
+ `count` accepts a number, a string or a snippet. Write a snippet as `{#snippet count()}...{/snippet}` inside the Badge tag; it is rendered as is, and the `type` and `theme` classes are removed. Pass numbers with `count={5}`: `count="5"` is a string and is never cut off by `overflowCount`. The element the badge is attached to goes inside the tag, as the `children` snippet.
22
+
23
+ ```svelte
24
+ <script lang="ts">
25
+ import { IconLock } from '@fibrae/semi-icons-svelte';
26
+ import { Avatar, Badge } from '@fibrae/semi-ui-svelte';
27
+
28
+ const style = 'width: 42px; height: 42px; border-radius: 4px';
29
+ </script>
30
+
31
+ <div>
32
+ <Badge count={5}>
33
+ <Avatar color="blue" shape="square" {style}>BM</Avatar>
34
+ </Badge>
35
+ <br />
36
+ <br />
37
+ <Badge dot>
38
+ <Avatar color="blue" shape="square" {style}>YL</Avatar>
39
+ </Badge>
40
+ <br />
41
+ <br />
42
+ <Badge>
43
+ {#snippet count()}
44
+ <IconLock style="color: var(--semi-color-primary)" />
45
+ {/snippet}
46
+ <Avatar color="light-blue" shape="square" {style}>XZ</Avatar>
47
+ </Badge>
48
+ <br />
49
+ <br />
50
+ <Badge count="NEW">
51
+ <Avatar color="light-blue" shape="square" {style}>WF</Avatar>
52
+ </Badge>
53
+ </div>
54
+ ```
55
+
56
+ ### Maximum Value
57
+
58
+ You can use the `overflowCount` property to cap the number value of the badge content. When the actual value exceeds that value, it will be formatted into `${overflowCount}+`.
59
+
60
+ ```svelte
61
+ <script lang="ts">
62
+ import { Avatar, Badge } from '@fibrae/semi-ui-svelte';
63
+
64
+ const style = 'width: 42px; height: 42px; border-radius: 4px';
65
+ </script>
66
+
67
+ <div>
68
+ <Badge count={99}>
69
+ <Avatar color="teal" shape="square" {style}>ZH</Avatar>
70
+ </Badge>
71
+ <br />
72
+ <br />
73
+ <Badge count={100}>
74
+ <Avatar color="teal" shape="square" {style}>HS</Avatar>
75
+ </Badge>
76
+ <br />
77
+ <br />
78
+ <Badge count={99} overflowCount={10}>
79
+ <Avatar color="green" shape="square" {style}>DY</Avatar>
80
+ </Badge>
81
+ <br />
82
+ <br />
83
+ <Badge count={1000} overflowCount={999}>
84
+ <Avatar color="green" shape="square" {style}>TT</Avatar>
85
+ </Badge>
86
+ </div>
87
+ ```
88
+
89
+ ### Position
90
+
91
+ You can use the `position` property to set the position of the badge to its children. The prop uses one of: `leftTop`, `leftBottom`, `rightTop`(default), `rightBottom`. Under an RTL ConfigProvider the default is `leftTop`.
92
+
93
+ ```svelte
94
+ <script lang="ts">
95
+ import { Avatar, Badge } from '@fibrae/semi-ui-svelte';
96
+
97
+ const style = 'width: 42px; height: 42px; border-radius: 4px';
98
+ </script>
99
+
100
+ <div>
101
+ <Badge count="VIP" position="rightTop" type="danger">
102
+ <Avatar color="amber" shape="square" {style}>ZH</Avatar>
103
+ </Badge>
104
+ <br />
105
+ <br />
106
+ <Badge count="VIP" position="rightBottom" type="danger">
107
+ <Avatar color="amber" shape="square" {style}>HS</Avatar>
108
+ </Badge>
109
+ <br />
110
+ <br />
111
+ <Badge count="VIP" position="leftTop" type="danger">
112
+ <Avatar color="orange" shape="square" {style}>DY</Avatar>
113
+ </Badge>
114
+ <br />
115
+ <br />
116
+ <Badge count="VIP" position="leftBottom" type="danger">
117
+ <Avatar color="orange" shape="square" {style}>TT</Avatar>
118
+ </Badge>
119
+ </div>
120
+ ```
121
+
122
+ ### Theming
123
+
124
+ You can use the `theme` and `type` prop to customize the styling. `theme` supports the following values: `solid`(default), `light`, `inverted`.
125
+
126
+ ```svelte
127
+ <script lang="ts">
128
+ import { Avatar, Badge } from '@fibrae/semi-ui-svelte';
129
+
130
+ const bgStyle = 'padding: 8px';
131
+ const style = 'width: 42px; height: 42px; border-radius: 4px';
132
+ </script>
133
+
134
+ <div style="display: flex">
135
+ <div style={bgStyle}>
136
+ <Badge count={5} theme="solid">
137
+ <Avatar color="indigo" shape="square" {style}>XZ</Avatar>
138
+ </Badge>
139
+ </div>
140
+ <div style={bgStyle}>
141
+ <Badge count={5} theme="light">
142
+ <Avatar color="indigo" shape="square" {style}>YB</Avatar>
143
+ </Badge>
144
+ </div>
145
+ <div style={bgStyle}>
146
+ <Badge count={5} theme="inverted">
147
+ <Avatar color="light-green" shape="square" {style}>LX</Avatar>
148
+ </Badge>
149
+ </div>
150
+ <br />
151
+ <div style={bgStyle}>
152
+ <Badge dot theme="solid">
153
+ <Avatar color="light-green" shape="square" {style}>YZ</Avatar>
154
+ </Badge>
155
+ </div>
156
+ <div style={bgStyle}>
157
+ <Badge dot theme="light">
158
+ <Avatar color="lime" shape="square" {style}>HW</Avatar>
159
+ </Badge>
160
+ </div>
161
+ <div style="padding: 8px; border-radius: 4px; background-color: var(--semi-color-fill-0)">
162
+ <Badge dot theme="inverted">
163
+ <Avatar color="lime" shape="square" {style}>XM</Avatar>
164
+ </Badge>
165
+ </div>
166
+ </div>
167
+ ```
168
+
169
+ `type` support the following values: `primary`(default),`secondary`,`tertiary`,`warning` and `danger`.
170
+
171
+ ```svelte
172
+ <script lang="ts">
173
+ import { Avatar, Badge } from '@fibrae/semi-ui-svelte';
174
+
175
+ const bgStyle = 'padding: 8px 8px 3px 8px';
176
+ const style = 'width: 42px; height: 42px; border-radius: 4px';
177
+ </script>
178
+
179
+ <div style="display: flex">
180
+ <div style={bgStyle}>
181
+ <Badge count={5} type="primary">
182
+ <Avatar color="violet" shape="square" {style}>MR</Avatar>
183
+ </Badge>
184
+ </div>
185
+ <div style={bgStyle}>
186
+ <Badge count={5} type="secondary">
187
+ <Avatar color="violet" shape="square" {style}>YL</Avatar>
188
+ </Badge>
189
+ </div>
190
+ <div style={bgStyle}>
191
+ <Badge count={5} type="tertiary">
192
+ <Avatar color="red" shape="square" {style}>ZW</Avatar>
193
+ </Badge>
194
+ </div>
195
+ <br />
196
+ <div style={bgStyle}>
197
+ <Badge count={5} type="warning">
198
+ <Avatar color="red" shape="square" {style}>JL</Avatar>
199
+ </Badge>
200
+ </div>
201
+ <div style={bgStyle}>
202
+ <Badge count={5} type="danger">
203
+ <Avatar color="pink" shape="square" {style}>RT</Avatar>
204
+ </Badge>
205
+ </div>
206
+ <div style={bgStyle}>
207
+ <Badge dot type="primary">
208
+ <Avatar color="pink" shape="square" {style}>YF</Avatar>
209
+ </Badge>
210
+ </div>
211
+ </div>
212
+ ```
213
+
214
+ ### Independent Usage
215
+
216
+ Badge can be used alone when it is a stand-alone element.
217
+
218
+ ```svelte
219
+ <script lang="ts">
220
+ import { Badge } from '@fibrae/semi-ui-svelte';
221
+ </script>
222
+
223
+ <div>
224
+ <Badge count={5} />
225
+ <br />
226
+ <br />
227
+ <Badge count="NEW" theme="light" />
228
+ <br />
229
+ <br />
230
+ <Badge count={99} overflowCount={10} type="danger" />
231
+ <br />
232
+ <br />
233
+ <span><Badge dot type="primary" /> 进行中 processing</span>
234
+ <br />
235
+ <span><Badge dot type="tertiary" /> 信息 info</span>
236
+ <br />
237
+ <span><Badge dot type="success" /> 成功 success</span>
238
+ <br />
239
+ <span><Badge dot type="warning" /> 提醒 warning</span>
240
+ <br />
241
+ <span><Badge dot type="danger" /> 错误 error</span>
242
+ </div>
243
+ ```
244
+
245
+ ## API Reference
246
+
247
+ **Props**
248
+
249
+ | Property | Description | Type | Default |
250
+ | - | - | - | - |
251
+ | children | Snippet for the element the badge is attached to. Without it the badge stands alone. | `Snippet` | - |
252
+ | classNames | Class names of the inner parts, keyed by count; values take anything class takes (string, array or object) and merge with the built-in classes. | `Partial<Record<BadgePart, ClassValue>>` | - |
253
+ | count | Badge content as a number, string or snippet. A snippet is rendered as given and removes the type and theme classes. | `number \| string \| Snippet \| null` | - |
254
+ | dot | Shows a small dot instead of the content. | `boolean` | `false` |
255
+ | overflowCount | Maximum number shown; larger numbers display as `${overflowCount}+`. Applies to numbers only, and 0 counts as unset. | `number` | - |
256
+ | position | Badge position relative to the wrapped element. Defaults to leftTop under an RTL ConfigProvider and rightTop otherwise. | `BadgePosition` | - |
257
+ | styles | Style strings of the inner parts, keyed like classNames. | `Partial<Record<BadgePart, string>>` | - |
258
+ | theme | Badge theme: solid, light or inverted. | `BadgeTheme` | `"solid"` |
259
+ | type | Badge type: primary, secondary, tertiary, danger, warning or success. | `BadgeType` | `"primary"` |
260
+
261
+ `class`, `style`, native attributes and native events (such as `id`, `aria-*` and `onclick`) land on the root `<span>` element. `classNames.count` and `styles.count` only apply to the count element.
262
+
263
+ ## Content Guidelines
264
+
265
+ - Capitalize the first letter
266
+
267
+ ## Design Tokens
268
+
269
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/badge/>
270
+
271
+ ## Changes from Semi Design
272
+
273
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
274
+
275
+ - 破坏性:删除 `countClassName`、`countStyle`,改用 `classNames.count`、`styles.count`,落在计数节点上。
276
+ - Svelte:`count` 接受数字、字符串或 snippet;`styles` 的值只接受字符串。
@@ -0,0 +1,352 @@
1
+ # Calendar
2
+
3
+ > Calendar component that allows to display corresponding events in day/week/month view
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/calendar/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Calendar } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Day Mode
18
+
19
+ Day mode. You could toggle the red line of current time using `showCurrTime`.
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { Calendar } from '@fibrae/semi-ui-svelte';
24
+
25
+ // A fixed date keeps the server render and the browser on the same first frame
26
+ const displayValue = new Date(2026, 9, 25);
27
+ </script>
28
+
29
+ <Calendar {displayValue} mode="day" />
30
+ ```
31
+
32
+ ### Week Mode
33
+
34
+ Week mode. You could toggle the red line of current time using `showCurrTime`.
35
+
36
+ ```svelte
37
+ <script lang="ts">
38
+ import { Calendar } from '@fibrae/semi-ui-svelte';
39
+
40
+ // A fixed date keeps the server render and the browser on the same first frame
41
+ const displayValue = new Date(2026, 9, 25);
42
+ </script>
43
+
44
+ <Calendar {displayValue} mode="week" />
45
+ ```
46
+
47
+ ### Month Mode
48
+
49
+ Month Mode.
50
+
51
+ ```svelte
52
+ <script lang="ts">
53
+ import { Calendar } from '@fibrae/semi-ui-svelte';
54
+
55
+ // A fixed date keeps the server render and the browser on the same first frame
56
+ const displayValue = new Date(2019, 6, 23);
57
+ </script>
58
+
59
+ <Calendar {displayValue} mode="month" />
60
+ ```
61
+
62
+ ### Set week start day
63
+
64
+ The day of the week can be set as the first day of the week through weekStartsOn, 0 for Sunday, 1 for Monday, and so on. Default is Sunday.\
65
+ `weekStartsOn` takes effect for month view and week view.
66
+
67
+ ```svelte
68
+ <script lang="ts">
69
+ import { Calendar, Radio, RadioGroup, type WeekStartsOn } from '@fibrae/semi-ui-svelte';
70
+
71
+ let weekStartsOn = $state(0);
72
+ const days = ['周日', '周一', '周二', '周三', '周四', '周五', '周六'];
73
+ // A fixed date keeps the server render and the browser on the same first frame
74
+ const displayValue = new Date(2019, 6, 23);
75
+ </script>
76
+
77
+ <div>
78
+ <RadioGroup aria-label="周起始日" bind:value={weekStartsOn} name="demo-radio-group-vertical" type="button">
79
+ {#each days as day, index (day)}
80
+ <Radio value={index}>{day}</Radio>
81
+ {/each}
82
+ </RadioGroup>
83
+ <Calendar {displayValue} mode="month" style="margin-block-start: 20px" weekStartsOn={weekStartsOn as WeekStartsOn} />
84
+ </div>
85
+ ```
86
+
87
+ ### Range Mode
88
+
89
+ Range Mode. `range` is required which is a left-closed and right-open interval.
90
+
91
+ ```svelte
92
+ <script lang="ts">
93
+ import { Calendar } from '@fibrae/semi-ui-svelte';
94
+
95
+ const displayValue = new Date(2020, 8, 26);
96
+ const range = [new Date(2020, 8, 26), new Date(2020, 8, 31)];
97
+ </script>
98
+
99
+ <Calendar {displayValue} mode="range" {range} />
100
+ ```
101
+
102
+ ### Render Events
103
+
104
+ You could pass in an array of event objects to `events` to render items. For detailed format, refer to Event Object below.
105
+
106
+ The content of an event defaults to the `children` text. For custom DOM use the `event` snippet; its `{ event }` argument is the original object from `events`, which may carry any custom fields. When one event is shown in several places (such as a multi-day event), the snippet is called once for each place.
107
+
108
+ ```svelte
109
+ <script lang="ts">
110
+ import { Calendar, DatePicker, Radio, RadioGroup, type CalendarMode, type EventObject } from '@fibrae/semi-ui-svelte';
111
+
112
+ let mode = $state('week');
113
+ let displayValue = $state(new Date(2019, 6, 23, 8, 32, 0));
114
+
115
+ const onChangeDate = (date?: Date | Date[]) => {
116
+ if (date instanceof Date) displayValue = date;
117
+ };
118
+
119
+ const dailyEventStyle = 'border-radius: 3px; box-sizing: border-box; border: var(--semi-color-primary) 1px solid; padding: 10px; background-color: var(--semi-color-primary-light-default); height: 100%; overflow: hidden';
120
+ const allDayStyle = 'border-radius: 3px; box-sizing: border-box; border: var(--semi-color-bg-1) 1px solid; padding: 2px 4px; background-color: var(--semi-color-primary-light-active); height: 100%; overflow: hidden';
121
+ // `daily` marks the events that keep the padded style outside the month view; any extra key is passed to the event snippet.
122
+ const events: EventObject[] = [
123
+ {
124
+ key: '0',
125
+ start: new Date(2019, 5, 25, 14, 45, 0),
126
+ end: new Date(2019, 6, 26, 6, 18, 0),
127
+ children: '6月25日 14:45 ~ 7月26日 6:18',
128
+ },
129
+ {
130
+ key: '1',
131
+ start: new Date(2019, 6, 18, 10, 0, 0),
132
+ end: new Date(2019, 6, 30, 8, 0, 0),
133
+ children: '7月18日 10:00 ~ 7月30日 8:00',
134
+ },
135
+ {
136
+ key: '2',
137
+ start: new Date(2019, 6, 19, 20, 0, 0),
138
+ end: new Date(2019, 6, 23, 14, 0, 0),
139
+ children: '7月19日 20:00 ~ 7月23日 14:00',
140
+ },
141
+ {
142
+ key: '3',
143
+ start: new Date(2019, 6, 21, 6, 0, 0),
144
+ end: new Date(2019, 6, 25, 6, 0, 0),
145
+ children: '7月21日 6:00 ~ 7月25日 6:00',
146
+ },
147
+ { key: '4', allDay: true, start: new Date(2019, 6, 22, 8, 0, 0), children: '7月22日 全天' },
148
+ {
149
+ key: '5',
150
+ start: new Date(2019, 6, 22, 9, 0, 0),
151
+ end: new Date(2019, 6, 23, 23, 0, 0),
152
+ children: '7月22日 9:00 ~ 7月23日 23:00',
153
+ },
154
+ {
155
+ key: '6',
156
+ daily: true,
157
+ start: new Date(2019, 6, 23, 8, 32, 0),
158
+ end: new Date(2019, 6, 23, 8, 42, 0),
159
+ children: '7月23日 8:32',
160
+ },
161
+ {
162
+ key: '7',
163
+ daily: true,
164
+ start: new Date(2019, 6, 23, 14, 30, 0),
165
+ end: new Date(2019, 6, 23, 20, 0, 0),
166
+ children: '7月23日 14:30-20:00',
167
+ },
168
+ {
169
+ key: '8',
170
+ start: new Date(2019, 6, 25, 8, 0, 0),
171
+ end: new Date(2019, 6, 27, 6, 0, 0),
172
+ children: '7月25日 8:00 ~ 7月27日 6:00',
173
+ },
174
+ {
175
+ key: '9',
176
+ start: new Date(2019, 6, 26, 10, 0, 0),
177
+ end: new Date(2019, 6, 27, 16, 0, 0),
178
+ children: '7月26日 10:00 ~ 7月27日 16:00',
179
+ },
180
+ ];
181
+ const range = $derived(mode === 'range' ? [new Date(2019, 6, 23), new Date(2019, 6, 26)] : []);
182
+ </script>
183
+
184
+ <RadioGroup aria-label="视图模式" bind:value={mode} type="button">
185
+ <Radio value="day">日视图</Radio>
186
+ <Radio value="week">周视图</Radio>
187
+ <Radio value="month">月视图</Radio>
188
+ <Radio value="range">多日视图</Radio>
189
+ </RadioGroup>
190
+ <br />
191
+ <br />
192
+ <DatePicker onChange={onChangeDate} value={displayValue} />
193
+ <br />
194
+ <br />
195
+ <Calendar {displayValue} {events} height={400} minEventHeight={40} mode={mode as CalendarMode} {range}>
196
+ {#snippet event(eventData)}
197
+ <div style={eventData.event.daily && mode !== 'month' ? dailyEventStyle : allDayStyle}>{eventData.event.children}</div>
198
+ {/snippet}
199
+ </Calendar>
200
+ ```
201
+
202
+ ### Custom Render
203
+
204
+ You could use the `dateGrid` snippet (argument `{ date, dateString }`) to render customized date cell or column. Use absolute positioning for elements.
205
+
206
+ #### Custom Render Events
207
+
208
+ ```svelte
209
+ <script lang="ts">
210
+ import { Calendar } from '@fibrae/semi-ui-svelte';
211
+
212
+ const dailyEventStyle = 'position: absolute; inset-inline: 0; border-radius: 3px; box-sizing: border-box; border: var(--semi-color-primary) 1px solid; padding: 10px; background-color: var(--semi-color-primary-light-default); overflow: hidden';
213
+ const displayValue = new Date(2019, 6, 23, 8, 32, 0);
214
+ const targetDateString = new Date(2019, 6, 23).toString();
215
+ </script>
216
+
217
+ <Calendar {displayValue} height={700} mode="week">
218
+ {#snippet dateGrid(cell)}
219
+ {#if cell.dateString === targetDateString}
220
+ <div style="{dailyEventStyle}; top: 500px; height: 50px">吃饭 🍰</div>
221
+ <div style="{dailyEventStyle}; top: 0; height: 400px">睡觉 😪</div>
222
+ <div style="{dailyEventStyle}; top: 700px; height: 100px">打豆豆 🎮</div>
223
+ {/if}
224
+ {/snippet}
225
+ </Calendar>
226
+ ```
227
+
228
+ #### Customized Date Cell Style
229
+
230
+ You could also use the `dateGrid` snippet to customize date cell style, e.g. backgroundColor. Please notice that in Month View, the date text on the right corner has a z-index of 3. Use a larger z-index if you would like to cover the text as well.
231
+
232
+ ```svelte
233
+ <script lang="ts">
234
+ import { Calendar } from '@fibrae/semi-ui-svelte';
235
+
236
+ const importantDate = 'position: absolute; inset-inline: 0; top: 0; bottom: 0; background-color: var(--semi-color-danger-light-default)';
237
+ const displayValue = new Date(2019, 6, 23, 8, 32, 0);
238
+ const importDates = [new Date(2019, 6, 2), new Date(2019, 6, 8), new Date(2019, 6, 19), new Date(2019, 6, 23)];
239
+ </script>
240
+
241
+ <Calendar {displayValue} height={700} mode="month">
242
+ {#snippet dateGrid(cell)}
243
+ {#if importDates.some((date) => date.toString() === cell.dateString)}
244
+ <div style={importantDate}></div>
245
+ {/if}
246
+ {/snippet}
247
+ </Calendar>
248
+ ```
249
+
250
+ #### Customized Date Render
251
+
252
+ You could use the `dateDisplay` snippet (argument `{ date }`) to customize the display of date.
253
+
254
+ ```svelte
255
+ <script lang="ts">
256
+ import { Avatar, Calendar } from '@fibrae/semi-ui-svelte';
257
+
258
+ const displayValue = new Date(2023, 4, 14);
259
+ const colors = ['amber', 'blue', 'cyan', 'green', 'grey', 'indigo', 'lime'] as const;
260
+ </script>
261
+
262
+ <Calendar {displayValue} height={400} mode="week">
263
+ {#snippet dateDisplay(display)}
264
+ <div style="padding-block: 6px">
265
+ <Avatar color={colors[display.date.getDay()]} size="small">{display.date.getDate()}</Avatar>
266
+ </div>
267
+ {/snippet}
268
+ </Calendar>
269
+ ```
270
+
271
+ ## API Reference
272
+
273
+ ### Calendar
274
+
275
+ **Props**
276
+
277
+ | Property | Description | Type | Default |
278
+ | - | - | - | - |
279
+ | allDayEvents | Snippet for the area for events at the top of the day, range and week views; events is the whole events array that was passed in, to be filtered by the snippet, which renders li items. | `Snippet<[CalendarAllDayEventsArgs]>` | - |
280
+ | dateDisplay | Snippet for custom date text: the column titles of the week and range views and every cell of the month view. The day view does not use it. | `Snippet<[CalendarDateDisplayArgs]>` | - |
281
+ | dateGrid | Snippet for custom content of a date cell or column, with the date and its dateString (date.toString()). Use absolute positioning for elements. | `Snippet<[CalendarDateGridArgs]>` | - |
282
+ | displayValue | Display date. When omitted it is the current date and updates at midnight. | `Date` | - |
283
+ | event | Snippet for custom event content. event is the original object from events and the snippet is called once for each place the event appears. The text of children is rendered when it is absent. | `Snippet<[CalendarEventArgs]>` | - |
284
+ | events | Events to render, see Event Object. | `EventObject[]` | `[]` |
285
+ | header | Snippet for custom header content. | `Snippet` | - |
286
+ | height | Height of the calendar; a number is in pixels. | `number \| string` | `600` |
287
+ | markWeekend | Shows weekend columns in grey to tell them from weekdays. | `boolean` | `false` |
288
+ | minEventHeight | Minimum height in pixels of events in the day, range and week views. | `number` | - |
289
+ | mode | View mode: day, week, month or range. The view switches as soon as it changes. | `CalendarMode` | `"week"` |
290
+ | onClick | Called when a date cell is clicked, with the event and the date of the cell. The unit is half an hour in the day, week and range views and one day in the month view. | `(event: MouseEvent, value: Date) => void` | - |
291
+ | onClose | Called when the card showing all events of a day closes in the month view: the click event for the close button or a second click on "N more", the keyboard event for Esc, and null for a click outside. | `(event: MouseEvent \| KeyboardEvent \| null) => void` | - |
292
+ | onMoreClick | Called when a click on "N more" opens the card in the month view, with the event, the date and the number of collapsed events. It is not called when a second click closes the card. | `(event: MouseEvent, date: Date, remaining: number) => void` | - |
293
+ | range | Date range shown in range mode, left-closed and right-open. Required in range mode. | `Date[]` | - |
294
+ | scrollTop | Default scroll offset of the content in the day, week and range views. | `number` | `400` |
295
+ | showCurrTime | Shows the red line of the current time in the day, week and range views. | `boolean` | `true` |
296
+ | timeDisplay | Snippet for custom time text in the day, week and range views; time is the hour. | `Snippet<[CalendarTimeDisplayArgs]>` | - |
297
+ | weekStartsOn | Day of the week that starts the week, 0 for Sunday, 1 for Monday and so on. Applies to the month and week views. | `WeekStartsOn` | `0` |
298
+ | width | Width of the calendar; a number is in pixels. | `number \| string` | - |
299
+
300
+ `class`, `style` and other native attributes (such as `id`, `data-*`, `aria-label`) land on the root element of the current view; `aria-label` takes precedence over the default table name. `onClick`, `onClose` and `onMoreClick` are callbacks of Calendar itself and do not land on the root element.
301
+
302
+ ### Event Object
303
+
304
+ `events` is an array of event objects.\
305
+ An event needs at least a start or an end time to be valid; an event with neither is skipped with a warning. An all-day event with only an end time starts on the day of its end. A timed event with only one end is extended by 1 hour, without crossing into another day. The end time is exclusive: a timed event that ends exactly at 00:00 is shown only on its start day, with no extra segment on the next day.
306
+
307
+ > **Attention**
308
+ >
309
+ > Key property is required and must be unique. It identifies the event. When `events` changes, the layout is recomputed from its content, so an event that keeps its key but changes its time or children is updated as well.
310
+
311
+ | Properties | Instructions | type | Default |
312
+ | - | - | - | - |
313
+ | allDay | Whether it is an all-day event | boolean | false |
314
+ | children | Displayed content, rendered as text without the `event` snippet | string \| number | - |
315
+ | end | End time of the event | Date | - |
316
+ | key | Required and must be unique. | string | - |
317
+ | start | Start time of the event | Date | - |
318
+ | Other fields | Custom fields are kept as they are for the `event` snippet (color, title) | any | - |
319
+
320
+ ## Accessibility
321
+
322
+ ### Keyboard and Focus
323
+
324
+ - The day, week and range views scroll, and the view itself is one Tab stop that the arrow keys scroll
325
+ - In the month view, "N more" for the collapsed events is a button: `Enter` or `Space` opens the card of the day and moves focus to its close button; `Esc` or the close button closes the card and returns focus to "N more"
326
+ - Clicks on a day cell or a time slot (`onClick` in React, `@click` in Vue, `onClick` in Svelte) respond to the pointer only and have no keyboard equivalent
327
+
328
+ The accessible names of the views and day cells are formatted by date-fns: with the built-in zh-CN or en-US picked by the current locale's `code`, and enUS for other languages. When needed, import another language from `date-fns/locale` and pass it to the `dateFnsLocale` of ConfigProvider; see [Internationalization](../other/locale.md).
329
+
330
+ ## Content Guidelines
331
+
332
+ - Both 12-hour and 24-hour clocks can be used when the time needs to be displayed
333
+ - If the 12-hour clock is used, it needs to be used together with AM/PM. For details, please refer to [Time Specification](../experience/content-guidelines.md#8.%20%E6%97%A5%E6%9C%9F%E4%B8%8E%E6%97%B6%E9%97%B4)
334
+ - For the abbreviation rules for month, week and time, please refer to [Abbreviation Specification](../experience/content-guidelines.md#1.%20%E7%BC%A9%E5%86%99)
335
+
336
+ ## Design Tokens
337
+
338
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/calendar/>
339
+
340
+ ## Changes from Semi Design
341
+
342
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
343
+
344
+ - 破坏性(类型):React、Solid 的 `dateGridRender` 两个参数改为必填。
345
+ - 破坏性(深路径导入,类型):foundation `calendar/foundation`、`calendar/event-util` 的 `weekStartsOnEnum` 改名 `WeekStartsOn`(与 Vue、Svelte 的同名类型一致)。
346
+ - 破坏性(类型):`onClose` 参数改为 `React.MouseEvent | KeyboardEvent | null`(点击外部关闭为 `null`);`CalendarProps` 不再包含 `children`;`DayColProps.events` 收紧为 `DailyEventLayout[]`。
347
+ - 各视图改为 ARIA 表格(ul、li 改 div,类名不变),月视图「N 更多」改为原生 `button`,展开卡片是对话框,依赖旧 DOM 结构或 role 的测试与选择器需调整。日期格与时间槽的点击回调仍只能由指针触发(已知限制)。
348
+ - 各视图的「今天」标记与当前时间线在服务端渲染与 hydration 期间不出现,挂载后再标出。
349
+ - Svelte:自定义渲染用 snippet,名字照 Vue 插槽:`header`、`event`、`dateDisplay`、`dateGrid`、`timeDisplay`、`allDayEvents`;事件为回调 prop:`onClick(event, value)`、`onClose(event | null)`、`onMoreClick(event, date, remaining)`;`events[].children` 只接受 `string | number`,其他内容用 `event` snippet。
350
+ - Svelte:提供 `header` snippet 后,即使渲染为空也保留表头行;month 视图首帧行数上限为 0,有事件的日期在服务端 HTML 里先折叠成「还有 N 项」,挂载后按真实行高展开;未传 `displayValue` 时,服务端不输出 today 高亮与当前时间线,挂载后才出现,SSR 场景应传 `displayValue`。
351
+ - RTL 下全天事件与日视图事件镜像,内联定位由 `left` 改为 `inset-inline-start`。React:月视图可见事件数变化时不再重新挂载整棵视图,事件内容的状态保留。
352
+ - 月视图同时只开一张「N 更多」卡片,打开另一张时前一张直接关闭;被折叠的日期格因行高或事件变化不再折叠时,卡片关闭并通知一次 `onClose`,不会自己重新弹出。