For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/drawer.md.

Drawer 抽屉

从页面边缘展开内容,查看详情或完成操作。

基础用法

通过 onClose 响应关闭请求并更新 open。没有 title 时,使用 aria-label 提供名称。

basic.tsx
import { Button, Drawer, Paragraph } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerBasic() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button onClick={() => setOpen(true)}>查看详情</Button>
      <Drawer open={open} title="文档详情" onClose={() => setOpen(false)}>
        <Paragraph>此文档由设计团队维护,最近更新于本周。</Paragraph>
      </Drawer>
    </>
  );
}

示例

展开方向

左右方向使用 width,上下方向使用 height。

placement.tsx
import { Button, Drawer, type DrawerProps, Paragraph, Space } from '@ifhover/leaf-ui';
import { useState } from 'react';

const placements = [
  { value: 'left', label: '左侧' },
  { value: 'right', label: '右侧' },
  { value: 'top', label: '顶部' },
  { value: 'bottom', label: '底部' },
] as const;

export function DrawerPlacement() {
  const [open, setOpen] = useState(false);
  const [placement, setPlacement] = useState<DrawerProps['placement']>('right');
  return (
    <>
      <Space wrap>
        {placements.map((item) => (
          <Button
            key={item.value}
            onClick={() => {
              setPlacement(item.value);
              setOpen(true);
            }}
          >
            {item.label}
          </Button>
        ))}
      </Space>
      <Drawer open={open} placement={placement} title="文档详情" onClose={() => setOpen(false)}>
        <Paragraph>从选定的页面边缘展开详情。</Paragraph>
      </Drawer>
    </>
  );
}

底部提交

通过按钮的 form 属性关联抽屉内的表单,保留原生校验;提交与关闭都由应用处理。

sections.tsx
import { Button, Drawer, Form, FormField, Input, Space } from '@ifhover/leaf-ui';
import { useId, useState } from 'react';

export function DrawerSections() {
  const [open, setOpen] = useState(false);
  const formId = useId();
  return (
    <>
      <Button onClick={() => setOpen(true)}>编辑名称</Button>
      <Drawer
        open={open}
        title="编辑名称"
        onClose={() => setOpen(false)}
        footer={
          <Space wrap>
            <Button onClick={() => setOpen(false)}>取消</Button>
            <Button variant="solid" type="submit" form={formId}>
              保存
            </Button>
          </Space>
        }
      >
        <Form
          id={formId}
          layout="vertical"
          onSubmit={(event) => {
            event.preventDefault();
            setOpen(false);
          }}
        >
          <FormField label="名称" required>
            <Input name="name" defaultValue="Leaf UI" />
          </FormField>
        </Form>
      </Drawer>
    </>
  );
}

调整尺寸

启用 resizable 后,可拖动边缘,或聚焦分隔条后使用方向键调整。minSize 与 maxSize 限制 onResize 返回的调整值,实际可见尺寸仍受视口限制;修改 width 或 height 会重置手动调整值。

resize.tsx
import { Button, Drawer, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerResize() {
  const [open, setOpen] = useState(false);
  const [size, setSize] = useState<number>();
  return (
    <>
      <Button onClick={() => setOpen(true)}>调整抽屉宽度</Button>
      <Drawer
        open={open}
        title="调整宽度"
        onClose={() => setOpen(false)}
        resizable
        minSize={260}
        maxSize={640}
        onResize={setSize}
      >
        <Text tone="muted" role="status">
          {size == null ? '尚未调整尺寸' : `调整值:${size}px`}
        </Text>
      </Drawer>
    </>
  );
}

嵌套推移

在子抽屉上设置 push,打开时推移最近的父弹层;true 对应 40px,也可直接传入距离。Escape 仅关闭最上层抽屉,关闭后焦点回到对应触发按钮。父抽屉关闭时同时重置子抽屉的 open,避免下次打开时子层仍展开。

nested.tsx
import { Button, Drawer, Paragraph } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerNested() {
  const [open, setOpen] = useState(false);
  const [childOpen, setChildOpen] = useState(false);
  const closeParent = () => {
    setChildOpen(false);
    setOpen(false);
  };
  return (
    <>
      <Button onClick={() => setOpen(true)}>打开第一层</Button>
      <Drawer open={open} title="第一层抽屉" onClose={closeParent}>
        <Button onClick={() => setChildOpen(true)}>打开第二层</Button>
        <Drawer
          open={childOpen}
          title="第二层抽屉"
          width={300}
          push
          onClose={() => setChildOpen(false)}
        >
          <Paragraph>这里是第二层抽屉的内容。</Paragraph>
        </Drawer>
      </Drawer>
    </>
  );
}

标签页抽屉

通过 tabs 在标题下方或顶部嵌入线形标签页。标签栏固定在正文滚动区上方,即使 divided={false}(默认值)也会保留标签栏底部分割线;若仅将标签栏用于切换状态并把内容写在 Drawer 的 children 中,可省略各项的 children。

tabs.tsx
import { Button, Drawer, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DrawerTabs() {
  const [open, setOpen] = useState(false);
  const [view, setView] = useState('overview');
  return (
    <>
      <Button onClick={() => setOpen(true)}>查看详情</Button>
      <Drawer
        open={open}
        title="任务详情"
        onClose={() => setOpen(false)}
        tabs={{
          activeKey: view,
          onChange: setView,
          items: [
            { key: 'overview', label: '概览' },
            { key: 'logs', label: '运行日志' },
          ],
        }}
      >
        <Text>
          {view === 'overview'
            ? '省略标签项 children 时,可将标签栏作为正文状态切换器使用。'
            : '正在展示运行日志视图,标签栏底部分割线始终保留。'}
        </Text>
      </Drawer>
    </>
  );
}

内容保留与焦点配置参见 Modal 的进阶用法。

API

Drawer API

抽屉的受控打开状态、展开方向、内容区域与关闭行为配置。

属性类型默认值说明
openboolean必填受控的打开状态,应用负责更新。
titleReactNode—抽屉标题。
descriptionReactNode—补充说明。
tabsDrawerTabsProps—内嵌标签页;无标题时替代标题栏,有标题时位于其下方;底部分割线始终保留。
onClose() => void—请求关闭,由应用更新 open
placement'left' | 'right' | 'top' | 'bottom''right'展开方向
widthnumber | string380左右抽屉宽度
heightnumber | string300上下抽屉高度
footerReactNode—底部内容
extraReactNode—标题旁的操作内容
iconReactNode—标题左侧的装饰图标。
dividedbooleanfalse用浅分隔线划分标题、内容和底部操作区。
closablebooleantrue显示关闭按钮。
maskClosablebooleantrue点击遮罩时请求关闭。
keyboardbooleantrue允许按 Escape 请求关闭。
initialFocusRefObject<HTMLElement | null> | (() => HTMLElement | null)—指定打开后的初始焦点。
returnFocusboolean | RefObject<HTMLElement | null> | (() => HTMLElement | null)—关闭后返回原焦点;也可指定目标或设为 false。
resizablebooleanfalse允许拖动和使用方向键调整大小。
minSizenumber240最小尺寸,单位为像素。
maxSizenumber900最大尺寸,单位为像素。
onResize(size: number) => void—用户拖动或键盘调整时返回新尺寸;width 或 height 改变会重置手动尺寸。
pushboolean | numberfalse推动最近的父弹层;true 使用 40px,数字指定距离。
afterClose() => void—关闭过渡结束后触发
destroyOnClosebooleanfalse关闭后卸载内容;preserve 优先,forceRender 会保持挂载。
preserveboolean—指定是否保留内容,优先于 destroyOnClose;不重置组件外的受控状态。
forceRenderbooleanfalse打开前也挂载内容,关闭时保持隐藏。
containerElement | DocumentFragment | (() => Element | DocumentFragment)—指定 Portal 挂载目标,也可返回 ShadowRoot。

DrawerTabs API

内嵌标签页的可用属性见 Tabs API(新标签页打开)。Drawer 固定使用 type="line" 与 placement="top",标签栏固定在正文滚动区上方,底部分割线不受 divided={false} 影响;items 为空时恢复普通抽屉。

type DrawerTabsProps = Omit<TabsProps, 'type' | 'placement' | 'children'>;