For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/popover.md.

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。

属性类型默认值说明
titleReactNode—浮层标题。
contentReactNode必填浮层内容;交互内容使用点击模式。
childrenReactElement< 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'浮层方向
disabledbooleanfalse禁用交互。
openboolean—受控的展开状态。
defaultOpenbooleanfalse非受控模式的初始展开状态。
onOpenChange(open: boolean) => void—展开状态变化
autoFocusbooleantrue点击模式打开后聚焦首个可聚焦元素,没有时聚焦面板;悬停模式不移动焦点。
aria-labelstring—没有可见标题时,提供浮层的可访问名称。
widthnumber | string'max-content'浮层宽度;数字为像素。
maxWidthnumber | string320浮层最大宽度;数字为像素。
enterDelaynumber100悬停后等待多少毫秒再打开。
leaveDelaynumber100指针离开后等待多少毫秒再关闭。
classNamestring—浮层面板的 CSS 类名。
styleCSSProperties—浮层面板的内联样式。
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。