shadcn-svelte Alert Dialog 组件完全指南构建可访问的强制响应确认弹窗【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelteAlert Dialog警告对话框是 shadcn-svelte 组件库中用于打断用户当前操作、展示重要信息并要求其明确响应的模态弹窗。本文以 组件文档 为主体结合仓库内docs/src/lib/registry/ui/alert-dialog目录下的完整源码与官方示例系统讲解 Alert Dialog 的安装方式、基础用法、受控状态管理、尺寸定制、危险操作确认、媒体展示以及无障碍特性读完即可在 Svelte 5 项目中直接落地使用。组件定位它解决什么问题根据文档定义Alert Dialog 是A modal dialog that interrupts the user with important content and expects a response——一个打断用户并期待回应的模态对话框。它与普通 Dialog 的核心区别在于使用场景Dialog对话框适用于信息收集、表单填写等一般性交互Alert Dialog警告对话框专门用于需要用户明确确认或取消的高代价操作例如删除账号、清除数据、提交不可逆操作等。在 shadcn-svelte 中Alert Dialog 基于 bits-ui 的AlertDialog原语组件二次封装继承其完整的模态行为与无障碍语义焦点陷阱、Esc 关闭、背景遮罩、ARIA 角色alertdialog等并通过 shadcn 风格的设计令牌与 CSS 变量统一主题外观。安装CLI 一键安装与手动安装文档提供了两种安装方式任选其一即可。方式一CLI 安装推荐使用 shadcn-svelte CLI 的add命令直接添加npx shadcn-sveltelatest add alert-dialogCLI 会自动完成以下工作解析alert-dialog的 registry 定义仓库中对应 docs/static/registry/alert-dialog.json、将组件源码写入项目的src/lib/components/ui/alert-dialog或你在components.json中配置的路径、并处理相关依赖与样式。方式二手动安装手动安装分两步第一步安装底层原语依赖bits-uinpm install bits-ui -D第二步复制组件源码将 docs/src/lib/registry/ui/alert-dialog 目录下的全部.svelte文件与index.ts复制到项目的src/lib/components/ui/alert-dialog/目录中并确保项目内已存在 button 组件因为Action与Cancel复用了buttonVariants。基础用法一个完整的确认弹窗安装完成后在 Svelte 文件中引入组件命名空间script langts import * as AlertDialog from $lib/components/ui/alert-dialog/index.js; /script然后即可组合使用各子组件AlertDialog.Root AlertDialog.TriggerOpen/AlertDialog.Trigger AlertDialog.Content AlertDialog.Header AlertDialog.TitleAre you absolutely sure?/AlertDialog.Title AlertDialog.Description This action cannot be undone. This will permanently delete your account and remove your data from our servers. /AlertDialog.Description /AlertDialog.Header AlertDialog.Footer AlertDialog.CancelCancel/AlertDialog.Cancel AlertDialog.ActionContinue/AlertDialog.Action /AlertDialog.Footer /AlertDialog.Content /AlertDialog.Root文档页面的实时示例对应仓库中的 alert-dialog-demo.svelte会在此基础上为Trigger附加buttonVariants({ variant: outline })样式形成带按钮外观的触发入口script langts import * as AlertDialog from $lib/registry/ui/alert-dialog/index.js; import { buttonVariants } from $lib/registry/ui/button/index.js; /script AlertDialog.Root AlertDialog.Trigger class{buttonVariants({ variant: outline })} Show Dialog /AlertDialog.Trigger !-- 其余结构同上 -- /AlertDialog.Root组件结构解剖12 个子组件的职责与源码实现从 index.ts 可以看出Alert Dialog 由 12 个可独立导出的子组件组成既支持短名称Root、Content…也支持带前缀的全称别名AlertDialog、AlertDialogContent…两种写法等价。子组件对应源码文件核心职责Rootalert-dialog.svelte状态容器暴露open双向绑定与全部 RootPropsTriggeralert-dialog-trigger.svelte触发按钮点击打开弹窗Portalalert-dialog-portal.svelte将内容传送到document.body避免被父级overflow/transform裁剪Overlayalert-dialog-overlay.svelte全屏遮罩fixed inset-0 z-50点击可关闭Contentalert-dialog-content.svelte弹窗主体容器居中定位封装 Portal OverlayHeaderalert-dialog-header.svelte头部容器承载 Title 与 DescriptionFooteralert-dialog-footer.svelte底部操作区默认右对齐sm尺寸下变为两列网格Titlealert-dialog-title.svelte标题声明式语义标题Descriptionalert-dialog-description.svelte描述文本辅助说明操作后果Actionalert-dialog-action.svelte确认按钮默认variantdefault关闭弹窗并触发回调Cancelalert-dialog-cancel.svelte取消按钮默认variantoutline仅关闭弹窗Mediaalert-dialog-media.svelte媒体区域用于在弹窗内展示图片/插画配合小尺寸弹窗Root受控与非受控状态alert-dialog.svelte 是整个组件的状态中枢源码只有寥寥数行script langts import { AlertDialog as AlertDialogPrimitive } from bits-ui; let { open $bindable(false), ...restProps }: AlertDialogPrimitive.RootProps $props(); /script AlertDialogPrimitive.Root bind:open {...restProps} /关键点在于open $bindable(false)默认关闭非受控但通过bind:open即可升级为受控模式与父组件状态同步。典型受控用法script langts import * as AlertDialog from $lib/components/ui/alert-dialog/index.js; let open $state(false); /script AlertDialog.Root bind:open !-- ... -- /AlertDialog.RootContent尺寸与 Portal 定制alert-dialog-content.svelte 除固定居中定位样式fixed top-1/2 left-1/2 z-50 grid w-full -translate-x-1/2 -translate-y-1/2外额外暴露两个自定义 propsize?: default | sm控制弹窗尺寸。小尺寸模式会通过data-size属性联动Footer的栅格布局group-data-[sizesm]/alert-dialog-content:grid-cols-2适合紧凑型确认框portalProps透传给内部Portal的 props例如自定义传送目标to节点。内部结构上Content始终先渲染Overlay再渲染内容本体保证遮罩层级正确AlertDialogPortal {...portalProps} AlertDialogOverlay / AlertDialogPrimitive.Content ... / /AlertDialogPortalAction 与 Cancel危险操作确认的完整闭环Action与Cancel是确认弹窗的两只手两者都基于 buttonVariants 渲染成标准按钮Actionalert-dialog-action.svelte默认variantdefault、sizedefault接受ButtonVariant/ButtonSize覆盖。点击后关闭弹窗并通过 bits-ui 的onAction回调执行确认逻辑Cancelalert-dialog-cancel.svelte默认variantoutline点击仅关闭弹窗不触发动作。典型场景删除确认处理破坏性操作时通常将Action样式改为危险变体并在onAction中执行删除逻辑AlertDialog.Root AlertDialog.Trigger class{buttonVariants({ variant: destructive })} Delete Account /AlertDialog.Trigger AlertDialog.Content AlertDialog.Header AlertDialog.TitleAre you absolutely sure?/AlertDialog.Title AlertDialog.Description This action cannot be undone. Your account and all associated data will be permanently removed. /AlertDialog.Description /AlertDialog.Header AlertDialog.Footer AlertDialog.CancelCancel/AlertDialog.Cancel AlertDialog.Action variantdestructive onAction{() deleteAccount()} Delete /AlertDialog.Action /AlertDialog.Footer /AlertDialog.Content /AlertDialog.Root更多实战形态仓库内置的示例变体仓库在 docs/src/lib/registry/examples/create/alert-dialog 目录下准备了多套可直接参考的示例变体alert-dialog-basic.svelte最基础的结构模板alert-dialog-destructive.svelte危险操作确认的完整写法alert-dialog-in-dialog.svelte嵌套场景——在 Dialog 内部再打开 Alert Dialogalert-dialog-small.svelte/alert-dialog-with-media.svelte紧凑尺寸、带媒体内容的弹窗alert-dialog-small-with-media.svelte小尺寸 媒体的组合形态配合Media子组件与sizesm使用。例如带插图的确认弹窗可以这样组织AlertDialog.Root AlertDialog.Trigger class{buttonVariants({ variant: outline })} Open with Media /AlertDialog.Trigger AlertDialog.Content sizesm AlertDialog.Media img src/illustration.png alt确认操作示意 classmx-auto / /AlertDialog.Media AlertDialog.Header AlertDialog.Title确认操作/AlertDialog.Title AlertDialog.Description操作后果说明/AlertDialog.Description /AlertDialog.Header AlertDialog.Footer AlertDialog.Cancel取消/AlertDialog.Cancel AlertDialog.Action确认/AlertDialog.Action /AlertDialog.Footer /AlertDialog.Content /AlertDialog.Root无障碍与交互行为说明由于封装自 bits-ui 的AlertDialog原语组件自动继承以下关键无障碍与交互特性无需手动实现模态语义弹出时对背景内容设置aria-hidden与inert语义阻止背景交互焦点管理打开时自动聚焦弹窗内部默认聚焦Cancel/取消按钮关闭时焦点还原到Trigger键盘支持Esc键关闭弹窗Tab焦点在弹窗内循环不逃逸到背景ARIA 角色Content声明rolealertdialogTitle/Description通过aria-labelledby/aria-describedby建立关联屏幕阅读器可正确播报标题与描述关闭策略默认支持 Esc、点击遮罩关闭且弹窗打开期间背景滚动被锁定取决于 bits-ui 的preventScroll配置可通过 Root 透传。若需禁用遮罩点击关闭或改变其他行为可直接在Root上透传 bits-ui 的RootPropsAlertDialog.Root closeOnInteractOutside{false} !-- ... -- /AlertDialog.Root主题与样式定制每个子组件都带有可识别的data-slot属性如alert-dialog-content、alert-dialog-overlay、alert-dialog-action以及cn-前缀的样式钩子类如cn-alert-dialog-content配合 shadcn-svelte 的 CSS 变量体系可以在全局 CSS 中统一调整遮罩透明度、弹窗圆角、标题字体等外观而无需改动组件源码。常规尺寸定制则优先使用Content的sizeprop 与Footer的响应式栅格完成。小结Alert Dialog 是 shadcn-svelte 中面向高风险操作确认场景的专用模态组件通过Root受控/非受控、Trigger、Content含size与portalProps、Header/Footer、Title/Description、Action/Cancel以及可选的Media十二个子组件组合出从基础确认到带插图小尺寸弹窗的完整形态。其底层由 bits-ui 提供模态、焦点陷阱与无障碍语义外观则由 shadcn-svelte 的按钮变体与主题令牌统一开箱即用、可深度定制。结合 组件文档、组件源码 与 官方示例即可在项目中快速构建专业、可访问的确认交互。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考