企业官网建设流程全解析

• 前端
• 智能家居
• UI组件

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 的全部交互与弹出层能力，只做两件定制：

1. 将 WebAwesome 的 CSS 令牌（--wa-tooltip-*）映射为 HA 主题令牌（--ha-tooltip-*），使悬浮提示能跟随 Home Assistant 的主题系统自动换肤；
2. 自定义显示/隐藏动画，通过.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 id="hover">Hover Me</ha-button> <ha-tooltip for="hover"> This is a tooltip </ha-tooltip>

这里的关键点是for属性：tooltip 并不要求目标元素必须是自己的子元素，而是通过for="hover"与页面中任意id="hover"的元素建立关联。结合源码中的属性定义（ha-tooltip.ts），ha-tooltip还暴露了show-delay、hide-delay等属性（详见第三节）。

布局无侵入原理：ha-tooltip使用display: contents，这意味着它自身不会产生任何盒子，因此不会干扰元素在 flex 或 grid 布局中的定位。你可以在布局中随意插入<ha-tooltip>包裹代码，而不用担心它把布局"挤歪"。

三、定位（placement）与延迟参数

ha-tooltip继承自 WebAwesome Tooltip，支持通过placement属性控制弹出位置。在 ha-help-tooltip.ts 中可以确认完整的位置取值集合：

除了定位，组件源码 还定义了两个延迟属性：

@property({ attribute: "show-delay", type: Number }) showDelay = 350; @property({ attribute: "hide-delay", type: Number }) hideDelay = 150;

• show-delay（默认 350ms）：鼠标移入后等待多久才显示提示，防止鼠标"扫过"时误触发；
• hide-delay（默认 150ms）：鼠标移出后等待多久才隐藏提示，给用户移动到提示内容上的时间。

如果需要即时显示/隐藏，可以显式传show-delay="0" hide-delay="0"。仓库中的 ha-sidebar.ts 就是这么做的：

return html`<ha-tooltip for=${id} show-delay="0" hide-delay="0" placement="right" > ${text} </ha-tooltip>`;

此外，ha-tooltip还支持disabled属性：当需要按条件禁用提示时，可以通过.disabled=${condition}绑定。见 ha-icon-button-toolbar.ts 中"没有 tooltip 文案就不显示提示"的写法：

html`<ha-tooltip .disabled=${!item.tooltip} .for=${item.id ?? "icon-button-" + item.label} >${item.tooltip ?? ""}</ha-tooltip >`

四、仓库内的真实调用场景

ha-tooltip在整个前端被广泛使用（src目录下有 40 余处引用），这里挑选几个典型场景说明最佳实践：

1. 图标帮助提示（ha-help-tooltip）

ha-help-tooltip.ts 是它的一个直接封装：一个帮助图标（问号圆点）+ 关联的 tooltip，并且把position属性透传给 tooltip：

<ha-svg-icon id="svg-icon" .path=${mdiHelpCircleOutline}></ha-svg-icon> <ha-tooltip for="svg-icon" .placement=${this.position}> ${this.label} </ha-tooltip>

2. 能源仪表盘卡片的说明气泡

在自给自足仪表盘卡片 hui-energy-self-sufficiency-gauge-card.ts 中，tooltip 指向一个信息图标并定位到左侧：

<ha-svg-icon id="info" .path=${mdiInformationOutline}></ha-svg-icon> <ha-tooltip for="info" placement="left"> ${this._i18n.localize("ui.panel.lovelace.cards.energy.self_sufficiency_gauge.card_indicates_self_sufficiency_quota")} </ha-tooltip>

3. 通过::part()微调弹出层间距

Tooltip 的弹出层暴露了base__popup这个 Shadow Parts 选择器，可以在使用处调整它的外观。同样是上面的能源卡片（hui-energy-self-sufficiency-gauge-card.ts）：

ha-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 组件文档 的令牌清单：

源码层面的实际默认值（与文档的差异点）

对照 组件源码，当前实现中部分令牌的实际兜底默认值与文档表格存在细微差异（文档描述的是主题令牌的标准语义，源码则直接内联了运行时兜底值），使用时可留意：

• 背景色实际兜底为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组件