前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载本文以 Home Assistant 前端组件库中 Gallery 页面「Expansion Panel」gallery/src/pages/components/ha-expansion-panel.markdown为核心深入剖析ha-expansion-panel折叠面板组件的属性、插槽、事件、ARIA 无障碍实现与展开动画机制并结合组件在过滤器面板、自动化编辑器、安全设置对话框等真实场景的用法帮助开发者掌握如何在自定义卡片或面板中正确、可访问地复用它。组件定位一张「完全遵循 ARIA 规范」的折叠面板Gallery 中对该组件的官方定位只有一句话——Expansion panel following all the ARIA guidelines。这句话点明了该组件最核心的设计约束它不是普通的div click折叠块而是一个在语义、键盘交互、焦点管理和 ARIA 状态同步上都符合无障碍规范的可折叠区域。这一点在组件源码 src/components/ha-expansion-panel.ts 中得到了完整印证折叠触发器使用rolebutton并配合aria-expanded、aria-controls内容区使用roleregion、aria-hidden和aria-labelledby建立与触发器的关联同时支持Tab聚焦与Enter/Space键展开收起。Home Assistant 的界面大量依赖该组件承载可折叠的设置分组自动化编辑器的动作/条件/触发行、各类过滤器面板、安全设置分组等因此它的无障碍质量直接影响整站键盘用户的操作体验。快速上手最小可用示例与组件同名的最小组件用例如下属性写法header/secondary与插槽写法可混用插槽优先ha-expansion-panel header属性标题 secondary属性副标题 这里是折叠后才会渲染的内容…… /ha-expansion-panel对应到 Gallery 演示 gallery/src/pages/components/ha-expansion-panel.ts 中的第一个样例即为仅带header属性的形式第二个样例在此基础上增加了secondary属性展示副标题。默认状态下面板处于收起状态expanded初始为false点击标题行后以 300ms 动画展开。属性Property/Attribute全解组件通过property声明了六个对外配置项其中布尔型属性均带有reflect: true会同步反映为 DOM 属性便于外部选择器与状态观察属性对应 attribute类型/默认值作用expandedexpandedBoolean /false是否展开收起状态下内容区高度为 0outlinedoutlinedBoolean /false使用--outline-color描边并去除阴影形成卡片式边框leftChevronleft-chevronBoolean /false将展开箭头放在标题左侧右侧是默认位置noCollapseno-collapseBoolean /false禁止折叠不渲染箭头、tabindex-1、点击无效headerheaderstring标题文本仅在没有header插槽内容时显示secondarysecondarystring副标题文本仅在没有secondary插槽内容时显示各属性的底层实现见 src/components/ha-expansion-panel.tsproperty({ type: Boolean, reflect: true }) expanded false; property({ type: Boolean, reflect: true }) outlined false; property({ attribute: left-chevron, type: Boolean, reflect: true }) public leftChevron false; property({ attribute: no-collapse, type: Boolean, reflect: true }) public noCollapse false; property() header?: string; property() secondary?: string;关键行为细节no-collapse用于「必须始终可见」的分组。例如 dialog-edit-security.ts 中常用实体与告警实体两个编辑分组就同时使用了outlined、expanded、no-collapse内容始终平铺展示blueprint-generic-editor.ts 则在表单必填项不足时通过.noCollapse${anyRequired}强制展开关键区域。left-chevron在垂直堆叠的列表中更常见——所有ha-filter-*过滤器面板实体、设备、标签、集成等都以left-chevronexpanded-changed组合使用形成左侧箭头的分组列表观感。插槽Slot体系标题、图标与操作区的组合组件一共暴露五个命名插槽与一个默认插槽Gallery 的第 59 个样例逐一演示了它们的组合header标题传入任意元素覆盖header属性例如ha-filter-entities.ts中在标题右侧追加了数量badge与清除筛选的ha-icon-buttonsecondary副标题覆盖secondary属性渲染为小号次级文本--secondary-text-color、--ha-font-size-sleading-icon前导图标位于标题最左侧left-chevron模式下紧贴箭头之后自动化编辑器用它放置服务图标/条件图标安全对话框用它放置mdi:star-outline、mdi:shield-alert-outline等图标icons尾部操作区位于标题最右侧可放置多个ha-icon-button如 Gallery 样例中的mdiPacMan操作按钮以及自动化动作行的ha-dropdown溢出菜单event事件徽章位于标题中部自动化编辑器的运行状态 chipha-automation-row-event-chip即通过slotevent注入见 ha-automation-action-row.ts默认插槽折叠内容区且为惰性渲染——收起时_showContent为false内容不会写入 DOM。插槽渲染逻辑的核心在渲染函数中src/components/ha-expansion-panel.tsslot nameleading-icon/slot slot nameheader div classheader ${this.header} slot classsecondary namesecondary${this.secondary}/slot /div /slot slot nameevent/slot slot nameicons/slot事件expanded-will-change与expanded-changed组件通过fireEvent向外派发两个自定义事件类型声明见 src/components/ha-expansion-panel.tsinterface HASSDomEvents { expanded-changed: { expanded: boolean }; expanded-will-change: { expanded: boolean }; }expanded-will-change在动画开始前触发用于父组件提前同步状态或保存待改变标记expanded-changed在状态更新完成后触发是父组件监听展开状态的主要入口。实际业务中的典型用法是单向数据流绑定父组件持有expanded状态通过expanded-changed回调写回。例如 ha-filter-entities.tsha-expansion-panel left-chevron .expanded${this.expanded} expanded-changed${this._expandedChanged} 同样的模式遍布过滤器家族ha-filter-devices.ts、ha-filter-labels.ts 等 11 个过滤组件、自动化编辑器的动作/条件/触发/选项行以及云端引导对话框 dialog-cloud-onboarding.ts 的多个步骤面板。无障碍ARIA实现剖析组件对 ARIA 规范的遵循体现在标题行的按钮语义与内容区的区域语义两个层面src/components/ha-expansion-panel.ts触发器标题行div idsummary rolebutton tabindex${this.noCollapse ? -1 : 0} aria-expanded${this.expanded} aria-controlssect1 partsummary 内容区div classcontainer roleregion aria-labelledbysummary aria-hidden${!this.expanded} tabindex-1 配合partsummary外部可通过::part(summary)定制触发器的局部样式。键盘支持方面_toggleContainer同时处理click与keydown仅响应Enter或空格键Space其余按键直接忽略若事件已被preventDefault例如操作按钮的点击则不触发折叠。此外focus/blur事件会为标题行切换focused类结合:focus-visible为箭头图标绘制高亮背景保证键盘聚焦状态清晰可见。展开动画的实现机制组件的展开/收起动画是高度过渡方案完整逻辑在_toggleContainer与_handleTransitionEnd中src/components/ha-expansion-panel.ts触发时先将内容区overflow置为hidden防止动画期间内容溢出展开方向立即置_showContent true等待nextRender()完成动态内容渲染后读取scrollHeight写入style.height触发高度动画收起方向将高度先设为当前scrollHeight下一帧再置为0pxtransitionend时清除内联height、按需恢复overflow并同步_showContent收起后卸载内容 DOM。对应的 CSS 过渡src/components/ha-expansion-panel.ts为height 300ms cubic-bezier(0.4, 0, 0.2, 1)展开后由.container.expanded { height: auto; }接管。这种先量高再动画的做法保证了嵌套内容高度未知如虚拟列表、动态徽章时动画依然平滑而收起后卸载内容也避免了大量面板同时展开时的渲染开销。样式定制CSS 自定义属性清单组件样式全部通过 CSS 自定义属性开放覆盖标题区、内容区、箭头与描边可在外部或:host覆盖自定义属性默认值作用--expansion-panel-summary-padding0 8px标题行内边距--expansion-panel-content-padding0 8px内容区内边距--ha-card-border-radius/--ha-border-radius-lg全局圆角面板外圆角展开时底部圆角归零--input-fill-color全局填充色标题行聚焦背景--outline-color全局描边色outlined模式边框色--direction全局方向箭头图标方向支持 RTL 布局--ha-border-radius-circle全局圆形半径箭头图标圆形背景--ha-color-fill-neutral-normal-active全局中性色键盘聚焦时箭头背景--primary-text-color/--secondary-text-color全局文本色标题与副标题颜色--ha-font-weight-medium/--ha-font-size-s全局字体标题字重与副标题字号例如 Gallery 演示页 ha-expansion-panel.ts 通过ha-expansion-panel { margin: -16px; }消除卡片内边距实现面板与ha-card边缘对齐的贴边效果。Gallery 演示页9 组样例覆盖全部 API 面gallery/src/pages/components/ha-expansion-panel.ts 用 9 个SAMPLES样例完整覆盖了组件的 API 组合面仅header属性headersecondary属性仅.header属性绑定Property 写法.header.secondary属性绑定secondary插槽覆盖属性header插槽覆盖属性header插槽 icons插槽放置操作按钮header属性 icons插槽操作按钮leading-icon插槽放置前置图标mdiLightbulbOn。每个样例都通过 demo-black-white-row.ts 同时在浅色light与深色dark翻转主题两个分区渲染且深色分区中的样例固定启用leftChevronsample.template(slot, slot dark)便于开发者在两种主题与两种箭头位置下直接对比验证视觉与可访问性表现。实战建议在自定义界面中复用的最佳实践综合源码与既有用法在 Lovelace 自定义卡片或设置面板中接入ha-expansion-panel时建议遵循以下约定状态单向数据流始终用.expanded${...}绑定 expanded-changed回调的模式避免直接操作 DOM 或滥用内部状态保留可访问性不要用no-collapse之外的样式手段屏蔽键盘交互操作按钮需放在icons插槽并自行设置label如ha-icon-button的labelSome Action点击事件应preventDefault以免误触折叠善用惰性渲染把重量级内容虚拟列表、图表、表单放进默认插槽组件收起时会自动从 DOM 卸载配合 ha-filter-entities.ts 中面板外置内容 展开状态控制渲染的模式可进一步按需加载主题一致沿用组件暴露的 CSS 变量而非写死颜色确保在浅色/深色主题与 RTL 布局下自动适配。ha-expansion-panel是 Home Assistant 前端中复用面最广的基础组件之一从过滤器侧栏、自动化编辑器到备份配置、实体属性编辑器均有引用。理解其 ARIA 约束、动画机制与插槽模型是二次开发自定义卡片和面板时规避无障碍缺陷与交互坑点的重要前提。赞分享前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载相关推荐rsuite Panel 面板组件实战指南从基础用法到可折叠面板组的完整解析rsuite Panel 面板组件实战指南从基础用法到可折叠面板组的完整解析 Panel 是 rsuite 中最常用的内容容器组件之一用于承载一段内容区域前端UI组件WeChatMsg 完整指南免费导出微信聊天记录为 HTML、Word、CSV还能生成年度报告WeChatMsg 完整指南免费导出微信聊天记录为 HTML、Word、CSV还能生成年度报告 换手机之前你往聊天窗口里往上翻两年前的开头几段已经不见了rsuite Panel 组件实战指南内容容器、可折叠面板与手风琴的源码级解析rsuite Panel 组件实战指南内容容器、可折叠面板与手风琴的源码级解析 rsuite 的 Panel 组件是一个通用内容容器支持边框 border前端UI组件上一篇3种方案解决esbuild动态require陷阱从报错到优雅兼容下一篇Umi-OCR拖放功能文件拖入识别的用户体验优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考