文字提示

简单的文字提示气泡框。

何时使用

鼠标移入则显示提示，移出消失，气泡浮层不承载复杂文本和操作。

可用来代替系统默认的 title 提示，提供一个 按钮/文字/操作 的文案解释。

代码演示

• 基本 · basic

• 平滑过渡 · smooth-transition

• 位置 · placement

• 箭头展示 · arrow

• 贴边偏移 · shift

• 布局变化后重新对齐 · force-align

• 多彩文字提示 · colorful

• 禁用 · disabled

• 自定义子组件 · wrap-custom-component

• 自定义语义结构的样式和类 · style-class

API

通用属性参考：通用属性

共同的 API

<Antd component="Alert" title="以下 API 为 Tooltip、Popconfirm、Popover 共享的 API。" type="info" banner="true"></Antd>

ConfigProvider - tooltip.unique

可以通过 ConfigProvider 全局配置 Tooltip 的唯一性显示。当 unique 设置为 true 时，同一时间 ConfigProvider 下的 Tooltip 只会显示一个，提供更好的用户体验和平滑的过渡效果。

注意：配置后 getContainer、arrow 等属性将会失效。

import { Button, ConfigProvider, Space, Tooltip } from 'antd';

export default () => (
  <ConfigProvider
    tooltip={{
      unique: true,
    }}
  >
    <Space>
      <Tooltip title="第一个提示">
        <Button>按钮 1</Button>
      </Tooltip>
      <Tooltip title="第二个提示">
        <Button>按钮 2</Button>
      </Tooltip>
    </Space>
  </ConfigProvider>
);

Semantic DOM

语义说明来源: vendor/components/tooltip/demo/_semantic.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

声明来源: vendor/components/tooltip/style/index.ts

import { unit } from '@ant-design/cssinjs';

import type { CSSObject } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import { initFadeMotion, initZoomMotion } from '../../style/motion';

import type { ArrowOffsetToken } from '../../style/placementArrow';

import getArrowStyle, {
  getArrowOffsetToken,
  MAX_VERTICAL_CONTENT_RADIUS,
} from '../../style/placementArrow';

import type { ArrowToken } from '../../style/roundedArrow';

import { getArrowToken } from '../../style/roundedArrow';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genPresetColor, genStyleHooks, mergeToken } from '../../theme/internal';

import { genCssVar } from '../../theme/util/genStyleUtils';

export interface ComponentToken extends ArrowOffsetToken, ArrowToken {
  /**
   * @since 6.2.0
   * @desc 文字提示最大宽度
   * @descEN Max width of tooltip
   */
  maxWidth: number;
  /**
   * @desc 文字提示 z-index
   * @descEN z-index of tooltip
   */
  zIndexPopup: number;
}

interface TooltipToken extends FullToken<'Tooltip'> {
  // default variables
  tooltipMaxWidth: number;
  tooltipColor: string;
  tooltipBg: string;
  tooltipBorderRadius: number;
}

FAQ

为何有时候 HOC 组件无法生效？

请确保 Tooltip 的子元素能接受 onMouseEnter、onMouseLeave、onPointerEnter、onPointerLeave、onFocus、onClick 事件。

请查看 https://github.com/ant-design/ant-design/issues/15909

为何 Tooltip 的内容在关闭时不会更新？

Tooltip 默认在关闭时会缓存内容，以防止内容更新时出现闪烁：

// `title` 不会因为 `user` 置空而闪烁置空
<Tooltip open={user} title={user?.name} />

如果需要在关闭时也更新内容，可以设置 fresh 属性（例如 #44830 中的场景）：

<Tooltip open={user} title={user?.name} fresh />

布局变化后 Tooltip 没有重新对齐？

Tooltip 默认不会持续监听所有外部布局变化，以避免为每个打开的 Tooltip 带来额外开销。当异步加载数据、刷新列表或展开折叠区域导致触发元素的位置发生变化时，可以通过 ref 获取 TooltipRef，并在布局更新完成后调用 forceAlign 方法手动重新对齐（参考 #57809）。详见上方“布局变化后重新对齐” Demo。

<Antd component="Alert" title="以下常见问题均适用于 Tooltip、Popconfirm、Popover 组件" type="warning" banner="true"></Antd>

为何在严格模式中有时候会出现 findDOMNode is deprecated 这个警告？

这是由于 @rc-component/trigger 的实现方式导致的，@rc-component/trigger 强制要求 children 能够接受 ref，否则就会 fallback 到 findDOMNode，所以 children 需要是原生 html 标签，如果不是，则需要使用 React.forwardRef 把 ref 透传到原生 html 标签。

• findDOMNode is deprecated 重现：https://codesandbox.io/p/sandbox/finddomnode-c5hy96
• 使用 forwardRef 消除警告：https://codesandbox.io/p/sandbox/no-finddomnode-warning-forked-gdxczs

为什么自定义子组件无法正常工作？

类似问题: #15909, #12812。

请确保子元素能接受 onMouseEnter、onMouseLeave、onPointerEnter、onPointerLeave、onFocus、onClick 事件。参考示例

placement 的行为逻辑是什么？

当屏幕空间足够时，会按照 placement 的设置进行弹层。当空间不足时则会取反向位置进行弹层（例如 top 不够时，会改为 bottom，topLeft 不够时会改为 bottomLeft）。单一方向如 top bottom left right 当贴边时进行自动位移：

当设置为边缘对齐方向如 topLeft bottomRight 等，则会仅做翻转而不做位移。

如何支持键盘无障碍访问？

Tooltip 等组件的默认触发方式（trigger）为 hover，不包含 focus，因此无法响应键盘聚焦事件。如果你希望组件支持键盘操作，可以通过以下方式开启：

• 单个组件开启：将 trigger 属性设置为包含 focus 的值，例如 trigger="focus" 或 trigger={['hover', 'focus']}。
• 全局开启：通过 ConfigProvider 进行全局配置，这样应用内的所有相关组件都会默认支持键盘聚焦触发。

import { ConfigProvider, Tooltip, Button } from 'antd';

// 单个组件
<Tooltip trigger={['hover', 'focus']} title="Title">
  <Button>Button</Button>
</Tooltip>

// 全局配置
<ConfigProvider
  tooltip={{ trigger: ['hover', 'focus'] }}
  popover={{ trigger: ['hover', 'focus'] }}
  popconfirm={{ trigger: ['hover', 'focus'] }}
>
  <App />
</ConfigProvider>

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

• vendor/components/tooltip/PurePanel.tsx
• vendor/components/tooltip/hook/useMergedArrow.ts
• vendor/components/tooltip/index.tsx
• vendor/components/tooltip/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。