xiaoye-components

Appearance

Tooltip 文字提示 ​

xy-tooltip 用来承载一两句补充说明。它支持 hover、click、focus、contextmenu 和 manual，也支持触发方式数组、键盘切换、受控显示和虚拟触发，适合按钮解释、表头提示和轻量说明文案。

迁移提示 ​

  • 后台项目如果只是想收口 tooltip 的背景、边框、阴影或圆角，优先使用：
    • effect
    • popper-class
    • popper-style
    • 对应 --xy-tooltip-* 变量
  • 不建议继续在页面层 deep 到 .xy-tooltip__content 或箭头内部结构类名。
  • 如果内容已经超过一两句，或者开始出现按钮、表单和多段说明，优先改用 xy-popover，不要继续把复杂交互塞进 tooltip。

何时使用 ​

  • 需要对按钮、图标等元素补充简短说明（如工具栏图标的含义）时。
  • 需要在表头或标签旁放置提示信息时。
  • 需要鼠标悬停、点击或聚焦时展示补充文案时，配合 trigger 选择触发方式。
  • 需要完全由代码控制显示/隐藏时，使用 trigger="manual" 配合 model-value。
  • 需要虚拟触发（如给 SVG 元素或 Canvas 区域挂提示）时，使用 virtual-triggering。

何时不使用 ​

  • 需要承载复杂交互内容（表单、按钮组、多段文本）时，优先使用 xy-popover。
  • 需要确认类操作（如删除确认）时，优先使用 xy-popconfirm。
  • 需要菜单导航时，优先使用 xy-dropdown。
  • 需要大段富文本说明时，Tooltip 的 max-width 有限，不适合长内容。

基础用法 ​

Tooltip 不只服务鼠标悬停，也支持焦点进入触发区域时打开。

基础用法文字提示

气泡提示用于简短的信息提示，hover 或 focus 时显示。

不同方向 ​

placement 用于控制浮层方向，适合根据页面空间决定提示出现的位置。

自定义内容 ​

如果内容不只是单行文本，可以用 content 插槽渲染一小段说明，但仍然不建议承载复杂交互。

触发方式与尺寸控制 ​

trigger、offset、show-arrow 和 max-width 适合在点击提示、紧凑表头说明和较长文案场景里做细调。

实例级样式收口 ​

当业务只想让 tooltip 更贴近后台主题时，优先通过 popper-class 和组件变量收口，而不是继续 deep 到内部类名。

受控与手动模式 ​

trigger="manual" 时不会自动响应 hover、click 或 focus，适合完全由外部状态驱动。

当前状态：已关闭

高级触发 ​

trigger 可以传数组；trigger-keys、contextmenu 和 popper-options 适合更复杂的桌面端交互。

raw-content 会直接渲染 HTML 字符串，只建议在内容可信时使用；有现成 Vue 节点时优先使用 content 插槽。

命名映射 ​

Vue 模板会自动将 camelCase 属性名转换为 kebab-case，因此模板里写 kebab-case，TS / 源码里写 camelCase，两者完全等价：

模板写法（推荐）TS / 源码 props 写法
model-valuemodelValue
open-delayopenDelay
close-delaycloseDelay
show-aftershowAfter
hide-afterhideAfter
trigger-keystriggerKeys
show-arrowshowArrow
max-widthmaxWidth
append-toappendTo
popper-classpopperClass
popper-stylepopperStyle
close-on-esccloseOnEsc
close-on-outsidecloseOnOutside
aria-labelariaLabel
raw-contentrawContent
virtual-refvirtualRef
virtual-triggeringvirtualTriggering
popper-optionspopperOptions

其余属性（content、placement、disabled、trigger、offset、teleported、persistent、effect、transition、enterable）本身只有单个单词，模板和源码写法一致。

事件映射 ​

模板中监听 @update:model-value，对应源码 emit update:modelValue，Vue 会自动完成转换，两者等价。在 TS 中使用 defineEmits 或类型推导时写 update:modelValue，在模板中写 @update:model-value。

下方 API 表格统一按模板层推荐写法列出。

API ​

Tooltip Attributes ​

属性说明类型默认值
model-value受控显示状态booleanfalse
content纯文本提示内容string''
placement浮层方向Placement'top'
disabled是否禁用booleanfalse
open-delay打开延迟，单位毫秒number80
close-delay关闭延迟，单位毫秒number60
show-after打开延迟别名，优先级高于 open-delaynumberundefined
hide-after关闭延迟别名，优先级高于 close-delaynumberundefined
enterable浮层是否允许鼠标进入booleantrue
trigger触发方式，支持单值或数组TooltipTrigger | TooltipTrigger[]'hover'
trigger-keys触发器键盘切换按键string[]['Enter', 'NumpadEnter', 'Space', ' ']
offset浮层偏移量number10
show-arrow是否显示箭头booleantrue
max-width提示最大宽度string | number240
teleported是否通过 Teleport 挂载到外层容器booleantrue
append-toTeleport 的挂载目标string | HTMLElement'body'
persistent关闭后是否保留 DOMbooleanfalse
popper-class浮层容器自定义类名string''
popper-style浮层容器自定义样式StyleValueundefined
aria-label自定义辅助说明文本stringundefined
effect视觉主题TooltipEffect'dark'
raw-content是否把 content 当作 HTML 字符串渲染booleanfalse
transition过渡动画名称string'xy-fade'
virtual-ref虚拟触发引用ReferenceElement | nullnull
virtual-triggering是否启用虚拟触发booleanfalse
popper-options高级定位参数TooltipPopperOptionsundefined
close-on-esc按下 Escape 是否关闭booleantrue
close-on-outside点击外部是否关闭booleantrue

Tooltip Popper Options ​

popper-options 的类型为 TooltipPopperOptions：

ts
type TooltipPopperOptions = TooltipProps["popperOptions"];

Tooltip Events ​

事件说明参数
update:model-value开关状态变化TooltipModelValueChangeHandler
before-show打开前触发—
open打开时触发—
show进入过渡结束后触发—
before-hide关闭前触发—
close关闭时触发—
hide离场过渡结束后触发—

模板层监听事件使用 update:model-value；源码 emit 和 TS 类型层对应的是 update:modelValue。

Tooltip Slots ​

插槽说明
default触发区域。非虚拟触发时建议保持单一触发根节点
content自定义提示内容

Tooltip Exposes ​

名称说明类型
triggerRef当前触发节点引用TooltipExposed["triggerRef"]
contentRef当前内容节点引用TooltipExposed["contentRef"]
show立即打开 TooltipTooltipExposed["show"]
hide立即关闭 TooltipTooltipExposed["hide"]
updatePopper重新计算定位TooltipExposed["updatePopper"]
isFocusInsideContent判断焦点是否位于内容区TooltipExposed["isFocusInsideContent"]