Tooltip#
数据展示
@rockshin/tao-ui在悬停或键盘聚焦时展示简短补充说明。
#何时使用
图标、缩写或控件需要一行辅助解释时使用 Tooltip。
推荐
- 内容保持简短。
- 确保键盘聚焦也能触发。
避免
- 关键说明或交互内容不要只放在 Tooltip 中。
#代码演示
#基础用法
TSX
import { Button, Tooltip } from '@rockshin/tao-ui';
function TooltipExample() {
return (
<Tooltip title="Copy to clipboard">
<Button variant="secondary">Hover or focus</Button>
</Tooltip>
);
}
export default TooltipExample;#弹出位置
TSX
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
function TooltipPlacements() {
return (
<Stack direction="horizontal" gap="md">
<Tooltip title="Top" placement="top">
<Button variant="secondary">Top</Button>
</Tooltip>
<Tooltip title="Bottom" placement="bottom">
<Button variant="secondary">Bottom</Button>
</Tooltip>
<Tooltip title="Left" placement="left">
<Button variant="secondary">Left</Button>
</Tooltip>
<Tooltip title="Right" placement="right">
<Button variant="secondary">Right</Button>
</Tooltip>
</Stack>
);
}
export default TooltipPlacements;#箭头、颜色与受控显示
TSX
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
function TooltipStyles() {
return (
<Stack direction="horizontal" gap="md">
<Tooltip title="No arrow" arrow={false}>
<Button variant="secondary">No arrow</Button>
</Tooltip>
<Tooltip title="Brand color" color="#245b57">
<Button variant="secondary">Custom color</Button>
</Tooltip>
<Tooltip title="Focus also opens this hint">
<Button variant="secondary">Focus for a hint</Button>
</Tooltip>
</Stack>
);
}
export default TooltipStyles;#不显示箭头
arrow=false 去掉指向箭头。
TSX
import { Button, Tooltip } from '@rockshin/tao-ui';
export default function TooltipNoArrow() {
return (
<Tooltip title="No arrow tooltip" arrow={false}>
<Button variant="secondary">No arrow</Button>
</Tooltip>
);
}#受控提示
用 open 与 onOpenChange 同步可见状态。
TSX
import { useState } from 'react';
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
export default function Example() {
const [open, setOpen] = useState(false);
return (
<Stack direction="horizontal">
<Button onClick={() => setOpen(!open)}>
{open ? 'Hide hint' : 'Show hint'}
</Button>
<Tooltip open={open} onOpenChange={setOpen} title="Controlled hint">
<Button>Hint target</Button>
</Tooltip>
</Stack>
);
}#自定义颜色
color 自定义提示背景,使用时保证文字对比度。
TSX
import { Button, Stack, Tooltip } from '@rockshin/tao-ui';
export default function TooltipCustomColor() {
return (
<Stack direction="horizontal" gap="md" align="center">
<Tooltip title="Brand primary" color="#1677ff">
<Button variant="secondary">#1677ff</Button>
</Tooltip>
<Tooltip title="Warm orange" color="#f76b15">
<Button variant="secondary">#f76b15</Button>
</Tooltip>
</Stack>
);
}#悬停延迟
延迟以秒为单位,键盘焦点不等待悬停延迟。
TSX
import { Tooltip, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
<Tooltip
title="Wait 0.6 seconds on hover"
mouseEnterDelay={0.6}
mouseLeaveDelay={0.2}
>
<Button>Hover or focus</Button>
</Tooltip>
);
}#条件提示
title 为空时禁用提示,适合仅在需要解释时显示。
TSX
import { useState } from 'react';
import { Tooltip, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [enabled, setEnabled] = useState(true);
return (
<Stack direction="vertical">
<Button onClick={() => setEnabled(!enabled)}>
{enabled ? 'Disable hint' : 'Enable hint'}
</Button>
<Tooltip title={enabled ? 'Additional information' : null}>
<Button>Hint target</Button>
</Tooltip>
</Stack>
);
}#API
#Tooltip
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | Tooltip content. Empty strings, booleans, null and undefined disable it. | ReactNode | - |
| placement | Popup side relative to the trigger. Defaults to 'top'. | TooltipPlacement | undefined | - |
| arrow | Show the arrow pointing at the trigger. Defaults to true. | boolean | undefined | - |
| mouseEnterDelay | Hover delay in seconds before opening. Defaults to 0.1. Focus opens immediately. | number | undefined | - |
| mouseLeaveDelay | Delay in seconds before a pointer-leave closes the tooltip. Defaults to 0.1 (antd parity) — re-entering the trigger or content before the deadline cancels the close. Esc / focus-blur closes stay immediate. | number | undefined | - |
| color | Custom content background color. | string | undefined | - |
| className | 节点类名 | string | undefined | - |
| style | 节点样式 | CSSProperties | undefined | - |
| children | Exactly one trigger element. | ReactNode (必填) | - |