Popover#
数据展示
@rockshin/tao-ui在触发器附近展示补充信息或轻量交互内容。
#何时使用
内容比 Tooltip 更丰富,但不需要完整 Modal 时使用 Popover。
推荐
- 选择与触发方式匹配的交互。
- 内容保持紧凑并靠近触发器。
避免
- 不要在 Popover 中承载长流程。
#代码演示
#基础用法
TSX
import { Button, Popover } from '@rockshin/tao-ui';
function PopoverExample() {
return (
<Popover
trigger="click"
title="Deployment"
content="Production was updated 2 minutes ago."
>
<Button variant="secondary">View status</Button>
</Popover>
);
}
export default PopoverExample;#悬停、聚焦与点击
TSX
import { Button, Popover, Stack } from '@rockshin/tao-ui';
function PopoverTriggers() {
return (
<Stack direction="horizontal" gap="md">
<Popover title="Hover" content="Opens on pointer hover.">
<Button variant="secondary">Hover</Button>
</Popover>
<Popover
trigger="focus"
title="Focus"
content="Opens from keyboard focus."
>
<Button variant="secondary">Focus</Button>
</Popover>
<Popover
trigger="click"
title="Click"
content="Opens and closes on click."
>
<Button variant="secondary">Click</Button>
</Popover>
</Stack>
);
}
export default PopoverTriggers;#弹出位置与箭头
TSX
import { Button, Popover, Stack } from '@rockshin/tao-ui';
function PopoverPlacements() {
return (
<Stack direction="horizontal" gap="md">
<Popover
placement="topLeft"
title="Top left"
content="Aligned to the left edge."
>
<Button variant="secondary">Top left</Button>
</Popover>
<Popover
placement="bottom"
title="Bottom"
content="Centered below the trigger."
>
<Button variant="secondary">Bottom</Button>
</Popover>
<Popover
placement="right"
arrow={false}
title="No arrow"
content="Arrow disabled."
>
<Button variant="secondary">Right</Button>
</Popover>
</Stack>
);
}
export default PopoverPlacements;#受控弹层与内部关闭
内容中的按钮可以更新 open,完成后明确关闭弹层。
TSX
import { useState } from 'react';
import { Popover, Button } from '@rockshin/tao-ui';
export default function Example() {
const [open, setOpen] = useState(false);
return (
<Popover
trigger="click"
title="Quick action"
open={open}
onOpenChange={setOpen}
content={<Button onClick={() => setOpen(false)}>Done</Button>}
>
<Button>Open actions</Button>
</Popover>
);
}#键盘焦点触发
trigger=focus 可用于键盘聚焦时展示辅助内容,关键说明也应在页面可见。
TSX
import { Popover, Input } from '@rockshin/tao-ui';
export default function Example() {
return (
<Popover
trigger="focus"
title="Project code"
content="Use a short, recognizable identifier."
>
<Input aria-label="Project code" placeholder="Focus this input" />
</Popover>
);
}#箭头与延迟
悬停延迟使用秒,arrow 控制是否展示箭头。
TSX
import { Popover, Button } from '@rockshin/tao-ui';
export default function Example() {
return (
<Popover
title="Details"
content="Additional context appears after a short delay."
arrow={false}
mouseEnterDelay={0.4}
mouseLeaveDelay={0.2}
>
<Button>Hover for details</Button>
</Popover>
);
}#弹层中的表单
弹层可以容纳输入和操作;提交后反馈结果并关闭。
TSX
import { useState } from 'react';
import { Popover, Input, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [open, setOpen] = useState(false);
const [name, setName] = useState('Workspace');
return (
<Stack direction="vertical">
<Popover
trigger="click"
open={open}
onOpenChange={setOpen}
title="Rename"
content={
<form
onSubmit={(e) => {
e.preventDefault();
setName(String(new FormData(e.currentTarget).get('name')));
setOpen(false);
}}
>
<Stack direction="vertical">
<Input
name="name"
aria-label="New name"
defaultValue={name}
required
/>
<Button type="submit">Save name</Button>
</Stack>
</form>
}
>
<Button>Rename project</Button>
</Popover>
<output>{name}</output>
</Stack>
);
}#API
#Popover
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | Header content of the popup. | PopoverRender | - |
| content | Body content of the popup. | PopoverRender | - |
| trigger | How the popup opens. Defaults to 'hover'. | PopoverTrigger | PopoverTrigger[] | undefined | hover |
| placement | Popup position relative to the trigger. Defaults to 'top'. | PopoverPlacement | undefined | top |
| mouseEnterDelay | Hover delay in seconds before opening. Defaults to 0.1. | number | undefined | 0.1 |
| mouseLeaveDelay | Hover delay in seconds before closing. Defaults to 0.1. | number | undefined | 0.1 |
| arrow | Show a pointing arrow on the popup. Defaults to true. | boolean | { pointAtCenter?: boolean | undefined; } | undefined | true |
| destroyOnHidden | Unmount the popup content while closed. Defaults to false. | boolean | undefined | - |
| destroyTooltipOnHide | @deprecated Use destroyOnHidden instead. | boolean | undefined | - |
| className | Merged onto the popup root. | string | undefined | - |
| style | 节点样式 | CSSProperties | undefined | - |
| children | Exactly one trigger element. | ReactNode (必填) | - |