# 工具提示 · Tooltip

- 页面: https://jiguang132.com/zh/resources/astryx/docs/tooltip
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

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

## 安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

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

## API 与上游详细参考

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

## Tooltip

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

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

## 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

```json
[
  {
    "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.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt