手风琴 accordion

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

示例

基础用法

默认单开：展开一项即收起其余，defaultValue 只给初始值，之后由组件自己维护

装 @xihan-ui/vue 与 @xihan-ui/styles 两个包，皮肤单独引一次。

<script setup lang="ts">
import { XhAccordionRoot } from "@xihan-ui/vue";

const items = [
  {
    value: "install",
    label: "怎么安装",
    content: "装 @xihan-ui/vue 与 @xihan-ui/styles 两个包，皮肤单独引一次。",
  },
  {
    value: "theme",
    label: "怎么换皮肤",
    content: "皮肤只认 data-part 与 data-state，覆写同名令牌即可。",
  },
  {
    value: "a11y",
    label: "键盘怎么走",
    content: "方向键只在标题之间搬焦点，永不进内容区，首尾不回绕。",
  },
];
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot :collection="items" :default-value="['install']" />
  </div>
</template>

多项展开

multiple 允许多项并存，展开集合恒为 string[]，用 v-model:value 拿到它

value、defaultValue、multiple。

orientation 决定方向键走哪条轴，默认 vertical。

展开：basic、size

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

const items = [
  { value: "basic", label: "基础属性", content: "value、defaultValue、multiple。" },
  {
    value: "size",
    label: "排版",
    content: "orientation 决定方向键走哪条轴，默认 vertical。",
  },
  {
    value: "events",
    label: "事件",
    content: "value-change 携带 { value }，update:value 携带裸数组。",
  },
];

const panels = ref<string[]>(["basic", "size"]);
</script>

<template>
  <div style="width: 100%; max-width: 420px; display: grid; gap: 12px">
    <XhAccordionRoot v-model:value="panels" :collection="items" multiple />
    <span>展开：{{ panels.length ? panels.join("、") : "（无）" }}</span>
  </div>
</template>

允许全收

单开模式下最后一项默认收不起来，加 collapsible 才能把它也收上

点当前展开项的标题，它会收起，展开集合变成空数组。

<script setup lang="ts">
import { XhAccordionRoot } from "@xihan-ui/vue";

const items = [
  {
    value: "one",
    label: "再点一次就收起",
    content: "点当前展开项的标题，它会收起，展开集合变成空数组。",
  },
  {
    value: "two",
    label: "另一项",
    content: "展开它会把上一项挤掉，单开模式一次只留一项。",
  },
];
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot :collection="items" :default-value="['one']" collapsible />
  </div>
</template>

指示器与禁用

indicator 的朝向由 data-state 驱动，禁用项点不动、方向键也跳过它

标题右侧那个箭头就是 indicator，展开时自动翻转。

<script setup lang="ts">
import { XhAccordionRoot } from "@xihan-ui/vue";

const items = [
  {
    value: "ready",
    label: "已发布",
    content: "标题右侧那个箭头就是 indicator，展开时自动翻转。",
  },
  {
    value: "draft",
    label: "草稿（禁用）",
    content: "这一项展不开。",
    disabled: true,
  },
  {
    value: "archived",
    label: "已归档",
    content: "从第一项按方向键，会直接跳到这里。",
  },
];
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot :collection="items" :default-value="['ready']" />
  </div>
</template>

语气

tone 落在展开态的标题上，六种语气各预置一项展开做对照

tone="brand"

tone="neutral"

tone="success"

tone="warning"

tone="danger"

tone="info"

<script setup lang="ts">
import { XhAccordionRoot } from "@xihan-ui/vue";

const tones = [
  { value: "brand", label: "品牌" },
  { value: "neutral", label: "中性" },
  { value: "success", label: "成功" },
  { value: "warning", label: "警告" },
  { value: "danger", label: "危险" },
  { value: "info", label: "信息" },
].map((tone) => ({
  ...tone,
  panels: [
    {
      value: "open",
      label: `${tone.label}（展开）`,
      content: `tone="${tone.value}"`,
    },
    {
      value: "closed",
      label: `${tone.label}（收起）`,
      content: "收起态的标题不吃语气色。",
    },
  ],
}));
</script>

<template>
  <div
    style="
      display: grid;
      gap: 16px;
      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
    "
  >
    <XhAccordionRoot
      v-for="tone in tones"
      :key="tone.value"
      :tone="tone.value"
      :collection="tone.panels"
      :default-value="['open']"
    />
  </div>
</template>

尺寸

size 换的是标题栏的高度、内边距与字号，三档并排对照

标题栏最矮，字号也最小。

不写 size 就是这一档。

标题栏最高，字号也最大。

<script setup lang="ts">
import { XhAccordionRoot } from "@xihan-ui/vue";

const another = {
  value: "b",
  label: "另一项",
  content: "同一档内所有标题一致。",
};

// 中间一档不写 size，用 undefined 表达
const groups = [
  {
    size: "sm",
    key: "sm",
    panels: [
      { value: "a", label: "小号 sm", content: "标题栏最矮，字号也最小。" },
      another,
    ],
  },
  {
    size: undefined,
    key: "md",
    panels: [
      { value: "a", label: "缺省档", content: "不写 size 就是这一档。" },
      another,
    ],
  },
  {
    size: "lg",
    key: "lg",
    panels: [
      { value: "a", label: "大号 lg", content: "标题栏最高，字号也最大。" },
      another,
    ],
  },
];
</script>

<template>
  <div
    style="
      display: grid;
      gap: 16px;
      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
      align-items: start;
    "
  >
    <XhAccordionRoot
      v-for="group in groups"
      :key="group.key"
      :size="group.size"
      :collection="group.panels"
      :default-value="['a']"
    />
  </div>
</template>

嵌套

content 里再放一组手风琴，内外两组各自维护展开集合，方向键也各管各的

次日达，节假日照常发货。

<script setup lang="ts">
import {
  XhAccordionContent,
  XhAccordionHeader,
  XhAccordionIndicator,
  XhAccordionItem,
  XhAccordionRoot,
  XhAccordionTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot :default-value="['shipping']">
      <XhAccordionItem value="shipping">
        <XhAccordionHeader>
          <XhAccordionTrigger>
            <span>配送</span>
            <XhAccordionIndicator />
          </XhAccordionTrigger>
        </XhAccordionHeader>
        <XhAccordionContent>
          <!-- 内层是另一组独立的手风琴：展开集合、单开与否都自己说了算 -->
          <XhAccordionRoot :default-value="['express']" multiple>
            <XhAccordionItem value="express">
              <XhAccordionHeader>
                <XhAccordionTrigger>
                  <span>快递</span>
                  <XhAccordionIndicator />
                </XhAccordionTrigger>
              </XhAccordionHeader>
              <XhAccordionContent>次日达，节假日照常发货。</XhAccordionContent>
            </XhAccordionItem>
            <XhAccordionItem value="pickup">
              <XhAccordionHeader>
                <XhAccordionTrigger>
                  <span>自提</span>
                  <XhAccordionIndicator />
                </XhAccordionTrigger>
              </XhAccordionHeader>
              <XhAccordionContent>下单后到门店凭码取货。</XhAccordionContent>
            </XhAccordionItem>
          </XhAccordionRoot>
        </XhAccordionContent>
      </XhAccordionItem>

      <XhAccordionItem value="refund">
        <XhAccordionHeader>
          <XhAccordionTrigger>
            <span>退换</span>
            <XhAccordionIndicator />
          </XhAccordionTrigger>
        </XhAccordionHeader>
        <XhAccordionContent>签收七日内可退，运费到付。</XhAccordionContent>
      </XhAccordionItem>
    </XhAccordionRoot>
  </div>
</template>

标题栏附加信息

标题栏里的节点全归作者，把计数与指示器包成一组排在末尾

还没有人认领。

<script setup lang="ts">
import {
  XhAccordionContent,
  XhAccordionHeader,
  XhAccordionIndicator,
  XhAccordionItem,
  XhAccordionRoot,
  XhAccordionTrigger,
} from "@xihan-ui/vue";

const groups = [
  { value: "todo", label: "待处理", extra: "3 项", body: "还没有人认领。" },
  { value: "doing", label: "进行中", extra: "1 项", body: "预计今天完成。" },
  { value: "done", label: "已完成", extra: "12 项", body: "本周已归档。" },
];
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot :default-value="['todo']">
      <XhAccordionItem v-for="g in groups" :key="g.value" :value="g.value">
        <XhAccordionHeader>
          <XhAccordionTrigger>
            <span>{{ g.label }}</span>
            <!-- 附加信息与指示器同属末尾这一组，标题栏两端对齐照旧生效 -->
            <span style="display: flex; align-items: center; gap: 8px; font-size: 12px">
              <span>{{ g.extra }}</span>
              <XhAccordionIndicator />
            </span>
          </XhAccordionTrigger>
        </XhAccordionHeader>
        <XhAccordionContent>{{ g.body }}</XhAccordionContent>
      </XhAccordionItem>
    </XhAccordionRoot>
  </div>
</template>

指示器在前

指示器写在标题之前就落到起始缘，标题拿 auto 外边距吃掉余量

指示器在标题左边，展开时照样翻转。

<script setup lang="ts">
import {
  XhAccordionContent,
  XhAccordionHeader,
  XhAccordionIndicator,
  XhAccordionItem,
  XhAccordionRoot,
  XhAccordionTrigger,
} from "@xihan-ui/vue";

const items = [
  { value: "one", label: "第一章", body: "指示器在标题左边，展开时照样翻转。" },
  { value: "two", label: "第二章", body: "部件的先后顺序就是它们在标题栏里的顺序。" },
  { value: "three", label: "第三章", body: "标题吃掉余量，右侧留白。" },
];
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot :default-value="['one']">
      <XhAccordionItem v-for="item in items" :key="item.value" :value="item.value">
        <XhAccordionHeader>
          <XhAccordionTrigger>
            <XhAccordionIndicator />
            <span style="margin-inline-end: auto">{{ item.label }}</span>
          </XhAccordionTrigger>
        </XhAccordionHeader>
        <XhAccordionContent>{{ item.body }}</XhAccordionContent>
      </XhAccordionItem>
    </XhAccordionRoot>
  </div>
</template>

缩小触发区域

trigger 只包住指示器，标题文字留在 header 里，点标题不再展开

账户资料

只有右边那个按钮能展开这一段。

账单信息

<script setup lang="ts">
import {
  XhAccordionContent,
  XhAccordionHeader,
  XhAccordionIndicator,
  XhAccordionItem,
  XhAccordionRoot,
  XhAccordionTrigger,
} from "@xihan-ui/vue";

const items = [
  { value: "profile", label: "账户资料", body: "只有右边那个按钮能展开这一段。" },
  { value: "billing", label: "账单信息", body: "标题文字不在按钮里，点它没有反应。" },
];
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot :default-value="['profile']">
      <XhAccordionItem v-for="item in items" :key="item.value" :value="item.value">
        <!-- 标题栏自己排布：文字是普通节点，按钮只占末尾一小格 -->
        <XhAccordionHeader
          style="display: flex; align-items: center; gap: 8px; padding-inline-start: 12px"
        >
          <span style="flex: 1">{{ item.label }}</span>
          <XhAccordionTrigger
            style="inline-size: auto"
            :aria-label="`展开${item.label}`"
          >
            <XhAccordionIndicator />
          </XhAccordionTrigger>
        </XhAccordionHeader>
        <XhAccordionContent>{{ item.body }}</XhAccordionContent>
      </XhAccordionItem>
    </XhAccordionRoot>
  </div>
</template>

自定义展开图标

indicator 是可选部件，不渲染它就没有默认字形；标记由作者按展开集合自己画

同城次日达，跨省三日达。

<script setup lang="ts">
import { ref } from "vue";
import {
  XhAccordionContent,
  XhAccordionHeader,
  XhAccordionItem,
  XhAccordionRoot,
  XhAccordionTrigger,
} from "@xihan-ui/vue";

const items = [
  { value: "shipping", label: "配送方式", body: "同城次日达，跨省三日达。" },
  { value: "invoice", label: "发票", body: "支持电子普票与专票。" },
  { value: "refund", label: "退换货", body: "签收七日内无理由退换。" },
];

const panels = ref<string[]>(["shipping"]);
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhAccordionRoot v-model:value="panels" multiple>
      <XhAccordionItem v-for="item in items" :key="item.value" :value="item.value">
        <XhAccordionHeader>
          <XhAccordionTrigger>
            <span>{{ item.label }}</span>
            <!-- 标记按这一项在不在展开集合里换字形 -->
            <span style="font-size: 12px; color: var(--xh-fg-muted)">
              {{ panels.includes(item.value) ? "－" : "＋" }}
            </span>
          </XhAccordionTrigger>
        </XhAccordionHeader>
        <XhAccordionContent>{{ item.body }}</XhAccordionContent>
      </XhAccordionItem>
    </XhAccordionRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-accordion>
Vue 组件	XhAccordionContent XhAccordionHeader XhAccordionIndicator XhAccordionItem XhAccordionRoot XhAccordionTrigger
组合式函数	useAccordion
状态机	accordionMachine
皮肤	@xihan-ui/styles/accordion.css

解剖

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

data-scope="accordion"：root · item · header · trigger · content · indicator

Props

属性	类型	必填	说明
collection	AccordionNode[]		条目数据，标题文本、正文与禁用的事实源。给了它，条目部件只需报 value。 缺省即回到「文本写在部件里、禁用写在条目上」的老路。
value	string[]		展开集合，给定即受控。
defaultValue	string[]
multiple	boolean		允许多项同时展开；false 时展开一项即收起其余。
collapsible	boolean		允许把最后一个展开项收起，默认 false。
orientation	Orientation		方向键轴向，默认 vertical。
dir	Direction		文字方向，默认 ltr；影响水平轴上 ArrowLeft/ArrowRight 的语义。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色。
size	Size		尺寸：sm / md / lg。
onValueChange	(details: AccordionValueChangeDetails) => void		展开集合变化回调。

状态机

状态：idle

事件：ITEM.TOGGLE · VALUE.SET

connect API

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

成员	类型	说明
value	string[]	当前展开集合，单开模式下长度 ≤ 1。
collection	readonly AccordionNodeMeta[]	collection 推出的条目元信息，按数据顺序排列；没给 collection 即空数组。
setValue	(next: string[]) => void
isOpen	(value: string) => boolean
getRootProps	() => T['element']
getItemProps	(props: AccordionItemProps) => T['element']
getHeaderProps	(props: AccordionItemProps) => T['element']
getTriggerProps	(props: AccordionItemProps) => T['button']
getContentProps	(props: AccordionItemProps) => T['element']
getIndicatorProps	(props: AccordionItemProps) => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Space / Enter	focus in trigger, not disabled	展开/收起该条目的 content
ArrowDown / ArrowRight	focus in trigger, 按键与 orientation 同轴（dir=rtl 时左右键语义互换）	焦点移到下一个 trigger，末条不回绕
ArrowUp / ArrowLeft	focus in trigger, 按键与 orientation 同轴（dir=rtl 时左右键语义互换）	焦点移到上一个 trigger，首条不回绕
Home	focus in trigger	焦点移到首个 trigger
End	focus in trigger	焦点移到末个 trigger
Tab / Shift+Tab	focus in trigger	按文档序进出：每个 trigger 都是独立 Tab 停靠点，无 roving tabindex