Tooltip 文字提示

包住触发元素使用。只放补充信息，不放必需信息：触屏上没有 hover， 关键内容请直接写在页面上，或用 Modal。

四个方向

placement 是首选方向，视口放不下时会翻到对面。焦点也会触发，键盘用户同样看得到。

<pt-tooltip placement="top" content="在上方">
  <pt-button variant="secondary">top</pt-button>
</pt-tooltip>
<pt-tooltip placement="right" content="在右侧">
  <pt-button variant="secondary">right</pt-button>
</pt-tooltip>
<pt-tooltip placement="bottom" content="在下方">
  <pt-button variant="secondary">bottom</pt-button>
</pt-tooltip>
<pt-tooltip placement="left" content="在左侧">
  <pt-button variant="secondary">left</pt-button>
</pt-tooltip>

纯文本触发

插槽里是不可聚焦的内容时，宿主自己补 tabindex="0" 兜底：键盘与触屏（点一下即聚焦）仍能触发。

这个词带提示：
<pt-tooltip content="补充说明">悬停或聚焦看看</pt-tooltip>

对齐与间距

align 是交叉轴上的对齐，触发元素比气泡宽时看得最清楚；offset 是气泡与触发元素的间距，默认 4px。

<pt-tooltip align="start" content="align=start">
  <pt-button variant="secondary">start 对齐</pt-button>
</pt-tooltip>
<pt-tooltip align="end" content="align=end">
  <pt-button variant="secondary">end 对齐</pt-button>
</pt-tooltip>
<pt-tooltip offset="12" content="offset=12">
  <pt-button variant="secondary">间距 12</pt-button>
</pt-tooltip>

触发方式

悬停与焦点都会触发 —— 焦点不触发的话，键盘用户永远看不到提示。离开或失焦即隐藏。 delay 决定悬停多久才出现，默认 200ms，设 0 表示立刻。

插槽里是不可聚焦的内容（纯文本、图标）时，宿主自己补 tabindex="0" 兜底， 键盘与触屏（点一下即聚焦）仍然触发得了。插槽里放的是 pt-button 这类自带焦点的元素时， 宿主不加 tabindex，Tab 序列里不会多出一站。

键盘

Esc 关掉提示 —— 提示挡住下面的内容时，键盘用户需要一个关掉它的办法 （WAI-ARIA tooltip 模式的硬性要求）。

位置

placement 是首选方向，视口放不下时会翻到对面；反射到属性上的仍是首选值。 align 是交叉轴上的对齐（start / center / end，默认 center）：placement 为 top / bottom 时 start 是行首一侧（RTL 下是右），为 left / right 时 start 是上。 offset 是气泡与触发元素的间距，默认 4px。

显示期间改 placement / align / offset，气泡按新参数重新定位。

受控

open 反映提示当前是否显示，悬停 / 聚焦打开、离开 / 失焦 / Esc 收起时组件自己改写它，并反射到宿主属性上。 外部也可以直接写：写 true 立即显示（不等 delay），写 false 立即收起。disabled 时写 true 不生效， open 会回落为 false；显示期间被禁用也会立即收起。

事件约定与 Modal 一致：

• ptOpen：气泡每次真正渲染出来之后发，不论是交互打开还是外部写 open 打开的。
• ptClose：只在用户交互收起时发，detail.reason 是 pointer（指针离开）/ blur（失焦）/ escape。 外部把 open 写成 false、或因 disabled 收起时不发 —— 那是调用方自己关的，它已经知道了。

悬停计时还没到时离开，提示根本没出现过，也不发 ptClose。

无障碍

气泡是 role="tooltip"。可见时挂到触发元素的 aria-describedby 上，隐藏时摘掉， 触发元素原有的 aria-describedby 原样保留。

content 属性放纯文本；富内容走 content 插槽。

API

属性

属性	Attribute	类型	默认值	说明
align	align	"center" | "end" | "start"	'center'	交叉轴上的对齐：top / bottom 时 start 是行首一侧（RTL 下是右），left / right 时 start 是上
content	content	string | undefined	—	提示文案。也可以用 content 插槽传富内容
delay	delay	number	200	悬停多久才出现（毫秒）。设 0 表示立刻
disabled	disabled	boolean	false	禁用提示
offset	offset	number	4	气泡与触发元素之间的距离（px）
open	open	boolean	false	是否显示。悬停 / 聚焦打开、离开 / 失焦 / Esc 收起时组件自己改写；外部写入立即生效，不受 delay 影响
placement	placement	"bottom" | "left" | "right" | "top"	'top'	相对触发元素的位置。视口放不下时会翻到对面，反射的属性仍是这里的首选值

事件

事件	detail 类型	说明
ptClose	{ reason: PtTooltipCloseReason; }	用户交互收起后发，detail 说明是怎么收起的。外部把 open 写成 false 不发 **不冒泡**：弹层常互相嵌套（弹窗里的菜单、气泡卡片里的下拉），冒泡的话外层上的监听会收到内层的开关。
ptOpen	void	气泡渲染出来之后发（交互或属性打开都发，与 pt-modal 一致） **不冒泡**：弹层常互相嵌套（弹窗里的菜单、气泡卡片里的下拉），冒泡的话外层上的监听会收到内层的开关。

插槽

名称	说明
（默认）	触发元素
content	提示内容

可定制的内部元素（::part()）

part	说明
base	提示气泡（组件可见的外层盒子，与 bubble 同一元素）
bubble	提示气泡

CSS 变量

变量	说明
--pt-tooltip-max-width	气泡最大宽度，默认 240px