Tooltip
基础反馈基于 Bootstrap 5 的提示气泡组件，Tooltip 渲染标准的气泡结构（.tooltip > .tooltip-arrow + .tooltip-inner），TooltipTrigger 负责触发、延迟、动画与定位，支持四个方向与对齐变体、HTML 内容、CSS 变量定制、click/hover/focus/manual 触发、受控模式、禁用元素与视口翻转
Component Demo
Basic usage and examples of the Tooltip component
基础用法
默认 trigger 为 `['hover', 'focus']`，悬停或聚焦按钮显示提示；空内容不渲染，与 Bootstrap 的「零长度标题不显示」行为一致
四个方向
placement 支持 `top`/`right`/`bottom`/`left` 四个方向，RTL 布局下方向自动镜像
对齐变体
每个方向都支持 `-start`/`-end` 对齐变体，与 Bootstrap 的 placement 选项一致
HTML 内容
title 是 ReactNode，天然支持富文本内容，无需 Bootstrap 的 `html` 选项
自定义样式
customClass 对应 Bootstrap 的 `customClass` 选项，配合 `--bs-tooltip-bg` 等 CSS 变量即可定制外观
禁用元素
禁用元素不触发鼠标事件，需将触发元素包裹在带 `tabIndex=0` 的 `span` 中；给禁用按钮设置 `pointer-events: none` 可让鼠标事件穿透到外层 span（与 Bootstrap 文档一致）
触发方式
`click`/`focus`/`hover` 可单独使用或组合，`manual` 则完全由 `show` 属性控制；提示显示时按 Esc 可关闭
延迟与动画
delay 传入数字同时作用于显示与隐藏，或传 `{ show, hide }` 分别设置；动画基于 Bootstrap 的 `fade` 类，并自动响应系统的减少动态效果设置
定位配置
定位基于 `src/utils/position.ts` 计算：offset 调整与触发元素的间距，padding 约束与视口边缘的 距离，flip 控制靠近视口边缘时是否翻转方向
受控模式
传入 `show` 后组件变为受控，配合 `trigger="manual"` 完全由外部状态控制显示
单独使用
Tooltip 单独渲染气泡结构，与 Bootstrap 生成的结构一致（`.tooltip` 包含 `.tooltip-arrow` 与 `.tooltip-inner`），也可作为 `overlay` 传给 TooltipTrigger
API Documentation
Complete API reference for the Tooltip component
Props
Tooltip
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
animation | boolean | true | 是否渲染 `fade` 类，配合 TooltipTrigger 播放淡入淡出过渡动画 |
arrowProps | HTMLAttributes | - | 透传给箭头元素（`.tooltip-arrow`）的属性 |
as | ElementType | 'div' | 根元素标签 |
children | ReactNode | - | 提示内容，渲染在 `.tooltip-inner` 内 |
className | string | - | 自定义类名，对应 Bootstrap 的 `customClass` 选项 |
flip | boolean | true | `true` 渲染 `bs-tooltip-auto` 类；`false` 渲染 `bs-tooltip-{placement}` 静态类。箭头方向始终随 `data-popper-placement`（当前实际位置）变化 |
id | string | - | 提示元素 id，供触发元素的 `aria-describedby` 引用 |
placement | Placement | 'top' | 展示位置，仅影响类名与箭头方向，实际定位由 TooltipTrigger 完成 |
show | boolean | true | 是否显示，渲染 `show` 类（配合 `fade` 播放透明度过渡） |
TooltipTrigger
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
animation | boolean | true | 是否启用淡入淡出动画，系统开启减少动态效果（prefers-reduced-motion）时自动禁用 |
children | ReactElement | - | 单个触发元素，组件会克隆该元素并注入触发事件与 `aria-describedby` |
customClass | string | - | 提示气泡上的自定义类名，可用于通过 CSS 变量定制外观 |
defaultShow | boolean | false | 非受控模式下的初始显示状态 |
delay | number | TooltipDelay | 0 | 显示/隐藏延迟（毫秒），传入数字同时作用于两者，或传 `{ show, hide }` 分别设置 |
disabled | boolean | false | 是否禁用触发，等价于 Bootstrap 的 `disable()` 方法 |
flip | boolean | true | 靠近视口边缘时是否自动翻转方向 |
id | string | - | 提示元素 id，缺省时自动生成 |
offset | [number, number] | '[0, 6]' | 定位偏移 `[水平偏移, 间距]` 元组，对应 Bootstrap 的 `offset` 选项 |
onToggle | (nextShow: boolean) => void | - | 显示状态变化回调，配合 `show` 实现受控模式 |
overlay | ReactElement | - | 自定义覆盖元素（如 `<Tooltip id="...">`），与 `title` 二选一，需支持注入 ref、`show`、`placement`、`id` |
padding | number | 2 | 提示与视口边缘的最小距离（像素） |
placement | Placement | 'top' | 期望的显示位置，支持 `top`/`right`/`bottom`/`left` 及 `-start`/`-end` 对齐变体 |
show | boolean | - | 受控的显示状态，需配合 `onToggle` 更新 |
title | ReactNode | - | 提示内容（简写形式），空内容不显示（与 Bootstrap 一致） |
trigger | TooltipTriggerType | TooltipTriggerType[] | ['hover', 'focus'] | 触发方式：`click`/`hover`/`focus`/`manual`，可传入数组组合 |
Type Definitions
TooltipDelay
显示/隐藏延迟配置
export interface TooltipDelay {
hide?: number;
show?: number;
}TooltipProps
提示气泡组件属性接口
export interface TooltipProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
animation?: boolean;
arrowProps?: HTMLAttributes<HTMLElement>;
as?: ElementType;
children?: ReactNode;
className?: string;
flip?: boolean;
id?: string;
placement?: Placement;
show?: boolean;
}TooltipTriggerProps
提示触发器组件属性接口
export interface TooltipTriggerProps {
animation?: boolean;
children: ReactElement;
customClass?: string;
defaultShow?: boolean;
delay?: number | TooltipDelay;
disabled?: boolean;
flip?: boolean;
id?: string;
offset?: readonly [number, number];
onToggle?: (nextShow: boolean) => void;
overlay?: ReactElement;
padding?: number;
placement?: Placement;
show?: boolean;
title?: ReactNode;
trigger?: TooltipTriggerType | TooltipTriggerType[];
}TooltipTriggerType
触发方式类型
export type TooltipTriggerType = 'click' | 'focus' | 'hover' | 'manual';