Collapse

17:06

Description

A composite of the container ux-collapse and the panel ux-collapse-item: the container manages the accordion/multi-open state and distributes global styles (arrow, arrowColor, headStyle, bodyStyle, itemStyle, hoverClass), while each panel renders the title and content, handles tap toggling, the expand height animation and the change event. A panel identifies itself by name and falls back to its mount order when unset; the container defaults to accordion mode (accordion=true), so at most one panel is open.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported (no expand/collapse transition; height switches directly between auto and 0)

Examples

Basic Usage

In non-accordion mode, multiple panels can be expanded at the same time; tap the title to toggle.

View source

<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 Mode

When accordion=true, only one panel is expanded at a time; expanding another collapses the current one.

View source

<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>

Initial Open

Set the initial expanded state of a panel via the open prop.

View source

<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>

Custom Title

Customize the panel title content via the title slot.

View source

<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>

Custom Styles

Customize the panel look via itemStyle, headStyle and bodyStyle; arrowColor sets the arrow color.

View source

<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 State

A panel with disabled=true cannot be expanded or collapsed by tapping.

View source

<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>

Nested Collapse

ux-collapse supports nesting: place another ux-collapse inside an outer panel, two levels expand independently and the outer height adapts automatically.

View source

<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

Property	Description	Type	Default	Version
customStyle	Custom style for the root node	UTSJSONObject	-	-
customClass	Custom class for the root node	string	''	-
accordion	Whether to use accordion mode	boolean	true	-
headStyle	Style for the panel head	UTSJSONObject	-	-
bodyStyle	Style for the panel body	UTSJSONObject	-	-
itemStyle	Style for each panel	UTSJSONObject	-	-
arrow	Whether to show the arrow on the right	boolean	true	-
arrowColor	Arrow color	string	''	-
hoverClass	Class applied while the title is pressed; "none" disables the feedback	string	'ux-collapse--hover'	-

ux-collapse-item

Property	Description	Type	Default	Version
customStyle	Custom style for the root node	UTSJSONObject	-	-
customClass	Custom class for the root node	string	''	-
title	Panel title	string	''	-
align	Title alignment	string	'left'	-
disabled	Whether the panel can be expanded or collapsed	boolean	false	-
open	Whether the panel is open initially	boolean	false	-
name	Unique identifier; falls back to mount order when unset	string | number	''	-
activeStyle	Active style merged into the title when expanded and the arrow is hidden	UTSJSONObject	-	-
index	Used in the event callback to identify the tapped panel	string | number	''	-

Events

ux-collapse-item

Event	Description	Params	Version
change	Emitted when a panel is expanded or collapsed	value: { index: string | number; name: string | number; show: boolean }	-

Slots

ux-collapse

Slot	Description	Version
default	Default slot holding ux-collapse-item panels	-

ux-collapse-item

Slot	Description	Version
title	Custom title text (the arrow is still shown)	-
title-all	Custom content for the whole head, including the arrow	-
default	Panel content	-

Notes

1. ux-collapse-item relies on its parent ux-collapse for context; used standalone without the container, its state is not linked and a tap only emits change.
2. The panel identifier resolves in the order name > index > mount order; when unset it is numbered automatically by order.
3. Accordion mode (accordion=true) allows at most one open panel, while non-accordion mode allows several; open registers the initial expanded state only on mount, and in accordion mode only the first open takes effect.
4. On WeChat Mini Program there is no expand/collapse transition (the transition is disabled) and the height switches directly to auto; App/H5 use the measured content height with a UniResizeObserver, so the outer height adapts automatically for nested or dynamic content.
5. arrow, arrowColor, headStyle, bodyStyle, itemStyle and hoverClass are all distributed by the container; used standalone, a panel falls back to its own defaults (arrow shown by default, arrow color from tipsColor).
6. The title slot replaces only the title text and the arrow is still shown; to customize the arrow as well use the title-all slot, which takes over the whole head.
7. activeStyle is merged into the title style only when the panel is expanded and the arrow is hidden.
8. change is emitted by the panel with { index, name, show }; a panel with disabled=true swallows the tap and does not toggle.