@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,358 @@
1
+ # TimePicker
2
+
3
+ > Users can easily select a compliant, formatted point of time using the time selector.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/input/time-picker/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ Click TimePicker, and then you can select or enter a time in the floating layer.
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
24
+ </script>
25
+
26
+ <TimePicker />
27
+ ```
28
+
29
+ ### Infinite Scroll
30
+
31
+ The default mode of ScrollItem in TimePicker is `normal`. If you want the effect of infinite scrolling, please refer to the following example.
32
+
33
+ ```svelte
34
+ <script lang="ts">
35
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
36
+ </script>
37
+
38
+ <TimePicker scrollItemProps={{ mode: 'wheel', cycled: true }} />
39
+ ```
40
+
41
+ ### Controlled Component
42
+
43
+ Use `bind:value` as a controlled component. There is no `defaultValue`; put the initial value on the bound variable. `null` is a controlled empty value, and `undefined` means uncontrolled. Cleared, the value is `undefined` (single) or an empty array (range).
44
+
45
+ ```svelte
46
+ <script lang="ts">
47
+ import { TimePicker, type TimePickerBaseValueType } from '@fibrae/semi-ui-svelte';
48
+
49
+ let value = $state<TimePickerBaseValueType | TimePickerBaseValueType[] | null>(null);
50
+ const onChange = (time: unknown) => console.log(time);
51
+ </script>
52
+
53
+ <TimePicker bind:value {onChange} />
54
+ ```
55
+
56
+ ### Different Format
57
+
58
+ The columns in the TimePicker float will follow `format` Change, when omitted `format` At some point, the corresponding column in the floating layer will also disappear.
59
+
60
+ NOTE: `format` Follow the date-fns v4 `format` Format. <https://date-fns.org/docs/format>
61
+
62
+ Text tokens such as AM and PM 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. When needed, import another language from `date-fns/locale` and pass it to the `dateFnsLocale` of ConfigProvider; see [Internationalization](../other/locale.md).
63
+
64
+ ```svelte
65
+ <script lang="ts">
66
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
67
+ </script>
68
+
69
+ <TimePicker format="HH:mm" value="10:24" />
70
+ ```
71
+
72
+ ### Set Panel Header and Footer
73
+
74
+ ```svelte
75
+ <script lang="ts">
76
+ import { Button, TimePicker } from '@fibrae/semi-ui-svelte';
77
+
78
+ let open = $state(false);
79
+ const closePanel = () => {
80
+ open = false;
81
+ };
82
+ const onOpenChange = (value: boolean) => {
83
+ console.log(value);
84
+ };
85
+ </script>
86
+
87
+ <div>
88
+ <TimePicker bind:open {onOpenChange}>
89
+ {#snippet panelHeader()}Time Select{/snippet}
90
+ {#snippet panelFooter()}
91
+ <Button onclick={closePanel}>close</Button>
92
+ {/snippet}
93
+ </TimePicker>
94
+ <br />
95
+ <br />
96
+ <TimePicker type="timeRange">
97
+ {#snippet panelHeader({ index })}{index === 0 ? 'start header' : 'end header'}{/snippet}
98
+ {#snippet panelFooter({ index })}
99
+ {#if index === 0}
100
+ <Button onclick={() => console.log('start footer')}>start footer</Button>
101
+ {:else}
102
+ <Button onclick={() => console.log('end footer')}>end footer</Button>
103
+ {/if}
104
+ {/snippet}
105
+ </TimePicker>
106
+ </div>
107
+ ```
108
+
109
+ ### Disable Time Selection
110
+
111
+ ```svelte
112
+ <script lang="ts">
113
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
114
+ </script>
115
+
116
+ <TimePicker disabled value="12:08:23" />
117
+ ```
118
+
119
+ ### Set Step Length
120
+
121
+ Available `Hour Step`, `Minute Step`, `Second Step` Show the optional minutes and seconds by step.
122
+
123
+ ```svelte
124
+ <script lang="ts">
125
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
126
+ </script>
127
+
128
+ <TimePicker minuteStep={15} secondStep={10} />
129
+ ```
130
+
131
+ ### 12-hour System
132
+
133
+ 12-hour time selector, default `format` for `a h:mm:ss`, an incoming `format` The format must be in [dateFns date format](https://date-fns.org/docs/format)Within range.
134
+
135
+ > For example, the default 12-hour format string is:`a h:mm:ss`, if passed in `A h:mm:ss` This will result in an inability to format correctly.
136
+
137
+ ```svelte
138
+ <script lang="ts">
139
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
140
+ </script>
141
+
142
+ <div>
143
+ <TimePicker use12Hours />
144
+ <br />
145
+ <br />
146
+ <TimePicker format="a h:mm" use12Hours />
147
+ </div>
148
+ ```
149
+
150
+ ### Time Range
151
+
152
+ Pass type = "timeRange" to enable time range selection.
153
+
154
+ ```svelte
155
+ <script lang="ts">
156
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
157
+ </script>
158
+
159
+ <div>
160
+ <TimePicker type="timeRange" value={['10:23:15', '12:38:32']} />
161
+ <br />
162
+ <br />
163
+ <TimePicker format="a h:mm" type="timeRange" use12Hours value={['上午 08:11', '下午 11:21']} />
164
+ </div>
165
+ ```
166
+
167
+ ### Disable left/right panels in Range mode (disabledTime)
168
+
169
+ When `type="timeRange"`, you can use `disabledTime(value, panelType)` to apply different disabled rules for the left/right panel.
170
+
171
+ - `value`: the currently selected times, the unpicked side `undefined` (e.g. `[date, undefined]`); an empty array when there is no value, and length 1 when `value`, `defaultValue` or the input holds a single time
172
+ - `panelType`: `'left' | 'right'`, representing start/end panel
173
+
174
+ In the following demo, after selecting a start time, the right (end) panel will disable options earlier than the start time.
175
+
176
+ ```svelte
177
+ <script lang="ts">
178
+ import { TimePicker } from '@fibrae/semi-ui-svelte';
179
+ </script>
180
+
181
+ <TimePicker
182
+ disabledTime={(value, panelType) => {
183
+ const start = value[0];
184
+ if (panelType === 'right' && start) {
185
+ const h = start.getHours();
186
+ const m = start.getMinutes();
187
+ return {
188
+ disabledHours: () => Array.from({ length: h }, (_, i) => i),
189
+ disabledMinutes: (hour) => (hour === h ? Array.from({ length: m }, (_, i) => i) : []),
190
+ };
191
+ }
192
+ return {};
193
+ }}
194
+ type="timeRange"
195
+ />
196
+ ```
197
+
198
+ ### Custom Trigger
199
+
200
+ By default we use the `Input` component as the trigger for the `TimePicker` component. You can customize this trigger with the `trigger` snippet. It receives `{ value, inputValue, placeholder, disabled, componentProps, onChange }`: the unpicked side of `value` is `undefined`, and `onChange` updates the input text, as typing would.
201
+
202
+ ```svelte
203
+ <script lang="ts">
204
+ import * as dateFns from 'date-fns';
205
+ import { IconTimePicker } from '@fibrae/semi-icons-svelte/lab';
206
+ import { Tag, TimePicker, type TimePickerBaseValueType } from '@fibrae/semi-ui-svelte';
207
+
208
+ const formatToken = 'HH:mm:ss';
209
+
210
+ let time = $state<TimePickerBaseValueType | TimePickerBaseValueType[] | null>(new Date(2024, 0, 1, 10, 30, 0));
211
+ </script>
212
+
213
+ <TimePicker bind:value={time} format={formatToken}>
214
+ {#snippet trigger({ placeholder })}
215
+ <Tag color="cyan" shape="circle" size="large" style="padding: 12px; padding-right: 16px; font-size: 14px" type="light">
216
+ {#snippet prefixIcon()}
217
+ <IconTimePicker />
218
+ {/snippet}
219
+ {time instanceof Date ? dateFns.format(time, formatToken) : placeholder}
220
+ </Tag>
221
+ {/snippet}
222
+ </TimePicker>
223
+ ```
224
+
225
+ ## TimeZone Config
226
+
227
+ Semi All configuration about time zone is converged in [ConfigProvider](../other/config-provider.md)
228
+
229
+ ```svelte
230
+ <script lang="ts">
231
+ import { ConfigProvider, Select, TimePicker } from '@fibrae/semi-ui-svelte';
232
+
233
+ const defaultTimestamp = 1581599305265;
234
+ const gmtList: string[] = [];
235
+ for (let hourOffset = -11; hourOffset <= 14; hourOffset++) {
236
+ const prefix = hourOffset >= 0 ? '+' : '-';
237
+ gmtList.push(`GMT${prefix}${String(Math.abs(hourOffset)).padStart(2, '0')}:00`);
238
+ }
239
+ const optionList = gmtList.map((gmt) => ({ value: gmt, label: gmt }));
240
+
241
+ let timeZone = $state('GMT+08:00');
242
+ </script>
243
+
244
+ <ConfigProvider {timeZone}>
245
+ <div style="width: 300px">
246
+ <h5 style="margin: 10px">Select Time Zone:</h5>
247
+ <Select aria-label="时区" onSelect={(value) => (timeZone = String(value))} {optionList} placeholder="请选择时区" showClear style="width: 300px" value={timeZone} />
248
+ <br />
249
+ <br />
250
+ <h5 style="margin: 10px">TimePicker:</h5>
251
+ <TimePicker onChange={(date, dateString) => console.log('DatePicker changed: ', date, dateString)} value={defaultTimestamp} />
252
+ </div>
253
+ </ConfigProvider>
254
+ ```
255
+
256
+ ## API Reference
257
+
258
+ **Props**
259
+
260
+ | Property | Description | Type | Default |
261
+ | - | - | - | - |
262
+ | autoAdjustOverflow | Whether to flip the popup automatically when it is clipped. | `boolean` | `true` |
263
+ | autofocus | Focuses the input on mount, which opens the panel. | `boolean` | `false` |
264
+ | borderless | Borderless mode. | `boolean` | `false` |
265
+ | classNames | Class names of the inner parts, keyed by dropdown (the panel card of the popup) and input (the root element of the input); values take anything class takes (string, array or object) and merge with the built-in classes. | `Partial<Record<TimePickerPart, ClassValue>>` | - |
266
+ | clearIcon | Custom clear icon; effective when showClear is true. | `Snippet` | - |
267
+ | disabled | Disables all interaction. | `boolean` | - |
268
+ | disabledHours | Returns the hours that cannot be selected. | `() => number[]` | - |
269
+ | disabledMinutes | Returns the minutes that cannot be selected for the selected hour. | `(selectedHour: number) => number[]` | - |
270
+ | disabledSeconds | Returns the seconds that cannot be selected for the selected hour and minute. | `(selectedHour: number, selectedMinute: number) => number[]` | - |
271
+ | disabledTime | Range mode only: returns the disabled rules of the left and right panel from the current value and the panel. The unpicked side of value is undefined; a returned disabledHours, disabledMinutes or disabledSeconds overrides the prop of the same name, and one left out falls back to it. | `(value: (Date \| undefined)[], panelType: PanelType) => DisabledTimeFns` | - |
272
+ | focusOnOpen | Focuses the input and selects its content once mounted, which opens the panel. | `boolean` | `false` |
273
+ | format | Display format, following date-fns format. Defaults to a h:mm:ss with use12Hours, else HH:mm:ss. | `string` | - |
274
+ | hideDisabledOptions | Hides the options that cannot be selected. | `boolean` | `false` |
275
+ | hourStep | Interval of the hour options; a positive integer. | `number` | - |
276
+ | inputReadOnly | Makes the input read-only, which avoids opening the virtual keyboard on mobile devices. | `boolean` | `false` |
277
+ | insetLabel | Inset label of the input. | `Snippet` | - |
278
+ | insetLabelId | id of the insetLabel, referenced through aria-labelledby. | `string` | - |
279
+ | minuteStep | Interval of the minute options; a positive integer. | `number` | - |
280
+ | motion | Whether the popup animates. | `boolean` | `true` |
281
+ | onBlur | Called when a click outside closes the panel, with the native event of that mousedown; leaving the input does not call it. | `(event: MouseEvent) => void` | - |
282
+ | onChange | Called when the time changes, with (Date value, formatted string); both are arrays in range mode. Cleared, it is undefined (single) or an empty array (range); the unpicked side of a range is undefined. | `(value: Date \| (Date \| undefined)[] \| undefined, str: string \| string[]) => void` | - |
283
+ | onEnterPress | Called when Enter is pressed in the input. | `(event: KeyboardEvent) => void` | - |
284
+ | onFocus | Called when the input's root element gains focus; moving focus between the input and the clear button does not call it. | `(event: FocusEvent) => void` | - |
285
+ | onKeyDown | keydown callback of the input. | `(event: KeyboardEvent) => void` | - |
286
+ | onKeyUp | keyup callback of the input. | `(event: KeyboardEvent) => void` | - |
287
+ | onOpenChange | Called when the panel opens or closes. | `(open: boolean) => void` | - |
288
+ | open | Whether the panel is open, used with bind:open; undefined means uncontrolled. | `boolean` | - |
289
+ | panel | Range mode only: used as both the header and the footer of panel index, taking precedence over panelHeader and panelFooter while it has content. | `Snippet<[TimePickerPanelSnippetProps]>` | - |
290
+ | panelFooter | Snippet for the content below the panel; index is the panel's position. | `Snippet<[TimePickerPanelSnippetProps]>` | - |
291
+ | panelHeader | Snippet for the content above the panel; index is the panel's position (0 for time, 0 or 1 for timeRange). Without it, a range shows the locale's start and end text. | `Snippet<[TimePickerPanelSnippetProps]>` | - |
292
+ | placeholder | Hint shown without a value; defaults to the locale text of type. | `string` | - |
293
+ | position | Popup position. Defaults to bottom when type is timeRange, and bottomLeft when it is time. | `Position` | - |
294
+ | prefix | Prefix content of the input. | `Snippet` | - |
295
+ | preventScroll | Whether the browser should scroll the document to show the newly focused element; applies to the focus call inside the component. | `boolean` | - |
296
+ | rangeSeparator | Separator between the two times of a range. | `string` | `" ~ "` |
297
+ | scrollItemProps | Props passed to the columns; only cycled, mode, motion and transform, as on the ScrollItem of ScrollList. | `TimePickerScrollItemProps` | - |
298
+ | secondStep | Interval of the second options; a positive integer. | `number` | - |
299
+ | showClear | Whether to show the clear button. | `boolean` | `true` |
300
+ | size | Size of the input. | `InputSize` | - |
301
+ | stopPropagation | Whether to stop click events on the popup from bubbling. | `boolean` | `true` |
302
+ | styles | Style strings of the inner parts, keyed like classNames. | `Partial<Record<TimePickerPart, string>>` | - |
303
+ | 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 a `TZDate` and the wall-time string of the zone. Falls back to the timeZone of ConfigProvider, then to the global default. | `string \| number` | - |
304
+ | trigger | Snippet of a custom trigger that replaces the default input; a click anywhere in it opens the panel. Receives value (the unpicked side undefined), inputValue, placeholder, disabled, componentProps and onChange (updates the input text, as typing would). | `Snippet<[TimePickerTriggerRenderProps]>` | - |
305
+ | type | Selection type: time for a single time, timeRange for a range. | `TimePickerType` | `"time"` |
306
+ | use12Hours | Uses the 12-hour clock. | `boolean` | `false` |
307
+ | validateStatus | Validation status. | `ValidateStatus` | - |
308
+ | value | Current time, used with bind:value; an array when type is timeRange. null is a controlled empty value, and undefined means uncontrolled. | `TimePickerBaseValueType \| TimePickerBaseValueType[] \| null` | - |
309
+
310
+ **Methods**
311
+
312
+ | Method | Description | Type |
313
+ | - | - | - |
314
+ | blur | Removes focus from the input; does nothing with a custom trigger. | `() => void` |
315
+ | focus | Focuses the input, which opens the panel; does nothing with a custom trigger. | `() => void` |
316
+
317
+ Of the undeclared attributes, `class` and `style` land on the root element, and the others (`id`, `title`, `aria-*`, `data-*`, native events and so on) land on the inner input; with the `trigger` snippet all of them land on the root element, whose role is `group` when `aria-label` or `aria-labelledby` is passed, and they are also available through `componentProps`.
318
+
319
+ Call `focus()` and `blur()` on the component instance; they do nothing with a custom trigger.
320
+
321
+ ## Accessibility
322
+
323
+ ### ARIA
324
+
325
+ - The input has the role `combobox` with `aria-haspopup="dialog"`, an `aria-expanded` that follows the panel, and `aria-controls` pointing at the panel
326
+ - The hour, minute, second and AM/PM columns are `listbox` lists named "Hour", "Minute", "Second" and "AM/PM"
327
+
328
+ ### Keyboard and Focus
329
+
330
+ - Focusing the input opens the panel; once it is open, `Down Arrow` moves focus into the first column
331
+ - Each column is one Tab stop: `Up Arrow`, `Down Arrow`, `Home`, `End` and typed characters select its value
332
+ - `Esc` closes the panel; focus inside the panel returns to the input
333
+
334
+ ## Content Guidelines
335
+
336
+ - The time selector includes at least hours and minutes, such as: 11:30, which can be adapted to 12-hour or 24-hour format during localization
337
+ - When 12-hour clock is selected, it needs to be used together with AM/PM
338
+
339
+ ## Design Tokens
340
+
341
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/input/time-picker/>
342
+
343
+ ## Changes from Semi Design
344
+
345
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
346
+
347
+ - 破坏性:删除 `inputStyle`、`popupClassName`、`popupStyle`,改用 `classNames`、`styles` 的 `input`、`dropdown` 键;`styles.dropdown` 落在面板卡片上,原 `popupStyle` 落在外层定位元素。
348
+ - 破坏性:删除 `getPopupContainer`、`zIndex`、`dropdownMargin`(面板在 top layer)、`onChangeWithDateFirst`(`onChange` 固定为 `(value, valueString)`)、无效的 `clearText`。
349
+ - 破坏性(类型):`TimePickerProps` 改为类型别名(`interface X extends TimePickerProps` 改交叉类型),`onChange` 按 `type` 判别为 `(Date, string)` 或 `(Date[], string[])`;删除无效的 `locale`、`localeCode`、`dateFnsLocale`(改用 `LocaleProvider`、`ConfigProvider`);`scrollItemProps` 收窄为 `cycled`、`mode`、`motion`、`transform`;`triggerRender` 参数改为 `TimePickerTriggerRenderProps`;ref 为 `TimePickerHandle { focus, blur }`。
350
+ - `timeRange` 只选一侧时 `value` 固定长度 2,空侧为 `undefined`,字符串为 `['07:00:00', '']`,`disabledTime` 收到 `[date, undefined]`;按 `length === 1` 判断的代码需调整。
351
+ - 破坏性(类型):`disabledTime` 的 `value` 与 `TimePickerTriggerRenderProps` 的 `value` 声明为 `(Date | undefined)[]`(与运行时一致,四个框架相同),读取一侧的日期前需判空;foundation 的 `TimePickerBaseProps.disabledTime` 与 `getDisabledTimeFns` 的 `dates` 同步放宽。
352
+ - React、Solid:使用 `triggerRender` 时未声明的属性(`id`、`aria-*`、`data-*`、原生事件等)落在根元素上(原来不落在任何元素上,与 Vue、Svelte 一致),传 `aria-label` 或 `aria-labelledby` 时根元素的 role 为 `group`;React 的根元素在触发器内没有可聚焦元素时本身是 `role="button"`,`aria-label` 为它命名,使用方的 `onClick`、`onKeyDown` 先于内部处理调用。
353
+ - 破坏性:设置 `timeZone` 后,字符串 `value` 按目标时区的钟点解析;`onChange` 的字符串是目标时区的钟点,即输入框文字(原来按系统时区格式化),日期与 `disabledTime` 的参数为 `TZDate`,序列化时带偏移而不是 `Z`。受控时切换 `timeZone` 按新时区重读 `value`。
354
+ - `ref.focus()` 聚焦触发器内第一个可聚焦元素,没有时聚焦根元素(自定义触发器同样可用);`ref.blur()` 让触发器或面板内当前聚焦的元素失焦。
355
+ - 行为变化:焦点离开输入框与面板(如在输入框上按 Tab)时关闭面板,不触发 `onBlur`(`onBlur` 仍只在点击外部时触发)。
356
+ - 受控 `open` 时点击外部会调用 `onOpenChange(false)` 与 `onBlur`;`open={undefined}` 按非受控;`value` 为 `null` 是受控空值,时间戳 `0` 有效;`hourStep` 等非正整数抛 `RangeError`。
357
+ - Svelte:`value`、`open` 可绑定(不提供 `defaultValue`、`defaultOpen`),回调为 `onChange(value, str)`、`onOpenChange`;清空时单选上报 `undefined`、范围上报 `[]`。
358
+ - Svelte:`triggerRender` 改为 `trigger` snippet,参数类型 `TimePickerTriggerRenderProps`,其中 `componentProps` 不含 snippet 与未声明属性;`panelHeader`、`panelFooter` snippet 带 `{ index }`,`panel` snippet 在范围模式下同时用作两个面板的头部与底部,不按下标回退;`styles` 的值只接受字符串;键盘回调经 `onKeyDown`、`onKeyUp`、`onEnterPress` 到达输入框;`focus()`、`blur()` 经 `bind:this` 调用。