Popover

Popover 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 Popover 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，Popover 由独立的多个组件组成：

1import { Popover, PopoverTrigger, PopoverContent, Button } from "@lenso/ui";2
3export default function App() {4  return (5    <Popover placement="right">6      <PopoverTrigger>7        <Button>Open</Button>8      </PopoverTrigger>9      <PopoverContent>10        <div>Content</div>11      </PopoverContent>12    </Popover>13  );14}

在 v3 中，Popover 改为复合组件：

1import { Popover, Button } from "@lenso/ui";2
3export default function App() {4  return (5    <Popover>6      <Button>Open</Button>7      <Popover.Content>8        <Popover.Dialog>9          <Popover.Heading>Title</Popover.Heading>10          <div>Content</div>11        </Popover.Dialog>12      </Popover.Content>13    </Popover>14  );15}

主要变化

1. 组件结构

v2： 独立的多个组件（Popover、PopoverTrigger、PopoverContent）
v3： 复合组件（Popover、Popover.Trigger、Popover.Content、Popover.Dialog、Popover.Heading、Popover.Arrow）

2. Prop 变更

v2 prop	v3 位置	说明
`placement`	`placement`（在 Content 上）	移至 `Popover.Content`
`offset`	`offset`（在 Content 上）	移至 `Popover.Content`
`shouldFlip`	`shouldFlip`（在 Content 上）	移至 `Popover.Content`
`isOpen` / `defaultOpen` / `onOpenChange`	同名（在根上）	受控状态仍保留在根 `Popover` 上
`showArrow`	—	改用 `Popover.Arrow` 子组件
`size`	—	已移除（请改用 Tailwind CSS）
`color`	—	已移除（请改用 Tailwind CSS）
`radius`	—	已移除（请改用 Tailwind CSS）
`shadow`	—	已移除（请改用 Tailwind CSS）
`backdrop`	—	已移除
`motionProps`	—	已移除（动画机制已不同）
`classNames`	—	改在各子组件上使用 `className`
`onClose`	—	改用 `onOpenChange((open) => { if (!open) { ... } })`

迁移示例

内容配置

1{/* With arrow */}2<Popover showArrow>3  <PopoverTrigger><Button>Open</Button></PopoverTrigger>4  <PopoverContent><div>Content</div></PopoverContent>5</Popover>6
7{/* With placement */}8<Popover placement="top">9  <PopoverTrigger><Button>Open</Button></PopoverTrigger>10  <PopoverContent><div>Content</div></PopoverContent>11</Popover>12
13{/* With offset */}14<Popover offset={10}>15  <PopoverTrigger><Button>Open</Button></PopoverTrigger>16  <PopoverContent><div>Content</div></PopoverContent>17</Popover>

带标题

1<PopoverContent>2  <div className="px-1 py-2">3    <div className="text-small font-bold">Title</div>4    <div className="text-tiny">Content</div>5  </div>6</PopoverContent>

受控

1import { useState } from "react";2
3const [isOpen, setIsOpen] = useState(false);4
5<Popover isOpen={isOpen} onOpenChange={setIsOpen}>6  <PopoverTrigger>7    <Button>Open</Button>8  </PopoverTrigger>9  <PopoverContent>10    <div>Content</div>11  </PopoverContent>12</Popover>

自定义触发器

1<PopoverTrigger>2  <CustomButton>Custom</CustomButton>3</PopoverTrigger>

组件结构

v3 Popover 遵循以下结构：

1Popover (Root)2  ├── Popover.Trigger (optional, or use Button directly)3  └── Popover.Content4      └── Popover.Dialog5          ├── Popover.Arrow (optional)6          ├── Popover.Heading (optional)7          └── Content

v3 中的新功能

Popover.Arrow 组件

在 v2 中，箭头通过根 Popover 上的 showArrow 布尔 prop 控制。在 v3 中，Popover.Arrow 是一个放置在 Popover.Content 内部的专用组件，让你可以完全控制其渲染：

1<Popover>2  <Button>Open</Button>3  <Popover.Content>4    <Popover.Arrow className="custom-arrow" />5    <Popover.Dialog>6      <div>Content</div>7    </Popover.Dialog>8  </Popover.Content>9</Popover>

Popover.Arrow 也接受 render prop，可完全自定义箭头的渲染。

受控打开状态

受控的打开状态仍保留在根 Popover 组件上，prop 名称与 v2 一致：

属性	类型	默认值	描述
`isOpen`	`boolean`	-	控制 Popover 的可见性（受控）
`defaultOpen`	`boolean`	`false`	初始打开状态（非受控）
`onOpenChange`	`(isOpen: boolean) => void`	-	打开状态变化时触发

自定义渲染函数

Popover.Content 与 Popover.Arrow 都支持 render prop，让你可以在高级场景下用自定义渲染函数覆盖默认 DOM 元素。

总结

组件结构：必须使用复合组件（Popover.Content、Popover.Dialog 等）
触发器：可以使用 Popover.Trigger，或直接将 Button 作为子节点
内容包装：内容必须放在 Popover.Dialog 中
箭头：移除 showArrow prop——改用 Popover.Arrow 子组件
标题：改用 Popover.Heading 组件
prop 移动位置：placement、offset、shouldFlip 移到 Popover.Content 上
移除样式 prop：size、color、radius、shadow —— 请改用 Tailwind CSS
移除 backdrop：backdrop prop 已移除
移除 motion：motionProps 已移除，动画机制已不同
移除 classNames：改在各子组件上使用 className prop