Modal

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

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

结构变化

在 v2 中，Modal 使用相互独立的组件：

1import { Modal, ModalContent, ModalHeader, ModalBody, ModalFooter, Button, useDisclosure } from "@lenso/ui";2
3export default function App() {4  const {isOpen, onOpen, onOpenChange} = useDisclosure();5
6  return (7    <>8      <Button onPress={onOpen}>Open Modal</Button>9      <Modal isOpen={isOpen} onOpenChange={onOpenChange}>10        <ModalContent>11          <ModalHeader>Title</ModalHeader>12          <ModalBody>Content</ModalBody>13          <ModalFooter>Footer</ModalFooter>14        </ModalContent>15      </Modal>16    </>17  );18}

在 v3 中，Modal 使用复合组件：

1import { Modal, Button } from "@lenso/ui";2
3export default function App() {4  return (5    <Modal>6      <Button>Open Modal</Button>7      <Modal.Backdrop>8        <Modal.Container>9          <Modal.Dialog>10            <Modal.CloseTrigger />11            <Modal.Header>12              <Modal.Heading>Title</Modal.Heading>13            </Modal.Header>14            <Modal.Body>Content</Modal.Body>15            <Modal.Footer>Footer</Modal.Footer>16          </Modal.Dialog>17        </Modal.Container>18      </Modal.Backdrop>19    </Modal>20  );21}

主要变化

1. 组件结构

v2： 相互独立的组件（Modal、ModalContent、ModalHeader、ModalBody、ModalFooter）
v3： 复合组件（Modal.Backdrop、Modal.Container、Modal.Dialog、Modal.Header、Modal.Body、Modal.Footer）

2. 内置触发：`Modal.Trigger`

v2： 需要 useDisclosure，并手动把 onPress 接到打开逻辑上。
v3： 提供 Modal.Trigger 作为内置触发组件，按下即可自动打开模态框，无需自行管理状态。

1import { Modal, ModalContent, Button, useDisclosure } from "@lenso/ui";2
3const {isOpen, onOpen, onOpenChange} = useDisclosure();4
5<Button onPress={onOpen}>Open Modal</Button>6<Modal isOpen={isOpen} onOpenChange={onOpenChange}>7  <ModalContent>{/* content */}</ModalContent>8</Modal>

Modal.Trigger 会把任意内容包装成可按压元素以打开模态框。当你需要标准 Button 以外的自定义触发元素时使用它。

3. 状态管理

v2： 使用 useDisclosure。
v3： 内置触发场景下可不需要状态；也可在 Modal.Backdrop 上用受控的 isOpen / onOpenChange，或使用 useOverlayState 并把 state 传给根组件。

`useOverlayState` 替代 `useDisclosure`

useOverlayState 可直接替代 v2 的 useDisclosure，支持受控与非受控：

1import { useOverlayState } from "@lenso/ui";2
3// 非受控（内部自管状态）4const state = useOverlayState();5
6// 非受控且默认打开7const state = useOverlayState({ defaultOpen: true });8
9// 带回调10const state = useOverlayState({11  onOpenChange: (isOpen) => console.log("Modal is now:", isOpen),12});13
14// 受控（由你管理状态）15const [isOpen, setIsOpen] = useState(false);16const state = useOverlayState({ isOpen, onOpenChange: setIsOpen });

Hook API：

属性	类型	说明
`state.isOpen`	`boolean`	浮层当前是否打开
`state.open()`	`() => void`	打开浮层
`state.close()`	`() => void`	关闭浮层
`state.toggle()`	`() => void`	切换打开/关闭
`state.setOpen(isOpen)`	`(isOpen: boolean) => void`	直接设置打开状态

将 state 传给 Modal 根组件以完成连接：

1const state = useOverlayState();2
3<Modal state={state}>4  <Button onPress={state.open}>Open</Button>5  <Modal.Backdrop>6    <Modal.Container>7      <Modal.Dialog>{/* content */}</Modal.Dialog>8    </Modal.Container>9  </Modal.Backdrop>10</Modal>

从 useDisclosure 迁移到 useOverlayState 的更多细节，请参阅 Hooks 迁移指南。

4. Prop 变更

v2 prop	v3 位置	说明
`size`	`size`（在 `Modal.Container`）	简化取值（xs、sm、md、lg、cover、full）
`radius`	—	已移除（请用 Tailwind CSS）
`shadow`	—	已移除（请用 Tailwind CSS）
`backdrop`	`variant`（在 `Modal.Backdrop`）	已重命名；取值不变（`opaque`、`blur`、`transparent`）
`scrollBehavior`	`scroll`（在 `Modal.Container`）	已重命名（`normal` → `inside`）
`placement`	`placement`（在 `Modal.Container`）	移到 Container
`isDismissable`	`isDismissable`（在 `Modal.Backdrop`）	移到 `Modal.Backdrop`
`isKeyboardDismissDisabled`	`isKeyboardDismissDisabled`（在 `Modal.Backdrop`）	移到 `Modal.Backdrop`
`isOpen`	`isOpen`（在 `Modal.Backdrop`）	受控状态在 `Modal.Backdrop`
`onOpenChange`	`onOpenChange`（在 `Modal.Backdrop`）	同上
`onClose`	—	使用渲染 prop 提供的 `close`
`hideCloseButton`	—	省略 `Modal.CloseTrigger` 即可
`closeButton`	—	使用 `Modal.CloseTrigger` 自定义内容
`motionProps`	—	已移除（动画机制已不同）
`classNames`	—	在各子组件上使用 `className`
`shouldBlockScroll`	—	已移除（由组件自动处理）
`portalContainer`	—	已移除

迁移示例

1import { useDisclosure } from "@lenso/ui";2
3const {isOpen, onOpen, onOpenChange} = useDisclosure();4
5<Modal isOpen={isOpen} onOpenChange={onOpenChange}>6  <ModalContent>7    {(onClose) => (8      <>9        <ModalHeader>Title</ModalHeader>10        <ModalBody>Content</ModalBody>11      </>12    )}13  </ModalContent>14</Modal>

useDisclosure → useOverlayState 的完整迁移说明，请参阅 Hooks 迁移指南。

遮罩与 Container 的 prop

1{/* Backdrop */}2<Modal backdrop="blur">3  <ModalContent>{/* content */}</ModalContent>4</Modal>5
6{/* Placement */}7<Modal placement="top">8  <ModalContent>{/* content */}</ModalContent>9</Modal>10
11{/* Scroll behavior */}12<Modal scrollBehavior="outside">13  <ModalContent>{/* content */}</ModalContent>14</Modal>

关闭按钮

1{/* Without close button */}2<Modal hideCloseButton>3  <ModalContent>{/* content */}</ModalContent>4</Modal>5
6{/* Custom close button */}7<Modal closeButton={<CustomCloseIcon />}>8  <ModalContent>{/* content */}</ModalContent>9</Modal>

自定义触发器

1import { Modal, ModalContent, useDisclosure } from "@lenso/ui";2
3const {isOpen, onOpen, onOpenChange} = useDisclosure();4
5{/* Any element needed manual onPress + useDisclosure */}6<div onClick={onOpen} className="cursor-pointer rounded-xl bg-surface p-4">7  <p className="font-semibold">Settings</p>8  <p className="text-xs text-muted">Manage your preferences</p>9</div>10<Modal isOpen={isOpen} onOpenChange={onOpenChange}>11  <ModalContent>{/* content */}</ModalContent>12</Modal>

图标与标题

1<ModalHeader className="flex flex-col gap-1">2  <Icon />3  Modal Title4</ModalHeader>

组件结构（Anatomy）

v3 的 Modal 结构如下：

1Modal (Root)2  ├── Trigger (e.g. Button or Modal.Trigger)3  └── Modal.Backdrop (variant, isDismissable, isKeyboardDismissDisabled)4      └── Modal.Container (placement, scroll, size)5          └── Modal.Dialog6              ├── Modal.CloseTrigger (optional)7              ├── Modal.Header8              │   ├── Modal.Icon (optional)9              │   └── Modal.Heading10              ├── Modal.Body11              └── Modal.Footer

总结

组件结构：必须使用复合组件（Modal.Container、Modal.Dialog 等）。
内置触发：自定义触发用 Modal.Trigger；或将 Button 作为 Modal 的直接子元素，无需再手动接线状态。
状态管理：useDisclosure 由 useOverlayState 替代；支持受控/非受控，并支持根 Modal 的 state prop。
prop 迁移：许多 prop 从 Modal 移到 Modal.Backdrop 与 Modal.Container。
关闭回调：onClose 由 Modal.Dialog 渲染 prop 中的 close 替代。
关闭按钮：hideCloseButton / closeButton 由 Modal.CloseTrigger 组合方式替代。
尺寸：在 Modal.Container 上使用 size（xs、sm、md、lg、cover、full）；radius 与 shadow 已移除，请用 Tailwind CSS。
遮罩：backdrop → Modal.Backdrop 上的 variant（opaque、blur、transparent）。
滚动 prop 重命名：scrollBehavior → scroll（normal → inside）。
动画：motionProps 已移除，动画机制已变化。
新增子组件：Modal.Trigger、Modal.Icon、Modal.Heading、Modal.CloseTrigger。