Collapse 折叠面板

可以折叠/展开的内容区域。

?

名称	分类	说明	类型	默认值
ghost	? 风格	幽灵模式，无边框和背景	boolean	false
icon-placement	? 风格	指示器图标位置	'start' | 'end'	'end'
CollapseItemshow-arrow	? 风格	是否显示箭头指示器	boolean	true
CollapseItemicon	? 风格	自定义指示器图标名称（支持所有内置图标）。设为 "plus" 时自动在展开/收起间切换加减号	string	—
color	? 颜色	颜色主题，支持预设名称（primary / success / warning / danger / info）或自定义十六进制颜色	string	—
CollapseItemdisabled	? 状态	是否禁用	boolean	false
accordion	? 行为	是否开启手风琴模式	boolean	false
trigger	? 行为	触发方式。focus 模式下聚焦展开、失焦收起	'click' | 'focus'	'click'
CollapseItemforce-open	? 行为	强制展开，忽略 modelValue 和点击交互	boolean	false
CollapseItemforce-close	? 行为	强制收起，忽略 modelValue 和点击交互。优先级高于 force-open	boolean	false
model-value / v-model	? 内容	当前激活的面板	string | string[]	—
CollapseItemname	? 内容	唯一标识符	string	—
CollapseItemtitle	? 内容	标题	string	—
change	? 事件	激活面板改变时触发	(activeNames: string | string[]) => void	—
CollapseItemdefault	? 插槽	面板内容		—
CollapseItemtitle	? 插槽	自定义标题		—

基础用法

可同时展开多个面板，面板之间不会影响。

<script setup lang="ts">
import { type CollapseItemName } from 'sakana-element';
import { ref } from 'vue';

const activeNames = ref(['1']);

function handleChange(_val: CollapseItemName[]) {}
</script>

<template>
  <px-collapse v-model="activeNames" @change="handleChange">
    <px-collapse-item title="Consistency" name="1">
      <div>
        Consistent with real life: in line with the process and logic of real
        life, and comply with languages and habits that the users are used to;
      </div>
      <div>
        Consistent within interface: all elements should be consistent, such as:
        design style, icons and texts, position of elements, etc.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Feedback" name="2">
      <div>
        Operation feedback: enable the users to clearly perceive their
        operations by style updates and interactive effects;
      </div>
      <div>
        Visual feedback: reflect current state by updating or rearranging
        elements of the page.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Efficiency" name="3">
      <div>
        Simplify the process: keep operating process simple and intuitive;
      </div>
      <div>
        Definite and clear: enunciate your intentions clearly so that the users
        can quickly understand and make decisions;
      </div>
      <div>
        Easy to identify: the interface should be straightforward, which helps
        the users to identify and frees them from memorizing and recalling.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Controllability" name="4">
      <div>
        Decision making: giving advices about operations is acceptable, but do
        not make decisions for the users;
      </div>
      <div>
        Controlled consequences: users should be granted the freedom to operate,
        including canceling, aborting or terminating current operation.
      </div>
    </px-collapse-item>
  </px-collapse>
</template>

手风琴模式

使用 accordion 属性来设置手风琴模式，每次只能展开一个面板。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>

<template>
  <px-collapse v-model="activeNames" accordion>
    <px-collapse-item title="Consistency" name="1">
      <div>
        Consistent with real life: in line with the process and logic of real
        life, and comply with languages and habits that the users are used to;
      </div>
      <div>
        Consistent within interface: all elements should be consistent, such as:
        design style, icons and texts, position of elements, etc.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Feedback" name="2">
      <div>
        Operation feedback: enable the users to clearly perceive their
        operations by style updates and interactive effects;
      </div>
      <div>
        Visual feedback: reflect current state by updating or rearranging
        elements of the page.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Efficiency" name="3">
      <div>
        Simplify the process: keep operating process simple and intuitive;
      </div>
      <div>
        Definite and clear: enunciate your intentions clearly so that the users
        can quickly understand and make decisions;
      </div>
      <div>
        Easy to identify: the interface should be straightforward, which helps
        the users to identify and frees them from memorizing and recalling.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Controllability" name="4">
      <div>
        Decision making: giving advices about operations is acceptable, but do
        not make decisions for the users;
      </div>
      <div>
        Controlled consequences: users should be granted the freedom to operate,
        including canceling, aborting or terminating current operation.
      </div>
    </px-collapse-item>
  </px-collapse>
</template>

颜色变体

使用 color 属性设置预设颜色名称，为折叠面板添加主题色。

<script setup lang="ts">
import { ref } from 'vue';

const active1 = ref(['1']);
const active2 = ref(['1']);
const active3 = ref(['1']);
const active4 = ref(['1']);
const active5 = ref(['1']);
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px;">
    <px-collapse v-model="active1" color="primary">
      <px-collapse-item title="Primary Color" name="1">
        This collapse uses the primary color theme.
      </px-collapse-item>
      <px-collapse-item title="Second Item" name="2">
        Content of the second item.
      </px-collapse-item>
    </px-collapse>

    <px-collapse v-model="active2" color="success">
      <px-collapse-item title="Success Color" name="1">
        This collapse uses the success color theme.
      </px-collapse-item>
      <px-collapse-item title="Second Item" name="2">
        Content of the second item.
      </px-collapse-item>
    </px-collapse>

    <px-collapse v-model="active3" color="warning">
      <px-collapse-item title="Warning Color" name="1">
        This collapse uses the warning color theme.
      </px-collapse-item>
      <px-collapse-item title="Second Item" name="2">
        Content of the second item.
      </px-collapse-item>
    </px-collapse>

    <px-collapse v-model="active4" color="danger">
      <px-collapse-item title="Danger Color" name="1">
        This collapse uses the danger color theme.
      </px-collapse-item>
      <px-collapse-item title="Second Item" name="2">
        Content of the second item.
      </px-collapse-item>
    </px-collapse>

    <px-collapse v-model="active5" color="info">
      <px-collapse-item title="Info Color" name="1">
        This collapse uses the info color theme.
      </px-collapse-item>
      <px-collapse-item title="Second Item" name="2">
        Content of the second item.
      </px-collapse-item>
    </px-collapse>
  </div>
</template>

自定义颜色

传递任意十六进制颜色字符串给 color 属性，实现完全自定义的颜色主题。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>

<template>
  <px-collapse v-model="activeNames" color="#e91e63">
    <px-collapse-item title="Custom Hex Color" name="1">
      This collapse uses a custom hex color (#e91e63).
    </px-collapse-item>
    <px-collapse-item title="Second Item" name="2">
      Content of the second item.
    </px-collapse-item>
    <px-collapse-item title="Third Item" name="3">
      Content of the third item.
    </px-collapse-item>
  </px-collapse>
</template>

幽灵模式

启用 ghost 模式，移除边框和背景 — 适合嵌入其他容器内使用。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>

<template>
  <px-collapse v-model="activeNames" ghost>
    <px-collapse-item title="Ghost Mode" name="1">
      This collapse uses ghost mode — no pixel border or shadow.
    </px-collapse-item>
    <px-collapse-item title="Clean Look" name="2">
      Perfect for embedding inside other containers.
    </px-collapse-item>
    <px-collapse-item title="Minimal Style" name="3">
      Keeps the interaction while removing visual weight.
    </px-collapse-item>
  </px-collapse>
</template>

聚焦触发

设置 trigger="focus" 使面板在聚焦时展开、失焦时收起。可使用 Tab 键导航。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref<string[]>([]);
</script>

<template>
  <px-collapse v-model="activeNames" trigger="focus">
    <px-collapse-item title="Focus to Open" name="1">
      This item opens when the header receives focus (Tab key or click).
    </px-collapse-item>
    <px-collapse-item title="Blur to Close" name="2">
      This item closes when focus moves away from the header.
    </px-collapse-item>
    <px-collapse-item title="Try Tab Key" name="3">
      Use Tab to navigate between items — they open and close automatically.
    </px-collapse-item>
  </px-collapse>
</template>

图标位置

使用 icon-placement="start" 将箭头指示器移到标题前方。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>

<template>
  <px-collapse v-model="activeNames" icon-placement="start">
    <px-collapse-item title="Icon at Start" name="1">
      The arrow indicator is placed before the title text.
    </px-collapse-item>
    <px-collapse-item title="Left-side Arrow" name="2">
      This layout is common in file explorers and tree views.
    </px-collapse-item>
    <px-collapse-item title="Familiar Pattern" name="3">
      Users can quickly identify expandable sections.
    </px-collapse-item>
  </px-collapse>
</template>

强制展开/收起

在单个项目上使用 force-open 或 force-close 锁定其状态。force-close 优先级高于 force-open。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['2']);
</script>

<template>
  <px-collapse v-model="activeNames">
    <px-collapse-item title="Always Open (force-open)" name="1" force-open>
      This item is always expanded, regardless of the v-model value. Clicking the header has no effect.
    </px-collapse-item>
    <px-collapse-item title="Normal Item" name="2">
      This item behaves normally — click to toggle.
    </px-collapse-item>
    <px-collapse-item title="Always Closed (force-close)" name="3" force-close>
      This item is always collapsed. Even if its name is in the v-model array, it stays closed.
    </px-collapse-item>
  </px-collapse>
</template>

隐藏箭头

设置 show-arrow="false" 隐藏箭头指示器，获得更简洁的外观。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>
<template>
  <px-collapse v-model="activeNames">
    <px-collapse-item title="How do I create an account?" name="1" :show-arrow="false">
      Click the "Sign Up" button in the top right corner and follow the registration process.
    </px-collapse-item>
    <px-collapse-item title="I forgot my password. What should I do?" name="2" :show-arrow="false">
      Click "Forgot Password" on the login page to reset your password via email.
    </px-collapse-item>
    <px-collapse-item title="How do I update my profile information?" name="3" :show-arrow="false">
      Go to Settings > Profile to update your personal information.
    </px-collapse-item>
  </px-collapse>
</template>

加减号图标

使用 icon="plus" 将默认箭头替换为加减号切换指示器。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>
<template>
  <px-collapse v-model="activeNames">
    <px-collapse-item title="How do I create an account?" name="1" icon="plus">
      Click the "Sign Up" button in the top right corner and follow the registration process.
    </px-collapse-item>
    <px-collapse-item title="I forgot my password. What should I do?" name="2" icon="plus">
      Click "Forgot Password" on the login page to reset your password via email.
    </px-collapse-item>
    <px-collapse-item title="How do I update my profile information?" name="3" icon="plus">
      Go to Settings > Profile to update your personal information.
    </px-collapse-item>
  </px-collapse>
</template>

自定义图标

使用 icon 属性设置任意内置图标名称来替换默认箭头。图标保持静态显示（不旋转）。设置 icon="plus" 可实现上方展示的加减号切换效果。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>
<template>
  <px-collapse v-model="activeNames">
    <px-collapse-item title="Favorites" name="1" icon="heart">
      Manage your favorite items and saved collections here.
    </px-collapse-item>
    <px-collapse-item title="Bookmarks" name="2" icon="bookmark">
      Access your bookmarked pages and resources.
    </px-collapse-item>
    <px-collapse-item title="Quick Actions" name="3" icon="zap">
      Shortcuts for frequently used operations.
    </px-collapse-item>
  </px-collapse>
</template>

自定义标题

使用 title 插槽来自定义标题内容。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>

<template>
  <px-collapse v-model="activeNames" accordion>
    <px-collapse-item name="1">
      <template #title>
        <span style="color: var(--px-color-danger)"> Consistency </span>
        <px-icon icon="info-box" />
      </template>
      <div>
        Consistent with real life: in line with the process and logic of real
        life, and comply with languages and habits that the users are used to;
      </div>
      <div>
        Consistent within interface: all elements should be consistent, such as:
        design style, icons and texts, position of elements, etc.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Feedback" name="2">
      <div>
        Operation feedback: enable the users to clearly perceive their
        operations by style updates and interactive effects;
      </div>
      <div>
        Visual feedback: reflect current state by updating or rearranging
        elements of the page.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Efficiency" name="3">
      <div>
        Simplify the process: keep operating process simple and intuitive;
      </div>
      <div>
        Definite and clear: enunciate your intentions clearly so that the users
        can quickly understand and make decisions;
      </div>
      <div>
        Easy to identify: the interface should be straightforward, which helps
        the users to identify and frees them from memorizing and recalling.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Controllability" name="4">
      <div>
        Decision making: giving advices about operations is acceptable, but do
        not make decisions for the users;
      </div>
      <div>
        Controlled consequences: users should be granted the freedom to operate,
        including canceling, aborting or terminating current operation.
      </div>
    </px-collapse-item>
  </px-collapse>
</template>

禁用状态

使用 disabled 属性来禁用面板。

<script setup lang="ts">
import { ref } from 'vue';

const activeNames = ref(['1']);
</script>

<template>
  <px-collapse v-model="activeNames">
    <px-collapse-item title="Consistency" name="1">
      <div>
        Consistent with real life: in line with the process and logic of real
        life, and comply with languages and habits that the users are used to;
      </div>
      <div>
        Consistent within interface: all elements should be consistent, such as:
        design style, icons and texts, position of elements, etc.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Feedback" name="2" disabled>
      <div>
        Operation feedback: enable the users to clearly perceive their
        operations by style updates and interactive effects;
      </div>
      <div>
        Visual feedback: reflect current state by updating or rearranging
        elements of the page.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Efficiency" name="3" disabled>
      <div>
        Simplify the process: keep operating process simple and intuitive;
      </div>
      <div>
        Definite and clear: enunciate your intentions clearly so that the users
        can quickly understand and make decisions;
      </div>
      <div>
        Easy to identify: the interface should be straightforward, which helps
        the users to identify and frees them from memorizing and recalling.
      </div>
    </px-collapse-item>
    <px-collapse-item title="Controllability" name="4">
      <div>
        Decision making: giving advices about operations is acceptable, but do
        not make decisions for the users;
      </div>
      <div>
        Controlled consequences: users should be granted the freedom to operate,
        including canceling, aborting or terminating current operation.
      </div>
    </px-collapse-item>
  </px-collapse>
</template>