工具提示 Tooltip — Astryx v0.7.1 文档

提供简短补充说明，不替代控件可访问名称。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

工具提示 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
工具提示 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
工具提示 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
工具提示 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.

使用建议

Keep tooltip content concise: aim for under 140 characters of plain text.
Add a tooltip to icon-only buttons and controls that lack a visible label.
Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.
避免：Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.
避免：Use tooltips for essential information that users must see to complete a task.

主题 API

{
  "targets": [
    {
      "className": "astryx-tooltip"
    }
  ]
}

工具提示显示的组件包装器，通过悬停或聚焦触发。

属性	类型	默认值	说明
children	ReactNode		激活工具提示的触发元素。
anchorRef	RefObject<HTMLElement>		兄弟模式的外部锚点引用。
content	ReactNode		工具提示内容，通常是简短文本。
placement	'above' \| 'below' \| 'start' \| 'end'	'above'	相对于锚点元素的位置。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。
alignment	'start' \| 'center' \| 'end'	'center'	沿放置轴的对齐方式。逻辑值：start/end 根据弹出层自身继承的方向解析（RTL 镜像）。
delay	number	200	显示延迟（毫秒）。
hideDelay	number	0	隐藏延迟（毫秒）。
focusTrigger	'auto' \| 'always' \| 'never'	'auto'	控制聚焦事件何时触发工具提示。
touchTrigger	'auto' \| 'tap' \| 'none'	'auto'	在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。
isEnabled	boolean	true	启用或禁用工具提示触发器。
onOpenChange	(isOpen: boolean) => void		工具提示可见性变化时触发的回调。显示时传入 true，隐藏时传入 false。
hasHoverIndication	'auto' \| boolean	'auto'	在触发元素上显示虚线下划线。
isDefaultOpen	boolean		是否在挂载时显示工具提示。仍然可以关闭。
isOpen	boolean		Controlled open state for the tooltip.

组件结构

Tooltip surface: Painted overlay surface that presents the tooltip.
Tooltip text: Tooltip content rendered within the surface.

useTooltip

Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.

Parameters

Parameter	Type	Description
placement	'above' \| 'below' \| 'start' \| 'end'	Position relative to the trigger. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS).
alignment	'start' \| 'center' \| 'end'	Alignment along the placement axis. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS).
delay	number	Delay before showing on hover, in milliseconds.
hideDelay	number	Delay before hiding after mouse or focus leaves, in milliseconds.
focusTrigger	'auto' \| 'always' \| 'never'	When focus should open the tooltip. auto only attaches focus listeners to naturally focusable elements.
touchTrigger	'auto' \| 'tap' \| 'none'	What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own; tap always opens (an info icon rendered as a button); none never opens on touch.
isEnabled	boolean	Whether hover and focus triggers are enabled.
isOpen	boolean	Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.
isDefaultOpen	boolean	Whether the tooltip should be shown on mount.
onShow	() => void	Callback fired when the tooltip becomes visible.
onHide	() => void	Callback fired when the tooltip is hidden.

Returns

[
  {
    "name": "ref",
    "type": "RefCallback<HTMLElement>",
    "description": "Combined ref that sets both position and interaction on the same trigger element."
  },
  {
    "name": "positionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the positioning anchor element."
  },
  {
    "name": "interactionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the hover/focus interaction element."
  },
  {
    "name": "anchorId",
    "type": "string",
    "description": "CSS anchor name for advanced positioning cases."
  },
  {
    "name": "describedBy",
    "type": "string",
    "description": "ID to compose into aria-describedby on the trigger."
  },
  {
    "name": "renderTooltip",
    "type": "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
    "description": "Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment."
  }
]

使用建议

Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.
Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.
避免：Put interactive content inside tooltips: use Popover or HoverCard instead.

工具提示

工具提示 · Tooltip

安装与前置条件

示例与使用方式

API 与上游详细参考

Tooltip

使用建议

主题 API

Tooltip

组件结构

useTooltip

Parameters

Returns

使用建议