#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
抽屉的受控打开状态、展开方向、内容区域与关闭行为配置。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
open | boolean | 必填 | 受控的打开状态,应用负责更新。 |
title | ReactNode | — | 抽屉标题。 |
description | ReactNode | — | 补充说明。 |
tabs | DrawerTabsProps | — | 内嵌标签页;无标题时替代标题栏,有标题时位于其下方;底部分割线始终保留。 |
onClose | () => void | — | 请求关闭,由应用更新 open |
placement | 'left' | 'right' | 'top' | 'bottom' | 'right' | 展开方向 |
width | number | string | 380 | 左右抽屉宽度 |
height | number | string | 300 | 上下抽屉高度 |
footer | ReactNode | — | 底部内容 |
extra | ReactNode | — | 标题旁的操作内容 |
icon | ReactNode | — | 标题左侧的装饰图标。 |
divided | boolean | false | 用浅分隔线划分标题、内容和底部操作区。 |
closable | boolean | true | 显示关闭按钮。 |
maskClosable | boolean | true | 点击遮罩时请求关闭。 |
keyboard | boolean | true | 允许按 Escape 请求关闭。 |
initialFocus | RefObject<HTMLElement | null> | (() => HTMLElement | null) | — | 指定打开后的初始焦点。 |
returnFocus | boolean | RefObject<HTMLElement | null> | (() => HTMLElement | null) | — | 关闭后返回原焦点;也可指定目标或设为 false。 |
resizable | boolean | false | 允许拖动和使用方向键调整大小。 |
minSize | number | 240 | 最小尺寸,单位为像素。 |
maxSize | number | 900 | 最大尺寸,单位为像素。 |
onResize | (size: number) => void | — | 用户拖动或键盘调整时返回新尺寸;width 或 height 改变会重置手动尺寸。 |
push | boolean | number | false | 推动最近的父弹层;true 使用 40px,数字指定距离。 |
afterClose | () => void | — | 关闭过渡结束后触发 |
destroyOnClose | boolean | false | 关闭后卸载内容;preserve 优先,forceRender 会保持挂载。 |
preserve | boolean | — | 指定是否保留内容,优先于 destroyOnClose;不重置组件外的受控状态。 |
forceRender | boolean | false | 打开前也挂载内容,关闭时保持隐藏。 |
container | Element | DocumentFragment | (() => Element | DocumentFragment) | — | 指定 Portal 挂载目标,也可返回 ShadowRoot。 |
#DrawerTabs API
内嵌标签页的可用属性见 Tabs API(新标签页打开)。Drawer 固定使用 type="line" 与 placement="top",标签栏固定在正文滚动区上方,底部分割线不受 divided={false} 影响;items 为空时恢复普通抽屉。
type DrawerTabsProps = Omit<TabsProps, 'type' | 'placement' | 'children'>;