Tooltip 文字提示
简单的文字提示气泡，hover 或键盘聚焦触发。
基础用法
悬停触发
放置方向
四个方向
空间不足时自动沿主轴翻转，并在视口边缘避让。
箭头
默认显示指向触发元素边缘的箭头；arrow="false" 隐藏箭头；arrow-point-at-center 让箭头指向触发元素中心（视口边缘避让导致面板偏移时，箭头仍指向锚点中心）。
箭头显隐与指向
arrow-position="merge" 让箭头与面板角融合成直角三角尖（通用形态，仅 *-start / *-end placement 生效）：直角三角贴角、直角边与面板两边共线，尖端正交指向锚点所在侧。
箭头 merge 融合模式
箭头形状走 CSS 变量 token 定制（宽高独立——宽高比即三角的高与角度）：
箭头形状 token（宽 / 高 / 对齐偏移 / 圆角）
--oas-tooltip-arrow-width / --oas-tooltip-arrow-height（默认各 12px，缺省回退既有 --oas-tooltip-arrow-size）；--oas-tooltip-arrow-align-offset（*-start / *-end 对齐侧的偏移，默认 16px——与 arrow-position="side" 的 arrow-offset 属性语义不同，后者是 side 态的距端间距）；--oas-tooltip-arrow-radius（箭头圆角，默认 0）。merge 形态为独立 8px 几何，不受这些 token 影响。
视口边缘自动调整
默认空间不足时自动沿主轴翻转并避让视口边缘；auto-adjust-overflow="false" 关闭自动调整，面板保持声明 placement（可能溢出视口）。
关闭自动调整
聚焦触发
键盘聚焦触发
受控显示
open 属性受控：外部按钮设置 / 移除 open 即可显示 / 隐藏提示（hover / focus 触发仍叠加生效）。
受控显示（open 属性）
长文本
长文本与最大宽度
虚拟触发
虚拟模式（virtual）不绑定宿主触发元素：open 完全受外部控制，位置由 virtual-anchor（锚点元素选择器）或 virtual-x / virtual-y（视口坐标）指定，placement 仍生效。适合图表点位、拖拽中的浮层提示等无法用普通触发元素的场景。
虚拟锚点跟随（图表点位）
悬停任意点位查看提示（tooltip 锚定该点显示）。
坐标跟随（鼠标移动）
触发方式
trigger 属性支持空格分隔的多选组合：hover（悬停）/ focus（聚焦）/ click（点击）/ contextmenu（右键）/ touch（长按）/ manual（完全受控）。默认 hover focus touch——触屏长按开箱即用（桌面鼠标自动过滤，长按时长 touch-delay 可调）。触屏（coarse pointer）下 hover 触发自动降级为点按切换：点按打开、再点按关闭、点按其他位置关闭（桌面悬停行为不变）。
点击触发
右键触发
手动触发（manual）
显示延迟
open-delay / close-delay 控制悬停显示/隐藏的延迟（ms），避免快速滑过时误触发。键盘焦点触发不等待 open-delay（键盘用户已主动定位，即时显示）。
显示延迟与隐藏延迟
连续在多个触发元素间快速移动时，skip-delay-duration（默认 300ms）会让下一个 tooltip 跳过 open-delay 立即显示，保持响应连贯。
延迟组（skip-delay-duration）
触屏设备长按显示（默认 trigger 已含 touch，touch-delay 控制长按时长，默认 500ms；桌面鼠标长按被自动过滤）。
触屏长按触发
触屏点按切换（coarse pointer 自动生效）
在触屏设备（pointer: coarse）上，hover 通道自动停用——触屏点按会同时合成 hover/focus/click 事件，若仍按桌面悬停语义会在点按瞬间"刚开即关"。降级后由点按接管切换，与 click 触发一致：打开后点按文档其他位置（或按 Esc）关闭。
富内容
content 属性显示纯文本；需要富内容（链接、图标、多行）时用 slot="content" 插槽，插槽存在时优先于属性文本。
富内容若含可交互元素（链接等），建议组合 interactive（浮层可悬停，指针移入不关）+ close-delay（给指针从锚点移向浮层留时间）——这也是 WCAG 1.4.13「hoverable」的推荐形态。
富内容插槽
interactive + close-delay 组合
键盘可达
打开状态下按 Esc 关闭，焦点还原到触发元素；打开时触发元素自动关联 aria-describedby 指向浮层（屏幕阅读器可读）。
Esc 关闭 + aria-describedby
trigger-keys 可指定按键（空格分隔）在聚焦时打开，如 trigger-keys="F1"。
trigger-keys 按键打开
最大宽度
默认最大宽度 240px（--oas-tooltip-max-width token 开口），max-width 属性可覆盖（数字或 CSS 长度）。
自定义最大宽度
禁用
disabled 时 tooltip 不显示（hover / 受控 open 均不生效）。
禁用
可悬停浮层
interactive 让浮层可悬停（鼠标移入浮层不关闭，浮层内链接可达）。
interactive 可悬停
偏移与碰撞
offset 控制主轴距离（默认 10px），skidding 控制交叉轴偏移，collision-padding 控制视口边缘避让边距（默认 4px）。
offset / skidding
collision-padding
颜色变体
color 属性支持语义色（primary / success / warning / danger）、11 预设名（如 magenta、blue）或任意 CSS 色值，全部走 token（含 dark 变体）。
颜色变体
挂载点
append-to 把浮层挂载到指定容器（body 或 CSS 选择器），脱离裁剪上下文（如 overflow: hidden 祖先）。
append-to body
自动关闭
auto-close（ms）在打开后自动关闭，适合引导提示等场景。
auto-close
新鲜内容
fresh 默认开启：关闭状态下内容变化也即时同步（再次打开所见即最新）；fresh="false" 时关闭期间冻结内容。
fresh 内容同步
滚动跟随与滚动关闭
打开期间普通锚点也会随滚动 / 窗口尺寸变化实时重定位（scroll capture + rAF 节流），浮层不再与锚点脱节；close-on-scroll 则让滚动即关闭（浮层不跟跑，适合紧凑提示）。
滚动跟随
滚动右侧滚动条：tooltip 打开时跟着按钮一起移动
close-on-scroll 滚动即关
先悬停打开提示，再滚动容器——提示立即关闭
点击触发与外部关闭
trigger 含 click / contextmenu 打开后，按下浮层与触发元素之外的任意位置即关闭（light dismiss），无需回头再点触发元素。仅 hover/focus/touch 触发或受控 open 不挂外部关闭。
click + 外点关闭
点击打开后，点击浮层 / 按钮之外任意处即关闭（观察状态 tag）。
可访问名语义（label）
a11y 切换 tooltip 的语义角色：默认 description（触发元素挂 aria-describedby 指向浮层，作补充描述）；label 时改挂 aria-labelledby——适合纯图标等没有自身文本的触发元素，用提示文字作可访问名。关闭后自动还原触发元素原有的 aria 关联值，不覆盖宿主自设属性。
label 可访问名
打开后按钮被挂 aria-labelledby 指向浮层（可访问名 = 提示文字）；关闭后还原宿主原值。
箭头 side 贴边与 arrow-offset
arrow-position="side" 让箭头吸附到锚点中心投影所在的半区（面板被视口避让偏移时箭头靠向对应侧边，而非钉在中心）；arrow-offset（px，仅 side 态生效）控制箭头距面板端的内缩量，默认 4px（防探出圆角的夹取安全量）。
箭头 side 与偏移
把触发元素滚到视口边缘再打开，能看到 side 箭头贴向锚点侧的差异。
动画定制（CSS 变量开口）
进场动画时长 / 缓动 / 动画名走 CSS 变量（在 <oas-tooltip> 元素上设置即可，变量沿 shadow 继承）：--oas-tooltip-duration（默认 0.15s）、--oas-tooltip-easing（默认 ease）、--oas-tooltip-animation（默认 oas-tooltip-in，设 none 关闭进场动画）。prefers-reduced-motion: reduce 下动画始终关闭。
时长 / 缓动 / 动画开关
智能放置与碰撞边界
placement="auto"（含auto-start/auto-end）：打开时四向择优，落到空间充足的一侧；fallback-placements：指定回退序列（空格或逗号分隔的 12 向 placement），主向放不下时逐项取首个放得下的；collision-boundary：把翻转 / 避让边界从视口换成指定元素矩形（如滚动容器可视区，可配append-to防裁剪）；fallback-axis-side：主向两侧都不足时的跨轴回退（start/end/ 默认none）。
auto 自适应与回退序列
碰撞边界 = 滚动容器可视区
collision-boundary 指向本容器：提示按容器可视区翻转避让
跨轴回退 fallback-axis-side
跟随光标
follow-cursor：打开后光标在触发元素区域内移动，浮层实时跟随光标（视口坐标通道复用，rAF 节流）。适合大范围悬浮提示。
follow-cursor 跟随光标
宽度随触发器
width="trigger" 让浮层与触发元素同宽（数字或 CSS 长度直接设宽度）；浮层宽仍受 --oas-tooltip-max-width（默认 240px）封顶，可调。
width 定制
事件来源（oas-open-change）
oas-open-change 的 detail 携带 { open, source, reason }：source 为触发通道（hover / focus / click / contextmenu / touch / key / escape / outside / scroll / auto-close / attribute），reason 为原因细化（如 escape-key / outside-pointer / timeout / long-press）。外部受控 setAttribute 路径 source 为 attribute。
事件来源反馈
尚未触发
边界
空内容
API
oas-tooltip
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
a11y | a11y 关联模式：description（默认，触发元素挂 aria-describedby 指向浮层）/ label（挂 aria-labelledby 作可访问名）；关闭时还原宿主原值 | string | description |
append-to | 浮层挂载点：body 或 CSS 选择器。把浮层移入目标容器的独立 shadow（样式作用域保真），脱离 overflow: hidden / transform 等裁剪上下文；挂载期间 ::part(tip) 无法从宿主穿透，定制走 CSS 变量或类选择器 | string | — |
arrow | 是否显示箭头（默认 true；arrow="false" 隐藏，箭头元素与 ::part(arrow) 保留） | string | true |
arrow-offset | 箭头贴边内缩量（px，默认 4）：仅 arrow-position="side" 生效（center/merge 忽略） | — | — |
arrow-point-at-center | 箭头指向触发元素中心（默认指向触发元素边缘；视口边缘避让导致面板偏移时箭头仍指向锚点中心） | boolean | — |
arrow-position | 箭头形态：center（默认，箭头在面板边缘居中）/ merge（仅 *-start/*-end placement 生效，直角三角与面板角共边融合：直角贴角点、直角边与面板两边共线，尖端正交指向锚点，通用形态） | string | center |
auto-adjust-overflow | 视口边缘自动翻转与避让（默认 true；"false" 关闭，保持声明 placement，可能溢出视口） | string | true |
auto-close | 打开后自动关闭时长（ms），0 或缺省不自动关闭 | — | — |
close-delay | 隐藏延迟（ms，默认 0）：mouseleave/focusout 后延迟关闭 | — | — |
close-on-scroll | 页面滚动即关闭（打开期间监听，首个滚动命中直接关；resize 只重定位不关） | boolean | — |
collision-boundary | 碰撞边界元素选择器：翻转/夹取判定边界从视口换成该元素矩形（property 通道 collisionBoundaryEl 优先） | Element | null | — |
collision-padding | 视口边缘避让边距（px，默认 4）：浮层被视口夹取时与边缘保留的距离 | — | — |
color | 颜色变体：语义色 primary/success/warning/danger、11 预设名（如 magenta、blue）或任意 CSS 色值；全部走 token（含 dark 变体），箭头底色同步 | string | — |
content | 提示内容文本（slot="content" 富内容存在时优先于属性文本） | string | — |
disabled | 禁用：tooltip 不显示（hover / 受控 open 均不生效） | boolean | — |
fallback-axis-side | 主轴两侧都放不下时的跨轴回退：start（转交叉轴起点侧 left/top）/ end（right/bottom）；默认 none 不跨轴（维持对侧翻转 + 视口夹取） | string | none |
fallback-placements | 自定义回退序列（空格/逗号分隔的 12 向 placement）：请求位放不下按序列逐项 fit，首个 fit 者胜出，全不 fit 取序列末位夹取兜底；未设置走默认主轴翻转 | string | — |
follow-cursor | 跟随光标：打开后以光标坐标（0 尺寸点位）定位，光标移动 rAF 节流跟随 | boolean | — |
fresh | 内容新鲜度（默认 true）：关闭期间内容变化也即时同步；"false" 时关闭期间冻结内容，再次打开才更新 | string | true |
interactive | 浮层可悬停：鼠标移入浮层不关闭（pointer-events: auto），浮层内链接可达 | boolean | — |
max-width | 浮层最大宽度（数字补 px 或 CSS 长度，默认走 --oas-tooltip-max-width token 240px） | string | — |
offset | 主轴距离（px，默认 10）：浮层与锚点沿主轴的间隔 | — | — |
open | 受控显示（布尔属性，存在即显示） | boolean | — |
open-delay | 显示延迟（ms，默认 0）：mouseenter/focusin 后延迟打开；skip-delay-duration 命中时跳过 | — | — |
placement | 浮层位置（12 向：top/bottom/left/right × start/center/end） | string | top |
skidding | 交叉轴偏移（px，默认 0）：top/bottom 系列沿水平轴（正右负左）、left/right 系列沿垂直轴（正下负上） | — | — |
skip-delay-duration | 全局延迟组阈值（ms，默认 300）：某 tooltip 关闭后这段时间内打开下一个 tooltip 时跳过 open-delay 立即显示（连续悬停响应连贯）；"0" 关闭该行为 | — | — |
touch-delay | touch 长按触发时长（ms，默认 500）：trigger 含 touch 时 pointerdown 长按到点打开，提前抬手/移出取消 | — | — |
trigger | 触发方式（空格分隔多选）：hover / focus / click / contextmenu / touch / manual，默认 hover focus touch；manual 全受控 | string | hover focus touch |
trigger-keys | 指定按键（空格分隔，如 F1）：焦点在触发元素上时按该键打开 | string | — |
virtual | 虚拟触发模式：不绑定宿主触发元素，open 完全受外部控制，位置由 virtual-anchor 或 virtual-x/virtual-y 指定（适合图表点位、拖拽中的浮层提示） | boolean | — |
virtual-anchor | 虚拟锚点元素选择器（如 #chart-point-1），tooltip 按该元素矩形定位；与 virtual-x/virtual-y 二选一，坐标优先 | — | — |
virtual-x | 虚拟锚点视口 X 坐标（px，如鼠标 clientX），与 virtual-y 同时设置时按坐标定位 | — | — |
virtual-y | 虚拟锚点视口 Y 坐标（px，如鼠标 clientY），与 virtual-x 同时设置时按坐标定位 | — | — |
width | 浮层宽度：数字（px）/ "trigger"（与触发元素同宽）/ 任意 CSS 值；仍受 --oas-tooltip-max-width（默认 240px）封顶 | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-open-change | open 状态变化（显示/隐藏）时派发，detail: { open, source, reason } |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 触发元素（hover/focus 触发）；virtual 虚拟模式下可省略 |
content | 富内容（存在时优先于 content 属性文本显示） |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-glass-blur | none |
--oas-glass-ring | transparent |
--oas-tip-cross | 999px |
--oas-tooltip-animation | oas-tooltip-in |
--oas-tooltip-arrow-align-offset | 16px |
--oas-tooltip-arrow-height | var(--oas-tooltip-arrow-size, 12px) |
--oas-tooltip-arrow-radius | 0 |
--oas-tooltip-arrow-width | var(--oas-tooltip-arrow-size, 12px) |
--oas-tooltip-bg | var(--oas-color-text-primary) |
--oas-tooltip-color | var(--oas-color-bg) |
--oas-tooltip-duration | 0.15s |
--oas-tooltip-easing | ease |
--oas-tooltip-max-width | 240px |
oas-open-change：open 状态变化（显示/隐藏）时派发，detail: { open, source, reason }（source 为触发通道，reason 为具体原因；外部受控写属性时 source 为 attribute）。hover / focus 触发显隐；role="tooltip"，浮层 pointer-events: none 不拦截交互。