Modal (对话框)
传送到 body 的对话框,焦点锁定、滚动锁定,可按 Esc 关闭。
基础用法
Basic.vue
尺寸
Sizes.vue
位置
Placement.vue
滚动行为
ScrollBehavior.vue
不可关闭与隐藏关闭按钮
NonDismissable.vue
警告对话框
AlertDialog.vue
手机端下滑关闭
把 sheet 往下拖就能关掉
placement="auto" 在 md 以下是底部 sheet,触屏上可以按住往下拖关闭 —— 拖过面板高度的 25%,或者快速一甩(0.4 px/ms)即可,不够则回弹。面板顶部那条小横杠就是这个手势的提示。内容滚动优先:只要 sheet 里的内容还没滚回顶部,下滑就是滚动而不是关闭,所以长内容不会被误关。桌面端、鼠标和 placement="center"/"top" 都不受影响;role="alertdialog" 和 isDismissable=false 同样拖不动。用 isSwipeDismissable=false 可以单独关掉。
Android 返回键
返回键关闭对话框,而不是退回上一页
在 Android 上打开对话框时,按返回键或使用返回手势会关掉最上层的对话框,页面留在原地 —— 与原生 dialog 元素的行为一致。桌面端不受影响(桌面唯一的关闭请求是 Esc,由组件自己处理)。iOS 没有返回键,不适用。isDismissable=false 时不生效;路由绑定的对话框可用 isCloseRequestDismissable=false 关掉这个行为。KunUI 不会向 history 里写任何东西,不会干扰你的路由。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue * | boolean | — | |
| ariaLabel | string | "" | Accessible name for a dialog that draws its own heading inside the slot instead of passing `title`. Ignored when `title` is set (that wins, via `aria-labelledby`). With neither, KunUI warns in dev. |
| className | string | "" | |
| description | string | "" | Rendered under the title and wired to `aria-describedby` — the supporting line a `role="alertdialog"` is required to point at. |
| innerClassName | string | "" | |
| isCloseRequestDismissable | boolean | true | Whether a platform close request dismisses the dialog — in practice Android's back button and back gesture, which close the dialog instead of leaving the page (the behaviour a native `<dialog>` already has). Desktop is unaffected: its only close request is Escape, handled separately. Turn this off for a dialog that is bound to a route and should let back navigate. Ignored when `isDismissable` is `false`. |
| isDismissable | boolean | true (backdrop excluded when role="alertdialog") | Whether a backdrop click or Escape closes the dialog. `role="alertdialog"` stops the BACKDROP from dismissing (a click that lands on the dim area is not an answer) while Escape still cancels, matching Radix and Reka. Pass `true` to opt the backdrop back in, `false` to turn both off. |
| isShowCloseButton | boolean | true | |
| isSwipeDismissable | boolean | true | Whether dragging the phone sheet downwards dismisses it, and whether the drag handle that advertises the gesture is drawn. Only applies where the sheet exists — `placement="auto"` below `md`, on a touch-primary pointer — and only while the content is scrolled to the top, so a swipe over scrollable content still scrolls it. Follows `isDismissable`, so a `role="alertdialog"` cannot be swiped away any more than it can be clicked away. |
| placement | KunModalPlacement | "auto" | Vertical alignment of the panel. Default 'auto' — a bottom sheet on phones, a centred dialog from `md` up. Pass 'center' for the pre-2.19 behaviour of centring at every width. |
| role | "dialog" | "alertdialog" | "dialog" | ARIA role of the panel. Use 'alertdialog' for confirm/destructive prompts that need an immediate response — it also flips the isDismissable default. Default 'dialog'. |
| rounded | KunUIRounded | — | |
| scrollBehavior | "inside" | "outside" | "inside" | inside (default): the panel body scrolls, capped at 90dvh — 85dvh for an `auto` sheet below `md`, which needs a wider tap-to-dismiss strip above it — and never taller than the visible viewport, so the on-screen keyboard can't bury it. outside: the whole overlay scrolls — for panels taller than the viewport. |
| size | KunModalSize | "md" | Max width of the panel (full = nearly the whole viewport). Default 'md'. |
| title | string | "" | Rendered as the panel's `<h2>` and wired to `aria-labelledby`, so the name a screen reader announces is the one on screen. Prefer it over `ariaLabel`. |
| withContainer | boolean | true |
事件
| 事件 | 回调参数 |
|---|---|
| close | — |
| update:modelValue | value: boolean |
插槽
| 插槽 | 作用域 |
|---|---|
| #default | — |