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
ariaLabelstring""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.
classNamestring""
descriptionstring""Rendered under the title and wired to `aria-describedby` — the supporting line a `role="alertdialog"` is required to point at.
innerClassNamestring""
isCloseRequestDismissablebooleantrueWhether 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`.
isDismissablebooleantrue (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.
isShowCloseButtonbooleantrue
isSwipeDismissablebooleantrueWhether 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.
placementKunModalPlacement"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'.
roundedKunUIRounded
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.
sizeKunModalSize"md"Max width of the panel (full = nearly the whole viewport). Default 'md'.
titlestring""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`.
withContainerbooleantrue

事件

事件回调参数
close
update:modelValuevalue: boolean

插槽

插槽作用域
#default