> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Popover

数据展示`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

在触发器附近展示补充信息或轻量交互内容。

## 何时使用

内容比 Tooltip 更丰富，但不需要完整 Modal 时使用 Popover。

**推荐**

- 选择与触发方式匹配的交互。
- 内容保持紧凑并靠近触发器。

**避免**

- 不要在 Popover 中承载长流程。

## 代码演示


### 基础用法
```tsx preview
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 preview
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 preview
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 preview
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 preview
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 preview
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 preview
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)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` **(必填)** | `-` |

