Drawer

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

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

结构变化

在 v2 中，Drawer 与 Modal 共享相同的 API，使用 DrawerContent、DrawerHeader、DrawerBody 和 DrawerFooter，并采用渲染回调模式：

1import { Drawer, DrawerContent, DrawerHeader, DrawerBody, DrawerFooter, 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 Drawer</Button>9      <Drawer isOpen={isOpen} onOpenChange={onOpenChange} placement="right">10        <DrawerContent>11          {(onClose) => (12            <>13              <DrawerHeader>Drawer Title</DrawerHeader>14              <DrawerBody>15                <p>Drawer content goes here.</p>16              </DrawerBody>17              <DrawerFooter>18                <Button onPress={onClose}>Close</Button>19              </DrawerFooter>20            </>21          )}22        </DrawerContent>23      </Drawer>24    </>25  );26}

在 v3 中，Drawer 改用复合组件模式，提供显式子组件与内置触发器支持：

1import { Drawer, Button } from "@lenso/ui";2
3export default function App() {4  return (5    <Drawer>6      <Button>Open Drawer</Button>7      <Drawer.Backdrop>8        <Drawer.Content placement="right">9          <Drawer.Dialog>10            <Drawer.Handle />11            <Drawer.CloseTrigger />12            <Drawer.Header>13              <Drawer.Heading>Drawer Title</Drawer.Heading>14            </Drawer.Header>15            <Drawer.Body>16              <p>Drawer content goes here.</p>17            </Drawer.Body>18            <Drawer.Footer>19              <Button slot="close">Close</Button>20            </Drawer.Footer>21          </Drawer.Dialog>22        </Drawer.Content>23      </Drawer.Backdrop>24    </Drawer>25  );26}

主要变化

1. 组件结构

v2： Drawer 包裹 DrawerContent，并使用渲染回调模式；触发器需要通过 useDisclosure 单独管理
v3： 复合组件：Drawer、Drawer.Backdrop、Drawer.Content、Drawer.Dialog、Drawer.Header、Drawer.Heading、Drawer.Body、Drawer.Footer、Drawer.Handle、Drawer.CloseTrigger。Drawer 的第一个子节点会成为触发器。

2. 触发模式

v2： 使用外部触发器，并通过 useDisclosure 钩子与 isOpen / onOpenChange 管理状态
v3： 内置触发器，Drawer 的第一个子节点会自动成为触发器。受控状态可通过 useOverlayState 钩子管理。

3. v3 新特性

拖动关闭：在手柄、头部和底部区域内置基于指针的拖动手势
拖动手柄：Drawer.Handle 是视觉拖动指示器组件
内置关闭触发器：Drawer.CloseTrigger 会渲染一个关闭按钮
基于 slot 的关闭：带有 slot="close" 的按钮会自动关闭 Drawer

4. Prop 变更

v2 prop	v3 等效项	说明
`isOpen`	`Drawer.Backdrop` 的 `isOpen`	或使用 `useOverlayState`
`onOpenChange`	`Drawer.Backdrop` 的 `onOpenChange`	或使用 `useOverlayState`
`onClose`	-	在按钮上使用 `onOpenChange` 或 `slot="close"`
`placement`	`Drawer.Content` 的 `placement`	`"right"` → `"right"`、`"left"` → `"left"`、`"top"` → `"top"`、`"bottom"` → `"bottom"`。默认值从 `"right"` 改为 `"bottom"`
`size`	-	已移除（请在 `Drawer.Dialog` 上使用 Tailwind CSS）
`radius`	-	已移除（请改用 Tailwind CSS）
`backdrop`	`Drawer.Backdrop` 的 `variant`	值保持一致：`"opaque"`、`"blur"`、`"transparent"`
`isDismissable`	`Drawer.Backdrop` 的 `isDismissable`	保持一致
`isKeyboardDismissDisabled`	`Drawer.Backdrop` 的 `isKeyboardDismissDisabled`	保持一致
`shouldBlockScroll`	-	v3 中始终会阻止滚动
`hideCloseButton`	-	省略 `Drawer.CloseTrigger` 即可隐藏
`closeButton`	-	将自定义内容传给 `Drawer.CloseTrigger`
`motionProps`	-	已移除（v3 使用基于 CSS 的动画）
`disableAnimation`	-	已移除
`portalContainer`	-	已移除
`classNames`	-	在各个复合组件上使用 `className`

5. Hook 变更

v2： 使用 useDisclosure 钩子管理打开 / 关闭状态
v3： 使用 useOverlayState 钩子（替代 useDisclosure）

1// v22const { isOpen, onOpen, onOpenChange } = useDisclosure();3
4// v35const state = useOverlayState();6// state.isOpen, state.open(), state.close(), state.toggle()

迁移示例

基本抽屉

1import { Drawer, DrawerContent, DrawerHeader, DrawerBody, DrawerFooter, Button, useDisclosure } from "@lenso/ui";2
3const { isOpen, onOpen, onOpenChange } = useDisclosure();4
5<>6  <Button onPress={onOpen}>Open</Button>7  <Drawer isOpen={isOpen} onOpenChange={onOpenChange}>8    <DrawerContent>9      {(onClose) => (10        <>11          <DrawerHeader>Title</DrawerHeader>12          <DrawerBody>Content</DrawerBody>13          <DrawerFooter>14            <Button onPress={onClose}>Close</Button>15          </DrawerFooter>16        </>17      )}18    </DrawerContent>19  </Drawer>20</>

位置

1<Drawer isOpen={isOpen} onOpenChange={onOpenChange} placement="left">2  <DrawerContent>3    {(onClose) => (4      <>5        <DrawerHeader>Left Drawer</DrawerHeader>6        <DrawerBody>Content</DrawerBody>7      </>8    )}9  </DrawerContent>10</Drawer>

遮罩变体

1<Drawer isOpen={isOpen} onOpenChange={onOpenChange} backdrop="blur">2  <DrawerContent>3    {(onClose) => (4      <>5        <DrawerHeader>Blurred Backdrop</DrawerHeader>6        <DrawerBody>Content</DrawerBody>7      </>8    )}9  </DrawerContent>10</Drawer>

受控状态

1import { useDisclosure } from "@lenso/ui";2
3const { isOpen, onOpen, onOpenChange } = useDisclosure();4
5<>6  <Button onPress={onOpen}>Open</Button>7  <Drawer isOpen={isOpen} onOpenChange={onOpenChange}>8    <DrawerContent>9      {(onClose) => (10        <>11          <DrawerHeader>Controlled</DrawerHeader>12          <DrawerBody>Content</DrawerBody>13          <DrawerFooter>14            <Button onPress={onClose}>Close</Button>15          </DrawerFooter>16        </>17      )}18    </DrawerContent>19  </Drawer>20</>

不可关闭

1<Drawer2  isOpen={isOpen}3  onOpenChange={onOpenChange}4  isDismissable={false}5  hideCloseButton6>7  <DrawerContent>8    {(onClose) => (9      <>10        <DrawerHeader>Confirm Action</DrawerHeader>11        <DrawerBody>Are you sure?</DrawerBody>12        <DrawerFooter>13          <Button onPress={onClose}>Confirm</Button>14        </DrawerFooter>15      </>16    )}17  </DrawerContent>18</Drawer>

样式变化

v2：`classNames` prop

1<Drawer2  classNames={{3    wrapper: "custom-wrapper",4    base: "custom-base",5    backdrop: "custom-backdrop",6    header: "custom-header",7    body: "custom-body",8    footer: "custom-footer",9    closeButton: "custom-close",10  }}11/>

v3：直接使用 `className` prop

1<Drawer>2  <Button>Open</Button>3  <Drawer.Backdrop className="custom-backdrop">4    <Drawer.Content>5      <Drawer.Dialog className="custom-base">6        <Drawer.CloseTrigger className="custom-close" />7        <Drawer.Header className="custom-header">8          <Drawer.Heading>Title</Drawer.Heading>9        </Drawer.Header>10        <Drawer.Body className="custom-body">Content</Drawer.Body>11        <Drawer.Footer className="custom-footer">Actions</Drawer.Footer>12      </Drawer.Dialog>13    </Drawer.Content>14  </Drawer.Backdrop>15</Drawer>

组件结构

v3 Drawer 遵循以下结构：

1Drawer (Root)2  ├── [Trigger element] (first child becomes trigger)3  └── Drawer.Backdrop4      └── Drawer.Content (placement)5          └── Drawer.Dialog6              ├── Drawer.Handle (optional, drag indicator)7              ├── Drawer.CloseTrigger (optional, close button)8              ├── Drawer.Header9              │   └── Drawer.Heading10              ├── Drawer.Body (scrollable)11              └── Drawer.Footer

总结

组件结构：渲染回调模式 → 带显式子组件的复合组件
触发模式：外部 useDisclosure + onPress → 内置触发器（Drawer 的第一个子节点）
状态钩子：useDisclosure → useOverlayState，并使用 open()、close()、toggle() 方法
位置：Drawer 上的 prop → Drawer.Content 上的 prop。默认值从 "right" 改为 "bottom"
遮罩：backdrop prop → Drawer.Backdrop 的 variant prop
关闭按钮：hideCloseButton / closeButton props → 省略或自定义 Drawer.CloseTrigger
基于 slot 的关闭：带有 slot="close" 的按钮会自动关闭 Drawer
新功能：通过 Drawer.Handle 拖动关闭，并支持基于速度的关闭
动画：motionProps（Framer Motion）→ 基于 CSS 的动画
已移除样式 prop：size、radius → 使用 Tailwind CSS
已移除 classNames：在各个复合组件上使用 className