> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/popover.html

> 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.

# Popover 气泡卡片

在元素附近展示说明或补充操作。


## 基础用法

点击触发器打开，Escape、点击外部或将焦点移出时关闭。


点击查看

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/popover/basic.tsx"
import { Button, Popover } from '@ifhover/leaf-ui';

export function PopoverBasic() {
  return (
    <Popover title="项目信息" content="在此查看项目概览和最近更新。">
      <Button variant="outline">点击查看</Button>
    </Popover>
  );
}
```

展开代码


## 示例

### 悬停提示

悬停模式适合说明文字，也支持键盘聚焦。含表单或按钮的内容使用默认点击模式。


悬停查看

hover.tsx

复制代码

```tsx lineNumbers file="../../src/examples/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

复制代码

```tsx lineNumbers file="../../src/examples/popover/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

复制代码

```tsx lineNumbers file="../../src/examples/popover/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](https://ifhover.github.io/leaf-ui/api/popup-options.md)。

| 属性                  | 类型                                                                                                                                                                   | 默认值             | 说明                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------------------- |
| `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。          |
