@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,517 @@
1
+ # Modal
2
+
3
+ > Modals are used to wait for the user to interact, inform the user of important information, or display more information without losing context.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/modal/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Modal } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ Use `bind:visible` to control visibility. `bind:visible` is written back with `false` only on the cancel paths: the cancel button, the close button, the mask and Esc. When `onCancel` returns a Promise, it is written back after the Promise fulfills, and a rejection keeps the modal open. Clicking ok only calls `onOk`; the caller sets `visible` to `false`. While `onCancel` runs, `visible` is still `true`.
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
24
+
25
+ let visible = $state(false);
26
+ const handleOk = () => {
27
+ visible = false;
28
+ console.log('Ok button clicked');
29
+ };
30
+ const handleCancel = () => {
31
+ console.log('Cancel button clicked');
32
+ };
33
+ const handleAfterClose = () => {
34
+ console.log('After Close callback executed');
35
+ };
36
+ </script>
37
+
38
+ <Button onclick={() => (visible = true)}>打开弹窗</Button>
39
+ <Modal afterClose={handleAfterClose} bind:visible closeOnEsc onCancel={handleCancel} onOk={handleOk} title="基本对话框">
40
+ This is the content of a basic modal.
41
+ <br />
42
+ More content...
43
+ </Modal>
44
+ ```
45
+
46
+ ### Bottom Button Fill up
47
+
48
+ Set `footerFill` to true to make the bottom buttons of the Modal footer fill up the arrangement.
49
+
50
+ ```svelte
51
+ <script lang="ts">
52
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
53
+
54
+ let visible = $state(false);
55
+ const handleOk = () => {
56
+ visible = false;
57
+ console.log('Ok button clicked');
58
+ };
59
+ const handleCancel = () => {
60
+ console.log('Cancel button clicked');
61
+ };
62
+ const handleAfterClose = () => {
63
+ console.log('After Close callback executed');
64
+ };
65
+ </script>
66
+
67
+ <Button onclick={() => (visible = true)}>打开弹窗</Button>
68
+ <Modal afterClose={handleAfterClose} bind:visible closeOnEsc footerFill onCancel={handleCancel} onOk={handleOk} title="基本对话框">
69
+ This is the content of a basic modal.
70
+ <br />
71
+ More content...
72
+ </Modal>
73
+ ```
74
+
75
+ ### Mask Closable
76
+
77
+ You can set `maskClosable={false}` to prevent modal from closing when clicking on the mask.
78
+
79
+ ```svelte
80
+ <script lang="ts">
81
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
82
+
83
+ let visible = $state(false);
84
+ const close = () => {
85
+ visible = false;
86
+ };
87
+ </script>
88
+
89
+ <Button onclick={() => (visible = true)}>点击遮罩层不可关闭</Button>
90
+ <Modal bind:visible maskClosable={false} onOk={close} title="对话框标题">
91
+ <p>This is a modal that cannot be closed by clicking on the mask.</p>
92
+ <p>More content...</p>
93
+ </Modal>
94
+ ```
95
+
96
+ ### Custom Button Text
97
+
98
+ You can set button text using `okText` and `cancelText`.
99
+
100
+ > A modal created with static methods is rendered outside the component tree, so it cannot read the locale from ConfigProvider or LocaleProvider. Set the texts with these two properties, or use `Modal.useModal`.
101
+
102
+ ```svelte
103
+ <script lang="ts">
104
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
105
+
106
+ let visible = $state(false);
107
+ const close = () => {
108
+ visible = false;
109
+ };
110
+ </script>
111
+
112
+ <Button onclick={() => (visible = true)}>自定义按钮文字</Button>
113
+ <Modal bind:visible cancelText="No, thanks." okText="Sounds great!" onOk={close} title="自定义按钮文字">
114
+ <p>This is a modal with customized button texts.</p>
115
+ <p>More content...</p>
116
+ </Modal>
117
+ ```
118
+
119
+ ### Custom Button Properties
120
+
121
+ You can set button properties using `okButtonProps` and `cancelButtonProps`. Their `onClick` runs before the built-in handling and does not replace it.
122
+
123
+ ```svelte
124
+ <script lang="ts">
125
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
126
+
127
+ let visible = $state(false);
128
+ const close = () => {
129
+ visible = false;
130
+ };
131
+ </script>
132
+
133
+ <Button onclick={() => (visible = true)}>自定义按钮属性</Button>
134
+ <Modal bind:visible cancelButtonProps={{ size: 'small', disabled: true }} okButtonProps={{ size: 'small', type: 'warning' }} onOk={close} title="自定义按钮属性">
135
+ <p>This is a modal with customized button props.</p>
136
+ <p>More content...</p>
137
+ </Modal>
138
+ ```
139
+
140
+ ### Custom Header & Footer
141
+
142
+ For more customized modal, you could use the `header` and `footer` snippets. An empty `header` snippet (`{#snippet header()}{/snippet}`) or `header={null}` removes the header area; likewise an empty `footer` snippet or `footer={null}` removes the footer area including buttons.
143
+
144
+ ```svelte
145
+ <script lang="ts">
146
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
147
+
148
+ let visible = $state(false);
149
+ </script>
150
+
151
+ <Button onclick={() => (visible = true)}>自定义页脚样式</Button>
152
+ <Modal bind:visible title="自定义页脚">
153
+ <p>This is a modal with a customized footer.</p>
154
+ <p>More content...</p>
155
+ {#snippet footer()}
156
+ <Button type="primary" onclick={() => (visible = false)}>Yes, I Understand</Button>
157
+ {/snippet}
158
+ </Modal>
159
+ ```
160
+
161
+ ### Custom Style
162
+
163
+ You can use `style` to customize styling or position e.g. `style.top = '30vh'`, or use `centered` to center modal. Also, you could use `styles` to customize the style of each part (such as `styles.mask` for the mask and `styles.body` for the content), and `classNames` likewise.
164
+
165
+ ```svelte
166
+ <script lang="ts">
167
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
168
+
169
+ let visible = $state(false);
170
+ const close = () => {
171
+ visible = false;
172
+ };
173
+ </script>
174
+
175
+ <Button onclick={() => (visible = true)}>自定义对话框样式</Button>
176
+ <Modal bind:visible centered onOk={close} styles={{ body: 'overflow: auto; height: 200px' }} title="自定义样式">
177
+ <p style="line-height: 1.8">Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用。设计系统包含设计语言以及一整套可复用的前端组件,帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。</p>
178
+ <p style="line-height: 1.8">区别于其他的设计系统而言,Semi Design 以用户中心、内容优先、设计人性化为设计理念,具有以下优势:</p>
179
+ <ul>
180
+ <li>
181
+ <p>Semi Design 以内容优先进行设计。</p>
182
+ </li>
183
+ <li>
184
+ <p>更容易地自定义主题。</p>
185
+ </li>
186
+ <li>
187
+ <p>适用国际化场景。</p>
188
+ </li>
189
+ <li>
190
+ <p>效率场景加入人性化关怀</p>
191
+ </li>
192
+ </ul>
193
+ </Modal>
194
+ ```
195
+
196
+ ### Custom Modal
197
+
198
+ By using the `header`, `footer` and other snippets, you could create any modal to your needs.
199
+
200
+ ```svelte
201
+ <script lang="ts">
202
+ import { IconSemiLogo, IconVigoLogo } from '@fibrae/semi-icons-svelte';
203
+ import { Button, List, Modal } from '@fibrae/semi-ui-svelte';
204
+
205
+ let visible = $state(false);
206
+ const data = [
207
+ {
208
+ icon: IconSemiLogo,
209
+ title: 'Boost new feature adoption with Integration',
210
+ content: 'Sample data is prepared for you to demonstrate how Integration may be useful for your team',
211
+ },
212
+ {
213
+ icon: IconVigoLogo,
214
+ title: 'Introducing Dark Mode',
215
+ content: 'Sample data is prepared for you to demonstrate how Integration may be useful for your team',
216
+ },
217
+ {
218
+ icon: IconSemiLogo,
219
+ title: 'New List Component',
220
+ content: 'Sample data is prepared for you to demonstrate how Integration may be useful for your team',
221
+ },
222
+ ];
223
+ const btnStyle = 'width: 240px; margin: 4px 50px';
224
+ </script>
225
+
226
+ <Button onclick={() => (visible = true)}>自定义对话框</Button>
227
+ <Modal bind:visible>
228
+ {#snippet header()}{/snippet}
229
+ <h3 style="text-align: center; font-size: 24px; margin: 40px">Semi Design New Features</h3>
230
+ <List dataSource={data} split={false}>
231
+ {#snippet item(listItem)}
232
+ <List.Item>
233
+ {#snippet header()}
234
+ <listItem.item.icon style="font-size: 48px" />
235
+ {/snippet}
236
+ {#snippet main()}
237
+ <div>
238
+ <h6 style="margin: 0; font-size: 16px">{listItem.item.title}</h6>
239
+ <p style="margin-block-start: 4px; color: var(--semi-color-text-1)">{listItem.item.content}</p>
240
+ </div>
241
+ {/snippet}
242
+ </List.Item>
243
+ {/snippet}
244
+ </List>
245
+ {#snippet footer()}
246
+ <div style="text-align: center">
247
+ <Button style={btnStyle} theme="solid" type="primary" onclick={() => (visible = false)}>Continue</Button>
248
+ <Button style={btnStyle} theme="borderless" type="primary" onclick={() => (visible = false)}>Learn more features</Button>
249
+ </div>
250
+ {/snippet}
251
+ </Modal>
252
+ ```
253
+
254
+ ### Full Screen Modal
255
+
256
+ Set `fullScreen` to use full screen Modal
257
+
258
+ ```svelte
259
+ <script lang="ts">
260
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
261
+
262
+ let visible = $state(false);
263
+ const close = () => {
264
+ visible = false;
265
+ };
266
+ </script>
267
+
268
+ <Button onclick={() => (visible = true)}>打开全屏弹窗</Button>
269
+ <Modal bind:visible fullScreen onOk={close} title="全屏对话框标题">
270
+ <p>This is a full screen modal</p>
271
+ <p>More content...</p>
272
+ </Modal>
273
+ ```
274
+
275
+ ### Confirm Modal
276
+
277
+ You could use static methods to create a confirm Modal. The `title`, `content`, `icon`, `closeIcon`, `header` and `footer` of a static call take a `ModalNode`: a string or a snippet; `icon: null` removes the icon. Any other option the Modal supports can be passed too.
278
+
279
+ ```svelte
280
+ <script lang="ts">
281
+ import { IconSend } from '@fibrae/semi-icons-svelte';
282
+ import { Button, Modal } from '@fibrae/semi-ui-svelte';
283
+
284
+ const success = () => Modal.success({ title: 'This is a success message', content: 'bla bla bla...' });
285
+ const info = () => Modal.info({ title: 'Here is some info', content: 'bla bla bla...' });
286
+ const error = () => Modal.error({ title: 'Unfortunately, there is an error', content: 'bla bla bla...' });
287
+ const warning = () => Modal.warning({ title: 'Warning: be cautious ahead', content: 'bla bla bla...' });
288
+ const confirm = () => Modal.confirm({ title: 'Are you sure ?', content: 'bla bla bla...' });
289
+ const custom = () =>
290
+ Modal.info({
291
+ title: 'This is a custom modal',
292
+ content: 'bla bla bla...',
293
+ icon: sendIcon,
294
+ cancelButtonProps: { theme: 'borderless' },
295
+ okButtonProps: { theme: 'solid' },
296
+ });
297
+ </script>
298
+
299
+ {#snippet sendIcon()}
300
+ <IconSend />
301
+ {/snippet}
302
+
303
+ <div>
304
+ <Button onclick={info}>Info</Button>
305
+ <br />
306
+ <br />
307
+ <Button onclick={success}>Success</Button>
308
+ <br />
309
+ <br />
310
+ <Button type="danger" onclick={error}>Error</Button>
311
+ <br />
312
+ <br />
313
+ <Button type="warning" onclick={warning}>Warning</Button>
314
+ <br />
315
+ <br />
316
+ <Button type="primary" onclick={confirm}>Confirm</Button>
317
+ <br />
318
+ <br />
319
+ <Button onclick={custom}>Custom</Button>
320
+ </div>
321
+ ```
322
+
323
+ ### useModal Hooks
324
+
325
+ `Modal.useModal()` returns `{ info, success, error, warning, confirm }` and has no Holder. It reads the context, ConfigProvider and locale of the component that calls it, so call it during component initialization, in the component that should supply those (usually a child of ConfigProvider). Dialogs it opened are removed when that component is destroyed.
326
+
327
+ ```svelte
328
+ <script lang="ts">
329
+ import { ConfigProvider } from '@fibrae/semi-ui-svelte';
330
+ import { en_US } from '@fibrae/semi-ui-svelte/locale';
331
+ import UseModalConfirm from './parts/use-modal-confirm.svelte';
332
+ </script>
333
+
334
+ <ConfigProvider locale={en_US}>
335
+ <UseModalConfirm />
336
+ </ConfigProvider>
337
+ ```
338
+
339
+ ### Draggable Modal
340
+
341
+ DragMove in Svelte is the `dragMove` attachment. Write `{@attach dragMove(options)}` directly on `<Modal>`; the attachment lands on the `role="dialog"` element and makes the dialog draggable. To place the dialog yourself, use the `modal` snippet (argument `{ modal }`, placed with `{@render modal()}`).
342
+
343
+ ```svelte
344
+ <script lang="ts">
345
+ import { Button, dragMove, Modal } from '@fibrae/semi-ui-svelte';
346
+
347
+ let visible = $state(false);
348
+ </script>
349
+
350
+ <div>
351
+ <Button onclick={() => (visible = true)}>Open Modal</Button>
352
+ <Modal {@attach dragMove({ positionStrategy: 'relative' })} bind:visible centered title="可拖拽Modal">
353
+ <p>This is the content of a basic sidesheet.</p>
354
+ <p>Here is more content...</p>
355
+ </Modal>
356
+ </div>
357
+ ```
358
+
359
+ ## API Reference
360
+
361
+ ### Modal
362
+
363
+ **Props**
364
+
365
+ | Property | Description | Type | Default |
366
+ | - | - | - | - |
367
+ | afterClose | Called after the dialog has fully closed. It is also called once when the dialog is unmounted while shown. | `() => void` | - |
368
+ | cancelButtonProps | Props of the cancel button. autoFocus focuses it on open; class and style land on the button; onclick runs before the built-in cancel handling, which still runs. | `ModalButtonProps` | - |
369
+ | cancelLoading | Whether the cancel button is loading. When omitted it follows the Promise returned by onCancel; pass false to turn that off. | `boolean` | - |
370
+ | cancelText | Cancel button text. Defaults to the locale entry Modal.cancel. | `string` | - |
371
+ | centered | Whether the dialog is vertically centered. | `boolean` | `false` |
372
+ | children | Body of the dialog, written inside the tag. | `Snippet` | - |
373
+ | classNames | Class names of the inner parts, keyed by mask, content, header, body and footer; values take anything class takes (string, array or object) and merge with the built-in classes. There is no header part when header is customized. | `Partial<Record<ModalPart, ClassValue>>` | - |
374
+ | closable | Whether the close button in the corner is shown. | `boolean` | `true` |
375
+ | closeIcon | Snippet for the icon inside the close button. | `Snippet` | - |
376
+ | closeOnEsc | Whether Esc cancels the dialog. | `boolean` | `true` |
377
+ | confirmLoading | Whether the ok button is loading. When omitted it follows the Promise returned by onOk; pass false to turn that off. | `boolean` | - |
378
+ | footer | Snippet that replaces the default footer buttons. An empty snippet or null renders no footer area. | `Snippet \| null` | - |
379
+ | footerFill | Whether the two buttons of the default footer fill the row. | `boolean` | - |
380
+ | fullScreen | Whether the dialog fills the screen. width and height are ignored. | `boolean` | `false` |
381
+ | getPopupContainer | Parent element the dialog is rendered into. A custom container needs position: relative; this changes where the dialog sits in the DOM, not where it is shown. | `() => HTMLElement` | - |
382
+ | hasCancel | Whether the default footer shows the cancel button. | `boolean` | `true` |
383
+ | header | Snippet that replaces the whole default header (icon, title and close button). An empty snippet or null renders no header area. | `Snippet \| null` | - |
384
+ | height | Height of the dialog. A number is in pixels; a string is any valid CSS length. | `string \| number` | - |
385
+ | icon | Snippet for the icon before the title. | `Snippet` | - |
386
+ | keepDOM | Whether the dialog content stays mounted while closed. | `boolean` | `false` |
387
+ | lazyRender | Used with keepDOM. When true, the dialog is not rendered until it is first shown. | `boolean` | `true` |
388
+ | mask | Whether the mask is shown. | `boolean` | `true` |
389
+ | maskClosable | Whether a click on the mask cancels the dialog. | `boolean` | `true` |
390
+ | maskFixed | Whether a mask confined to a custom container still covers the viewport with fixed positioning and is treated as modal (aria-modal, inert page, Tab lock, body scroll lock). | `boolean` | `false` |
391
+ | modal | Snippet for custom rendering of the dialog itself. Its argument is `{ modal }`, a snippet of the role=dialog element, placed with `{@render modal()}`. | `Snippet<[{ modal: Snippet }]>` | - |
392
+ | modalContentClass | Class name of the dialog content element. | `string` | - |
393
+ | motion | Whether the enter and leave animations run. | `boolean` | `true` |
394
+ | okButtonProps | Props of the ok button. autoFocus focuses it on open; class and style land on the button; onclick runs before the built-in ok handling, which still runs. | `ModalButtonProps` | - |
395
+ | okText | Ok button text. Defaults to the locale entry Modal.confirm. | `string` | - |
396
+ | okType | Type of the ok button. | `OKType` | `"primary"` |
397
+ | onCancel | Called by the cancel button, the close button, the mask and Esc; the argument is a native KeyboardEvent for Esc. A returned Promise keeps the cancel button loading; visible is written back once it fulfills, and a rejection keeps the dialog open. visible is still true while the callback runs. | `(event: MouseEvent \| KeyboardEvent) => unknown` | - |
398
+ | onOk | Called when the ok button is clicked. A returned Promise keeps the ok button loading until it settles. The component never closes itself on ok; the caller sets visible to false. | `(event: MouseEvent) => unknown` | - |
399
+ | preventScroll | Whether the focus calls made by the component avoid scrolling the focused element into view. Focus calls made by the caller are not affected. | `boolean` | - |
400
+ | role | role of the dialog element: dialog or alertdialog. | `'alertdialog' \| 'dialog'` | - |
401
+ | size | Width preset of the dialog: small is 448px, medium 684px, large 920px, full-width 100vw - 64px. | `Size` | `"small"` |
402
+ | styles | Inline styles of the inner parts, keyed like classNames; every value is a style string. | `Partial<Record<ModalPart, string>>` | - |
403
+ | title | Title, plain text or a snippet, which also names the dialog. It is a declared prop, so it never lands on an element as the native title attribute. | `string \| Snippet` | - |
404
+ | visible | Whether the dialog is visible, used with bind:visible. The cancel button, the close button, the mask and Esc write false once onCancel returns; ok only calls onOk and the caller sets visible to false. | `boolean` | - |
405
+ | width | Width of the dialog. A number is in pixels; a string is any valid CSS length. When omitted, size decides. | `string \| number` | - |
406
+ | zIndex | z-index of the outer layer. | `number` | `1000` |
407
+
408
+ **Methods**
409
+
410
+ | Method | Description | Type |
411
+ | - | - | - |
412
+ | getRoot | Returns the outermost element inside the portal, or null while nothing is rendered. | `() => any` |
413
+
414
+ `role` and every `aria-*` attribute land on the `role="dialog"` element, `style` lands on the `.semi-modal` dialog box, and `class` and other native attributes land on the outermost element inside the portal; an `{@attach}` written on `<Modal>` lands on the `role="dialog"` element. The Modal component does not render `content`; put the dialog content inside the tag. The `content` option is only for the static methods below.
415
+
416
+ ### Static Method
417
+
418
+ - `Modal.info`
419
+ - `Modal.success`
420
+ - `Modal.error`
421
+ - `Modal.warning`
422
+ - `Modal.confirm`
423
+
424
+ `ModalNode` is `string | Snippet`. The options are the props of the Modal component (`ModalProps`); `title`, `content`, `icon`, `closeIcon`, `header` and `footer` take a `ModalNode`. Unlike the component, a Promise returned by `onOk` or `onCancel` closes the modal after it fulfills, and a rejection keeps it open; any other return value closes it at once.
425
+
426
+ `aria-*` options land on the dialog. Creating modal with the above methods will return a reference to the instance. You could use it to update or close the modal. `update` takes the same options as the methods above (`ModalProps`) and merges them into the current config; it does not take `type`.
427
+
428
+ ```ts
429
+ const modal = Modal.info({ title: 'Title' });
430
+
431
+ modal.update({
432
+ title: 'Updated Title',
433
+ content: 'Updated Content',
434
+ });
435
+
436
+ modal.destroy();
437
+ ```
438
+
439
+ - `Modal.destroyAll`
440
+
441
+ You could use Modal.destroyAll() to destroy Modal that created by methods above e.g. `.info()`
442
+
443
+ - `Modal.useModal`\
444
+ When you need to read context, call `const modal = Modal.useModal()` during component initialization. Modals created through `modal` can access everything at the position of the calling component (context, ConfigProvider, locale), and are removed when that component is destroyed. It has no Holder. The `modal` object shares the same methods with Modal.method.
445
+
446
+ ## Accessibility
447
+
448
+ ### ARIA
449
+
450
+ WAI-ARIA: <https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/>
451
+
452
+ - The Modal component has role `dialog`, following the [APG Dialog (Modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) pattern
453
+ - Confirm dialogs (`Modal.confirm`, `info`, `success`, `warning`, `error`, and the same-named `useModal` methods) have role `alertdialog`, and `aria-describedby` points to the message, following the [APG Alert Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/) pattern
454
+ - aria-modal is set to true when the dialog is modal. A dialog is modal when it has a mask (`mask`) and is mounted in the body (judged by the actual container, so the `getPopupContainer` of ConfigProvider counts) or has `maskFixed`. With `mask={false}`, or a mask confined to a custom container, the page behind stays usable and aria-modal is omitted
455
+ - aria-labelledby corresponds to the dialog title; it is not generated when `aria-label` or a custom header is given
456
+ - The Modal component does not set aria-describedby by default: when the body holds a form, a list or several paragraphs, reading it out whole gets in the way. Pass it yourself when needed
457
+ - `role` and every `aria-*` attribute passed by the caller land on the element that carries the role
458
+ - The close button's aria-label comes from the current locale ('Close' in English, '关闭' in Simplified Chinese)
459
+
460
+ ### Keyboard and focus
461
+
462
+ - Modal automatically gets the focus when it is popped up. An element with `autoFocus` (`autofocus` in Vue and Svelte) inside the dialog gets the focus first; otherwise the cancel button does by default, which can be controlled by passing autoFocus in cancelButtonProps or okButtonProps. With `keepDOM`, opening it again gives the same result; with `keepDOM` and `lazyRender={false}` that starts hidden, an `autoFocus` element cannot take focus under `display: none`, so later openings land on the default button.
463
+ - When a modal dialog is closed, the focus automatically returns to the element before it was opened. Keyboard users can use the `Tab` key and `Shift + Tab` to move the focus in a loop within the Modal, including the Modal's own close button and OK cancel button. At this time, the page behind the Modal cannot be interacted with or tab-focused.
464
+ - A non-modal dialog (`mask={false}`, or a mask confined to a custom container without `maskFixed`) also takes focus when opened, but does not lock Tab and the rest of the page stays usable. When closed, focus is returned only if it is still inside the dialog or has fallen to the body; focus the user has moved elsewhere on the page stays. A Modal in the body with `mask={false}` does not lock body scrolling.
465
+ - Modify the default value of closeOnEsc to true, allowing users to directly close Modal through the keyboard for a better experience
466
+
467
+ ## Content Guidelines
468
+
469
+ - Imperative Modal and Default Modal The title of the two modal dialogs uses the format of verb + noun, whether it is a declarative sentence or a question sentence
470
+
471
+ | ✅ Recommended usage | ❌ Deprecated usage |
472
+ | - | - |
473
+ | Edit ticket | Edit |
474
+ | Delete form? | Are you sure you want to delete form? |
475
+
476
+ - The operation buttons of the two modal dialog boxes only need to use the verbs in the title under the premise of ensuring that the title description is clear
477
+
478
+ | ✅ Recommended usage | ❌ Deprecated usage |
479
+ | - | - |
480
+ | Edit | Edit ticket |
481
+
482
+ - Text specification for imperative Modal
483
+ - Give a specific explanation to the title, do not repeat the information of the title
484
+ - Make sure users know how to act if necessary
485
+
486
+ ## Design Tokens
487
+
488
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/modal/>
489
+
490
+ ## FAQ
491
+
492
+ - ### Why the button texts in Modal.confirm are not internationalized even when I use LocaleProvider?
493
+
494
+ A static Modal is rendered outside the component tree and reads only the global defaults and the default locale, so it cannot read the config from ConfigProvider or LocaleProvider. You could call `Modal.useModal()` in a component under that provider, or use `okText` and `cancelText` to set the texts yourself.
495
+
496
+ - ### Why is the spacing between title and content different under imperative and non-imperative calls?
497
+ In the imperative call scenario, the title and content are more closely related, so expressing this strong correlation with a closer distance is in line with expectations. If users don't want this effect, they can do their own style overrides.
498
+
499
+ ## Changes from Semi Design
500
+
501
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
502
+
503
+ - 破坏性:Modal 删除 `bodyStyle`、`maskStyle`,SideSheet 删除 `bodyStyle`、`headerStyle`、`maskStyle`,改用 `classNames`、`styles`,部位为 `mask`、`content`(`role="dialog"` 元素)、`header`、`body`、`footer`;Modal 的 `header` 部位只在默认标题头时存在。`Modal.info` 等静态方法与 `useModal` 的选项同样使用 `classNames`、`styles`。
504
+ - 破坏性:`Modal.info`、`success`、`error`、`warning`、`confirm`、`useModal`、`destroyAll` 改由 `modal/index` 挂载,深导入 `modal/modal` 的组件不再带这些静态方法;`cancelButtonProps.onClick`、`okButtonProps.onClick` 不再替换内置处理,先于 `onCancel`、`onOk` 调用,需替换的改在这两个回调里处理。
505
+ - 行为变化:SideSheet 关闭时与 Modal 一致,等离场动画结束(无动画时立即)才解除页面 inert、Tab 陷阱与 body 滚动锁,并把焦点还给打开前的元素(四个框架一致)。
506
+ - 行为变化:SideSheet 的 `afterVisibleChange(true)` 改在进场动画结束后调用,无动画时显示后立即调用;进场中被关闭时先补报 `true` 再报 `false`。
507
+ - 破坏性(类型):`onCancel` 参数为 `React.MouseEvent | KeyboardEvent`(Esc 传原生事件);Modal 的 `direction` 收窄为 `'ltr' | 'rtl'`,删除深路径导出的 `ConfirmType`、`Directions`;`Modal.useModal` 返回 `[ModalHookApi, ReactElement]`;`SideSheetState` 删除 `displayNone`;深路径 `side-sheet/index` 导出的 `SideSheetContentProps` 以 `sheetSize` 代替 `width`、`height`。
508
+ - 行为变化:Modal 的 `footer={undefined}`、`header={undefined}` 与不传相同,隐藏传 `null`;SideSheet 隐藏关闭按钮用 `closable={false}`;Modal 新增 `role?: 'dialog' | 'alertdialog'`(确认框默认 `alertdialog`),组件版不再默认设 `aria-describedby`;模态判断统一为 Modal `mask && (容器在 body 内 || maskFixed)`、SideSheet `mask && 容器在 body 内`,`mask={false}` 时不再锁 body 滚动、不拦截页面点击,非模态不再把 Tab 锁在层内。
509
+ - Svelte:SideSheet 的 `visible` 可绑定,没有 `defaultVisible`;关闭按钮、遮罩、Esc 先把 `visible` 写回 false,再调 `onCancel`(收到原生 `MouseEvent | KeyboardEvent`),函数绑定的 setter 可以拒绝关闭;`afterVisibleChange` 是回调 prop。
510
+ - Svelte:SideSheet 的 `title`(字符串或 snippet)、`footer`、`closeIcon`、`children` 是 snippet;`style` 与 `styles` 的值只接受字符串;`aria-*` 与 `style` 落在 `role="dialog"` 元素,`class` 和其余属性落在外层 `.semi-sidesheet`;抽屉挂载后才渲染,服务端不输出;`visible` 不读全局默认值;`bind:this` 的实例提供 `getRoot()`。
511
+ - Svelte:`Modal` 与 `Modal.info/success/error/warning/confirm`、`Modal.destroyAll`、`Modal.useModal` 随包提供;`useModal()` 返回 `{ info, success, error, warning, confirm }`,不返回 Holder,也没有 `install()`,确认框读调用组件所在处的 ConfigProvider 与 LocaleProvider;命令式确认框只能在浏览器调用,服务端调用抛出指明 API 名的错误。
512
+ - Svelte:`visible` 用 `bind:visible`;`onCancel` 返回 Promise 时,兑现后才写回 `false`,拒绝则保持打开,原因由 foundation 重新抛出;`title`、`header`、`footer`、`icon`、`closeIcon`、`modal` 是 snippet,`title`、`content`、`closeIcon` 也接受字符串;尺寸类型导出名为 `ModalSize`;动画由 class 驱动,`keepDOM` 重开保留节点和内部状态。
513
+ - 容器是全屏元素(`document.fullscreenElement`)时按覆盖整页处理:Modal、SideSheet、ImagePreview 为模态并锁 body 滚动。
514
+ - 同一元素有多个退出动画时,等全部结束才卸载(React、Solid、Svelte)。React:页面取消动画(`animation: none`)时离场立即结束并卸载,原来一直不卸载。
515
+ - 行为变化:Modal 的 `afterClose`、SideSheet 的 `afterVisibleChange` 每次显示只报一次:离场动画期间重新打开算同一次显示,卸载时仍欠着的 `afterClose` 补报。`Modal.destroyAll()` 只关闭本框架包创建的确认框,不同框架的包同页时互不关闭。确认框挂载前调用 `destroy()` 时不再渲染,`afterClose` 在 `destroy()` 内同步调用。
516
+ - 行为变化:React 的 Modal、SideSheet 被 `<Activity mode="hidden">` 隐藏时不报 `afterClose`、`afterVisibleChange(false)`,只有真正卸载才报;隐藏期间释放 body 滚动锁与遮罩栈,重新显示后再取回。SideSheet 每次显示时判定一次是否模态,显示期间改 `mask` 或容器要到下次显示才生效。React ModalContent 的初始焦点按 `autofocus` 处理,与其余三个框架一致。
517
+ - Vue、Svelte:显式传 `aria-labelledby={undefined}`、`aria-modal={undefined}` 时按未传处理,对话框仍由标题命名并保留默认的 `aria-modal`,与 React、Solid 一致(原来会去掉标题引用,对话框没有可访问名称)。