uView Pro X

简体中文

English

简体中文

English

主题

Collapse 折叠面板 ​

17:06

说明 ​

由容器 ux-collapse 与面板 ux-collapse-item 组合使用：容器负责手风琴/多开状态管理与全局样式下发（arrow、arrowColor、headStyle、bodyStyle、itemStyle、hoverClass），面板负责标题与内容渲染、点击切换、展开高度动画以及 change 事件。面板通过 name 标识自身，未设置时按挂载顺序自动编号；容器默认手风琴模式（accordion=true），此时最多展开一个面板。

兼容性 ​

平台支持情况
App✅ 支持
H5✅ 支持
微信小程序✅ 支持（展开/收起无过渡动画，直接用 auto 高度切换）

示例 ​

基础用法 ​

非手风琴模式下可同时展开多个面板，点击标题切换展开/收起。

查看源码
vue
<template>
    <ux-collapse :accordion="false">
        <ux-collapse-item title="标题一">
            <text class="body">内容一：非手风琴模式下可同时展开多个面板</text>
        </ux-collapse-item>
        <ux-collapse-item title="标题二">
            <text class="body">内容二：点击标题切换展开/收起</text>
        </ux-collapse-item>
        <ux-collapse-item title="标题三">
            <text class="body">内容三：互不影响，可全部展开</text>
        </ux-collapse-item>
    </ux-collapse>
</template>

<style scoped>
.body {
    font-size: 14px;
    color: #909399;
    line-height: 1.6;
}
</style>

手风琴模式 ​

accordion=true 时每次只展开一个面板，展开其他面板会自动收起当前面板。

查看源码
vue
<template>
    <ux-collapse accordion>
        <ux-collapse-item title="标题一">
            <text class="body">内容一：手风琴模式同时只能展开一个</text>
        </ux-collapse-item>
        <ux-collapse-item title="标题二">
            <text class="body">内容二：手风琴模式同时只能展开一个</text>
        </ux-collapse-item>
    </ux-collapse>
</template>

<style scoped>
.body {
    font-size: 14px;
    color: #909399;
    line-height: 1.6;
}
</style>

初始展开 ​

通过 open 属性设置某个面板初始即为展开状态。

查看源码
vue
<template>
    <ux-collapse>
        <ux-collapse-item title="标题一" open>
            <text class="body">内容一：默认展开状态</text>
        </ux-collapse-item>
        <ux-collapse-item title="标题二">
            <text class="body">内容二：默认收起状态</text>
        </ux-collapse-item>
    </ux-collapse>
</template>

<style scoped>
.body {
    font-size: 14px;
    color: #909399;
    line-height: 1.6;
}
</style>

自定义标题 ​

通过 title 插槽自定义面板标题内容。

查看源码
vue
<template>
    <ux-collapse>
        <ux-collapse-item>
            <template #title>
                <view class="head">
                    <ux-icon name="star" size="15" color="#fa3534" />
                    <text class="head-text">自定义标题</text>
                </view>
            </template>
            <text class="body">通过 title 插槽自定义标题内容</text>
        </ux-collapse-item>
    </ux-collapse>
</template>

<style scoped>
.head {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.head-text {
    font-size: 15px;
    color: #303133;
    margin-left: 4px;
}
.body {
    font-size: 14px;
    color: #909399;
    line-height: 1.6;
}
</style>

自定义样式 ​

通过 itemStyle、headStyle、bodyStyle 自定义面板外观，arrowColor 设置箭头颜色。

查看源码
vue
<template>
    <ux-collapse
        arrow-color="#2979ff"
        :body-style="customBodyStyle"
        :head-style="customHeadStyle"
        :item-style="customItemStyle"
    >
        <ux-collapse-item title="自定义边框与圆角">
            <text class="body">itemStyle 为每个面板添加了边框、圆角与外边距</text>
        </ux-collapse-item>
        <ux-collapse-item title="自定义头部与内容样式">
            <text class="body">headStyle 设置了头部背景色，bodyStyle 设置了内容内边距</text>
        </ux-collapse-item>
    </ux-collapse>
</template>

<script setup lang="uts">
const customItemStyle: UTSJSONObject = {
    'border-width': '1px',
    'border-style': 'solid',
    'border-color': '#ebeef5',
    'border-radius': '8px',
    'margin-top': '12px',
    'overflow': 'hidden'
};
const customHeadStyle: UTSJSONObject = {
    'background-color': '#f8f9fb',
    'padding-left': '12px',
    'padding-right': '12px'
};
const customBodyStyle: UTSJSONObject = {
    'padding-left': '12px',
    'padding-right': '12px'
};
</script>

<style scoped>
.body {
    font-size: 14px;
    color: #909399;
    line-height: 1.6;
}
</style>

禁用状态 ​

disabled=true 的面板不可点击展开或收起。

查看源码
vue
<template>
    <ux-collapse>
        <ux-collapse-item title="禁用面板" disabled>
            <text class="body">禁用状态下无法展开</text>
        </ux-collapse-item>
    </ux-collapse>
</template>

<style scoped>
.body {
    font-size: 14px;
    color: #909399;
    line-height: 1.6;
}
</style>

嵌套折叠 ​

ux-collapse 支持嵌套：在外层面板内再放一个 ux-collapse，两层独立展开，外层高度自动适应。

查看源码
vue
<template>
    <ux-collapse>
        <ux-collapse-item title="外层面板（默认展开）" open>
            <text class="body">外层内容：下方嵌套了一组内层折叠面板</text>
            <ux-collapse :item-style="nestedItemStyle">
                <ux-collapse-item title="内层面板一">
                    <text class="body">内层内容一：点击内层标题可独立展开，不影响外层状态</text>
                </ux-collapse-item>
                <ux-collapse-item title="内层面板二（默认展开）" open>
                    <text class="body">内层内容二：外层容器高度会随内层展开/收起自动变化</text>
                </ux-collapse-item>
            </ux-collapse>
        </ux-collapse-item>
    </ux-collapse>
</template>

<script setup lang="uts">
const nestedItemStyle: UTSJSONObject = {
    'border-width': '1px',
    'border-style': 'solid',
    'border-color': '#ebeef5',
    'border-radius': '6px',
    'margin-top': '8px',
    'padding-left': '12px',
    'padding-right': '12px',
    'background-color': '#fafafa',
    'overflow': 'hidden'
};
</script>

<style scoped>
.body {
    font-size: 14px;
    color: #909399;
    line-height: 1.6;
}
</style>

API ​

Props ​

ux-collapse ​

属性说明类型默认值版本
customStyle自定义根节点样式UTSJSONObject--
customClass自定义根节点样式类string''-
accordion是否手风琴模式booleantrue-
headStyle面板头部的样式UTSJSONObject--
bodyStyle面板主体的样式UTSJSONObject--
itemStyle每个面板的样式UTSJSONObject--
arrow是否显示右侧箭头booleantrue-
arrowColor箭头的颜色string''-
hoverClass标题部分按压时的样式类，"none" 为无效果string'ux-collapse--hover'-

ux-collapse-item ​

属性说明类型默认值版本
customStyle自定义根节点样式UTSJSONObject--
customClass自定义根节点样式类string''-
title面板标题string''-
align标题的对齐方式string'left'-
disabled面板是否可以打开或收起booleanfalse-
open面板初始状态是否打开booleanfalse-
name唯一标识符，不设置时按挂载顺序自动编号string | number''-
activeStyle不显示箭头时，展开态叠加到标题上的活动样式UTSJSONObject--
index用于事件回调，标识被点击的面板string | number''-

Events ​

ux-collapse-item ​

事件名说明回调参数版本
change某个面板被打开或收起时触发value: { index: string | number; name: string | number; show: boolean }-

Slots ​

ux-collapse ​

插槽名说明版本
default默认插槽，放置 ux-collapse-item 面板-

ux-collapse-item ​

插槽名说明版本
title自定义标题文字（箭头仍会显示）-
title-all自定义整个头部内容（含箭头）-
default面板内容-

注意事项 ​

  1. ux-collapse-item 依赖父级 ux-collapse 提供上下文；脱离容器单独使用时状态不联动，点击仅派发 change。
  2. 面板唯一标识的取值优先级为 name > index > 挂载顺序，未显式设置时按顺序自动编号。
  3. 手风琴模式（accordion=true）最多展开一个，非手风琴模式可多开；open 只在挂载时注册初始展开态，手风琴模式下只有第一个 open 生效。
  4. 微信小程序端展开/收起无过渡动画（transition 被禁用），展开高度直接用 auto；App/H5 使用测量得到的内容高度，并借助 UniResizeObserver 监听，嵌套或动态内容时外层高度会自动适应。
  5. arrow、arrowColor、headStyle、bodyStyle、itemStyle、hoverClass 均由容器统一下发；面板单独使用时走自身默认值（箭头默认显示、箭头色取 tipsColor）。
  6. title 插槽只替换标题文字，箭头仍会显示；需要连箭头一起自定义时改用 title-all，它会接管整个头部。
  7. activeStyle 仅在「已展开且不显示箭头」时叠加到标题样式上。
  8. change 由面板派发，参数为 { index, name, show }；disabled=true 的面板点击被拦截，不会切换状态。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5