@fibrae/semi-ui-svelte 0.9.1 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -4
- package/README.zh-CN.md +8 -4
- package/dist/components/anchor/interface.d.ts +14 -0
- package/dist/components/audio-player/interface.d.ts +5 -0
- package/dist/components/auto-complete/interface.d.ts +29 -0
- package/dist/components/avatar/interface.d.ts +24 -0
- package/dist/components/backtop/interface.d.ts +2 -0
- package/dist/components/badge/interface.d.ts +7 -0
- package/dist/components/banner/interface.d.ts +7 -0
- package/dist/components/breadcrumb/interface.d.ts +10 -0
- package/dist/components/button/interface.d.ts +18 -0
- package/dist/components/calendar/interface.d.ts +16 -0
- package/dist/components/card/interface.d.ts +18 -0
- package/dist/components/carousel/interface.d.ts +16 -0
- package/dist/components/cascader/interface.d.ts +57 -0
- package/dist/components/checkbox/interface.d.ts +19 -0
- package/dist/components/code-highlight/interface.d.ts +3 -0
- package/dist/components/collapse/interface.d.ts +16 -0
- package/dist/components/collapsible/interface.d.ts +10 -0
- package/dist/components/color-picker/interface.d.ts +10 -0
- package/dist/components/config-provider/interface.d.ts +7 -0
- package/dist/components/cropper/interface.d.ts +11 -0
- package/dist/components/date-picker/interface.d.ts +47 -0
- package/dist/components/descriptions/interface.d.ts +6 -0
- package/dist/components/divider/interface.d.ts +4 -0
- package/dist/components/dropdown/interface.d.ts +8 -0
- package/dist/components/empty/interface.d.ts +7 -0
- package/dist/components/feedback/interface.d.ts +16 -0
- package/dist/components/float-button/interface.d.ts +14 -0
- package/dist/components/form/interface.d.ts +47 -0
- package/dist/components/grid/interface.d.ts +13 -0
- package/dist/components/highlight/interface.d.ts +7 -0
- package/dist/components/hot-keys/interface.d.ts +3 -0
- package/dist/components/image/interface.d.ts +59 -0
- package/dist/components/input/interface.d.ts +67 -0
- package/dist/components/input-number/interface.d.ts +24 -0
- package/dist/components/json-viewer/interface.d.ts +7 -0
- package/dist/components/layout/interface.d.ts +3 -0
- package/dist/components/list/interface.d.ts +18 -0
- package/dist/components/locale/interface.d.ts +4 -0
- package/dist/components/lottie/interface.d.ts +2 -0
- package/dist/components/markdown-render/interface.d.ts +5 -0
- package/dist/components/modal/interface.d.ts +29 -0
- package/dist/components/navigation/interface.d.ts +47 -0
- package/dist/components/overflow-list/interface.d.ts +11 -0
- package/dist/components/pagination/interface.d.ts +12 -0
- package/dist/components/pincode/interface.d.ts +8 -0
- package/dist/components/popconfirm/interface.d.ts +12 -0
- package/dist/components/popover/interface.d.ts +30 -0
- package/dist/components/progress/interface.d.ts +13 -0
- package/dist/components/radio/interface.d.ts +22 -0
- package/dist/components/rating/interface.d.ts +12 -0
- package/dist/components/resizable/interface.d.ts +30 -0
- package/dist/components/scroll-list/interface.d.ts +6 -0
- package/dist/components/select/interface.d.ts +63 -0
- package/dist/components/side-sheet/interface.d.ts +19 -0
- package/dist/components/skeleton/interface.d.ts +7 -0
- package/dist/components/slider/interface.d.ts +23 -0
- package/dist/components/space/interface.d.ts +4 -0
- package/dist/components/spin/interface.d.ts +7 -0
- package/dist/components/steps/interface.d.ts +9 -0
- package/dist/components/switch/interface.d.ts +7 -0
- package/dist/components/table/interface.d.ts +48 -0
- package/dist/components/tabs/interface.d.ts +29 -0
- package/dist/components/tag/interface.d.ts +22 -0
- package/dist/components/tag-input/interface.d.ts +29 -0
- package/dist/components/time-picker/interface.d.ts +31 -0
- package/dist/components/timeline/interface.d.ts +5 -0
- package/dist/components/tooltip/interface.d.ts +20 -0
- package/dist/components/transfer/interface.d.ts +18 -0
- package/dist/components/tree/interface.d.ts +45 -0
- package/dist/components/tree-select/interface.d.ts +55 -0
- package/dist/components/typography/interface.d.ts +33 -0
- package/dist/components/upload/interface.d.ts +64 -0
- package/dist/components/user-guide/interface.d.ts +15 -0
- package/dist/components/video-player/interface.d.ts +22 -0
- package/docs/advanced/dark-mode.md +288 -0
- package/docs/basic/button.md +605 -0
- package/docs/basic/divider.md +103 -0
- package/docs/basic/float-button.md +246 -0
- package/docs/basic/grid.md +427 -0
- package/docs/basic/layout.md +459 -0
- package/docs/basic/resizable.md +584 -0
- package/docs/basic/space.md +163 -0
- package/docs/basic/tokens.md +425 -0
- package/docs/basic/typography.md +615 -0
- package/docs/changes-from-semi.md +105 -0
- package/docs/ecosystem/tailwind.md +210 -0
- package/docs/experience/accessibility.md +82 -0
- package/docs/experience/content-guidelines.md +819 -0
- package/docs/experience/internationalization.md +7 -0
- package/docs/feedback/banner.md +198 -0
- package/docs/feedback/feedback.md +294 -0
- package/docs/feedback/notification.md +401 -0
- package/docs/feedback/popconfirm.md +243 -0
- package/docs/feedback/progress.md +389 -0
- package/docs/feedback/skeleton.md +388 -0
- package/docs/feedback/spin.md +172 -0
- package/docs/feedback/toast.md +393 -0
- package/docs/input/auto-complete.md +399 -0
- package/docs/input/cascader.md +1558 -0
- package/docs/input/checkbox.md +408 -0
- package/docs/input/color-picker.md +175 -0
- package/docs/input/date-picker.md +942 -0
- package/docs/input/form.md +2550 -0
- package/docs/input/input-number.md +451 -0
- package/docs/input/input.md +640 -0
- package/docs/input/pincode.md +191 -0
- package/docs/input/radio.md +337 -0
- package/docs/input/rating.md +214 -0
- package/docs/input/select.md +1230 -0
- package/docs/input/slider.md +347 -0
- package/docs/input/switch.md +206 -0
- package/docs/input/tag-input.md +465 -0
- package/docs/input/time-picker.md +358 -0
- package/docs/input/transfer.md +1061 -0
- package/docs/input/tree-select.md +1300 -0
- package/docs/input/upload.md +1811 -0
- package/docs/llms.txt +147 -0
- package/docs/navigation/anchor.md +377 -0
- package/docs/navigation/backtop.md +100 -0
- package/docs/navigation/breadcrumb.md +284 -0
- package/docs/navigation/navigation.md +851 -0
- package/docs/navigation/pagination.md +217 -0
- package/docs/navigation/steps.md +315 -0
- package/docs/navigation/tabs.md +754 -0
- package/docs/navigation/tree.md +1956 -0
- package/docs/other/config-provider.md +599 -0
- package/docs/other/locale.md +353 -0
- package/docs/plus/audio-player.md +155 -0
- package/docs/plus/code-highlight.md +150 -0
- package/docs/plus/drag-move.md +214 -0
- package/docs/plus/hot-keys.md +174 -0
- package/docs/plus/json-viewer.md +392 -0
- package/docs/plus/lottie.md +176 -0
- package/docs/plus/markdown-render.md +240 -0
- package/docs/plus/video-player.md +325 -0
- package/docs/show/avatar.md +475 -0
- package/docs/show/badge.md +276 -0
- package/docs/show/calendar.md +352 -0
- package/docs/show/card.md +485 -0
- package/docs/show/carousel.md +592 -0
- package/docs/show/collapse.md +289 -0
- package/docs/show/collapsible.md +216 -0
- package/docs/show/cropper.md +285 -0
- package/docs/show/descriptions.md +325 -0
- package/docs/show/dropdown.md +466 -0
- package/docs/show/empty.md +225 -0
- package/docs/show/highlight.md +144 -0
- package/docs/show/image.md +433 -0
- package/docs/show/list.md +927 -0
- package/docs/show/modal.md +517 -0
- package/docs/show/overflow-list.md +272 -0
- package/docs/show/popover.md +534 -0
- package/docs/show/scroll-list.md +156 -0
- package/docs/show/side-sheet.md +274 -0
- package/docs/show/table.md +5437 -0
- package/docs/show/tag.md +428 -0
- package/docs/show/timeline.md +277 -0
- package/docs/show/tooltip.md +442 -0
- package/docs/show/user-guide.md +419 -0
- package/docs/start/getting-started.md +234 -0
- package/docs/start/introduction.md +57 -0
- package/docs/start/overview.md +21 -0
- 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` 变化时抛错。
|