Offcanvas

基础对话框

基于 React Portal 的侧边抽屉组件，支持四个方向的滑入滑出动画、遮罩与键盘选项、背景滚动控制，内置焦点管理与自定义过渡动画，可通过页眉、标题、正文与关闭按钮子组件自由组合内容

Component Demo

Basic usage and examples of the Offcanvas component

基础用法

四个方向

遮罩选项

背景滚动

键盘控制

表单交互

API Documentation

Complete API reference for the Offcanvas component

Props

属性名	类型	默认值	描述
`isOpen`	`boolean`	`false`	受控的打开状态，为 `true` 时抽屉打开
`onOpenChange`	`(isOpen: boolean) => void`	-	打开状态变化回调，抽屉通过它请求关闭（如 Esc 键、遮罩点击、`OffcanvasClose`），由使用者更新 `isOpen`
`placement`	`OffcanvasPlacement`	`'start'`	抽屉位置，`start`、`end`、`top`、`bottom` 分别对应左侧、右侧、顶部与底部
`backdrop`	`OffcanvasBackdrop`	`true`	背景遮罩行为，为 `false` 时不渲染遮罩且抽屉自动添加 `shadow-lg` 阴影（点击抽屉以外区域仍可关闭），为 `"static"` 时点击遮罩不会关闭
`keyboard`	`boolean`	`true`	是否允许通过 Esc 键关闭抽屉
`scroll`	`boolean`	`false`	抽屉打开期间是否允许背景滚动，为 `false` 时锁定背景滚动
`duration`	`number`	`300`	滑入与滑出动画时长（毫秒），系统开启减少动态效果时自动为 0
`ariaLabel`	`string`	-	无障碍标签，不提供时通过 `OffcanvasTitle` 生成的 id 关联标题
`className`	`string`	-	抽屉根元素自定义类名
`backdropClassName`	`string`	-	遮罩层自定义类名
`backdropStyle`	`CSSProperties`	-	遮罩层自定义内联样式
`style`	`CSSProperties`	-	抽屉根元素自定义内联样式
`children`	`ReactNode`	-	抽屉内容，支持任意 React 节点
`...rest`	`DialogHTMLAttributes`	-	透传原生 dialog 元素的所有属性（如 `id`、`onClick`、`onKeyDown` 等）

Type Definitions

OffcanvasPlacement

抽屉位置类型

export type OffcanvasPlacement = 'bottom' | 'end' | 'start' | 'top';

OffcanvasBackdrop

抽屉遮罩行为类型

export type OffcanvasBackdrop = 'static' | boolean;

OffcanvasAnimationStatus

抽屉动画状态类型

export type OffcanvasAnimationStatus = 'closed' | 'closing' | 'opened' | 'opening';

OffcanvasProps

抽屉组件属性接口

export interface OffcanvasProps extends Omit<DialogHTMLAttributes<HTMLDialogElement>, 'children'> {
  ariaLabel?: string;
  backdrop?: OffcanvasBackdrop;
  backdropClassName?: string;
  backdropStyle?: CSSProperties;
  children: ReactNode;
  className?: string;
  duration?: number;
  isOpen?: boolean;
  keyboard?: boolean;
  onOpenChange?: (isOpen: boolean) => void;
  placement?: OffcanvasPlacement;
  scroll?: boolean;
  style?: CSSProperties;
}

OffcanvasContextValue

抽屉上下文，供 OffcanvasTitle、OffcanvasClose 等子组件消费

export interface OffcanvasContextValue {
  close: () => void;
  status: OffcanvasAnimationStatus;
  titleId: string;
}

OffcanvasPartProps

抽屉子组件属性接口（OffcanvasHeader、OffcanvasTitle、OffcanvasBody、OffcanvasClose）

export interface OffcanvasHeaderProps extends HTMLAttributes<HTMLDivElement> {
  children?: ReactNode;
  className?: string;
  closeButton?: boolean;
  closeLabel?: string;
}

export interface OffcanvasTitleProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
}

export interface OffcanvasBodyProps extends HTMLAttributes<HTMLDivElement> {
  children?: ReactNode;
  className?: string;
}

export interface OffcanvasCloseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  children?: ReactNode;
  className?: string;
}