@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,942 @@
1
+ # DatePicker
2
+
3
+ > The date selector is used to help the user select a compliant, formatted date (time) or date (time) range.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/input/date-picker/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Use
18
+
19
+ ```svelte
20
+ <script lang="ts">
21
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
22
+ </script>
23
+
24
+ <DatePicker onChange={(_date, dateString) => console.log(dateString)} />
25
+ ```
26
+
27
+ ### Picker Density
28
+
29
+ The density can be used to control the size of the picker panel. The `compact` is the small size and the `default` is the default size.
30
+
31
+ ```svelte
32
+ <script lang="ts">
33
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
34
+ </script>
35
+
36
+ <div>
37
+ <DatePicker density="compact" type="dateTime" />
38
+ <br />
39
+ <br />
40
+ <DatePicker density="compact" style="width: 260px" type="dateRange" />
41
+ </div>
42
+ ```
43
+
44
+ ### Multiple Date Selection
45
+
46
+ Set `Multiple` to `true`, can choose multiple dates.
47
+
48
+ ```svelte
49
+ <script lang="ts">
50
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
51
+ </script>
52
+
53
+ <DatePicker multiple style="width: 240px" />
54
+ ```
55
+
56
+ ### Date and Time Selection
57
+
58
+ Set `type` to `dateTime`, can choose date and time.\
59
+ The default mode of ScrollItem in TimePicker is normal. If you want the infinite scrolling effect, you can enable it by passing in a specific configuration through timePickerOpts.
60
+
61
+ ```svelte
62
+ <script lang="ts">
63
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
64
+ </script>
65
+
66
+ <h4>默认日期与时间选择</h4>
67
+ <DatePicker type="dateTime" />
68
+ <br />
69
+ <br />
70
+ <h4>开启时间列表无限循环</h4>
71
+ <DatePicker timePickerOpts={{ scrollItemProps: { mode: 'wheel', cycled: true } }} type="dateTime" />
72
+ ```
73
+
74
+ ### Date Range Selection
75
+
76
+ Set `type` to `dateRange`, can choose the date range.
77
+
78
+ ```svelte
79
+ <script lang="ts">
80
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
81
+ </script>
82
+
83
+ <DatePicker onChange={console.log} style="width: 260px" type="dateRange" />
84
+ ```
85
+
86
+ > **Note**
87
+ >
88
+ > When you use range selection, if only one date is selected, neither onChange is called nor the bound value updated at this time. Only when both the start date and the end date are selected will they happen.
89
+
90
+ ### Date Time Range Selection
91
+
92
+ Set `type` to `dateTimeRange`, can choose the date range and choose time;
93
+
94
+ ```svelte
95
+ <script lang="ts">
96
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
97
+
98
+ const defaultPickerValue = [new Date('2022-08-08 00:00'), new Date('2022-08-09 12:00')];
99
+ </script>
100
+
101
+ <DatePicker onChange={console.log} style="width: 400px; margin-block-end: 8px" type="dateTimeRange" />
102
+ <DatePicker {defaultPickerValue} onChange={console.log} style="width: 400px" type="dateTimeRange" />
103
+ ```
104
+
105
+ ### Input in Panel
106
+
107
+ Use `insetInput` to control whether the date panel is inset with the input box, the default is `false`. Inset input boxes are suitable for the following scenarios:
108
+
109
+ - Date and time selection, you can directly input the time through the embedded input box, no need to select the time through the scroll wheel
110
+ - With a custom trigger and range selection, use the inset input box to modify the start and end dates independently
111
+
112
+ After `insetInput` is turned on, it includes the following functions:
113
+
114
+ - After clicking the trigger, the panel will pop up in the original position by default. You can customize the popup position by `position`
115
+ - Click the embedded date input box, the panel switches to date selection; click the embedded time input box, the panel switches to time selection
116
+ - Consistent with the external input box, if an illegal date is entered, the date will return to the previous legal date after the panel is closed
117
+
118
+ > **Notes**
119
+ >
120
+ > Note that some adjustments and restrictions will be made to the components after opening insetInput:
121
+ >
122
+ > 1. Trigger style: the trigger is read-only when the panel is not open, and the trigger is disabled when it is open
123
+ > 2. Panel style: when type includes time, hide the toggle button at the bottom
124
+ > 3. After insetInput is enabled, the `format` API only supports the `dateFormat[ timeFormat]` format. Using other formats will affect the display of the inset input box placeholder and trigger text. When timeFormat is a 12-hour format (such as `hh:mm a`), the inset time input shows and accepts 24-hour time
125
+
126
+ ```svelte
127
+ <script lang="ts">
128
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
129
+ </script>
130
+
131
+ <div>
132
+ <DatePicker insetInput type="date" />
133
+ <br />
134
+ <br />
135
+ <DatePicker insetInput type="dateTime" />
136
+ <br />
137
+ <br />
138
+ <DatePicker insetInput style="width: 260px" type="dateRange" />
139
+ <br />
140
+ <br />
141
+ <DatePicker insetInput style="width: 400px" type="dateTimeRange" />
142
+ <br />
143
+ <br />
144
+ <DatePicker insetInput placeholder="请选择年月" style="width: 140px" type="month" />
145
+ <br />
146
+ <br />
147
+ <DatePicker insetInput placeholder="请选择年月范围" style="width: 200px" type="monthRange" />
148
+ <br />
149
+ <br />
150
+ <DatePicker insetInput position="bottomLeft" type="date" />
151
+ <br />
152
+ <br />
153
+ <DatePicker format="yyyy-MM-dd HH:mm" insetInput type="dateTime" />
154
+ </div>
155
+ ```
156
+
157
+ ### Synchronously switch months
158
+
159
+ In the scenario of range selection, turning on `syncSwitchMonth` means to switch the two panels simultaneously. The default is false.
160
+
161
+ > Note: Clicking the year button will also switch the two panels synchronously. Switching the year and month from the scroll wheel will not switch the panels synchronously. This ensures the user's ability to select months at non-fixed intervals.
162
+
163
+ ```svelte
164
+ <script lang="ts">
165
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
166
+ </script>
167
+
168
+ <DatePicker style="width: 400px" syncSwitchMonth type="dateTimeRange" />
169
+ ```
170
+
171
+ ### Panel Change Callback
172
+
173
+ `onPanelChange` is called when the month or year of the panel is changed.
174
+
175
+ ```svelte
176
+ <script lang="ts">
177
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
178
+ </script>
179
+
180
+ <DatePicker onPanelChange={(date, dateString) => console.log(date, dateString)} style="width: 400px" syncSwitchMonth type="dateTimeRange" />
181
+ ```
182
+
183
+ ### Select Week
184
+
185
+ `daterange` is used with `startDateOffset` and `endDateOffset` to select range with single click, such as weekly selection and biweekly selection.
186
+
187
+ ```svelte
188
+ <script lang="ts">
189
+ import * as dateFns from 'date-fns';
190
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
191
+
192
+ const handleChange = (date?: Date | Date[]) => {
193
+ console.log('date changed', date);
194
+ };
195
+
196
+ const startOfWeek = (date: Date) => dateFns.startOfWeek(date, { weekStartsOn: 1 });
197
+ const endOfWeek = (date: Date) => dateFns.endOfWeek(date, { weekStartsOn: 1 });
198
+ const endOfNextWeek = (date: Date) => dateFns.add(endOfWeek(date), { days: 7 });
199
+ const sixDaysLater = (date: Date) => dateFns.add(date, { days: 6 });
200
+ </script>
201
+
202
+ <div>
203
+ <h4>选择自然周</h4>
204
+ <DatePicker endDateOffset={endOfWeek} onChange={handleChange} startDateOffset={startOfWeek} style="width: 260px" type="dateRange" weekStartsOn={1} />
205
+ <br />
206
+ <br />
207
+ <h4>选择双周</h4>
208
+ <DatePicker endDateOffset={endOfNextWeek} onChange={handleChange} startDateOffset={startOfWeek} style="width: 260px" type="dateRange" weekStartsOn={1} />
209
+ <br />
210
+ <br />
211
+ <h4>选择当前日和后6日</h4>
212
+ <DatePicker endDateOffset={sixDaysLater} onChange={handleChange} style="width: 260px" type="dateRange" weekStartsOn={1} />
213
+ <br />
214
+ <br />
215
+ </div>
216
+ ```
217
+
218
+ ### Selection
219
+
220
+ Set `type` to `month`, can make year-to-month selection.
221
+
222
+ ```svelte
223
+ <script lang="ts">
224
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
225
+
226
+ const value = new Date(2024, 4, 6, 10, 30, 0);
227
+ </script>
228
+
229
+ <DatePicker style="width: 140px" type="month" {value} />
230
+ ```
231
+
232
+ ### Year and Month Range Selection
233
+
234
+ Set `type` to `monthRange` to select the year and month range, small size and quick panel are not supported yet.
235
+
236
+ ```svelte
237
+ <script lang="ts">
238
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
239
+ </script>
240
+
241
+ <DatePicker style="width: 200px" type="monthRange" />
242
+ ```
243
+
244
+ ### Year Selection
245
+
246
+ Set `type` to `year` to select a year. The panel has a single year column, the selected value is January 1 of that year, and the default format is `yyyy`. `disabledDate` decides whether a year can be picked from January 1 of that year.
247
+
248
+ ```svelte
249
+ <script lang="ts">
250
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
251
+
252
+ const value = new Date(2024, 4, 6, 10, 30, 0);
253
+ </script>
254
+
255
+ <DatePicker style="width: 140px" type="year" {value} />
256
+ ```
257
+
258
+ ### Confirm Date and Time Selection
259
+
260
+ For the selection of "datetime" (type = "dateTime") or "datetime range" (type = "dateTimeRange"), you can confirm it before writing the value into the input box. You can pass `NeedConfirm` = true to enable this behavior.
261
+
262
+ At the same time, the click callbacks of the "confirm" (`onConfirm`) and "cancel" (`onCancel`) buttons are supported.
263
+
264
+ The following example passes three callbacks: `onChange`, `onConfirm` and `onCancel`, and you can open the console to see the difference in print information.
265
+
266
+ > Note: When opening `needConfirm`, you need to click the cancel button to close the panel, and clicking the blank area will no longer close the panel
267
+
268
+ ```svelte
269
+ <script lang="ts">
270
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
271
+ </script>
272
+
273
+ <DatePicker needConfirm onCancel={(...args) => console.log('Canceled: ', ...args)} onChange={(...args) => console.log('Changed: ', ...args)} onConfirm={(...args) => console.log('Confirmed: ', ...args)} type="dateTime" />
274
+ ```
275
+
276
+ ### Date and Time Selection with Shortcuts
277
+
278
+ Pass parameter `Presets` to set shortcuts for date selection.
279
+
280
+ ```svelte
281
+ <script lang="ts">
282
+ import { DatePicker, type DatePickerPresetsType } from '@fibrae/semi-ui-svelte';
283
+
284
+ const presets: DatePickerPresetsType = [
285
+ {
286
+ text: 'Today',
287
+ start: () => new Date(),
288
+ end: () => new Date(),
289
+ },
290
+ () => ({
291
+ text: 'Tomorrow',
292
+ start: new Date(new Date().valueOf() + 1000 * 3600 * 24),
293
+ end: new Date(new Date().valueOf() + 1000 * 3600 * 24),
294
+ }),
295
+ ];
296
+ </script>
297
+
298
+ <DatePicker presetPosition="left" {presets} type="dateTime" />
299
+ ```
300
+
301
+ ### Render TopSlot/BottomSlot
302
+
303
+ With the `topSlot` and `bottomSlot` snippets, you can customize the rendering of the top and bottom extra areas. The `leftSlot` and `rightSlot` snippets render the left and right extra areas.
304
+
305
+ ```svelte
306
+ <script lang="ts">
307
+ import { IconBulb } from '@fibrae/semi-icons-svelte';
308
+ import { DatePicker, Space, Tabs, Typography, type DatePickerValueType, type PlainTab } from '@fibrae/semi-ui-svelte';
309
+
310
+ const uedDisabledDate = (currentDate?: Date) => !!currentDate && currentDate.getDate() > 10 && currentDate.getDate() < 15;
311
+ const testDisabledDate = (currentDate?: Date) => !!currentDate && currentDate.getDate() > 15 && currentDate.getDate() < 25;
312
+
313
+ const tabList: PlainTab[] = [
314
+ { itemKey: '1', tab: 'UED 排期' },
315
+ { itemKey: '2', tab: '测试排期' },
316
+ ];
317
+
318
+ let activeTab = $state('1');
319
+ let date = $state<DatePickerValueType | null>();
320
+ const disabledDate = $derived(activeTab === '1' ? uedDisabledDate : testDisabledDate);
321
+ </script>
322
+
323
+ {#snippet tabs(padding: string)}
324
+ <Tabs bind:activeKey={activeTab} onChange={() => (date = null)} size="small" style={`padding: ${padding}`} {tabList} />
325
+ {/snippet}
326
+
327
+ {#snippet notice(padding: string, text: string, linkText: string)}
328
+ <Space style={`padding: ${padding}`}>
329
+ <IconBulb style="color: var(--semi-amber-5)" />
330
+ <Typography.Text strong style="color: var(--semi-color-text-2)">{text}</Typography.Text>
331
+ <Typography.Text link={{ href: 'https://semi-design-next.pages.dev/', target: '_blank' }}>{linkText}</Typography.Text>
332
+ </Space>
333
+ {/snippet}
334
+
335
+ <div>
336
+ <DatePicker bind:value={date} classNames={{ dropdown: 'components-datepicker-demo-slot' }} {disabledDate} placeholder="请选择排期">
337
+ {#snippet topSlot()}{@render tabs('12px 20px 0')}{/snippet}
338
+ </DatePicker>
339
+ <br />
340
+ <br />
341
+ <DatePicker placeholder="请选择发版时间">
342
+ {#snippet bottomSlot()}{@render notice('12px 20px', '定版前请阅读', '发版须知')}{/snippet}
343
+ </DatePicker>
344
+ <br />
345
+ <br />
346
+ <DatePicker placeholder="请选择年月" type="month">
347
+ {#snippet bottomSlot()}{@render notice('12px 20px', '请阅读', '须知')}{/snippet}
348
+ </DatePicker>
349
+ <br />
350
+ <br />
351
+ <DatePicker classNames={{ dropdown: 'components-datepicker-demo-slot' }} density="compact" placeholder="小尺寸">
352
+ {#snippet topSlot()}{@render tabs('8px 12px 0')}{/snippet}
353
+ {#snippet bottomSlot()}{@render notice('8px 12px', '定版前请阅读', '发版须知')}{/snippet}
354
+ </DatePicker>
355
+ <br />
356
+ <br />
357
+ <DatePicker placeholder="请选择时间范围" style="width: 400px" type="dateTimeRange">
358
+ {#snippet bottomSlot()}{@render notice('12px 20px', '定版前请阅读', '发版须知')}{/snippet}
359
+ </DatePicker>
360
+ <br />
361
+ <br />
362
+ </div>
363
+ ```
364
+
365
+ ```css
366
+ .components-datepicker-demo-slot {
367
+ .semi-tabs-content {
368
+ padding: 0;
369
+ }
370
+
371
+ .semi-tabs-bar-line.semi-tabs-bar-top {
372
+ border-bottom: none;
373
+ }
374
+ }
375
+ ```
376
+
377
+ ### Disable Date Selection
378
+
379
+ ```svelte
380
+ <script lang="ts">
381
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
382
+
383
+ const value = new Date(2024, 4, 6, 10, 30, 0);
384
+ </script>
385
+
386
+ <DatePicker disabled type="dateTime" {value} />
387
+ ```
388
+
389
+ ### Disable Partial Date or Time
390
+
391
+ Pass in `disabledDate` to disable the specified date, pass in `disabledTime` to disable the specified time, and with `defaultPickerValue` you can specify the year and month when the panel is opened.
392
+
393
+ `disabledDate` and`disabledTime`, the accepted input parameters are the current date, the former returns a `boolean` value, the latter returns an [object](../input/time-picker.md#API_Reference) It will be directly passed to the `TimePicker` component.
394
+
395
+ > **Note**
396
+ >
397
+ > With timeZone set, the first parameter is a `TZDate`, the same as the date the change callbacks get: `getDay()`, `getHours()` and the like read the date and clock of that time zone.
398
+
399
+ ```svelte
400
+ <script lang="ts">
401
+ import * as dateFns from 'date-fns';
402
+ import { range } from 'es-toolkit';
403
+ import { DatePicker, type DatePickerDisabledDateType, type DatePickerDisabledTimeType } from '@fibrae/semi-ui-svelte';
404
+
405
+ const nextValidMonth = new Date();
406
+ nextValidMonth.setMonth((nextValidMonth.getMonth() + 1) % 12);
407
+
408
+ const disabledTime: DatePickerDisabledTimeType = (date) =>
409
+ // With type dateTime, date is a single Date
410
+ dateFns.isToday(date as Date)
411
+ ? {
412
+ disabledHours: () => [17, 18],
413
+ disabledMinutes: (hour) => (19 === hour ? range(0, 10, 1) : []),
414
+ disabledSeconds: (hour, minute) => (hour === 20 && minute === 20 ? range(0, 20, 1) : []),
415
+ }
416
+ : {};
417
+
418
+ const disabledTime2: DatePickerDisabledTimeType = (_date, panelType) => {
419
+ if (panelType === 'left') {
420
+ return { disabledHours: () => [17, 18] };
421
+ }
422
+ return { disabledHours: () => [12, 13, 14, 15, 16, 17, 18] };
423
+ };
424
+
425
+ const disabledDate: DatePickerDisabledDateType = (date) => {
426
+ const deadDate = new Date();
427
+ const month = deadDate.getMonth();
428
+ deadDate.setDate(28);
429
+ deadDate.setMonth((month + 1) % 12);
430
+ return !!date && date.getTime() < deadDate.getTime();
431
+ };
432
+ </script>
433
+
434
+ <div>
435
+ <div>
436
+ <h4>禁用时间:禁用今天下午5-6点</h4>
437
+ <DatePicker {disabledTime} hideDisabledOptions={false} type="dateTime" />
438
+ </div>
439
+ <div>
440
+ <h4>禁用时间:两个面板禁用不同时间</h4>
441
+ <DatePicker disabledTime={disabledTime2} hideDisabledOptions={false} style="width: 400px" type="dateTimeRange" />
442
+ </div>
443
+ <div>
444
+ <h4>禁用日期:禁用下个月28号之前的所有日期</h4>
445
+ <DatePicker defaultPickerValue={nextValidMonth} {disabledDate} style="width: 400px" type="dateTimeRange" />
446
+ </div>
447
+ </div>
448
+ ```
449
+
450
+ When `type` contains `range`, the date can be disabled dynamically according to the rangeStart.
451
+
452
+ ```svelte
453
+ <script lang="ts">
454
+ import * as dateFns from 'date-fns';
455
+ import { DatePicker, type DatePickerDisabledDateType } from '@fibrae/semi-ui-svelte';
456
+
457
+ const disabledDate: DatePickerDisabledDateType = (date, options) => {
458
+ if (!date || !options?.rangeStart) {
459
+ return false;
460
+ }
461
+ const startDate = dateFns.parseISO(options.rangeStart);
462
+ return dateFns.isBefore(date, startDate);
463
+ };
464
+ </script>
465
+
466
+ <div>
467
+ <h4>动态禁用日期:禁止选择之前的日期</h4>
468
+ <DatePicker {disabledDate} style="width: 260px" type="dateRange" />
469
+ </div>
470
+ ```
471
+
472
+ When `type` contains `range`, dates can be disabled based on the focus state. The focus state is passed through the `rangeInputFocus` parameter in `options`.
473
+
474
+ ```svelte
475
+ <script lang="ts">
476
+ import * as dateFns from 'date-fns';
477
+ import { DatePicker, type DatePickerDisabledDateType } from '@fibrae/semi-ui-svelte';
478
+
479
+ const today = new Date();
480
+
481
+ const disabledDate: DatePickerDisabledDateType = (date, options) => {
482
+ if (!date) {
483
+ return false;
484
+ }
485
+ const rangeInputFocus = options?.rangeInputFocus;
486
+ const baseDate = dateFns.set(today, { hours: 0, minutes: 0, seconds: 0, milliseconds: 0 });
487
+ if (rangeInputFocus === 'rangeStart') {
488
+ const disabledStart = dateFns.subDays(baseDate, 2);
489
+ const disabledEnd = dateFns.addDays(baseDate, 2);
490
+ return disabledStart <= date && date <= disabledEnd;
491
+ } else if (rangeInputFocus === 'rangeEnd') {
492
+ const disabledStart = dateFns.subDays(baseDate, 3);
493
+ const disabledEnd = dateFns.addDays(baseDate, 3);
494
+ return disabledStart <= date && date <= disabledEnd;
495
+ } else {
496
+ return false;
497
+ }
498
+ };
499
+ </script>
500
+
501
+ <div>
502
+ <h4>开始日期禁用今天前2日和后2日,结束日期禁用今天前3天和后3天</h4>
503
+ <DatePicker defaultPickerValue={today} {disabledDate} motion={false} type="dateRange" />
504
+ </div>
505
+ ```
506
+
507
+ ### Custom Display Format
508
+
509
+ Pass parameter `format` to custom display format.
510
+
511
+ ```svelte
512
+ <script lang="ts">
513
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
514
+
515
+ const value = new Date(2024, 4, 6, 10, 30, 0);
516
+ </script>
517
+
518
+ <DatePicker format="yyyy年MM月dd日 HH:mm" type="dateTime" {value} />
519
+ ```
520
+
521
+ ### Custom Trigger
522
+
523
+ By default we use the `Input` component as the trigger for the `DatePicker` component. You can customize this trigger with the `trigger` snippet.
524
+
525
+ The custom trigger is a complete customization of the trigger, the default clear button will not take effect, if you need clear function, please customize a clear button that calls `onClear` from the snippet parameter, or sets the bound `value` to `null`.
526
+
527
+ The snippet parameter provides `value`, `inputValue`, `placeholder`, `disabled`, `size`, `inputReadOnly`, `rangeInputFocus`, `type`, `format`, `multiple`, `autofocus` and `componentProps`, plus `onChange` (sets the input text, as typing does), `onEnterPress` (commits the input text) and `onClear` (reports a click on the clear button). `inputValue` is `null` until the user types; show the formatted `value` then. The snippet parameter carries no `aria-*` attributes, so name the custom content yourself.
528
+
529
+ ```svelte
530
+ <script lang="ts">
531
+ import * as dateFns from 'date-fns';
532
+ import { IconChevronDown, IconClose } from '@fibrae/semi-icons-svelte';
533
+ import { Button, ButtonGroup, DatePicker, type DatePickerValueType } from '@fibrae/semi-ui-svelte';
534
+
535
+ const formatToken = 'yyyy-MM-dd';
536
+ let date = $state<DatePickerValueType | null>(new Date(2024, 4, 6, 10, 30, 0));
537
+ </script>
538
+
539
+ <DatePicker bind:value={date} format={formatToken}>
540
+ {#snippet trigger(triggerProps)}
541
+ <!-- The clear button is a sibling of the trigger button: buttons cannot nest -->
542
+ <ButtonGroup theme="light">
543
+ <Button iconPosition="right">
544
+ {#snippet icon()}<IconChevronDown />{/snippet}
545
+ {triggerProps.value.length ? dateFns.format(triggerProps.value[0], formatToken) : triggerProps.placeholder}
546
+ </Button>
547
+ {#if date}
548
+ <Button
549
+ aria-label="清除"
550
+ onclick={(event) => {
551
+ event.stopPropagation();
552
+ date = null;
553
+ }}
554
+ >
555
+ {#snippet icon()}<IconClose />{/snippet}
556
+ </Button>
557
+ {/if}
558
+ </ButtonGroup>
559
+ {/snippet}
560
+ </DatePicker>
561
+ ```
562
+
563
+ > **Note**
564
+ >
565
+ > When DatePicker is range type, the default date selected after the panel is opened is the start date, and it will switch to the end date selection after selection. The focus is reset when the panel is closed.
566
+ > We recommend providing a clear button, when you pass null value to DatePicker, DatePicker will also reset focus internally. This allows the user to reselect the date range after clearing.
567
+
568
+ ```svelte
569
+ <script lang="ts">
570
+ import * as dateFns from 'date-fns';
571
+ import { IconChevronDown, IconClose } from '@fibrae/semi-icons-svelte';
572
+ import { Button, ButtonGroup, DatePicker, type DatePickerValueType } from '@fibrae/semi-ui-svelte';
573
+
574
+ const formatToken = 'yyyy-MM-dd HH:mm:ss';
575
+ let date = $state<DatePickerValueType | null>(null);
576
+
577
+ const onChange = (value?: Date | Date[]) => {
578
+ console.log(value);
579
+ };
580
+ </script>
581
+
582
+ <DatePicker bind:value={date} {onChange} type="dateTimeRange">
583
+ {#snippet trigger(triggerProps)}
584
+ <!-- The clear button is a sibling of the trigger button: buttons cannot nest -->
585
+ <ButtonGroup theme="light">
586
+ <Button iconPosition="right">
587
+ {#snippet icon()}<IconChevronDown />{/snippet}
588
+ {triggerProps.value.length ? `${dateFns.format(triggerProps.value[0], formatToken)} ~ ${dateFns.format(triggerProps.value[1], formatToken)}` : '请选择日期时间范围'}
589
+ </Button>
590
+ {#if triggerProps.value.length}
591
+ <Button
592
+ aria-label="清除"
593
+ onclick={(event) => {
594
+ event.stopPropagation();
595
+ date = null;
596
+ }}
597
+ >
598
+ {#snippet icon()}<IconClose />{/snippet}
599
+ </Button>
600
+ {/if}
601
+ </ButtonGroup>
602
+ {/snippet}
603
+ </DatePicker>
604
+ ```
605
+
606
+ ### Custom Render Date Content
607
+
608
+ The `date` snippet receives `{ dayNumber, fullDate }`.
609
+
610
+ - `dayNumber`: such as `13`.
611
+ - `fullDate`: such as `2020-08-13`.
612
+
613
+ ```svelte
614
+ <script lang="ts">
615
+ import { DatePicker, Tooltip } from '@fibrae/semi-ui-svelte';
616
+
617
+ const dateStyle = 'width: 100%; height: 100%; border: 1px solid var(--semi-color-primary); display: flex; justify-content: center; align-items: center';
618
+ </script>
619
+
620
+ <DatePicker>
621
+ {#snippet date(dateProps)}
622
+ {#if dateProps.dayNumber === 1}
623
+ <Tooltip>
624
+ {#snippet content()}Always Day 1{/snippet}
625
+ <div style={dateStyle}>{dateProps.dayNumber}</div>
626
+ </Tooltip>
627
+ {:else}
628
+ {dateProps.dayNumber}
629
+ {/if}
630
+ {/snippet}
631
+ </DatePicker>
632
+ ```
633
+
634
+ ### Custom Render Date Box
635
+
636
+ The `fullDate` snippet receives `{ dayNumber, fullDate, dayStatus }` and replaces the whole date box; the box keeps only its base and active class names.
637
+
638
+ `dayStatus` is this status of current date box. The included keys are as follows.
639
+
640
+ ```md
641
+ type DayStatusType = { isToday?: boolean, isSelected?: boolean, isDisabled?: boolean, isSelectedStart?: boolean, isSelectedEnd?: boolean, isInRange?: boolean, isHover?: boolean, isOffsetRangeStart?: boolean, isOffsetRangeEnd?: boolean, isHoverInOffsetRange?: boolean, }
642
+ ```
643
+
644
+ ```svelte
645
+ <script lang="ts">
646
+ import { DatePicker } from '@fibrae/semi-ui-svelte';
647
+
648
+ const prefix = 'components-datepicker-demo';
649
+ const dayStyle = 'display: flex; align-items: center; justify-content: center; width: 80%; height: 80%; border-radius: var(--semi-border-radius-circle)';
650
+ </script>
651
+
652
+ <DatePicker style="width: 260px" type="dateRange">
653
+ {#snippet fullDate(fullDateProps)}
654
+ <div
655
+ class={{
656
+ [`${prefix}-day-inrange`]: fullDateProps.dayStatus.isInRange,
657
+ [`${prefix}-day-hover`]: fullDateProps.dayStatus.isHover,
658
+ [`${prefix}-day-selected`]: fullDateProps.dayStatus.isSelected,
659
+ [`${prefix}-day-selected-start`]: fullDateProps.dayStatus.isSelectedStart,
660
+ [`${prefix}-day-selected-end`]: fullDateProps.dayStatus.isSelectedEnd,
661
+ }}
662
+ style={dayStyle}
663
+ >
664
+ {fullDateProps.dayNumber}
665
+ </div>
666
+ {/snippet}
667
+ </DatePicker>
668
+ ```
669
+
670
+ ```css
671
+ .components-datepicker-demo-day-inrange,
672
+ .components-datepicker-demo-day-hover {
673
+ background: var(--semi-color-primary-light-hover);
674
+ }
675
+
676
+ .components-datepicker-demo-day-selected,
677
+ .components-datepicker-demo-day-selected-start,
678
+ .components-datepicker-demo-day-selected-end {
679
+ color: var(--semi-color-bg-2);
680
+ background: var(--semi-color-primary);
681
+ }
682
+ ```
683
+
684
+ ## API Reference
685
+
686
+ **Props**
687
+
688
+ | Property | Description | Type | Default |
689
+ | - | - | - | - |
690
+ | autoAdjustOverflow | Whether the panel adjusts its direction when it is clipped. | `boolean` | `true` |
691
+ | autofocus | Focuses the input on mount, which opens the panel. | `boolean` | `false` |
692
+ | autoSwitchDate | Switches the selected date automatically when the year or month is changed with the arrow buttons or the dropdown. Only for the date type. | `boolean` | `true` |
693
+ | borderless | Removes the border of the input. | `boolean` | `false` |
694
+ | bottomSlot | Extra area at the bottom of the panel. | `Snippet` | - |
695
+ | classNames | Class names of the inner parts, keyed by dropdown (the panel) and input (the root element of the input, on both inputs of a range); values take anything class takes (string, array or object) and merge with the built-in classes. | `Partial<Record<DatePickerPart, ClassValue>>` | - |
696
+ | clearIcon | Custom clear icon, used when showClear is true. | `Snippet` | - |
697
+ | date | Content of a day cell, with dayNumber and fullDate (yyyy-MM-dd). | `Snippet<[DatePickerDateSnippetProps]>` | - |
698
+ | defaultPickerValue | The date the panel shows while there is no value; for dateTime types it is also the default time at the bottom. Compared by content: when the content changes the panel moves back to it, so passing `new Date()` on every render counts as a change. | `DatePickerValueType` | - |
699
+ | density | Size of the panel: default or compact. | `DatePickerDensity` | `"default"` |
700
+ | disabled | Whether the picker is disabled. | `boolean` | - |
701
+ | disabledDate | Returns true to disable a date. The second argument carries rangeStart, rangeEnd and rangeInputFocus. When type is year, it is called with January 1 of each year, and returning true disables that year. | `DatePickerDisabledDateType` | - |
702
+ | disabledTime | Returns disabledHours, disabledMinutes and disabledSeconds for the current date and panel position. | `DatePickerDisabledTimeType` | - |
703
+ | disabledTimePicker | Whether the time selection is disabled; for dateTime and dateTimeRange only. | `boolean` | `false` |
704
+ | endDateOffset | For dateRange, the end date of a range chosen with one click. | `DatePickerDateOffsetType` | - |
705
+ | endYear | Last year of the year wheel, which must be after the start year. Defaults to 100 years after this year. | `number` | - |
706
+ | format | Format of the text in the input; the default depends on type. A format without time tokens turns dateTime into date and dateTimeRange into dateRange. | `string` | - |
707
+ | fullDate | Replaces the whole day cell, with dayNumber, fullDate and dayStatus. The cell keeps only its base and active classes. | `Snippet<[DatePickerFullDateSnippetProps]>` | - |
708
+ | hideDisabledOptions | Hides the times that are disabled. | `boolean` | `false` |
709
+ | inputReadOnly | Whether the input is read-only. | `boolean` | `false` |
710
+ | insetInput | Moves the inputs into the panel; pass an object to set the placeholders of the inputs. | `boolean \| DatePickerInsetInputProps` | `false` |
711
+ | insetLabel | Inset label of the input. | `Snippet` | - |
712
+ | insetLabelId | The id of the inset label element. | `string` | - |
713
+ | leftSlot | Extra area at the left of the panel. | `Snippet` | - |
714
+ | max | The number of dates multiple allows; unlimited when omitted. | `number` | - |
715
+ | motion | Whether the panel animates when it opens. | `boolean` | `true` |
716
+ | multiple | Whether several dates can be chosen; only for type date. | `M` | `false` |
717
+ | needConfirm | Whether the value is written only after a confirmation; for dateTime and dateTimeRange only. | `boolean` | `false` |
718
+ | onBlur | Called when the panel closes. The argument is the mousedown that closed it from outside; other ways to close, such as confirming, choosing a date or Esc, pass none. | `(event?: MouseEvent) => void` | - |
719
+ | onCancel | Called when the selection is cancelled, with the last confirmed value. Only with needConfirm. | `(date: Date \| Date[], dateString: string \| string[]) => void` | - |
720
+ | onChange | Called when the value changes, with the date and the date string; both are arrays for range and multiple. When cleared, a single value is undefined and range and multiple are \[]. A range type calls it only after both dates are chosen. | `T extends 'dateRange' \| 'dateTimeRange' \| 'monthRange' ? (date: Date[], dateString: string[]) => void : T extends 'date' ? M extends true ? (date: Date[], dateString: string[]) => void : (date: Date \| undefined, dateString: string \| undefined) => void : (date: Date \| undefined, dateString: string \| undefined) => void` | - |
721
+ | onClear | Called when the clear button is clicked. | `(event: MouseEvent) => void` | - |
722
+ | onClickOutSide | Called when the panel is open and the user presses outside the panel and the trigger, with the native mousedown event. | `(event: MouseEvent) => void` | - |
723
+ | onConfirm | Called when the selection is confirmed, with the selected value. Only with needConfirm. | `(date: Date \| Date[], dateString: string \| string[]) => void` | - |
724
+ | onFocus | Called when an input gets focus, or when a click or key press on the trigger focuses the range start. rangeType is set for range inputs only, and moving between them does not call it again. | `(event: FocusEvent \| MouseEvent \| KeyboardEvent, rangeType?: DatePickerRangeInput) => void` | - |
725
+ | onOpenChange | Called when the panel opens or closes. | `(open: boolean) => void` | - |
726
+ | onPanelChange | Called when the year or month of the panel changes. | `(date: Date \| Date[], dateString: string \| string[]) => void` | - |
727
+ | onPresetClick | Called when a preset button is clicked; the second argument is the native MouseEvent. | `(item: DatePickerPresetType, event: MouseEvent) => void` | - |
728
+ | open | Whether the panel is open, two-way bindable with bind:open. A plain value is the initial state. While bound, open() and close() do not change the visibility; the bound value wins. | `boolean` | - |
729
+ | placeholder | Placeholder of the input; an array for range types. Defaults to the text of the locale for type. | `string \| string[]` | - |
730
+ | position | Position of the panel. Defaults to bottomLeft (bottomRight in RTL), and to leftTopOver with insetInput. | `Position` | - |
731
+ | prefix | Prefix of the input. | `Snippet` | - |
732
+ | presetPosition | Position of the presets: left, right, top or bottom. | `DatePickerPresetPosition` | `"bottom"` |
733
+ | presets | Shortcuts for dates and times. An item, and its start or end, can be a function that is called when the panel renders and when it is clicked. | `DatePickerPresetsType` | - |
734
+ | preventScroll | Whether focusing the input prevents the browser from scrolling to it. | `boolean` | - |
735
+ | rangeSeparator | Separator between the dates of a range input, also used to parse the text. Use the rangeSeparatorNode snippet to change only how it is shown. | `string` | `" ~ "` |
736
+ | rangeSeparatorNode | How the separator between the range inputs is shown. It does not affect parsing. | `Snippet` | - |
737
+ | rightSlot | Extra area at the right of the panel. | `Snippet` | - |
738
+ | showClear | Whether the clear button is shown. | `boolean` | `true` |
739
+ | size | Size of the input: small, default or large. | `InputSize` | - |
740
+ | spacing | Distance between the panel and the trigger. 1 for an insetInput panel over the trigger, otherwise the Popover spacing. | `number` | - |
741
+ | startDateOffset | For dateRange, the start date of a range chosen with one click. | `DatePickerDateOffsetType` | - |
742
+ | startYear | First year of the year wheel. Defaults to 100 years before this year. | `number` | - |
743
+ | stopPropagation | Whether click events on the panel stop propagating. | `boolean \| string` | `true` |
744
+ | styles | Style strings of the inner parts, keyed like classNames. | `Partial<Record<DatePickerPart, string>>` | - |
745
+ | syncSwitchMonth | Switches both panels of a range together. | `boolean` | `false` |
746
+ | timePickerOpts | Options for the time panel: use12Hours, hourStep, minuteStep, secondStep, defaultIsAM and scrollItemProps. The panel owns the format, the value and the disabled times. | `DatePickerTimePickerOpts` | - |
747
+ | timeZone | Time zone: a number is the hour offset from UTC, a string an IANA time zone name or `GMT±HH:MM`. When set, a `Date` or timestamp is read as an instant and a string as a wall time of the zone; callbacks get `TZDate`s, and `dateString` and the today mark follow the zone too. Falls back to the timeZone of ConfigProvider, then to the global default. | `string \| number` | - |
748
+ | topSlot | Extra area at the top of the panel. | `Snippet` | - |
749
+ | trigger | Replaces the trigger. It receives value, inputValue, placeholder, disabled, size, inputReadOnly, rangeInputFocus, type, format, multiple, autofocus and componentProps, plus onChange (sets the input text), onEnterPress (commits it) and onClear. The default clear button no longer applies. | `Snippet<[DatePickerTriggerRenderProps]>` | - |
750
+ | type | Type: date, dateRange, dateTime, dateTimeRange, month, monthRange or year. | `T` | `"date"` |
751
+ | validateStatus | Validation status: default, error or warning. Only affects the style. | `ValidateStatus` | - |
752
+ | value | The value, two-way bindable with bind:value: a Date, a timestamp or a string in format, and an array for range and multiple. A plain value is the initial value; null is a controlled empty value, undefined leaves the picker uncontrolled. | `DatePickerValueType \| null` | - |
753
+ | weekStartsOn | The first day of the week: 0 is Sunday, 1 is Monday, and so on. | `WeekStartNumber` | `0` |
754
+ | yearAndMonthOpts | Options for the year and month columns: cycled, mode, motion and transform. The panel owns the list and the selection. | `DatePickerYearAndMonthOpts` | - |
755
+
756
+ **Methods**
757
+
758
+ | Method | Description | Type |
759
+ | - | - | - |
760
+ | blur | Blurs the input. | `() => void` |
761
+ | close | Closes the panel. A bound open wins. | `() => void` |
762
+ | focus | Focuses the input. A range focuses its start input unless rangeEnd is given. With insetInput the focus goes to the input in the panel. | `(focusType?: RangeInput) => void` |
763
+ | open | Opens the panel. A bound open wins. | `() => void` |
764
+
765
+ `value` and `open` can be bound with `bind:`, or given a plain value as the initial state; there is no `defaultValue` or `defaultOpen`. `autofocus` is lowercase; `triggerRender`, `renderDate`, `renderFullDate` and the other ReactNode props are snippets of the same name (`trigger`, `date`, `fullDate`), and the separator is shown by the `rangeSeparatorNode` snippet. Callbacks are written `onChange` and so on, not native events. `style` and the values of `styles` are strings.
766
+
767
+ Undeclared attributes such as `class`, `style`, `id`, `title`, `data-*` and `aria-label` land on the root element, which is `role="group"` when it has an `aria-label`. Where `aria-labelledby`, `aria-describedby`, `aria-errormessage`, `aria-invalid` and `aria-required` land:
768
+
769
+ - A single input: all of them land on the input
770
+ - A range type: the root element is `role="group"` and takes `aria-labelledby`; the other four land on both inputs
771
+ - `trigger` content without a focusable element: `aria-labelledby`, `aria-describedby`, `aria-errormessage` and `aria-invalid` land on the wrapper with the role `button`; `aria-required` is not forwarded
772
+ - `trigger` content with its own focusable element: none of them is forwarded, so set them on the snippet content
773
+
774
+ ## Methods
775
+
776
+ DatePicker exposes `open()`, `close()`, `focus(rangeEnd?)` and `blur()` through `export function`; get the instance with `bind:this` and call them. `focus` focuses the input; a range focuses its start input unless `rangeEnd` is given, and with insetInput the focus goes to the input in the panel. `blur` blurs the input. A bound `open` wins: `open()` and `close()` do not change the visibility of the panel then.
777
+
778
+ ```svelte
779
+ <script lang="ts">
780
+ import { Button, DatePicker, Space } from '@fibrae/semi-ui-svelte';
781
+
782
+ let picker = $state<ReturnType<typeof DatePicker>>();
783
+
784
+ const handleClickOutside = () => {
785
+ console.log('click outside');
786
+ };
787
+ </script>
788
+
789
+ <Space align="start" vertical>
790
+ <Space>
791
+ <Button onclick={() => picker?.open()}>open</Button>
792
+ <Button onclick={() => picker?.close()}>close</Button>
793
+ <Button onclick={() => picker?.focus()}>focus</Button>
794
+ <Button onclick={() => picker?.blur()}>blur</Button>
795
+ </Space>
796
+ <div>
797
+ <DatePicker bind:this={picker} onClickOutSide={handleClickOutside} type="dateTime" />
798
+ </div>
799
+ </Space>
800
+ ```
801
+
802
+ ## Interface Define
803
+
804
+ ```typescript
805
+ type DatePickerBaseValueType = string | number | Date;
806
+ type DatePickerValueType = DatePickerBaseValueType | DatePickerBaseValueType[];
807
+ type DatePickerType = 'date' | 'dateRange' | 'dateTime' | 'dateTimeRange' | 'month' | 'monthRange' | 'year';
808
+ type DatePickerRangeInput = 'rangeStart' | 'rangeEnd';
809
+ interface DatePickerTriggerRenderProps {
810
+ value: Date[];
811
+ inputValue: string | null;
812
+ placeholder: string | string[];
813
+ disabled: boolean;
814
+ size: InputSize;
815
+ inputReadOnly: boolean;
816
+ rangeInputFocus?: DatePickerRangeInput | false;
817
+ type: DatePickerType;
818
+ format?: string;
819
+ multiple: boolean;
820
+ autofocus: boolean;
821
+ // The declared props, without snippets, callbacks and undeclared attributes
822
+ componentProps: Partial<DatePickerProps>;
823
+ onChange: (inputValue: string) => void;
824
+ onEnterPress: (inputValue: string) => void;
825
+ onClear: (event: MouseEvent) => void;
826
+ }
827
+ ```
828
+
829
+ ## Accessibility
830
+
831
+ ### ARIA
832
+
833
+ - The input has the role `combobox` with `aria-haspopup="dialog"`, an `aria-expanded` that follows the panel, and `aria-controls` pointing at the panel; both inputs of a range do
834
+ - A single input is named `Choose date` while no date is selected and `Change date` once one is (an `aria-labelledby` you pass wins)
835
+ - When the content of a custom trigger (`triggerRender` in React, the `#trigger` slot in Vue) has no focusable element, the wrapper is the focus target with the role `button`, named as above
836
+ - The role of the month in the date panel is `grid`, named by the year and month title at the top of the panel; the role of the week is set to `row`, and the date cell is set to `gridcell`
837
+ - The year and month scroll columns are `listbox` lists named "year" and "month"
838
+ - `aria-disabled` is true for the corresponding option when date and time are disabled
839
+ - With multiple or range selection, `aria-multiselectable` of month is true, and `aria-selected` of date grid is true when selected
840
+ - Some decorative icons in the panel, their `aria-hidden` is true
841
+
842
+ ### Keyboard and Focus
843
+
844
+ - `Down Arrow` in the input opens the panel; once the panel is open, `Down Arrow` moves focus into it
845
+ - The date grid is one Tab stop: the `arrow keys`, `Home`, `End`, `PageUp` and `PageDown` (by year with `Shift`) move the active date, and `Enter` or `Space` picks it
846
+ - The date and time switches at the bottom of a dateTime panel are buttons that `Enter` or `Space` activates
847
+ - With a range value, Tab reaches the clear button after the end input, and `Enter` or `Space` clears the range
848
+ - `Esc` closes the panel; focus inside the panel returns to the input, or to the custom trigger when there is one
849
+ - When the content of a custom trigger has no focusable element, Tab reaches the wrapper, and `Enter`, `Space` or `Down Arrow` opens the panel
850
+
851
+ ## Date and Time Format
852
+
853
+ Adopted in the semi-ui component library [date-fns v4](https://date-fns.org/docs/Getting-Started) As a date and time engine, formatting token means the following:
854
+
855
+ - `"y"`: Year
856
+ - `"M"`: month
857
+ - `"d"`: day
858
+ - `"H"`: hours
859
+ - `"h"`: hours (12h)
860
+ - `"m"`: minutes
861
+ - `"s"`: seconds
862
+
863
+ The following uses `new Date('2023-12-09 08:08:00')` or `[new Date('2023-12-09 08:08:00'), new Date('2023-12-10 10 :08:00')]` as `value` to explain the impact of different types and different `format` values on the displayed value:
864
+
865
+ | type | format | display value |
866
+ | - | - | - |
867
+ | date | yyyy-MM-dd | 2023-12-09 |
868
+ | dateTime | yyyy-MM-dd HH:mm:ss | 2023-12-09 08:08:00 |
869
+ | month | yyyy-MM | 2023-12 |
870
+ | year | yyyy | 2023 |
871
+ | dateRange | yyyy-MM-dd | 2023-12-09 \~ 2023-12-10 |
872
+ | dateTimeRange | yyyy-MM-dd HH:mm:ss | 2023-12-09 08:08 \~ 2023-12-10 10:08 |
873
+
874
+ Multiple dates or times are used by default `","` (English comma) separated.
875
+
876
+ > More token available [Date-fns official website](https://date-fns.org/docs/Unicode-Tokens)
877
+
878
+ Text tokens such as month and weekday names, and parsing input by `format`, use a date-fns locale: the built-in zh-CN or en-US picked by the current locale's `code`, and enUS for other languages. For another language, import it from `date-fns/locale` and pass it to the `dateFnsLocale` of ConfigProvider; see [Internationalization](../other/locale.md).
879
+
880
+ ## Content Guidelines
881
+
882
+ - Date picker is recommended to be used with tags
883
+ - Use concise labels to indicate what the date selection refers to
884
+ - Please refer to [Date and Time](../experience/content-guidelines.md#8.%20%E6%97%A5%E6%9C%9F%E4%B8%8E%E6%97%B6%E9%97%B4)
885
+
886
+ ## Design Tokens
887
+
888
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/input/date-picker/>
889
+
890
+ ## FAQ
891
+
892
+ - **Date time picker, when you choose time, minute and second, you don't want to scroll infinitely. How to achieve the effect?**\
893
+ The default mode of ScrollItem in TimePicker is normal. If you want the infinite scrolling effect, you can control this behavior through a specific switch in timePickerOpts, that is:
894
+
895
+ `timePickerOpts={{ scrollItemProps: { mode: 'wheel', cycled: true } }}`.
896
+
897
+ - **How to set the default display time when the panel is opened?**\
898
+ You can use the defaultPickerValue property.
899
+
900
+ - **Date time selection, range date selection, after inputting some dates, the panel does not echo the date?**
901
+
902
+ The input box needs to be entered completely before it is showed to the panel. For example, for `dateTime` type, the full requested date and time have been entered. For `dateRange` type, full requires start and end dates to be entered.
903
+
904
+ - **What is the displayed time at the bottom of the date time selection panel?**
905
+
906
+ When no time is selected, it is the value of the time in `defaultPickerValue`, if not set it is the time when the panel was opened. After selecting a time, it is the selected time.
907
+
908
+ Since it has two hidden meanings in design, which may lead to ambiguity, it is recommended to use inline styles and open them through `insetInput`. It is recommended to read the relevant [Documentation](#input-in-panel) before use.
909
+
910
+ ## Changes from Semi Design
911
+
912
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
913
+
914
+ - 破坏性:删除 `dropdownClassName`、`dropdownStyle`、`inputStyle`,改用 `classNames`、`styles` 的 `dropdown`(面板)、`input`(输入框外层,范围模式下两个输入框都有)键。
915
+ - 破坏性:删除 `getPopupContainer`、`zIndex`、`dropdownMargin`,面板在 top layer。ref 改为 `DatePickerHandle { open, close, focus, blur }`,删除 `BaseDatePicker` 导出;受控 `open` 时 `open()`、`close()` 不改变可见性。
916
+ - 破坏性:删除 `onChangeWithDateFirst`,`onChange` 固定为 `(date, dateString)`;React 删除 `locale`、`localeCode`、`dateFnsLocale` 属性,改经 `LocaleProvider`、`ConfigProvider` 设置。
917
+ - 日历按 APG 支持键盘:每个月份网格一个 Tab 停靠点,方向键、PageUp、PageDown 移动日期,Enter、Space 选中,Esc 关闭面板。输入框为 `role="combobox"`,按 `textbox` 查询的测试需改为 combobox。
918
+ - 破坏性(类型):`onClear` 为 `MouseEventHandler<HTMLButtonElement>`,`onClickOutSide` 参数为原生 `MouseEvent`,`onBlur` 改为面板关闭时触发的 `(e?: MouseEvent) => void`;`yearAndMonthOpts`、`timePickerOpts` 收窄;深路径 foundation 的 `RangeType` 改名 `RangeInput`,不再导出 `OnChangeType`。
919
+ - 破坏性(类型):`onChange` 按 `type` 与 `multiple` 判别,单值类型(含 `multiple` 不生效的 `dateTime`、`month`、`year`)为 `(Date, string)`,范围类型与 `type="date"` 的 `multiple` 为 `(Date[], string[])`。React、Solid 的 `DatePickerProps` 改为类型别名(`interface X extends DatePickerProps` 改交叉类型),省略 `type` 时内联 `onChange` 的参数推断不出(这两个包不开启 strictNullChecks);Vue 的 DatePicker 与 `FormDatePicker` 是泛型组件,模板中 `@change` 按 `type`、`multiple` 收窄,单值为 `Date | undefined`、`string | undefined`;Svelte 的 `DatePickerProps<T, M>` 带泛型,单值同为可含 `undefined`。传入类型为宽联合的 `type` 变量时需先收窄。
920
+ - `multiple` 只对 `type="date"` 生效;支持 `type="year"`,选中值为该年 1 月 1 日。`onOpenChange` 只在由关到开时上报一次,`needConfirm` 时 Esc 关闭会调用 `onCancel`,键入无法解析的日期按 Enter 不再以今天提交。
921
+ - `month`、`monthRange` 的预设与回落值取当月 1 日 00:00,`disabledDate` 以每月 1 日 00:00 调用,`rangeStart`、`rangeEnd` 无值时为 `''`。`timeZone` 取值顺序为 prop、ConfigProvider、全局默认值。
922
+ - 范围类型(`dateRange`、`dateTimeRange`、`monthRange`)只提交两端都是有效日期的值:只选或只输入一端时不写入 `value`,不触发 `onChange`、`onConfirm`,确认按钮禁用,输入框保留已输入的文字;清空仍触发 `onChange([], [])`。
923
+ - `open` 或 `defaultOpen` 为 true 且 `disabled` 时,初始不显示面板。
924
+ - 行为变化:焦点离开输入框与面板(如在输入框上按 Tab)时关闭面板,与点击外部相同,`needConfirm` 时不关闭;范围类型在起止输入框之间按 Tab 不关闭。面板打开后用键盘进入面板改为在输入框上按 ArrowDown。
925
+ - `defaultPickerValue` 是无法按 `format` 解析的字符串时按未传处理,面板显示当前月份(原来得到无效日期)。
926
+ - 首次渲染即由 `value`、`defaultValue` 算出选中值,服务端 HTML 的输入框带格式化后的日期(原来挂载后才填入)。
927
+ - 面板的「今天」标记在服务端渲染与 hydration 期间不出现,hydration 后再标出,并在跨日时更新(原来在面板挂载时固定)。
928
+ - Svelte:`value`、`open` 可绑定,没有 `defaultValue`、`defaultOpen`,`defaultPickerValue` 保留(不是受控值的初值);`needConfirm` 时点日期只触发 `onChange` 并更新待选值,可绑定的 `value` 在点确认时才写回,取消在各写法下都恢复原值。
929
+ - Svelte:插槽改为同名 snippet:`trigger`、`date`、`fullDate`、`topSlot`、`bottomSlot`、`leftSlot`、`rightSlot`、`prefix`、`insetLabel`、`clearIcon`,分隔符节点的 snippet 叫 `rangeSeparatorNode`(`rangeSeparator` 已是字符串 prop),`trigger` 参数的 `componentProps` 不含原生属性、`on*` 回调与 snippet。
930
+ - Svelte:`styles` 的值只接受字符串;`inputReadOnly` 只禁止键入、保留清除按钮;`open()`、`close()`、`focus(focusType?)`、`blur()` 经 `bind:this` 调用。
931
+ - Svelte:`needConfirm` 下点清除按钮立即写回空值(`undefined`,范围类型为 `[]`),不等确认;`autoSwitchDate` 选年份只通知一次 `onChange`;范围类型的清除按钮因值清空而消失时(键盘清除、指针清除、父级清空),焦点交给起始输入框,焦点原本不在清除按钮上时不移交;单值类型清除后焦点落在输入框;实例 `open()`、`close()` 在用户交互后仍有效;新增类型导出 `DatePickerHandle`(`open`、`close`、`focus(focusType?)`、`blur`)。
932
+ - 受控 `value` 加 `autoSwitchDate` 时,选年只触发一次 `onChange`。范围选择中一侧显示时间或年月列表时,另一侧月份周数变化后列表选中项保持居中。React:input 上不再有 `format` 属性。
933
+ - 设置 `timeZone` 后,输入按目标时区解析:系统时区夏令时跳过、目标时区有效的时刻可以输入并正确显示;目标时区自身跳过的时刻一律不接受。
934
+ - 破坏性:设置 `timeZone` 后,`Date` 与时间戳是时刻,字符串是目标时区的钟点。`value`、`defaultValue`、`presets`、`defaultPickerValue` 中的字符串按 `format` 解析为目标时区的钟点(原来按系统时区解析再换算),`defaultPickerValue` 的 `Date` 也按时刻换算。受控时切换 `timeZone` 按新时区重读 `value`,字符串值的钟点不变。
935
+ - 破坏性:设置 `timeZone` 后,交给使用方的日期都是 `TZDate`(`Date` 子类):`onChange`、`onConfirm`、`onCancel`、`onPanelChange` 的 `date`,`disabledDate`、`disabledTime` 的参数,`triggerRender` 的 `value`。`getTime()` 是时刻,getter 与 date-fns 按目标时区读,`toISOString()` 与 `JSON.stringify` 输出带偏移(如 `+09:00`)而不是 `Z`(原来 `disabledDate` 的 `getDay()` 读到系统时区的日期,`triggerRender` 拿到内部表示)。`dateString` 按目标时区格式化,与输入框文字一致,可原样传回 `value`(原来按系统时区格式化)。
936
+ - 设置 `timeZone` 后,今天的标记、默认面板月份、空输入回落的今天、嵌入输入框自动补的时间都按目标时区取当前时间。
937
+ - `utcToZonedTime`(TimePicker 同用)遇到系统时区跳过的时刻不再后移一小时,返回 `TZDate`(`Date` 子类),其 `toISOString()` 带偏移而不带 `Z`。`TZDate` 在首次加载时从 `Date.prototype` 复制 getter,测试中 mock `Date` 且用 `timeZone` 时,要在 mock 之前加载组件。
938
+ - 受控 DatePicker 在值已为空时点清除不再触发 `onChange([])`,值非空时照旧触发,输入框在使用方改值前继续显示原值。
939
+ - 范围选择:焦点移到另一端发生在 `onChange` 之后(原来在之前),`onChange` 里读到的焦点仍是选中日期所属的输入框。
940
+ - `insetInput` 的时间输入框聚焦时,两侧面板逐个切到时间视图,第二个滚动列表出现时量一次高度并重新居中。
941
+ - 受控 `open` 改为 false 时,面板内的键盘焦点(嵌入输入框、日期格、时间列表)交还触发器,与 Esc、选中关闭一致(原来落到 body)。`insetInput` 的范围类型在出场动画期间关闭时,焦点不再被拉回即将卸载的嵌入输入框。
942
+ - 日期格的键盘处理放行带 Alt、Ctrl、Meta 的按键(如 Alt+ArrowLeft 后退),不再 `preventDefault`、不移动活动日;Shift+PageUp、Shift+PageDown 照旧切换年份。