折叠区域 collapsible

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

示例

基础用法

不传 open 即为非受控，defaultOpen 只给初始值，之后由组件自己维护开合

defaultOpen 只影响初始状态。

<script setup lang="ts">
import {
  XhCollapsibleContent,
  XhCollapsibleRoot,
  XhCollapsibleTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="width: 100%; max-width: 420px; display: grid; gap: 12px">
    <XhCollapsibleRoot>
      <XhCollapsibleTrigger>展开详情</XhCollapsibleTrigger>
      <XhCollapsibleContent>
        收起时内容只加 hidden，节点不卸载，里面的输入框与滚动位置都留着。
      </XhCollapsibleContent>
    </XhCollapsibleRoot>

    <XhCollapsibleRoot default-open>
      <XhCollapsibleTrigger>一上来就开着</XhCollapsibleTrigger>
      <XhCollapsibleContent>defaultOpen 只影响初始状态。</XhCollapsibleContent>
    </XhCollapsibleRoot>
  </div>
</template>

受控

传了 open 就由宿主说了算，组件自己不再改状态，只发 open-change 报告意图

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhCollapsibleContent,
  XhCollapsibleRoot,
  XhCollapsibleTrigger,
} from "@xihan-ui/vue";

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

<template>
  <div style="width: 100%; max-width: 420px; display: grid; gap: 12px">
    <XhButton size="sm" @click="open = !open">
      从外面{{ open ? "收起" : "展开" }}
    </XhButton>

    <XhCollapsibleRoot v-model:open="open">
      <XhCollapsibleTrigger>面板标题</XhCollapsibleTrigger>
      <XhCollapsibleContent>
        当前状态：{{ open ? "展开" : "收起" }}。触发器与上面的按钮改的是同一份状态。
      </XhCollapsibleContent>
    </XhCollapsibleRoot>
  </div>
</template>

禁用

disabled 把触发器整个关停，点击与键盘都不再改开合，已展开的内容维持原样

内容停在展开态，收不上。

<script setup lang="ts">
import {
  XhCollapsibleContent,
  XhCollapsibleRoot,
  XhCollapsibleTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="width: 100%; max-width: 420px; display: grid; gap: 12px">
    <XhCollapsibleRoot disabled>
      <XhCollapsibleTrigger>收起且禁用</XhCollapsibleTrigger>
      <XhCollapsibleContent>点不开。</XhCollapsibleContent>
    </XhCollapsibleRoot>

    <XhCollapsibleRoot default-open disabled>
      <XhCollapsibleTrigger>展开且禁用</XhCollapsibleTrigger>
      <XhCollapsibleContent>内容停在展开态，收不上。</XhCollapsibleContent>
    </XhCollapsibleRoot>
  </div>
</template>

尺寸

size 换的是触发按钮的高度、内边距与字号，三档并排对照

按钮最矮，字号也最小。

不写 size 就是这一档。

按钮最高，字号也最大。

<script setup lang="ts">
import {
  XhCollapsibleContent,
  XhCollapsibleRoot,
  XhCollapsibleTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <div
    style="
      display: grid;
      gap: 16px;
      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
      align-items: start;
    "
  >
    <XhCollapsibleRoot size="sm" default-open>
      <XhCollapsibleTrigger>小号 sm</XhCollapsibleTrigger>
      <XhCollapsibleContent>按钮最矮，字号也最小。</XhCollapsibleContent>
    </XhCollapsibleRoot>

    <XhCollapsibleRoot default-open>
      <XhCollapsibleTrigger>缺省档</XhCollapsibleTrigger>
      <XhCollapsibleContent>不写 size 就是这一档。</XhCollapsibleContent>
    </XhCollapsibleRoot>

    <XhCollapsibleRoot size="lg" default-open>
      <XhCollapsibleTrigger>大号 lg</XhCollapsibleTrigger>
      <XhCollapsibleContent>按钮最高，字号也最大。</XhCollapsibleContent>
    </XhCollapsibleRoot>
  </div>
</template>

自定义展开标记

折叠区域不带指示器部件，标记由作者按 open 自己画，触发器两端对齐排

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCollapsibleContent,
  XhCollapsibleRoot,
  XhCollapsibleTrigger,
} from "@xihan-ui/vue";

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

<template>
  <div style="width: 100%; max-width: 420px; display: grid; gap: 12px">
    <XhCollapsibleRoot v-model:open="open">
      <XhCollapsibleTrigger>
        <span>高级筛选</span>
        <!-- 标记跟着 open 换字形，触发器里放什么全归作者 -->
        <span style="font-size: 12px">{{ open ? "收起 ▴" : "展开 ▾" }}</span>
      </XhCollapsibleTrigger>
      <XhCollapsibleContent>
        创建时间、负责人、标签这些不常用的条件收在这里。
      </XhCollapsibleContent>
    </XhCollapsibleRoot>
  </div>
</template>

展开动画

收起时节点不卸载，作者接管内容区的 display，用一条行高过渡就能平滑展开

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCollapsibleContent,
  XhCollapsibleRoot,
  XhCollapsibleTrigger,
} from "@xihan-ui/vue";

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

<template>
  <div style="width: 100%; max-width: 420px; display: grid; gap: 12px">
    <XhCollapsibleRoot v-model:open="open">
      <XhCollapsibleTrigger>{{ open ? "收起详情" : "展开详情" }}</XhCollapsibleTrigger>
      <!-- 行高在 0fr 与 1fr 之间过渡，不必测量内容高度；
           内边距挪到内层，收起时外层才不留白；display 被接管后，收起态改用 inert 隔离 -->
      <XhCollapsibleContent
        :inert="!open || undefined"
        :style="{
          display: 'grid',
          gridTemplateRows: open ? '1fr' : '0fr',
          paddingBlock: '0',
          transition:
            'grid-template-rows var(--xh-motion-duration-enter) var(--xh-motion-ease-enter)',
        }"
      >
        <div style="overflow: hidden">
          <p style="margin: 0; padding-block: 12px">
            展开与收起都走同一条过渡，中途再点一次会从当前高度掉头。
          </p>
        </div>
      </XhCollapsibleContent>
    </XhCollapsibleRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-collapsible>
Vue 组件	XhCollapsibleContent XhCollapsibleRoot XhCollapsibleTrigger
组合式函数	useCollapsible
状态机	collapsibleMachine
皮肤	@xihan-ui/styles/collapsible.css

解剖

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

data-scope="collapsible"：root · trigger · content

Props

属性	类型	必填	说明
open	boolean
defaultOpen	boolean
disabled	boolean
size	Size		尺寸：sm / md / lg。
onOpenChange	(details: CollapsibleOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。

状态机

状态：open · closed

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

判据：isOpenControlled

connect API

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

成员	类型	说明
open	boolean
setOpen	(next: boolean) => void
getRootProps	() => T['element']
getTriggerProps	() => T['button']
getContentProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Space / Enter	focus in trigger, not disabled	展开/收起 content