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

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# Popover 气泡卡片

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

## 触发方式


点击查看悬停查看

basic.tsx

复制代码

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

export function PopoverBasic() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Popover title="项目信息" content="在此查看项目概览和最近更新。">
        <Button variant="outline">点击查看</Button>
      </Popover>
      <Popover
        title="提示"
        trigger="hover"
        placement="right"
        content="这里可以查看项目的更多说明。"
      >
        <Button variant="outline">悬停查看</Button>
      </Popover>
    </Flex>
  );
}
```

展开代码

## 受控编辑


点击编辑

controlled.tsx

复制代码

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

import { useState } from 'react';

export function PopoverControlled() {
  const [open, setOpen] = useState(false);
  return (
    <Popover
      title="编辑项目"
      open={open}
      onOpenChange={setOpen}
      width={260}
      content={
        <Form
          layout="vertical"
          onSubmit={(event) => {
            event.preventDefault();
            setOpen(false);
          }}
        >
          <FormField label="项目名称">
            <Input defaultValue="Leaf Garden" />
          </FormField>
          <Button type="submit">保存并关闭</Button>
        </Form>
      }
    >
      <Button variant="outline">点击编辑</Button>
    </Popover>
  );
}
```

展开代码

## 浮层位置


上方下方左侧右侧

placements.tsx

复制代码

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

export function PopoverPlacements() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      {(['top', 'bottom', 'left', 'right'] as const).map((placement) => (
        <Popover
          key={placement}
          placement={placement}
          title="项目提示"
          content="浮层会根据可用空间调整位置。"
        >
          <Button variant="outline">
            {{ top: '上方', bottom: '下方', left: '左侧', right: '右侧' }[placement]}
          </Button>
        </Popover>
      ))}
    </Flex>
  );
}
```

展开代码

## Popover API

| 属性                        | 类型                                                                                                                                                                   | 默认值                   | 说明                |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------- |
| `children`                | `ReactElement`                                                                                                                                                       | 必填                    | 触发元素，需要支持 ref 与事件 |
| `title / content`         | `ReactNode`                                                                                                                                                          | — / 必填                | 标题 / 内容           |
| `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'`               | 浮层方向              |
| `open / defaultOpen`      | `boolean`                                                                                                                                                            | `false`               | 受控 / 初始展开状态       |
| `onOpenChange`            | `(open: boolean) => void`                                                                                                                                            | —                     | 展开状态变化            |
| `disabled`                | `boolean`                                                                                                                                                            | `false`               | 禁止展开              |
| `autoFocus`               | `boolean`                                                                                                                                                            | `true`                | 点击展开后聚焦第一个操作      |
| `enterDelay / leaveDelay` | `number`                                                                                                                                                             | `100`                 | 悬停展开 / 收起延迟，毫秒    |
| `width / maxWidth`        | `number \| string`                                                                                                                                                   | `'max-content' / 320` | 宽度 / 最大宽度         |
| `className / style`       | `string / CSSProperties`                                                                                                                                             | —                     | 作用于浮层             |

## 类型

定义组件属性或组装列表时可导入相关类型。

```ts
import type { PopoverProps } from '@ifhover/leaf-ui';
```

## 使用说明

点击浮层适合放置交互内容；悬停浮层适合说明文字。Escape、点击外部和移走焦点会收起浮层，交互内容中的 Tab 顺序保持可用。没有标题时请使用 aria-label 提供名称。