#Tooltip 文字提示
为页面元素补充简短说明。
#基础用法
悬停或键盘聚焦可展示提示,Escape 关闭。提示只放简短说明;需要交互内容时使用 Popover。
basic.tsx
import { Button, Tooltip } from '@ifhover/leaf-ui';
export function TooltipBasic() {
return (
<Tooltip content="保存当前项目的修改">
<Button variant="outline">保存</Button>
</Tooltip>
);
}
#示例
#提示位置
通过 placement 设置期望位置,空间不足时会自动调整。
上方
下方
左侧
右侧
placements.tsx
import { Button, Flex, Grid, Text, Tooltip } from '@ifhover/leaf-ui';
const placements = [
{ placement: 'top', label: '上方' },
{ placement: 'bottom', label: '下方' },
{ placement: 'left', label: '左侧' },
{ placement: 'right', label: '右侧' },
] as const;
export function TooltipPlacements() {
return (
<Flex direction="column" gap="md">
{placements.map(({ placement, label }) => (
<Grid
key={placement}
role="group"
aria-label={label}
columns={{ xs: 1, sm: 2 }}
gap="8px"
align="center"
>
<Text tone="muted">{label}</Text>
<Tooltip placement={placement} content="保存当前项目的修改">
<Button variant="outline">保存</Button>
</Tooltip>
</Grid>
))}
</Flex>
);
}
#禁用提示
Tooltip 的 disabled 只关闭提示,不会禁用按钮。禁用按钮本身不能接收焦点;如需解释原因,可使用外层可聚焦的元素作为提示触发器。
默认
禁用提示
disabled.tsx
import { Button, Flex, Grid, Text, Tooltip } from '@ifhover/leaf-ui';
const states = [
{ disabled: false, label: '默认' },
{ disabled: true, label: '禁用提示' },
];
export function TooltipDisabled() {
return (
<Flex direction="column" gap="md">
{states.map(({ disabled, label }) => (
<Grid
key={label}
role="group"
aria-label={label}
columns={{ xs: 1, sm: 2 }}
gap="8px"
align="center"
>
<Text tone="muted">{label}</Text>
<Flex align="start">
<Tooltip content="保存当前项目的修改" disabled={disabled}>
<Button variant="outline">保存</Button>
</Tooltip>
</Flex>
</Grid>
))}
</Flex>
);
}
#受控展开
使用 open 与 onOpenChange 管理显示状态。不传 open 时,defaultOpen 只设置初始状态。
controlled.tsx
import { Button, Flex, Tooltip } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function TooltipControlled() {
const [open, setOpen] = useState(false);
return (
<Flex gap="sm" align="center" wrap>
<Tooltip content="该设置应用于当前项目" open={open} onOpenChange={setOpen}>
<Button variant="outline">查看说明</Button>
</Tooltip>
<Button variant="outline" onClick={() => setOpen(true)}>
展开提示
</Button>
<Button variant="outline" onClick={() => setOpen(false)}>
收起提示
</Button>
</Flex>
);
}
#API
#Tooltip API
配置提示内容、出现位置和展开方式。
触发元素需透传 ref 与事件;现有的 aria-describedby 会与提示关联合并。共享浮层参数见 PopupOptions。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content | ReactNode | 必填 | 提示内容;为空字符串、null 或 undefined 时不显示。 |
children | ReactElement< HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement>; disabled?: boolean } > | 必填 | 触发元素,需支持 ref 和事件 |
placement | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'top' | 期望展示位置,空间不足时自动调整 |
arrow | boolean | true | 是否显示指向触发元素的箭头。 |
disabled | boolean | false | 禁止显示提示,不禁用触发元素。 |
open | boolean | — | 受控的展开状态。 |
defaultOpen | boolean | false | 非受控模式的初始展开状态。 |
onOpenChange | (open: boolean) => void | — | 展开状态变化 |
enterDelay | number | 100 | 悬停后等待多少毫秒再打开。 |
leaveDelay | number | 100 | 指针离开后等待多少毫秒再关闭。 |
className | string | — | 提示浮层类名 |
popupPlacement | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | — | 浮层相对触发控件的位置。 |
popupClassName | string | — | 浮层的自定义类名。 |
popupStyle | CSSProperties | — | 浮层的自定义样式。 |
popupRender | (content: React.ReactNode) => React.ReactNode | — | 包装或补充面板内容,保留传入的内容以维持交互。 |
getPopupContainer | () => Element | DocumentFragment | — | 返回浮层的挂载容器,也可返回 ShadowRoot。 |