#Popover 气泡卡片
在元素附近展示说明或补充操作。
#基础用法
点击触发器打开,Escape、点击外部或将焦点移出时关闭。
basic.tsx
import { Button, Popover } from '@ifhover/leaf-ui';
export function PopoverBasic() {
return (
<Popover title="项目信息" content="在此查看项目概览和最近更新。">
<Button variant="outline">点击查看</Button>
</Popover>
);
}
#示例
#悬停提示
悬停模式适合说明文字,也支持键盘聚焦。含表单或按钮的内容使用默认点击模式。
hover.tsx
import { Button, Popover } from '@ifhover/leaf-ui';
export function PopoverHover() {
return (
<Popover title="项目信息" content="在此查看项目概览和最近更新。" trigger="hover">
<Button variant="outline">悬停查看</Button>
</Popover>
);
}
#受控编辑
通过 open 与 onOpenChange 控制显示。示例保存后更新项目名称,未保存就关闭时,下次打开会恢复已保存的值。点击模式默认将焦点移入浮层,保存或按 Escape 关闭后返回触发器。
项目名称: Leaf Garden
controlled.tsx
import { Button, Flex, Form, FormField, Input, Popover, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function PopoverControlled() {
const [open, setOpen] = useState(false);
const [name, setName] = useState('Leaf Garden');
const [draft, setDraft] = useState(name);
return (
<Flex direction="column" gap="md" align="start">
<Popover
title="编辑项目"
width={280}
open={open}
onOpenChange={(next) => {
if (next) setDraft(name);
setOpen(next);
}}
content={
<Form
layout="vertical"
onSubmit={(event) => {
event.preventDefault();
setName(draft.trim());
setOpen(false);
}}
>
<FormField label="项目名称">
<Input
name="projectName"
value={draft}
onChange={(event) => setDraft(event.currentTarget.value)}
required
/>
</FormField>
<Button type="submit" disabled={!draft.trim()}>
保存并关闭
</Button>
</Form>
}
>
<Button variant="outline">编辑项目</Button>
</Popover>
<Text role="status" tone="muted">
项目名称: {name}
</Text>
</Flex>
);
}
#浮层位置
通过 placement 设置期望位置,空间不足时会自动调整。
上方
下方
左侧
右侧
placements.tsx
import { Button, Flex, Grid, Popover, Text } from '@ifhover/leaf-ui';
const placements = [
{ placement: 'top', label: '上方' },
{ placement: 'bottom', label: '下方' },
{ placement: 'left', label: '左侧' },
{ placement: 'right', label: '右侧' },
] as const;
export function PopoverPlacements() {
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>
<Popover placement={placement} title="项目信息" content="在此查看项目概览和最近更新。">
<Button variant="outline">查看详情</Button>
</Popover>
</Grid>
))}
</Flex>
);
}
#API
#Popover API
配置浮层内容、触发方式和受控展开状态。
触发元素需透传 ref 与事件。没有 title 时,通过 aria-label 为浮层提供名称。Tab 可以离开浮层,不会将焦点限制在其中。共享浮层参数见 PopupOptions。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | ReactNode | — | 浮层标题。 |
content | ReactNode | 必填 | 浮层内容;交互内容使用点击模式。 |
children | ReactElement< HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement>; disabled?: boolean } > | 必填 | 触发元素,需要支持 ref 与事件 |
trigger | 'click' | 'hover' | 'click' | 触发方式 |
placement | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'top' | 浮层方向 |
disabled | boolean | false | 禁用交互。 |
open | boolean | — | 受控的展开状态。 |
defaultOpen | boolean | false | 非受控模式的初始展开状态。 |
onOpenChange | (open: boolean) => void | — | 展开状态变化 |
autoFocus | boolean | true | 点击模式打开后聚焦首个可聚焦元素,没有时聚焦面板;悬停模式不移动焦点。 |
aria-label | string | — | 没有可见标题时,提供浮层的可访问名称。 |
width | number | string | 'max-content' | 浮层宽度;数字为像素。 |
maxWidth | number | string | 320 | 浮层最大宽度;数字为像素。 |
enterDelay | number | 100 | 悬停后等待多少毫秒再打开。 |
leaveDelay | number | 100 | 指针离开后等待多少毫秒再关闭。 |
className | string | — | 浮层面板的 CSS 类名。 |
style | CSSProperties | — | 浮层面板的内联样式。 |
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。 |