抽屉 drawer

反馈与浮层组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

root 留在页面原地，content 被 portal 到 body；Escape 关闭、Tab 在面板里循环，展开期间页面滚不动

<script setup lang="ts">
import {
  XhButton,
  XhDrawerCloseTrigger,
  XhDrawerContent,
  XhDrawerDescription,
  XhDrawerRoot,
  XhDrawerTitle,
  XhDrawerTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <XhDrawerRoot v-slot="{ setOpen }" :translations="{ close: '关闭' }">
    <XhDrawerTrigger>打开抽屉</XhDrawerTrigger>
    <XhDrawerContent>
      <XhDrawerTitle>筛选条件</XhDrawerTitle>
      <XhDrawerDescription>
        面板贴住右边，这是 side 的默认值。
      </XhDrawerDescription>
      <XhButton variant="solid" @click="setOpen(false)">应用并关闭</XhButton>
      <XhDrawerCloseTrigger>✕</XhDrawerCloseTrigger>
    </XhDrawerContent>
  </XhDrawerRoot>
</template>

贴边方向

side 只落成 data-side，面板压在哪条边由皮肤按这个值决定；root 与 content 报的是同一条边

<script setup lang="ts">
import {
  XhDrawerCloseTrigger,
  XhDrawerContent,
  XhDrawerDescription,
  XhDrawerRoot,
  XhDrawerTitle,
  XhDrawerTrigger,
} from "@xihan-ui/vue";

const sides = [
  { value: "left", label: "左侧" },
  { value: "right", label: "右侧" },
  { value: "top", label: "顶部" },
  { value: "bottom", label: "底部" },
] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px">
    <XhDrawerRoot
      v-for="s in sides"
      :key="s.value"
      v-slot="{ side }"
      :side="s.value"
      :translations="{ close: '关闭' }"
    >
      <XhDrawerTrigger>{{ s.label }}</XhDrawerTrigger>
      <XhDrawerContent>
        <XhDrawerTitle>{{ s.label }}抽屉</XhDrawerTitle>
        <XhDrawerDescription>
          当前 data-side 是 {{ side }}。
        </XhDrawerDescription>
        <XhDrawerCloseTrigger>✕</XhDrawerCloseTrigger>
      </XhDrawerContent>
    </XhDrawerRoot>
  </div>
</template>

受控

传了 open 就由宿主说了算；Escape、点面板外、按叉都只回写 open，不自己改状态

当前：收起

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhDrawerCloseTrigger,
  XhDrawerContent,
  XhDrawerDescription,
  XhDrawerRoot,
  XhDrawerTitle,
} from "@xihan-ui/vue";

const open = ref(false);
</script>

<template>
  <XhDrawerRoot v-model:open="open" side="left" :translations="{ close: '关闭' }">
    <div style="display: flex; align-items: center; gap: 12px">
      <XhButton variant="solid" @click="open = true">打开左侧抽屉</XhButton>
      <span>当前：{{ open ? "展开" : "收起" }}</span>
    </div>
    <XhDrawerContent>
      <XhDrawerTitle>受控抽屉</XhDrawerTitle>
      <XhDrawerDescription>
        这里没有 trigger，开合完全跟着外面那颗按钮与 open 走。
      </XhDrawerDescription>
      <XhDrawerCloseTrigger>✕</XhDrawerCloseTrigger>
    </XhDrawerContent>
  </XhDrawerRoot>
</template>

尺寸

size 落成 content 的 data-size，只改面板贴边方向上的厚度；三档各自一个抽屉，点开才看得出厚薄

<script setup lang="ts">
import {
  XhButton,
  XhDrawerCloseTrigger,
  XhDrawerContent,
  XhDrawerDescription,
  XhDrawerRoot,
  XhDrawerTitle,
  XhDrawerTrigger,
} from "@xihan-ui/vue";

// 中间档不传 size，缺省即中档
const sizes = [
  { key: "sm", size: "sm", label: "sm 薄" },
  { key: "md", size: undefined, label: "缺省" },
  { key: "lg", size: "lg", label: "lg 厚" },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px">
    <XhDrawerRoot
      v-for="s in sizes"
      :key="s.key"
      v-slot="{ setOpen }"
      :size="s.size"
      :translations="{ close: '关闭' }"
    >
      <XhDrawerTrigger>{{ s.label }}</XhDrawerTrigger>
      <XhDrawerContent>
        <XhDrawerTitle>{{ s.label }}抽屉</XhDrawerTitle>
        <XhDrawerDescription>
          面板贴住右边，三档只有厚度不同。
        </XhDrawerDescription>
        <XhButton variant="solid" @click="setOpen(false)">关闭</XhButton>
        <XhDrawerCloseTrigger>✕</XhDrawerCloseTrigger>
      </XhDrawerContent>
    </XhDrawerRoot>
  </div>
</template>

内容滚动

面板本身定高，把中间那段设成可伸缩并开滚动，标题与底部操作就钉在两头

<script setup lang="ts">
import {
  XhButton,
  XhDrawerCloseTrigger,
  XhDrawerContent,
  XhDrawerDescription,
  XhDrawerRoot,
  XhDrawerTitle,
  XhDrawerTrigger,
} from "@xihan-ui/vue";

const records = Array.from({ length: 24 }, (_, i) => ({
  id: i + 1,
  text: `第 ${i + 1} 条操作记录`,
}));
</script>

<template>
  <XhDrawerRoot v-slot="{ setOpen }" :translations="{ close: '关闭' }">
    <XhDrawerTrigger>查看操作记录</XhDrawerTrigger>
    <XhDrawerContent>
      <XhDrawerTitle>操作记录</XhDrawerTitle>
      <XhDrawerDescription>共 {{ records.length }} 条，往下翻。</XhDrawerDescription>
      <div style="flex: 1; min-block-size: 0; overflow: auto">
        <p
          v-for="r in records"
          :key="r.id"
          style="
            margin: 0;
            padding: 8px 0;
            border-block-end: 1px solid var(--xh-border-subtle);
          "
        >
          {{ r.text }}
        </p>
      </div>
      <XhButton variant="solid" @click="setOpen(false)">看完了</XhButton>
      <XhDrawerCloseTrigger>✕</XhDrawerCloseTrigger>
    </XhDrawerContent>
  </XhDrawerRoot>
</template>

关闭前拦截

受控时组件不自改状态：Escape、点面板外、按叉都只发一次收起意图，写不写由宿主定

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhDrawerCloseTrigger,
  XhDrawerContent,
  XhDrawerDescription,
  XhDrawerRoot,
  XhDrawerTitle,
  XhDrawerTrigger,
} from "@xihan-ui/vue";

const open = ref(false);
const asking = ref(false);

// 展开意图照单全收，收起意图先扣下来，等下面那两颗按钮表态
function onOpenChange(details: { open: boolean }) {
  asking.value = !details.open;
  if (details.open) open.value = true;
}

function discard() {
  asking.value = false;
  open.value = false;
}
</script>

<template>
  <XhDrawerRoot :open="open" :translations="{ close: '关闭' }" @open-change="onOpenChange">
    <XhDrawerTrigger>编辑草稿</XhDrawerTrigger>
    <XhDrawerContent>
      <XhDrawerTitle>编辑草稿</XhDrawerTitle>
      <XhDrawerDescription>
        这里假定草稿一直有未保存的改动，任何一次收起意图都要先问一句。
      </XhDrawerDescription>
      <p style="margin: 0">
        {{ asking ? "改动还没保存，确定丢掉吗？" : "试试按 Escape、点面板外，或者按右上角的叉。" }}
      </p>
      <div v-if="asking" style="display: flex; gap: 8px">
        <XhButton variant="outline" @click="asking = false">继续编辑</XhButton>
        <XhButton variant="solid" @click="discard">丢弃并关闭</XhButton>
      </div>
      <XhDrawerCloseTrigger>✕</XhDrawerCloseTrigger>
    </XhDrawerContent>
  </XhDrawerRoot>
</template>

拖边缘改厚度

面板里放一根把手，拖动时把新厚度写进 content 的 --xh-drawer-size；这个槽压过 size 三档，滑入滑出仍按面板自身宽度算

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhDrawerCloseTrigger,
  XhDrawerContent,
  XhDrawerDescription,
  XhDrawerRoot,
  XhDrawerTitle,
  XhDrawerTrigger,
} from "@xihan-ui/vue";

const MIN = 260;
const MAX = 560;

const width = ref(0);
const dragging = ref(false);
let panel: HTMLElement | null = null;

function begin(event: PointerEvent): void {
  const handle = event.currentTarget as HTMLElement;
  panel = handle.closest<HTMLElement>('[data-scope="drawer"][data-part="content"]');
  if (!panel) return;
  dragging.value = true;
  // 起点取面板当前的实际厚度
  width.value = Math.round(panel.getBoundingClientRect().width);
  handle.setPointerCapture(event.pointerId);
}

function move(event: PointerEvent): void {
  if (!dragging.value || !panel) return;
  // 面板贴右边，厚度就是视口右缘到指针的距离
  width.value = Math.round(Math.min(MAX, Math.max(MIN, window.innerWidth - event.clientX)));
  panel.style.setProperty("--xh-drawer-size", `${width.value}px`);
}

function end(event: PointerEvent): void {
  if (!dragging.value) return;
  dragging.value = false;
  panel = null;
  (event.currentTarget as HTMLElement).releasePointerCapture(event.pointerId);
}
</script>

<template>
  <XhDrawerRoot v-slot="{ setOpen }" :translations="{ close: '关闭' }">
    <XhDrawerTrigger>打开可调宽的抽屉</XhDrawerTrigger>
    <XhDrawerContent>
      <div
        style="
          position: absolute;
          inset-block: 0;
          inset-inline-start: 0;
          inline-size: 8px;
          cursor: ew-resize;
          touch-action: none;
        "
        @pointerdown="begin"
        @pointermove="move"
        @pointerup="end"
        @pointercancel="end"
      />
      <XhDrawerTitle>字段设置</XhDrawerTitle>
      <XhDrawerDescription>
        拖面板左边缘，厚度在 {{ MIN }} 到 {{ MAX }} 像素之间取值。
      </XhDrawerDescription>
      <p style="margin: 0; color: var(--xh-fg-muted)">
        当前厚度：{{ width ? width + " px" : "默认" }}
      </p>
      <XhButton variant="solid" @click="setOpen(false)">关闭</XhButton>
      <XhDrawerCloseTrigger>✕</XhDrawerCloseTrigger>
    </XhDrawerContent>
  </XhDrawerRoot>
</template>

产物

层	值
自定义元素	<xh-drawer>
Vue 组件	XhDrawerCloseTrigger XhDrawerContent XhDrawerDescription XhDrawerRoot XhDrawerTitle XhDrawerTrigger
组合式函数	useDrawer
状态机	drawerMachine
皮肤	@xihan-ui/styles/drawer.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="drawer"：root · trigger · backdrop · positioner · content · title · description · close-trigger

Props

属性	类型	必填	说明
open	boolean
defaultOpen	boolean
modal	boolean
side	DrawerSide		从哪条边滑出，默认 'right'。只影响输出的 data-side，不参与状态转移。
role	'dialog' | 'alertdialog'
closeOnEscape	boolean
closeOnInteractOutside	boolean
restoreFocus	boolean
size	Size		尺寸：sm / md / lg。横放时换面板宽度、竖放时换面板高度，随 side 而定。
translations	Partial<DrawerTranslations>
onOpenChange	(details: DrawerOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。

状态机

状态：open · closed

事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE

判据：isOpenControlled

connect API

useDrawer 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
open	boolean
side	DrawerSide	已解析的滑出边（prop 缺省时是默认值），作者据此配动画。
setOpen	(next: boolean) => void
getRootProps	() => T['element']
getTriggerProps	() => T['button']
getBackdropProps	() => T['element']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getTitleProps	() => T['element']
getDescriptionProps	() => T['element']
getCloseTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	focus in trigger	打开抽屉并把焦点移入 content
Escape	open	关闭并把焦点还给 trigger
Tab	open 且 modal	在 content 内向后循环焦点
Shift+Tab	open 且 modal	在 content 内向前循环焦点