Home Assistant 前端 ha-tooltip 悬浮提示组件实战：用法、定位与主题令牌完全指南

前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载ha-tooltip是 Home Assistant 前端本项目仓库frontend中基于 WebAwesomewa-tooltip封装的自定义悬浮提示tooltip组件用于在鼠标悬停时为目标元素显示说明性文本。本文以 gallery 组件文档 为主线结合 组件源码 与仓库内十余处真实调用场景完整讲解其使用规则、定位与延迟参数、主题样式令牌以及如何在 flex/grid 布局中无侵入地接入。读完本文你可以直接在自定义 Lovelace 卡片或前端组件中正确使用ha-tooltip并通过主题变量统一定制它的外观。一、组件定位WebAwesome Tooltip 的 HA 风格封装ha-tooltip不是从零实现的组件而是对 WebAwesomewa-tooltip的轻量二次封装。源码 ha-tooltip.ts 中可以看到import Tooltip from home-assistant/webawesome/dist/components/tooltip/tooltip; ... customElement(ha-tooltip) export class HaTooltip extends Tooltip {它继承了 WebAwesome Tooltip 的全部交互与弹出层能力只做两件定制将 WebAwesome 的 CSS 令牌--wa-tooltip-*映射为 HA 主题令牌--ha-tooltip-*使悬浮提示能跟随 Home Assistant 的主题系统自动换肤自定义显示/隐藏动画通过.tooltip::part(popup)设置animation-duration见 ha-tooltip.ts。因此如果你需要更深层的 API如位置计算、焦点管理、快捷键交互可以参考 WebAwesome Tooltip 的官方文档而样式层面本文下面的主题令牌一节已经覆盖了 HA 侧的完整映射。二、快速上手让 Tooltip 指向目标元素ha-tooltip的目标target是它的第一个子元素这是它最重要的使用规则。因此一个ha-tooltip内部只能包裹一个元素如果想让提示同时出现在多个元素上需要先把这些元素嵌套进一个容器中再把容器作为 tooltip 的唯一子元素。官方 gallery 文档 ha-tooltip.markdown 给出的最小示例是一个悬停显示的按钮ha-button idhoverHover Me/ha-button ha-tooltip forhover This is a tooltip /ha-tooltip这里的关键点是for属性tooltip 并不要求目标元素必须是自己的子元素而是通过forhover与页面中任意idhover的元素建立关联。结合源码中的属性定义ha-tooltip.tsha-tooltip还暴露了show-delay、hide-delay等属性详见第三节。布局无侵入原理ha-tooltip使用display: contents这意味着它自身不会产生任何盒子因此不会干扰元素在 flex 或 grid 布局中的定位。你可以在布局中随意插入ha-tooltip包裹代码而不用担心它把布局挤歪。三、定位placement与延迟参数ha-tooltip继承自 WebAwesome Tooltip支持通过placement属性控制弹出位置。在 ha-help-tooltip.ts 中可以确认完整的位置取值集合placement 取值说明top/bottom/left/right上、下、左、右四个基本方位top-start/top-end顶部靠左 / 顶部靠右right-start/right-end右侧靠上 / 右侧靠下bottom-start/bottom-end底部靠左 / 底部靠右left-start/left-end左侧靠上 / 左侧靠下除了定位组件源码 还定义了两个延迟属性property({ attribute: show-delay, type: Number }) showDelay 350; property({ attribute: hide-delay, type: Number }) hideDelay 150;show-delay默认 350ms鼠标移入后等待多久才显示提示防止鼠标扫过时误触发hide-delay默认 150ms鼠标移出后等待多久才隐藏提示给用户移动到提示内容上的时间。如果需要即时显示/隐藏可以显式传show-delay0 hide-delay0。仓库中的 ha-sidebar.ts 就是这么做的return htmlha-tooltip for${id} show-delay0 hide-delay0 placementright ${text} /ha-tooltip;此外ha-tooltip还支持disabled属性当需要按条件禁用提示时可以通过.disabled${condition}绑定。见 ha-icon-button-toolbar.ts 中没有 tooltip 文案就不显示提示的写法htmlha-tooltip .disabled${!item.tooltip} .for${item.id ?? icon-button- item.label} ${item.tooltip ?? }/ha-tooltip 四、仓库内的真实调用场景ha-tooltip在整个前端被广泛使用src目录下有 40 余处引用这里挑选几个典型场景说明最佳实践1. 图标帮助提示ha-help-tooltipha-help-tooltip.ts 是它的一个直接封装一个帮助图标问号圆点 关联的 tooltip并且把position属性透传给 tooltipha-svg-icon idsvg-icon .path${mdiHelpCircleOutline}/ha-svg-icon ha-tooltip forsvg-icon .placement${this.position} ${this.label} /ha-tooltip2. 能源仪表盘卡片的说明气泡在自给自足仪表盘卡片 hui-energy-self-sufficiency-gauge-card.ts 中tooltip 指向一个信息图标并定位到左侧ha-svg-icon idinfo .path${mdiInformationOutline}/ha-svg-icon ha-tooltip forinfo placementleft ${this._i18n.localize(ui.panel.lovelace.cards.energy.self_sufficiency_gauge.card_indicates_self_sufficiency_quota)} /ha-tooltip3. 通过::part()微调弹出层间距Tooltip 的弹出层暴露了base__popup这个 Shadow Parts 选择器可以在使用处调整它的外观。同样是上面的能源卡片hui-energy-self-sufficiency-gauge-card.tsha-tooltip::part(base__popup) { margin-top: 4px; }4. Gallery 演示页与 e2e 测试组件在 gallery 演示页 中通过import ../../../../src/components/ha-tooltip引入并展示对应的 e2e 测试选择器为demo-components-ha-tooltip见 test/e2e/gallery/pages.ts。如果你在 gallery 中浏览组件可以直接用鼠标悬停按钮体验效果。五、HA 主题令牌完整的样式定制清单ha-tooltip的全部样式都是通过 CSS 自定义属性令牌暴露的。在 Home Assistant 的主题设置中定义这些变量时不要带--前缀例如主题 YAML 里写ha-tooltip-background-color:而不是--ha-tooltip-background-color:。下表来自 gallery 组件文档 的令牌清单主题令牌文档默认值--ha-tooltip-background-colorvar(--secondary-background-color)--ha-tooltip-text-colorvar(--primary-text-color)--ha-tooltip-font-familyvar(--ha-font-family-body)--ha-tooltip-font-sizevar(--ha-font-size-s)--ha-tooltip-font-weightvar(--ha-font-weight-normal)--ha-tooltip-line-heightvar(--ha-line-height-condensed)--ha-tooltip-padding8px--ha-tooltip-border-radiusvar(--ha-border-radius-sm)--ha-tooltip-arrow-size8px源码层面的实际默认值与文档的差异点对照 组件源码当前实现中部分令牌的实际兜底默认值与文档表格存在细微差异文档描述的是主题令牌的标准语义源码则直接内联了运行时兜底值使用时可留意背景色实际兜底为var(--ha-color-surface-default)ha-slider等组件内则是var(--secondary-background-color)字号实际兜底为var(--ha-font-size-m)字重实际兜底为var(--ha-font-weight-medium)圆角实际兜底为var(--ha-border-radius-md)箭头尺寸实际兜底为0px同时源码固定了--wa-tooltip-border-width: 0px——也就是说当前 HA 封装的 tooltip 默认是无箭头、无边框的扁平气泡风格内边距通过var(--ha-space-2)8px 级距换算。无论兜底值如何一旦你在主题中定义了ha-tooltip-*令牌它们都会优先生效因此日常定制只需关心文档表格里的令牌名。源码中额外提供的两个令牌除了文档表格列出的令牌源码 ha-tooltip.ts 还额外支持两个实用令牌它们不在文档表格中但同样可用于定制--ha-tooltip-animation-duration默认0控制弹出层显示/隐藏动画的时长设置为正数如0.2s即可开启自定义动画--ha-tooltip-box-shadow默认var(--ha-box-shadow-m)控制气泡的阴影例如改成none可以去除阴影。另外源码将--wa-z-index-tooltip固定为1000确保 tooltip 始终浮在普通内容之上ha-tooltip.ts。六、主题定制示例在 Home Assistant 的主题设置中新增或修改一个主题时可以这样定制全局 tooltip 外观注意不带--前缀ha-tooltip-background-color: #202124 ha-tooltip-text-color: #e8eaed ha-tooltip-font-size: 12px ha-tooltip-font-weight: 500 ha-tooltip-padding: 10px ha-tooltip-border-radius: 6px如果只想影响局部例如某个卡片内部也可以在组件样式中直接内联设置ha-tooltip { --ha-tooltip-background-color: var(--primary-color); --ha-tooltip-text-color: #fff; --ha-tooltip-animation-duration: 0.2s; }这样既能全局统一风格也能针对特定区域做局部差异化且所有改动都会自动继承 HA 主题系统的变量层级。七、总结与注意事项ha-tooltip的目标是第一个子元素一个 tooltip 只包裹一个元素多元素场景请先包一层容器通过for属性关联任意id元素通过placement控制 12 种方位通过show-delay/hide-delay默认 350/150ms控制显示节奏组件使用display: contents不会影响 flex/grid 布局可以放心插入全部样式通过--ha-tooltip-*令牌暴露主题设置中定义时去掉--前缀文档与源码的兜底默认值存在细微差异以主题定义为最终优先值弹出层可通过ha-tooltip::part(base__popup)做局部微调。无论是想为侧边栏图标、帮助问号还是图表卡片加上提示信息都可以直接复用ha-tooltip保持与 Home Assistant 主题风格完全一致。赞分享前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载相关推荐Home Assistant 前端组件 ha-switch 完全指南属性、样式定制与实战应用Home Assistant 前端组件 ha switch 完全指南属性、样式定制与实战应用 ha switch 是 Home Assistant 前端本仓前端智能家居UI组件Home Assistant 前端 ha-dropdown 下拉菜单组件组合式用法、源码实现与主题定制Home Assistant 前端 ha dropdown 下拉菜单组件组合式用法、源码实现与主题定制 ha dropdown 是 Home Assist前端智能家居UI组件Home Assistant 前端组件 ha-alert 完全指南四级警示消息组件实战与源码解析Home Assistant 前端组件 ha alert 完全指南四级警示消息组件实战与源码解析 导读 ha alert 是 Home Assistant前端智能家居UI组件上一篇Kubo v0.35.0 版本全解析数据导入、内容提供与检索系统的一次系统性升级下一篇RenderCV 的 GitHub Actions 自动化流水线从测试、文档部署到跨平台发布的全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考