@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,214 @@
1
+ # DragMove
2
+
3
+ > Set elements to change their position by dragging
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/plus/drag-move/
6
+
7
+ ## When to use
8
+
9
+ It is used to set the element that can be dragged to change its position. It supports limiting the drag range and customizing the elements that trigger dragging.
10
+
11
+ ## Demos
12
+
13
+ ### How to introduce
14
+
15
+ ```svelte
16
+ <script lang="ts">
17
+ import { dragMove } from '@fibrae/semi-ui-svelte';
18
+ </script>
19
+ ```
20
+
21
+ ### Basic usage
22
+
23
+ In Svelte, DragMove is the `dragMove` attachment. Write `{@attach dragMove(options)}` on an element and that element can be dragged to change its position.
24
+
25
+ ***Notice***
26
+
27
+ - DragMove uses absolute positioning by default. Set `positionStrategy="relative"` when the element should keep its original layout position, such as a centered Modal
28
+
29
+ * `dragMove` is an attachment, not a component: it makes the element it is written on draggable, and each element needs its own attachment. It writes `position`, `top`, `left`, `cursor` and `touch-action` inline, so give the element `style:` directives rather than a reactive `style` attribute, which would overwrite them. The options are read when the attachment runs; passing a new options object runs it again and ends a drag in progress
30
+
31
+ ```svelte
32
+ <script lang="ts">
33
+ import { dragMove } from '@fibrae/semi-ui-svelte';
34
+ </script>
35
+
36
+ <!-- dragMove positions the element absolutely, so the wrapper keeps room for it in the preview -->
37
+ <div style="height: 120px">
38
+ <div {@attach dragMove()} style:align-items="center" style:background-color="var(--semi-color-primary)" style:border-radius="10px" style:color="var(--semi-white)" style:display="flex" style:font-weight="500" style:height="80px" style:justify-content="center" style:position="absolute" style:width="80px">
39
+ Drag me
40
+ </div>
41
+ </div>
42
+ ```
43
+
44
+ ### Limit drag range
45
+
46
+ Pass in `constrainer`, either `'parent'` or a function that returns the element limiting the draggable range.
47
+
48
+ ***Note: The elements returned by the constrainer need to be positioned relative***
49
+
50
+ ```svelte
51
+ <script lang="ts">
52
+ import { dragMove } from '@fibrae/semi-ui-svelte';
53
+
54
+ let container = $state<HTMLDivElement>();
55
+ </script>
56
+
57
+ <div bind:this={container} style="background-color: var(--semi-grey-2); width: 300px; height: 300px; padding: 5px; position: relative; color: var(--semi-white); font-weight: 500">
58
+ <span style="color: var(--semi-color-text-0)">Constrainer</span>
59
+ <div
60
+ {@attach dragMove({ constrainer: () => container ?? null })}
61
+ style:align-items="center"
62
+ style:background-color="var(--semi-color-primary)"
63
+ style:border-radius="10px"
64
+ style:display="flex"
65
+ style:height="80px"
66
+ style:justify-content="center"
67
+ style:left="80px"
68
+ style:position="absolute"
69
+ style:top="80px"
70
+ style:width="80px"
71
+ >
72
+ Drag me
73
+ </div>
74
+ </div>
75
+ ```
76
+
77
+ ### Customize elements that trigger dragging
78
+
79
+ Passing in `handler`, this function returns the element that triggered the drag. If not set, you can click anywhere to drag; if set, only the part of the element returned by the handler can be dragged.
80
+
81
+ ```svelte
82
+ <script lang="ts">
83
+ import { IconTransparentStroked } from '@fibrae/semi-icons-svelte';
84
+ import { dragMove } from '@fibrae/semi-ui-svelte';
85
+
86
+ let container = $state<HTMLDivElement>();
87
+ let handlerEl = $state<HTMLDivElement>();
88
+ </script>
89
+
90
+ <div bind:this={container} style="background-color: var(--semi-grey-2); width: 300px; height: 300px; padding: 5px; position: relative; color: var(--semi-white); font-weight: 500">
91
+ <span style="color: var(--semi-color-text-0)">Constrainer</span>
92
+ <div
93
+ {@attach dragMove({ constrainer: () => container ?? null, handler: () => handlerEl ?? null })}
94
+ style:align-items="center"
95
+ style:background-color="var(--semi-color-primary)"
96
+ style:border-radius="10px"
97
+ style:display="flex"
98
+ style:height="80px"
99
+ style:justify-content="center"
100
+ style:left="50px"
101
+ style:position="absolute"
102
+ style:top="50px"
103
+ style:width="80px"
104
+ >
105
+ <div bind:this={handlerEl} style="width: fit-content; height: fit-content">
106
+ <IconTransparentStroked size="large" />
107
+ </div>
108
+ </div>
109
+ </div>
110
+ ```
111
+
112
+ ### Customize position processing after dragging
113
+
114
+ You can customize the position processing after dragging through `customMove`. After this parameter is set, the DragMove component will only return the calculated position through the parameters without setting it. The user can set the new position as needed.
115
+
116
+ ```svelte
117
+ <script lang="ts">
118
+ import { dragMove } from '@fibrae/semi-ui-svelte';
119
+
120
+ let container = $state<HTMLDivElement>();
121
+ let startPoint: { x: number; y: number } | null = null;
122
+
123
+ const customMove = (element: HTMLElement, top: number, left: number) => {
124
+ const bounds = container;
125
+ if (bounds && left + 100 > bounds.offsetWidth) {
126
+ element.style.right = `${bounds.offsetWidth - left - element.offsetWidth}px`;
127
+ element.style.left = 'auto';
128
+ } else {
129
+ element.style.left = left + 'px';
130
+ }
131
+ element.style.top = top + 'px';
132
+ };
133
+
134
+ const toggleWidth = (element: HTMLElement) => {
135
+ element.style.width = element.style.width === '60px' ? '100px' : '60px';
136
+ };
137
+
138
+ const onmousedown = (e: MouseEvent) => {
139
+ startPoint = { x: e.clientX, y: e.clientY };
140
+ };
141
+
142
+ const onmouseup = (e: MouseEvent) => {
143
+ if (startPoint && Math.abs(e.clientX - startPoint.x) < 5 && Math.abs(e.clientY - startPoint.y) < 5) {
144
+ toggleWidth(e.currentTarget as HTMLElement);
145
+ }
146
+ startPoint = null;
147
+ };
148
+
149
+ const onkeydown = (e: KeyboardEvent) => {
150
+ if (e.key === 'Enter') {
151
+ toggleWidth(e.currentTarget as HTMLElement);
152
+ }
153
+ };
154
+ </script>
155
+
156
+ <span>蓝色色块点击可改变宽度,改变前后蓝色色块均不会超出范围限制 </span>
157
+ <br />
158
+ <br />
159
+ <div bind:this={container} style="background-color: var(--semi-grey-2); width: 300px; height: 300px; position: relative; padding: 10px; color: var(--semi-white); font-weight: 500">
160
+ <span style="color: var(--semi-color-text-0)">Constrainer</span>
161
+ <button
162
+ {@attach dragMove({ constrainer: () => container ?? null, customMove })}
163
+ style:align-items="center"
164
+ style:background-color="var(--semi-color-primary)"
165
+ style:border="none"
166
+ style:border-radius="10px"
167
+ style:box-sizing="content-box"
168
+ style:color="inherit"
169
+ style:display="flex"
170
+ style:font="inherit"
171
+ style:height="50px"
172
+ style:justify-content="center"
173
+ style:left="50px"
174
+ style:padding="5px"
175
+ style:position="absolute"
176
+ style:top="50px"
177
+ style:width="60px"
178
+ type="button"
179
+ {onkeydown}
180
+ {onmousedown}
181
+ {onmouseup}
182
+ >
183
+ Drag me
184
+ </button>
185
+ </div>
186
+ ```
187
+
188
+ ### API
189
+
190
+ `dragMove(options?: DragMoveOptions)` returns an `Attachment<HTMLElement>`. `DragMoveOptions` is exported from `@fibrae/semi-ui-svelte`.
191
+
192
+ | Property | Description | Type | Default |
193
+ | - | - | - | - |
194
+ | allowInputDrag | Whether dragging is allowed when pressing on a native input or textarea. | boolean | false |
195
+ | allowMove | Function that decides whether a drag may start on pointer down; returning false prevents it. | (e: PointerEvent, element: HTMLElement) => boolean | - |
196
+ | constrainer | The element that limits the draggable range: `'parent'` for the parent element, or a function that returns it. It needs to be positioned relatively. | 'parent' \| (() => HTMLElement \| null) | - |
197
+ | customMove | Custom position handling after dragging. When set, only the calculated position is passed back and the element's top and left are no longer written. | (element: HTMLElement, top: number, left: number) => void | - |
198
+ | handler | The element that triggers dragging, or a function that returns it. Defaults to the dragged element itself. | HTMLElement \| (() => HTMLElement \| null) | - |
199
+ | onMouseDown | Called when a mouse or pen pointer is pressed. | (e: PointerEvent) => void | - |
200
+ | onMouseMove | Called when a mouse or pen pointer moves. | (e: PointerEvent) => void | - |
201
+ | onMouseUp | Called when a mouse or pen pointer is released. | (e: PointerEvent) => void | - |
202
+ | onTouchCancel | Called when the pointer is cancelled by the system (pointercancel). | (e: PointerEvent) => void | - |
203
+ | onTouchEnd | Called when a touch pointer is released. | (e: PointerEvent) => void | - |
204
+ | onTouchMove | Called when a touch pointer moves. | (e: PointerEvent) => void | - |
205
+ | onTouchStart | Called when a touch pointer is pressed. | (e: PointerEvent) => void | - |
206
+ | positionStrategy | Positioning strategy. relative keeps the element's original layout position. | 'absolute' \| 'relative' | 'absolute' |
207
+
208
+ ## Changes from Semi Design
209
+
210
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
211
+
212
+ - 破坏性(类型):`onMouse*`、`onTouch*`、`allowMove` 参数改为 `PointerEvent`;`children` 收窄为 `ReactNode`;`handler` 改为 `() => HTMLElement | null`,返回的元素需位于被拖元素内;右键、中键不再启动拖动。
213
+ - Svelte:没有 `DragMove` 组件,改为 attachment,写成 `<div {@attach dragMove(options)}>`,从 `@fibrae/semi-ui-svelte` 导入 `dragMove` 与 `DragMoveOptions`;Vue 的同名 props(`handler`、`constrainer`、`allowInputDrag`、`allowMove`、`customMove`、`positionStrategy`)变成同名 options,`handler` 可传函数或元素;7 个事件变成 `onMouseDown`、`onMouseMove`、`onMouseUp`、`onTouchStart`、`onTouchMove`、`onTouchEnd`、`onTouchCancel` 回调(参数为 `PointerEvent`);不是组件,没有全局默认值。
214
+ - 松手时先写入最后位置再触发结束回调,回调里设置的位置不再被覆盖;移动回调中卸载组件后不再调用 `customMove`。
@@ -0,0 +1,174 @@
1
+ # HotKeys
2
+
3
+ > used to facilitate the customization of keyboard shortcut
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/plus/hot-keys/
6
+
7
+ ## When to use
8
+
9
+ When it is necessary to express the usage method of shortcut key combinations to users, using the `Hotkeys` component can quickly render the corresponding UI elements and automatically obtain event bindings.
10
+
11
+ ## Demos
12
+
13
+ ### How to import
14
+
15
+ ```svelte
16
+ <script lang="ts">
17
+ import { HotKeys } from '@fibrae/semi-ui-svelte';
18
+ </script>
19
+ ```
20
+
21
+ ### Explanation
22
+
23
+ A hotkey is one regular key plus zero or more modifier keys (`Shift`, `Control`, `Meta`, `Alt`). A single regular key without modifiers (such as `['k']`) is valid too. The listener is a keydown handler on `document.body` (or the element returned by `getListenerTarget`), so it also fires while focus is inside an input; check `event.target` in `onHotKey` (`@hotKey` in Vue) to skip typing contexts. Modifiers must match exactly: with `['k']`, pressing Ctrl and K does not trigger it.
24
+
25
+ Keys are matched by physical key position. Symbols that need Shift to type, such as `!`, `@` and `?`, are not valid keys and throw when set. Write them as `Shift` plus the base key instead, for example `['Shift', '1']` or `['Shift', '/']`.
26
+
27
+ > [Meta](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/metaKey) corresponds to Command on macOS and Win on Windows.
28
+
29
+ When setting a shortcut that overlaps with common shortcuts like Ctrl/Meta + C, the preventDefault setting can be used to control whether the default event is triggered.
30
+
31
+ ### Basic Usage
32
+
33
+ Pass in key combinations via `hotKeys` and bind a shortcut handler function using `onHotKey` (`@hotKey` in Vue) to respond to the action.
34
+
35
+ When pressing `Ctrl + Shift + A`, it opens the modal. By default, it listens on the body, making it effective globally.
36
+
37
+ [values reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
38
+
39
+ It's also recommended to use the `HotKeys.Keys` wrapper to set hotkeys.
40
+
41
+ ```svelte
42
+ <script lang="ts">
43
+ import { HotKeys, Modal } from '@fibrae/semi-ui-svelte';
44
+
45
+ let visible = $state(false);
46
+ const close = () => {
47
+ visible = false;
48
+ };
49
+ const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.A];
50
+ </script>
51
+
52
+ <div>
53
+ <HotKeys {hotKeys} onHotKey={() => (visible = true)} />
54
+ <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: {hotKeys.join('+')}.</Modal>
55
+ </div>
56
+ ```
57
+
58
+ ### Custom content
59
+
60
+ Set the characters through `content`
61
+
62
+ ```svelte
63
+ <script lang="ts">
64
+ import { HotKeys, Modal } from '@fibrae/semi-ui-svelte';
65
+
66
+ let visible = $state(false);
67
+ const close = () => {
68
+ visible = false;
69
+ };
70
+ const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B];
71
+ </script>
72
+
73
+ <div>
74
+ <HotKeys content={['Ctrl', 'Shift', 'B']} {hotKeys} onHotKey={() => (visible = true)} />
75
+ <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: {hotKeys.join('+')}.</Modal>
76
+ </div>
77
+ ```
78
+
79
+ Replace the element through the `children` snippet (written inside the HotKeys tag). With it the default key hint is not rendered and the hot keys stay active.
80
+
81
+ ```svelte
82
+ <script lang="ts">
83
+ import { HotKeys, Modal, Tag } from '@fibrae/semi-ui-svelte';
84
+
85
+ let visible = $state(false);
86
+ const close = () => {
87
+ visible = false;
88
+ };
89
+ const hotKeys = [HotKeys.Keys.Control, HotKeys.Keys.R];
90
+ </script>
91
+
92
+ <div>
93
+ <HotKeys {hotKeys} onHotKey={() => (visible = true)}>
94
+ <Tag>Press Ctrl+R to Open Modal</Tag>
95
+ </HotKeys>
96
+ <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: {hotKeys.join('+')}.</Modal>
97
+ </div>
98
+ ```
99
+
100
+ ### prevent Default event
101
+
102
+ Control the default event by setting `preventDefault`.
103
+
104
+ ```svelte
105
+ <script lang="ts">
106
+ import { HotKeys, Modal } from '@fibrae/semi-ui-svelte';
107
+
108
+ let visible = $state(false);
109
+ const close = () => {
110
+ visible = false;
111
+ };
112
+ const metaKeys = [HotKeys.Keys.Meta, HotKeys.Keys.S];
113
+ const controlKeys = [HotKeys.Keys.Control, HotKeys.Keys.S];
114
+ </script>
115
+
116
+ <div>
117
+ <HotKeys hotKeys={metaKeys} onHotKey={() => (visible = true)} preventDefault />
118
+ <br />
119
+ <HotKeys hotKeys={controlKeys} onHotKey={() => (visible = true)} preventDefault />
120
+ <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: Meta/Control + S.</Modal>
121
+ </div>
122
+ ```
123
+
124
+ ### change the DOM element the listener is mounted on
125
+
126
+ The hotkey is listened to on the body by default, through `getListenerTarget`
127
+
128
+ ```svelte
129
+ <script lang="ts">
130
+ import { HotKeys, Input, Modal } from '@fibrae/semi-ui-svelte';
131
+
132
+ const hotKeys = ['Control', 'q'];
133
+ let visible = $state(false);
134
+ const close = () => {
135
+ visible = false;
136
+ };
137
+ let input = $state<ReturnType<typeof Input>>();
138
+ const getListenerTarget = () => input?.getInput();
139
+ </script>
140
+
141
+ <div>
142
+ <Input bind:this={input} placeholder="test for target" />
143
+ <HotKeys {getListenerTarget} {hotKeys} onHotKey={() => (visible = true)} />
144
+ <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: {hotKeys.join('+')}.</Modal>
145
+ </div>
146
+ ```
147
+
148
+ ## API Reference
149
+
150
+ ### HotKeys
151
+
152
+ **Props**
153
+
154
+ | Property | Description | Type | Default |
155
+ | - | - | - | - |
156
+ | children | Replaces the key hint, written inside the tag. With children the default key hint is not rendered and the hot keys stay active. | `Snippet` | - |
157
+ | content | Key labels to show. Defaults to hotKeys. | `string[]` | - |
158
+ | getListenerTarget | Returns the element that listens for keydown. When omitted, or when it returns null or undefined, document.body is used. | `() => HTMLElement \| null \| undefined` | - |
159
+ | hotKeys | The key combination: any number of modifiers plus one other key, as KeyboardEvent.key values. An invalid combination throws on mount or when hotKeys changes. | `KeyboardEvent['key'][]` | - |
160
+ | onHotKey | Called when the full key combination is pressed, with the native KeyboardEvent. | `(event: KeyboardEvent) => void` | - |
161
+ | preventDefault | Whether the default behavior of the key combination is prevented. | `boolean` | `false` |
162
+
163
+ `class`, `style` (a string) and native attributes (such as `id`, `aria-*` and `onclick`) land on the root element (`div`). `HotKeys.Keys` is kept and used as in the other frameworks.
164
+
165
+ ## Design Tokens
166
+
167
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/plus/hot-keys/>
168
+
169
+ ## Changes from Semi Design
170
+
171
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
172
+
173
+ - 破坏性:`HotKeys.Keys` 删除需 Shift 才能输入的符号别名(`Exclamation`、`At`、`Hash` 等),`hotKeys` 写 `'!'`、`'@'` 现在抛错,改写为 `['Shift', '1']`;删除无效的 `mergeMetaCtrl`;`HotKeysProps` 收窄为实际接受的属性(不含 `children`),`hotKeys` 必填。
174
+ - Svelte:`render` 改为 `children` snippet,回调为 `onHotKey`,`HotKeys.Keys` 保留;无效的按键组合在挂载或 `hotKeys` 变化时抛错。