Tooltip
补充短说明或不可见标签。中文惯用名：文字提示。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.tooltip |
| 名称 | Tooltip |
| 二级分类 | 通用（general） |
| 用途 | 补充短说明或不可见标签 |
| 描述 | 中文惯用名：文字提示。 |
预览
静态结构：Base UI Tooltip（data-slot="tooltip"）——children 为触发元素，经 span（data-slot="tooltip-trigger-wrap"）接入 Trigger（DSL 适配器不透传未知 props，须由包装接住触发器合并的 aria / ref / 事件）；提示浮层 data-slot="tooltip-content" 走 Portal + Positioner（缺省 side=top、align=center、sideOffset=4），反色底 bg-primary + text-xs，open / closed 由 data-open / data-closed 变体驱动；className / style 挂在浮层而非触发元素。
DSL 结构
{
"type": "Tooltip",
"props": {
"content": "这里是提示内容"
},
"children": [
{
"type": "Button",
"props": {
"text": "悬浮查看提示",
"variant": "default"
}
}
]
}何时用
何时使用
- 补充短说明：图标按钮含义、字段口径、缩写全称。
- 展示被截断文本的完整内容：列表单元格、标签溢出时。
- 给出不可见标签：纯图标入口的可访问名称来源之一。
何时不用
- 需要承载复杂内容或交互（多行、按钮、表单、链接）：使用 Popover。
- 需要用户确认或输入：使用 Popconfirm / Dialog / Drawer。
- 承载关键信息：触屏与键盘用户可能无法触发悬浮，关键内容必须直接可见。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 图标按钮提示 | hover 图标上方浮出反色小气泡 | 无文字的工具栏 / 表头按钮说明 |
| 文本截断提示 | hover 被截断文本展示全文 | 列表单元格、标签、路径 |
| 表单字段说明 | hover 标签浮出字段口径 | 字段含义、格式要求补充 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content | string | — | 提示文案（纯文本，不支持 DSL 子树） |
children | DslNode[] | — | 触发元素（DSL 子树，经 Renderer children 机制渲染） |
className / style | string / CSSProperties | — | 通用：挂在提示浮层根节点（不是触发元素）的 class 合并 / 内联样式 |
使用规范
- 文案一句话说清，不加句号、不放交互元素。
- 触发元素必须可悬浮且可聚焦（Button、Icon 等），纯文本裸节点在键盘下不可达。
- 不嵌套 Tooltip，也不在 Tooltip 里放链接或按钮。
- 关键信息直接可见，Tooltip 只做锦上添花。
正例
- ✓ 工具栏图标按钮：Tooltip content="下载 CSV" 包裹 Button（icon 通道）。
- ✓ 字段标签：Tooltip 说明「结算周期」的口径后再放输入控件。
反例
- ✕ 把表单或操作按钮放进 Tooltip 内容（应使用 Popover）。
- ✕ 依赖 Tooltip 承载必读提示（触屏与键盘用户看不到）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。