Home Assistant 前端对话框（Dialog）设计规范与 ha-dialog 组件实战指南

前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载导读本文以 Home Assistant 前端仓库中官方组件画廊的 ha-dialogs.markdown 设计规范文档为骨架系统讲解前端对话框Dialog的交互设计准则、内容组织要点并结合仓库源码深入剖析ha-dialog组件的宽度体系、头部/页脚插槽、事件机制以及ha-adaptive-dialog、dialog-box等衍生实现。读完本文你将掌握 Home Assistant 前端的对话框设计语言并能在实际开发中正确选用、配置和二次封装对话框组件。一、设计基石基于 Material Design 3 的取舍Home Assistant 的对话框构建在最新版Material Design 3之上但其设计团队对官方规范做了一些深思熟虑的调整形成了自己的交互约定。官方规格与指南可在 Material Design 3 的 Dialogs 组件文档 及其配套的 ha-dialog-header 与 ha-dialog-footer。与原版 Material 规范相比最显著的差异包括关闭图标固定放在左上角、确认类对话框不含 X 图标、受保护的对话框不允许 ESC 或点击遮罩关闭等。这些规则全部落到了组件代码中下文会逐一对照说明。二、设计规范Guidelines2.1 宽度与尺寸普通对话框的最大宽度为560px告警Alert与确认Confirmation对话框使用固定 320px宽度。如果内容确实需要更宽应优先考虑改用专用页面dedicated page而不是一味拉伸对话框。在组件实现层面ha-dialog 的样式定义 提供了四档宽度预设由width属性控制small | medium | large | fullsmallmin(var(--ha-dialog-width-sm, 320px), var(--full-width))medium默认min(var(--ha-dialog-width-md, 580px), var(--full-width))largemin(var(--ha-dialog-width-lg, 1024px), var(--full-width))fullvar(--full-width)其中--full-width依据屏幕可用宽度计算大屏幕上对话框最大为95vw小屏幕上则为100vw减去安全区safe area内边距。这一计算逻辑在 gallery 的演示页说明 中有明确描述并与样式中的--full-width定义相互印证。提示设计规范中的 560px 上限与实现默认的580px之间存在细微出入前者是设计团队的视觉约束后者是可被主题覆盖的 CSS 变量默认值。如果你需要严格的 560px 上限可通过--ha-dialog-width-md变量覆盖。2.2 头部布局关闭用的X 图标位于左上角且在所有屏幕尺寸上都保持一致位置但告警与确认对话框例外——它们只有操作按钮没有 X 图标这一点与 Material 官方指南不同。额外的图标按钮如帮助、设置、展开对话框放在右上角当图标按钮超过 2 个时多余项应收进 overflow 菜单溢出菜单。组件实现中默认头部由ha-dialog-header渲染左侧navigationIcon插槽承载关闭按钮mdiClose图标中间为标题与副标题右侧actionItems插槽放置额外操作按钮相关结构见 ha-dialog 的 render 实现 与 ha-dialog-header 组件。ha-dialog-header还支持subtitle-positionabove/below控制副标题相对标题的位置。2.3 关闭行为与表单保护当对话框内含用户已修改过的表单时不允许通过 ESC 键或点击对话框外部来关闭此时用户强行关闭对话框会以轻微抖动shake动画给出不行的反馈。在源码层面这一保护由prevent-scrim-close属性承担ha-dialog 的_handleKeyDown会在preventScrimClose开启时阻止 ESC 默认行为而_handleHide会拦截来自遮罩scrim或原生 cancel 的隐藏事件防止用户在表单有改动时误关ha-dialog.ts。通用对话框dialog-box同样遵循此规则当参数为确认/提示类型或表单处于 dirty 状态时会动态设置prevent-scrim-close见 dialog-box.ts。2.4 底部操作区提交按钮与取消按钮分组位于右下角在所有屏幕尺寸上保持一致全屏移动端对话框的操作区则固定吸附在底部sticky。带操作的对话框必须提供放弃discard按钮桌面端为Cancel按钮 X 图标移动端仅保留 X 图标。破坏性destructive操作必须使用红色警告按钮。尽量避免在单个对话框中同时出现三个按钮尤其是当任务尚未完成时就离开对话框的场景。组件侧对应的是ha-dialog-footer它提供secondaryAction次级操作建议使用appearanceplain的按钮与primaryAction主操作默认外观两个插槽并默认右对齐见 ha-dialog-footer.ts。破坏性操作在dialog-box中通过variantdanger呈现dialog-box.ts。2.5 文字标签按钮与标签保持简短例如Save、Delete、Enable避免冗长文案。三、内容规范Content3.1 标题即便 Material 规范中标题是可选的Home Assistant 仍强烈建议总是使用标题。用户阅读时主要关注标题和按钮因此最重要的信息应放在这两处。应避免在标题中放置用户生成内容如用户自定义名称否则标题可能被撑到无法阅读若确需引用用户内容建议截断或缩写并配合描述区说明细节。3.2 描述区当用户产生疑惑时他们会去读描述。描述应清楚说明接下来会发生什么what will happen而不是含糊其辞。整体追求极简主义minimalism只保留完成任务所需的最小信息量。四、确认对话框示例Example设计文档给出了一条完整的确认对话框文案范式可直接套用Delete dashboard?Dashboard [dashboard name] will be permanently deleted from Home Assistant.Cancel / Delete对照规范可以拆解出这条文案的三个要点标题用一句疑问句点明动作Delete dashboard?描述区明确后果will be permanently deleted…操作区只有Cancel与Delete两个按钮且Delete是破坏性操作应渲染为红色警告按钮。在仓库中这类确认框的工程化封装是showConfirmationDialog见 show-dialog-box.ts调用方式类似showConfirmationDialog(element, { title: Delete dashboard?, text: Dashboard [name] will be permanently deleted from Home Assistant., confirmText: Delete, destructive: true, confirm: () { /* 执行删除 */ }, });该函数会将参数包装为dialog-box并通过show-dialog事件触发返回Promiseboolean对话框内部按确认类型自动切换为typealert并设置prevent-scrim-closedialog-box.ts。五、组件级实现ha-dialog 详解5.1 属性Attributesha-dialog的完整属性清单可在其 源码 JSDoc 与 gallery 演示页 API 表格 中找到核心属性如下属性说明默认值可选值open控制对话框打开状态falsefalse/truetype对话框类型standardalert/standardwidth宽度预设mediumsmall/medium/large/fullprevent-scrim-close禁止点击遮罩关闭falsetrueheader-title头部标题文本未提供自定义标题插槽时生效——header-subtitle头部副标题文本——header-subtitle-position副标题相对标题的位置belowabove/belowflexcontent将正文区域变为 flex 容器便于灵活布局falsefalse/true5.2 插槽Slotsha-dialog提供以下插槽用于自定义各区域ha-dialog.ts 文档注释插槽用途header替换整个头部区域headerNavigationIcon头部左侧操作如关闭/返回按钮headerTitle自定义标题内容当未设置header-title时使用headerSubtitle自定义副标题内容headerActionItems头部右侧操作按钮、菜单等默认插槽对话框正文内容footer对话框页脚内容5.3 事件Events事件触发时机opened对话框显示时closed对话框隐藏后closed事件被 DialogMixin 等消费方用于清理对话框实例并广播dialog-closed进而驱动对话框管理器收尾。5.4 可定制化 CSS 变量ha-dialog暴露了大量 CSS 自定义属性供主题定制见 ha-dialog.ts 样式--dialog-content-padding正文内边距--ha-dialog-show-duration/--ha-dialog-hide-duration显示/隐藏动画时长默认 200ms--ha-dialog-surface-background对话框背景色--ha-dialog-surface-backdrop-filter对话框表面 backdrop-filter--dialog-box-shadow对话框阴影--ha-dialog-border-radius对话框圆角--ha-dialog-scrim-backdrop-filter/--dialog-backdrop-filter遮罩 backdrop-filter后者为兼容旧版--mdc-dialog-scrim-color遮罩颜色兼容旧版 mdc--dialog-surface-margin-top对话框顶部外边距5.5 使用示例来自 gallery 演示页 的完整示例涵盖头部操作、标题/副标题、页脚按钮的完整组合ha-dialog open header-titleDialog title header-subtitleDialog subtitle prevent-scrim-close div slotheaderActionItems ha-icon-button labelSettings pathmdiCog/ha-icon-button ha-icon-button labelHelp pathmdiHelp/ha-icon-button /div divDialog content/div ha-dialog-footer slotfooter ha-button>赞分享前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载相关推荐React Native Elements 对话框组件(Dialog)完全指南React Native Elements 对话框组件 Dialog 完全指南 什么是对话框组件 对话框 Dialog 是移动应用开发中常见的UI组件用于向用UI组件移动开发前端Element UI 对话框组件 Dialog 使用详解Element UI 对话框组件 Dialog 使用详解 什么是 Dialog 组件 Dialog 对话框组件是 Element UI 提供的一个模态窗口组件前端UI组件设计系统Phoenix 前端 Alert Dialog 设计规范中断式提示框的文案、变体与按钮样式实战指南Phoenix 前端 Alert Dialog 设计规范中断式提示框的文案、变体与按钮样式实战指南 本文是 PhoenixAI Observability可观测性AI 评测LLMOpsAI 应用人工智能上一篇wagmi Vue 中的 createStorage 详解为以太坊 DApp 构建可持久化的 Storage 存储层下一篇n8n 子工作流即 Agent 工具用 toolWorkflow 节点构建可复用、可测试的 Agent 能力创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考