Vant3 是一套面向 Vue3 的移动端组件库，Collapse 折叠面板是其中使用频率很高的一个组件。它可以把大段内容收纳起来，用户点击标题再展开，非常适合用于列表筛选、设置项分组、常见问题展示等场景。本文将从基本用法、核心属性、操作要点以及常见疑问几个方面，把这个组件讲透，帮助初次接触的开发者快速上手。
一、Collapse 折叠面板的基本用法
Collapse 组件由两部分组成：外层的 van-collapse 作为容器，内层的 van-collapse-item 表示每一个可折叠的项目。最简单的用法只需要给每个 item 设置 name 属性，再用 v-model 绑定当前展开项即可。
<template>
<van-collapse v-model="activeNames">
<van-collapse-item title="标题一" name="1">内容一</van-collapse-item>
<van-collapse-item title="标题二" name="2">内容二</van-collapse-item>
</van-collapse>
</template>
<script setup>
import { ref } from 'vue';
// 普通模式下 activeNames 必须是数组
const activeNames = ref(['1']);
</script>上面的代码中，页面初始渲染时第一个面板处于展开状态，因为数组里包含了它的 name 值。点击标题时，组件会自动把对应的 name 加入或移出数组，实现展开与收起，不需要手动处理点击逻辑。
需要特别注意的是 v-model 绑定值的类型。普通模式下必须是数组，手风琴模式下必须是字符串或数字，两者用错会导致面板点击没有反应或者行为异常，这是新手最常见的问题之一。
二、手风琴模式与常用属性详解
当希望同一时间只展开一个面板时，给 van-collapse 加上 accordion 属性即可，这就是手风琴模式。此时 v-model 绑定的不再是数组，而是单个值。
<van-collapse v-model="activeName" accordion>
<van-collapse-item title="标题一" name="a">内容一</van-collapse-item>
<van-collapse-item title="标题二" name="b">内容二</van-collapse-item>
</van-collapse>
<script setup>
import { ref } from 'vue';
// 手风琴模式绑定单个值，默认没有展开项
const activeName = ref('');
</script>除了 accordion，还有几个常用属性值得了解。border 控制是否显示外边框，默认为 true；如果页面本身有分割线设计，可以设为 false 避免线条重复。readonly 和 disabled 都能限制操作，区别在于 readonly 只禁止切换但仍可查看当前状态，disabled 则完全禁用，通常配合样式变灰展示。
在 van-collapse-item 层面，title 用于设置标题文字，icon 可以在标题前加图标，value 显示右侧的附加文字，is-link 控制是否显示右侧箭头。如果标题内容复杂，还可以通过具名插槽 title 自定义，比如标题里放一个标签或按钮。
<van-collapse-item name="3">
<template #title>
<div class="custom-title">
会员权益
<van-tag type="danger">推荐</van-tag>
</div>
</template>
具体权益内容...
</van-collapse-item>三、操作要点与事件监听
实际项目里经常需要在面板展开或收起时做额外处理，比如埋点上报、懒加载内容。Collapse 提供了 change 事件，在切换面板时触发，回调参数就是当前展开项的 name 值，普通模式下是数组，手风琴模式下是单个值。
<van-collapse v-model="activeNames" @change="onChange">
...
</van-collapse>
<script setup>
const onChange = (names) => {
console.log('当前展开的面板：', names);
// 可以在这里触发懒加载、埋点等逻辑
};
</script>一个实用技巧是配合动态数据渲染面板。当列表数据来自接口时，用 v-for 循环生成 van-collapse-item，name 绑定每条数据的唯一标识如 id，而不是简单的数组下标。因为列表刷新后下标可能变化，用 id 更稳定，展开状态也不会错乱。
另一个要点是动画高度的计算。Collapse 展开动画依赖内容区高度，如果内容是通过异步请求填充的，可能出现动画不流畅或高度异常。解决办法是内容加载完成后强制触发一次更新，或者预先给内容区设置最小高度，保证过渡自然。
四、常见疑问解答
问题一：点击面板没反应是怎么回事？先检查 v-model 绑定值的类型和模式是否匹配，普通模式用数组、手风琴模式用单个值。再检查是否误加了 readonly 或 disabled 属性。另外确认 name 属性有设置，且值与绑定数组中的元素类型一致，比如 name 是数字 1，数组里存的却是字符串 '1'，严格比较不通过也会导致状态不生效。
问题二：面板可以嵌套使用吗？可以在 van-collapse-item 的内容区再放一个 van-collapse，实现多级折叠，常见于分类菜单。但要注意内外层的 v-model 变量必须分开定义，name 值也建议用不同的前缀区分，避免状态互相干扰。层级不宜过深，否则用户体验和性能都会下降。
问题三：如何用代码控制面板展开或收起？直接修改 v-model 绑定的值即可。比如点击一个按钮展开全部面板，只需把所有 name 组成的数组赋值给绑定变量。在 script setup 中用 ref 包装的变量直接赋新值，视图会自动更新，非常方便。
<van-button @click="expandAll">全部展开</van-button>
<script setup>
const activeNames = ref(['1']);
const expandAll = () => {
activeNames.value = ['1', '2', '3'];
};
</script>问题四：为什么动态添加的面板默认展开不生效？因为 v-model 绑定的数组是在初始化时赋值的，后续新增的 name 不会自动加入。需要在数据加载完成后，手动把要展开项的 name 追加到数组中，例如在接口返回后执行 activeNames.value.push(newId)，这样新增面板才会处于展开状态。
掌握以上内容，Vant3 Collapse 折跃面板在日常开发中的绝大多数需求都能从容应对。核心记住三点：绑定值类型要与模式匹配、动态数据用唯一 id 作 name、异步内容注意高度更新，就能有效避开常见的坑。
Vant3Collapse折叠面板vue3组件修改时间：2026-09-04 18:08:36