--- id: "tooltip" title: "文字提示：悬停、聚焦与关闭" category: "浮层组件" document_type: "component-specification" spec_status: "local-current-draft" element_ui: "2.15.6" vue: "2.6.14" page: "../index.html#spec-tooltip" source_data: "../component-data.json" official_components: ["tooltip"] template_components: ["el-button", "el-tooltip"] scenario_count: 6 verification: "scenario-checklist-not-full-test-pass" --- # 文字提示：悬停、聚焦与关闭 专题 `tooltip` · 浮层组件 · Element UI 2.15.6 ## 适用范围与组件映射 公共色板及字体基线适用于整个运营后台。本库整理基础组件、组件状态和可复用的组合模式；本轮补齐表单整体验证、页面布局和导航组合；具体业务字段与跨页流程仍在业务场景中说明。专题验收清单包含接入要求，不表示当前示例已实现或已验证全部场景。 官方条目映射：`tooltip`。 本页模板直接使用的 Element UI 标签：`el-button`、`el-tooltip`。 ## 通用基线 - 组件库：Element UI **2.15.6**；运行样例 Vue **2.6.14**。 - 系统中文字体：macOS 优先苹方，Windows 通常微软雅黑；工程顺序固定为 `"PingFang SC", "Microsoft YaHei", sans-serif`。不要求安装或加载网络字体，兼容回退不是另一套可选样式。 - 后续仅采用经验证且固定版本的兼容 Element UI 2.x；Element Plus 属于独立迁移路线。 - 正文、数据值、输入及已选值：`14px / 400 / 21px`，`#303133`。 - 表头及组件分组标题：`14px / 600 / 21px`；弹窗标题：`16px / 600 / 24px`，均使用 `#303133`。 - 辅助说明：`12px / 400 / 18px`，`#595959`；错误、链接、状态、禁用与占位按各自语义处理。 - 适用组件的默认尺寸为 `small / 32px`；不得将这一高度机械应用于表格、文本域、浮层等全部组件。 - 规范正文与场景说明使用 `14px / 400 / 24px`、`#303133`，不降成灰蓝小字。 - 筛选文本输入占位统一“请输入”；未选择下拉统一“请选择”；默认全部的下拉显示“全部”。字段标签保留业务含义；日期保留开始/结束语义。 - 次级文字操作（查看更多、编辑、详情、数据中心、更多）：`12px / 400 / 18px`，`#3377BB`；保留点击热区。 - 本规范库的深色目录、蓝色展示区属于文档排版，不是业务组件颜色或业务导航规范。 ## 本页用法与分类 默认用法：默认用统一白底的短文字提示解释控件；本页放在触发器上方，鼠标悬停或键盘聚焦显示。 | 区分什么 | 本页内容 | 选用或触发条件 | | --- | --- | --- | | 用途 | 只承载简短说明，不承载按钮、表单或唯一的错误信息。 | 短说明使用本组件；内容需要点击或填写时改用气泡浮层或对话框。 | | 位置与空间 | 上方位置、边缘翻转和长文本换行属于位置适配。 | 本页以上方为起点；靠近视口边缘时适配可见空间，不另选一套提示配色。 | | 自动显隐 | 显示和关闭由鼠标、焦点及退出键触发。 | 悬停或聚焦进入提示，按规则移出、失焦或退出键关闭；禁用动作仍不可执行。 | 使用边界：白底、正文深灰和灰边是统一外观；悬停、聚焦、关闭以及自动翻转不是可自由选择的样式。 ## 组件规则 - **TOOLTIP-R01**：非交互短说明统一白底 #FFFFFF、正文深灰 #303133、边框灰 #DCDFE6；文字12px/400/18px，复用公共阴影。提示宽度随内容，最大360px且不超过视口减24px，长文自然换行。鼠标悬停与键盘聚焦均可显示，退出键可关闭，移入提示层保持显示；不另设黑底白字样式。 - **TOOLTIP-R02**：放置在可见区域内，不被滚动层和固定列剪裁；长内容换行。纯 tooltip 不承载按钮或输入。 - **TOOLTIP-R03**：有交互的内容使用 气泡浮层 / 对话框，不把隐藏 tooltip 当作关键错误的唯一来源。 - **TOOLTIP-R04**：【公共用色】颜色仅从公共色值 引用：主色系 3 个基础色值、辅助功能色 3 个、中性色 10 个，共 16 个基础色值。角色可以多个，实际色值复用；不为每个组件、悬停 或不同字段再新增近似颜色。透明效果仅限遮罩 35% 与阴影 12%，从 外壳深色 派生。 - **TOOLTIP-R05**：【统一字体】统一系统中文字体：macOS 优先苹方（PingFang SC），Windows 通常使用微软雅黑（Microsoft YaHei）；工程顺序固定为 "PingFang SC", "Microsoft YaHei", sans-serif。使用设备已有字体，不要求安装或加载网络字体；最后一项仅作兼容回退，不是供页面作者任选的另一套样式。正文 14px/400/21px；表头与分组标题 14px/600/21px，弹窗标题 16px/600/24px；次级文字操作和辅助说明 12px/400/18px。正文与标题同用 #303133；不通过额外加粗或透明度改变正文轻重。 - **TOOLTIP-R06**：【叠加优先级】状态叠加规则：禁用阻断交互；输入类控件错误边框覆盖蓝色聚焦边框；输入框不叠加外圈或阴影，其他无边框操作保留键盘焦点提示；选中底覆盖悬停底；只读不等于禁用；加载不等于成功；业务启用/停用的文字结果不等于控件是否可点击。 - **TOOLTIP-R07**：【提示外观】提示白底、正文深灰、边框灰，必要阴影复用公共阴影；不新增独立黑色提示底。 - **TOOLTIP-R08**：【打开条件】鼠标悬停或键盘聚焦触发同一文字提示；触发器焦点按原组件定义，提示正文不变主题色。 - **TOOLTIP-R09**：【关闭与不可用】移出、失焦或退出键关闭提示；没有内容时不显示空壳。禁用控件的说明不能让禁用动作重新可执行。 - **TOOLTIP-R10**：【组件边界】文字提示没有确认/取消按钮、模态遮罩、提交加载或危险动作；需要可交互内容时使用气泡浮层。 ## 场景与验收清单 以下为需核对的场景组；`[ ]` 不代表已经测试通过。 - [ ] **TOOLTIP-S01**：鼠标悬停、键盘聚焦、退出键关闭、鼠标移入提示层保持显示。 - [ ] **TOOLTIP-S02**：位置与空间验收：边缘翻转、长文本换行；接入时按需配置显示延时和禁用触发器说明。所有情况沿用统一白底、正文深灰和灰边。 - [ ] **TOOLTIP-S03**：容器滚动和弹窗中的层级正确；关键信息不能只放在悬浮文字提示中。 - [ ] **TOOLTIP-S04**：核对本专题每个适用状态引用公共色值；禁用/错误+聚焦/选中+悬停组合按优先级检查。 - [ ] **TOOLTIP-S05**：提示层文字核对12px/400/18px与#303133；触发按钮保持自身组件规格。检查实际提示层及内部文字，不能用外层正文14px规则覆盖提示文字。 - [ ] **TOOLTIP-S06**：当前提示：退出键关闭后，辅助技术隐藏标识 aria-hidden 同步为 true；再次移入或重新聚焦可打开，不能只隐藏画面而保留展开状态。 ### 专题验收重点 悬停 / 聚焦 / 退出键 / 鼠标移入浮层 / 失焦。 ## 当前示例模板 以下来自本专题的结构化示例，使用 Vue 2 模板语法。`v-model`、事件方法、数据列表等依赖 [components.js](../components.js)；完整样式文件及加载顺序见 [通用基线](FOUNDATIONS.md)。自定义组合标签的内部实现由下方依赖文件提供，不能仅复制标签作为完整组件。 ```html 悬停或键盘聚焦 ``` ## 交付与使用边界 - 规范条款、示例代码与待验收场景分开理解；有示例不等于已覆盖所有样式、交互状态和使用场景。 - 业务接口、权限、时区、金额精度、数据规模等依赖应从实际项目读取，不使用演示值代替生产约定。 - 发生样式或文案变更时，同步专题数据、页面与 Markdown，避免规范和样例分离。 ## 来源与关联 - 来源线索：历史样板规范 51；本次键盘补充。 - [打开本专题页面](../index.html#spec-tooltip) - [通用基线](FOUNDATIONS.md) - [规范总索引](README.md) - [结构化规范数据](../component-data.json)（记录 id：`tooltip`） - [原始历史样板](../original-20260621.html) - [历史规范条目](../spec-notes.json) ## 本组件颜色状态表 | 状态 / 条件 | 统一规则 | | --- | --- | | 提示外观 | 提示白底、正文深灰、边框灰，必要阴影复用公共阴影；不新增独立黑色提示底。 | | 打开条件 | 鼠标悬停或键盘聚焦触发同一文字提示；触发器焦点按原组件定义，提示正文不变主题色。 | | 关闭与不可用 | 移出、失焦或退出键关闭提示；没有内容时不显示空壳。禁用控件的说明不能让禁用动作重新可执行。 | 文字提示没有确认/取消按钮、模态遮罩、提交加载或危险动作；需要可交互内容时使用气泡浮层。 [公共颜色与字体 token](../color-tokens.json) · [公共组件样式](../color-contract.css) · [系统字体合同（最后加载）](../font-contract.css) ## 业务落地场景 - [通知管理 · 截断字段或图标的完整说明](../../showcase/index.html#site-messages) · [场景文档](../../showcase/docs/site-messages.md) - [推广报表 · 日报 · 报表截断字段完整说明](../../showcase/index.html#reports) · [场景文档](../../showcase/docs/reports.md) - [推广报表 · 代理报表截断字段完整说明](../../showcase/index.html#agents) · [场景文档](../../showcase/docs/agents.md) - [运营总览 · 图表点与指标说明](../../showcase/index.html#overview) · [场景文档](../../showcase/docs/overview.md) [竞品组件拆解](../../reference-review/竞品组件反推规范.html) · [业务场景分类](../../业务场景分类清单.md)