@tanzhenxing/zx-collapse v1.0.2

zx-collapse 折叠面板

折叠面板组件，可以将内容区域进行折叠和展开，支持手风琴模式，适用于展示层级结构信息。

功能特性

• ✅ 支持多个面板同时展开/折叠
• ✅ 支持手风琴模式（同时只能展开一个面板）
• ✅ 支持自定义图标位置（左侧/右侧）
• ✅ 支持禁用状态
• ✅ 支持自定义标题、内容和图标
• ✅ 支持动画效果
• ✅ 支持边框显示/隐藏
• ✅ 响应式设计，适配不同屏幕尺寸

平台兼容性

基础用法

<template>
  <zx-collapse v-model="activeNames" :items="items" @change="handleChange" />
</template>

<script setup>
import { ref } from 'vue'

const activeNames = ref(['1'])

const items = ref([
  {
    name: '1',
    title: '一致性',
    content: '与现实生活一致：与现实生活的流程、逻辑保持一致，遵循用户习惯的语言和概念。'
  },
  {
    name: '2', 
    title: '反馈',
    content: '控制反馈：通过界面样式和交互动效让用户可以清晰的感知自己的操作。'
  },
  {
    name: '3',
    title: '效率',
    content: '简化流程：设计简洁直观的操作流程；清晰明确：语言表达清晰且表意明确。'
  }
])

const handleChange = (value) => {
  console.log('当前激活的面板:', value)
}
</script>

手风琴模式

设置 accordion 属性为 true 开启手风琴模式，每次只能展开一个面板。

<template>
  <zx-collapse 
    v-model="activeName" 
    :items="items" 
    accordion 
    @change="handleChange" 
  />
</template>

<script setup>
import { ref } from 'vue'

const activeName = ref('1')
// 手风琴模式下，v-model 绑定的是字符串或数字
</script>

自定义图标位置

通过 expand-icon-position 属性控制展开图标的位置。

<template>
  <!-- 图标在左侧 -->
  <zx-collapse 
    v-model="activeNames" 
    :items="items" 
    expand-icon-position="left" 
  />
  
  <!-- 图标在右侧（默认） -->
  <zx-collapse 
    v-model="activeNames" 
    :items="items" 
    expand-icon-position="right" 
  />
</template>

禁用状态

在数据项中设置 disabled: true 来禁用特定的面板。

<template>
  <zx-collapse v-model="activeNames" :items="items" />
</template>

<script setup>
import { ref } from 'vue'

const activeNames = ref([])

const items = ref([
  {
    name: '1',
    title: '可用面板',
    content: '这是一个可用的面板内容'
  },
  {
    name: '2',
    title: '禁用面板',
    content: '这是一个禁用的面板内容',
    disabled: true
  }
])
</script>

自定义标题和内容

使用具名插槽可以自定义标题和内容。

<template>
  <zx-collapse v-model="activeNames" :items="items">
    <!-- 自定义标题 -->
    <template #title="{ item, isActive }">
      <view class="custom-title">
        <text :style="{ color: isActive ? '#409EFF' : '#303133' }">
          {{ item.title }}
        </text>
        <zx-tag v-if="item.tag" :type="item.tagType">{{ item.tag }}</zx-tag>
      </view>
    </template>
    
    <!-- 自定义内容 -->
    <template #default="{ item }">
      <view class="custom-content">
        <text>{{ item.content }}</text>
        <zx-button v-if="item.showButton" size="small" type="primary">
          查看详情
        </zx-button>
      </view>
    </template>
  </zx-collapse>
</template>

自定义图标

使用 icon 插槽可以自定义展开图标。

<template>
  <zx-collapse v-model="activeNames" :items="items">
    <template #icon="{ item, isActive }">
      <zx-icon 
        :name="isActive ? 'arrow-down' : 'arrow-right'" 
        color="#409EFF" 
        size="20"
      />
    </template>
  </zx-collapse>
</template>

API

Props

Items 数据结构

每个面板项支持以下属性：

Events

Slots

样式变量

组件支持以下 CSS 变量自定义：

.zx-collapse {
  --zx-collapse-border-color: #EBEEF5;
  --zx-collapse-bg-color: #fff;
  --zx-collapse-hover-bg-color: #F5F7FA;
  --zx-collapse-border-radius: 8rpx;
  --zx-collapse-header-padding: 20rpx;
  --zx-collapse-header-min-height: 88rpx;
  --zx-collapse-content-padding: 20rpx;
  --zx-collapse-transition-duration: 0.3s;
}

注意事项

1. 数据项中的 name 字段应该是唯一的，如果不提供会使用数组索引作为标识符
2. 手风琴模式下，v-model 绑定的值应该是字符串或数字，普通模式下应该是数组
3. 组件依赖 zx-icon 组件，请确保项目中已经引入
4. 在小程序环境下，动画效果可能会有所差异
5. 内容区域的高度变化使用了 CSS 过渡动画，在某些情况下可能需要手动触发重新渲染

更新日志

v1.0.0

• 初始版本发布
• 支持基础的折叠展开功能
• 支持手风琴模式
• 支持自定义样式和图标