uni-app
uni-app x
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
uni-app
uni-app x
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
uni-app x
GitHub
组件
uni-collapse
基本用法
具名插槽标题
externalClass
Slots
uni-collapse-item
Events
uni-collapse-item
Expose
uni-collapse-item
展示全部

# uni-collapse

折叠面板组件

本 Component 是 uni ext component，需下载插件：uni-collapse

折叠面板组件，包含：

  • uni-collapse：父容器
  • uni-collapse-item：子面板

一个折叠面板组件可以包含若干uni-collapse-item。每个uni-collapse-item包括顶部标题栏和通过slot传入的内容区。

# 基本用法

<uni-collapse :accordion="true">
  <uni-collapse-item title="标题 1" :open="true">
    <view><text>内容 1</text></view>
  </uni-collapse-item>
  <uni-collapse-item title="标题 2">
    <view><text>内容 2</text></view>
  </uni-collapse-item>
</uni-collapse>

uni-collapse-item的标题栏的自定义：

  • 标题栏容器可通过 title-wrap-class 自定义背景等容器样式。
  • 标题栏支持title属性，可通过title-class自定义文字样式。
  • 标题展开态可通过 title-open-class 自定义激活文字样式。组件默认使用透明度区分状态，便于外部继续覆盖文字颜色。
  • 标题禁用态可通过 title-disabled-class 自定义禁用文字样式。若同时存在展开态和禁用态，以禁用态为最终状态。
  • 内容外层容器可通过 content-wrap-class 自定义背景等容器样式。
  • 标题栏右边默认带有箭头，可通过arrow-class自定义箭头样式。该箭头为一个view包括2个直角边的边框，然后旋转而成。
  • 箭头展开态和禁用态可分别通过 arrow-open-class、arrow-disabled-class 覆盖。组件默认也使用透明度区分状态，便于外部继续覆盖箭头颜色。
  • 如果完全不想要默认包含的title和arrow，也可以传入一个名为title的具名插槽来替换。

# 具名插槽标题

<uni-collapse-item>
  <template #title="{ open, disabled }">
    <view class="custom-title">
      <view class="custom-title-icon"></view>
      <text class="custom-title-text">{{ open ? '已展开' : '未展开' }}</text>
    </view>
  </template>
  <view><text>自定义标题内容</text></view>
</uni-collapse-item>

# externalClass

<uni-collapse-item
  title="自定义样式"
  title-wrap-class="my-title-wrap-class"
  title-class="my-title-class"
  title-open-class="my-title-open-class"
  content-wrap-class="my-content-wrap-class"
  arrow-class="my-arrow-class"
  arrow-open-class="my-arrow-open-class"
>
  <view><text>内容区域</text></view>
</uni-collapse-item>

# Slots

# uni-collapse-item

插槽名 说明 插槽参数
default 面板内容 -
title 自定义标题区域 open: boolean、disabled: boolean

# Events

# uni-collapse-item

事件名 说明 回调参数
change 面板展开状态变化时触发 open: boolean

# Expose

# uni-collapse-item

方法名 说明
openCollapse(open: boolean) 执行展开/收起，会遵循 disabled 和手风琴逻辑
openOrClose(open: boolean) 直接切换内容显示状态

# 暗黑模式适配

建议通过组件 class 和 externalClass 组合传入暗色样式：

  • 用组件 class 统一控制根节点和内容区等外层视觉。
  • 用 title-wrap-class、title-class、title-open-class、content-wrap-class、arrow-class、arrow-open-class 等 externalClass 覆盖标题区、内容外层和箭头样式。
  • 默认展开态和禁用态主要通过透明度表达，减少颜色覆盖时的交叉冲突。

# 注意

  • 本组件在Android上需HBuilderX 5.09+。在低版本上箭头变颜色+旋转时，在Android上会消失

# 兼容性

Web 微信小程序 Android Android(Vapor) iOS iOS(Vapor) HarmonyOS HarmonyOS(Vapor)
5.07 5.07 5.07 x 5.07 x 5.07 5.07

# 属性

名称 类型 默认值 兼容性 描述
accordion boolean true - 是否开启手风琴模式，开启后同一时间仅允许一个子项展开

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<template>
  <scroll-view class="page">
    <view class="section">
      <text class="section-title">手风琴模式</text>
      <uni-collapse :accordion="true">
        <uni-collapse-item title="面板 A（默认展开）" :open="data.enableOpen" @change="onPanelAChange">
          <view class="content-box" @click="onPanelAClick">
            <text class="content-text">手风琴模式下，同时只会保持一个面板展开。点击当前标题会自动收起其他面板。</text>
          </view>
        </uni-collapse-item>
        <uni-collapse-item title="面板 B" @change="onPanelBChange">
          <view id="panel-b" class="content-box">
            <text class="content-text">当前项展开时，其他已展开的项会自动收起。这里用于验证切换动画和事件回调。</text>
          </view>
        </uni-collapse-item>
        <uni-collapse-item title="禁用项" :disabled="true">
          <view class="content-box">
            <text class="content-text">禁用状态下不会响应点击，也不会触发展开或收起。</text>
          </view>
        </uni-collapse-item>
      </uni-collapse>
    </view>

    <view class="section">
      <text class="section-title">普通模式-可同时展开的分组折叠列表</text>
      <uni-collapse :accordion="false">
        <uni-collapse-item v-for="(group, index) in categoryGroups" :key="group.title" :title="group.title" @change="onCategoryChange(group.title, $event as boolean)">
          <view class="category-list">
            <view v-for="(item, itemIndex) in group.items" :key="item.title" class="category-list-item"
              :class="{'category-list-item--last': itemIndex == group.items.length - 1}">
              <text class="category-list-text">{{ item.title }}</text>
              <view class="category-list-arrow"></view>
            </view>
          </view>
        </uni-collapse-item>
      </uni-collapse>
    </view>

    <view class="section">
      <text class="section-title">externalClass 示例</text>
      <uni-collapse :accordion="false">
        <uni-collapse-item title="自定义标题文字" title-class="demo-title-emphasis">
          <view class="content-box">
            <text class="content-text">通过 title-class 可以覆盖 title 属性对应 text 组件的样式。</text>
          </view>
        </uni-collapse-item>
        <uni-collapse-item title="自定义箭头样式" arrow-class="demo-arrow-large">
          <view class="content-box">
            <text class="content-text">通过 arrow-class 可以覆盖默认箭头 view 的尺寸、边框粗细和颜色。</text>
          </view>
        </uni-collapse-item>
        <uni-collapse-item title="同时自定义标题和箭头" title-class="demo-title-accent" arrow-class="demo-arrow-accent">
          <view class="content-box">
            <text class="content-text">title-class 和 arrow-class 可以组合使用。</text>
          </view>
        </uni-collapse-item>
      </uni-collapse>
    </view>

    <view class="section">
      <text class="section-title">具名插槽标题</text>
      <uni-collapse :accordion="false">
        <uni-collapse-item>
          <template #title="{ open, disabled }">
            <view class="slot-title-wrap">
              <view class="slot-title-icon" :class="{'slot-title-icon--open': open, 'slot-title-icon--disabled': disabled}"></view>
              <text class="slot-title-text" :class="{'slot-title-text--open': open, 'slot-title-text--disabled': disabled}">消息中心</text>
              <text class="slot-title-badge" :class="{'slot-title-badge--open': open}">{{ open ? 'OPEN' : 'CLOSE' }}</text>
            </view>
          </template>
          <view class="content-box">
            <text class="content-text">通过 #title 可以自定义标题区域结构，例如在文字前增加图标、状态徽标和辅助说明。</text>
          </view>
        </uni-collapse-item>
        <uni-collapse-item>
          <template #title="{ open }">
            <view class="slot-title-wrap">
              <view class="slot-title-icon slot-title-icon--secondary" :class="{'slot-title-icon--open': open}"></view>
              <text class="slot-title-text" :class="{'slot-title-text--open': open}">设置中心</text>
              <text class="slot-title-note">{{ open ? '当前已展开' : '点击展开配置项' }}</text>
            </view>
          </template>
          <view class="content-box">
            <text class="content-text">具名插槽会透出 open 和 disabled 状态，方便你在标题区域里联动样式。</text>
          </view>
        </uni-collapse-item>
      </uni-collapse>
    </view>

    <view class="section section-dark">
      <text class="section-title section-title-dark">暗黑模式 externalClass 示例</text>
      <view class="dark-tip">
        <text class="dark-tip-text">这个示例通过给 uni-collapse-item 传入 class 和 externalClass，分别定制内容区和标题区样式。</text>
      </view>
      <uni-collapse :accordion="false">
        <uni-collapse-item class="dark-collapse-item" title="暗色标题 A" :open="true" title-wrap-class="dark-title-wrap" title-class="dark-title-text" title-open-class="dark-title-text-open" content-wrap-class="dark-content-wrap" arrow-class="dark-arrow" arrow-open-class="dark-arrow-open">
          <view class="content-box dark-content-box">
            <text class="content-text dark-content-text">组件根节点通过 class 统一接入暗色卡片样式，标题背景、默认文字、展开态文字和箭头颜色通过 externalClass 传入。</text>
          </view>
        </uni-collapse-item>
        <uni-collapse-item class="dark-collapse-item dark-collapse-item-strong" title="暗色标题 B" title-wrap-class="dark-title-wrap-strong" title-class="dark-title-text-strong" title-open-class="dark-title-text-open" content-wrap-class="dark-content-wrap" arrow-class="dark-arrow-strong" arrow-open-class="dark-arrow-open">
          <view class="content-box dark-content-box">
            <text class="content-text dark-content-text">你也可以继续组合不同的根容器 class、标题字重、箭头粗细和激活色样式。</text>
          </view>
        </uni-collapse-item>
        <uni-collapse-item class="dark-collapse-item dark-collapse-item-muted" title="暗色禁用项" :disabled="true" title-wrap-class="dark-title-wrap-muted" title-class="dark-title-text" title-disabled-class="dark-title-text-disabled" content-wrap-class="dark-content-wrap-muted" arrow-class="dark-arrow" arrow-disabled-class="dark-arrow-disabled">
          <view class="content-box dark-content-box dark-content-box-muted">
            <text class="content-text dark-content-text">禁用态默认通过透明度表达状态，外部依然可以继续指定禁用态文字和箭头颜色。</text>
          </view>
        </uni-collapse-item>
      </uni-collapse>
    </view>

    <view class="log-section">
      <text class="log-title">最近事件</text>
      <text class="log-text">{{ data.lastEvent }}</text>
    </view>
  </scroll-view>
</template>

<script setup lang="uts">
  type CategoryItem = {
    title : string
  }

  type CategoryGroup = {
    title : string,
    items : CategoryItem[]
  }

  const categoryGroups : CategoryGroup[] = [
    {
      title: '分类1',
      items: [
        { title: '分类1-item1' },
        { title: '分类1-item2' },
        { title: '分类1-item3' }
      ]
    },
    {
      title: '分类2',
      items: [
        { title: '分类2-item1' },
        { title: '分类2-item2' },
        { title: '分类2-item3' }
      ]
    },
    {
      title: '分类3',
      items: [
        { title: '分类3-item1' },
        { title: '分类3-item2' },
        { title: '分类3-item3' }
      ]
    }
  ]

  type Data = {
    lastEvent: string,
    enableOpen: boolean
  }

  const data = reactive<Data>({
    lastEvent: '暂无交互',
    enableOpen: true
  })

  function updateEvent(panel : string, open : boolean) {
    const stateText = open ? '展开' : '收起'
    const message = `${panel}${stateText}`
    data.lastEvent = message
    console.log(`[collapse] ${message}`)
  }

  function onPanelAChange(open : boolean) {
    updateEvent('面板 A ', open)
  }

  function onPanelBChange(open : boolean) {
    updateEvent('面板 B ', open)
  }

  function onCategoryChange(title : string, open : boolean) {
    updateEvent(`${title} `, open)
  }

  const onPanelAClick = () => {
    console.log('onPanelAClick')
  }

  defineExpose({
    data,
    onPanelAClick
  })
</script>

<style>
  .page {
    flex: 1;
    padding: 12px;
  }

  .section {
    margin-bottom: 12px;
    border-radius: 8px;
    overflow: hidden;
    background-color: var(--list-background-color, #ffffff);
  }

  .section-title {
    padding: 12px;
    font-size: 14px;
    color: var(--text-color, #333333);
    font-weight: 500;
  }

  .content-box {
    padding: 12px;
    background-color: var(--active-background-color, #f8fafc);
  }

  .content-text {
    font-size: 13px;
    color: var(--text-color, #475569);
    opacity: 0.78;
    line-height: 20px;
  }

  .category-list {
    background-color: var(--active-background-color, #f8fafc);
  }

  .category-list-item {
    flex-direction: row;
    align-items: center;
    justify-content: space-between;
    padding: 12px 18px;
    border-bottom-width: 1px;
    border-bottom-style: solid;
    border-bottom-color: var(--border-color, #e2e8f0);
  }

  .category-list-item--last {
    border-bottom-width: 0px;
  }

  .category-list-text {
    flex: 1;
    font-size: 13px;
    color: var(--text-color, #334155);
    line-height: 20px;
  }

  .category-list-arrow {
    width: 8px;
    height: 8px;
    margin-left: 12px;
    transform: rotate(-45deg);
    border-right-width: 1px;
    border-right-style: solid;
    border-right-color: var(--arrow-color, #94a3b8);
    border-bottom-width: 1px;
    border-bottom-style: solid;
    border-bottom-color: var(--arrow-color, #94a3b8);
  }

  .demo-title-emphasis {
    font-size: 16px;
    font-weight: 700;
  }

  .demo-title-accent {
    font-size: 15px;
    font-weight: 700;
    color: #0f766e;
  }

  .demo-arrow-large {
    width: 12px;
    height: 12px;
    border-right-width: 2px;
    border-bottom-width: 2px;
  }

  .demo-arrow-accent {
    border-right-color: #0f766e;
    border-bottom-color: #0f766e;
    border-right-width: 2px;
    border-bottom-width: 2px;
  }

  .slot-title-wrap {
    flex: 1;
    flex-direction: row;
    align-items: center;
  }

  .slot-title-icon {
    width: 10px;
    height: 10px;
    border-radius: 5px;
    margin-right: 10px;
    background-color: #94a3b8;
  }

  .slot-title-icon--secondary {
    background-color: #c084fc;
  }

  .slot-title-icon--open {
    background-color: #2563eb;
  }

  .slot-title-icon--disabled {
    background-color: #cbd5e1;
  }

  .slot-title-text {
    flex: 1;
    font-size: 14px;
    color: var(--text-color, #1f2937);
    font-weight: 600;
  }

  .slot-title-text--open {
    color: #2563eb;
  }

  .slot-title-text--disabled {
    color: #94a3b8;
  }

  .slot-title-badge {
    padding: 4px 8px;
    border-radius: 10px;
    background-color: #e2e8f0;
    font-size: 11px;
    color: #475569;
  }

  .slot-title-badge--open {
    background-color: #dbeafe;
    color: #1d4ed8;
  }

  .slot-title-note {
    font-size: 12px;
    color: #64748b;
  }

  .section-dark {
    background-color: #111827;
  }

  .section-title-dark {
    color: #e5e7eb;
  }

  .dark-collapse-item {
    background-color: #111827;
  }

  .dark-collapse-item-strong {
    background-color: #0f172a;
  }

  .dark-collapse-item-muted {
    background-color: #101826;
  }

  .dark-tip {
    padding: 0px 12px 12px 12px;
  }

  .dark-tip-text {
    font-size: 12px;
    color: #9ca3af;
    line-height: 18px;
  }

  .dark-content-box {
    background-color: #1f2937;
  }

  .dark-content-wrap {
    background-color: #1f2937;
  }

  .dark-content-text {
    color: #cbd5e1;
  }

  .dark-content-box-muted {
    background-color: #182333;
  }

  .dark-content-wrap-muted {
    background-color: #182333;
  }

  .dark-title-wrap {
    background-color: #111827;
  }

  .dark-title-wrap-strong {
    background-color: #0f172a;
  }

  .dark-title-wrap-muted {
    background-color: #101826;
  }

  .dark-title-text {
    color: #f8fafc;
  }

  .dark-title-text-strong {
    font-size: 15px;
    font-weight: 700;
    color: #e2e8f0;
  }

  .dark-title-text-open {
    color: #60a5fa;
  }

  .dark-title-text-disabled {
    color: #94a3b8;
  }

  .dark-arrow {
    border-right-color: #cbd5e1;
    border-bottom-color: #cbd5e1;
  }

  .dark-arrow-strong {
    border-right-color: #cbd5e1;
    border-bottom-color: #cbd5e1;
    border-right-width: 2px;
    border-bottom-width: 2px;
  }

  .dark-arrow-open {
    border-right-color: #60a5fa;
    border-bottom-color: #60a5fa;
  }

  .dark-arrow-disabled {
    border-right-color: #94a3b8;
    border-bottom-color: #94a3b8;
  }

  .log-section {
    padding: 12px;
    border-radius: 8px;
    background-color: var(--list-background-color, #ffffff);
  }

  .log-title {
    font-size: 13px;
    color: var(--text-color, #333333);
    font-weight: 500;
    margin-bottom: 8px;
  }

  .log-text {
    font-size: 13px;
    color: #2563eb;
  }
</style>

# 参见

# uni-collapse-item

折叠面板子项组件

本 Component 是 uni ext component，需下载插件：uni-collapse-item

折叠面板组件，包含：

  • uni-collapse：父容器
  • uni-collapse-item：子面板

一个折叠面板组件可以包含若干uni-collapse-item。每个uni-collapse-item包括顶部标题栏和通过slot传入的内容区。

# 基本用法

<uni-collapse :accordion="true">
  <uni-collapse-item title="标题 1" :open="true">
    <view><text>内容 1</text></view>
  </uni-collapse-item>
  <uni-collapse-item title="标题 2">
    <view><text>内容 2</text></view>
  </uni-collapse-item>
</uni-collapse>

uni-collapse-item的标题栏的自定义：

  • 标题栏容器可通过 title-wrap-class 自定义背景等容器样式。
  • 标题栏支持title属性，可通过title-class自定义文字样式。
  • 标题展开态可通过 title-open-class 自定义激活文字样式。组件默认使用透明度区分状态，便于外部继续覆盖文字颜色。
  • 标题禁用态可通过 title-disabled-class 自定义禁用文字样式。若同时存在展开态和禁用态，以禁用态为最终状态。
  • 内容外层容器可通过 content-wrap-class 自定义背景等容器样式。
  • 标题栏右边默认带有箭头，可通过arrow-class自定义箭头样式。该箭头为一个view包括2个直角边的边框，然后旋转而成。
  • 箭头展开态和禁用态可分别通过 arrow-open-class、arrow-disabled-class 覆盖。组件默认也使用透明度区分状态，便于外部继续覆盖箭头颜色。
  • 如果完全不想要默认包含的title和arrow，也可以传入一个名为title的具名插槽来替换。

# 具名插槽标题

<uni-collapse-item>
  <template #title="{ open, disabled }">
    <view class="custom-title">
      <view class="custom-title-icon"></view>
      <text class="custom-title-text">{{ open ? '已展开' : '未展开' }}</text>
    </view>
  </template>
  <view><text>自定义标题内容</text></view>
</uni-collapse-item>

# externalClass

<uni-collapse-item
  title="自定义样式"
  title-wrap-class="my-title-wrap-class"
  title-class="my-title-class"
  title-open-class="my-title-open-class"
  content-wrap-class="my-content-wrap-class"
  arrow-class="my-arrow-class"
  arrow-open-class="my-arrow-open-class"
>
  <view><text>内容区域</text></view>
</uni-collapse-item>

# Slots

# uni-collapse-item

插槽名 说明 插槽参数
default 面板内容 -
title 自定义标题区域 open: boolean、disabled: boolean

# Events

# uni-collapse-item

事件名 说明 回调参数
change 面板展开状态变化时触发 open: boolean

# Expose

# uni-collapse-item

方法名 说明
openCollapse(open: boolean) 执行展开/收起，会遵循 disabled 和手风琴逻辑
openOrClose(open: boolean) 直接切换内容显示状态

# 暗黑模式适配

建议通过组件 class 和 externalClass 组合传入暗色样式：

  • 用组件 class 统一控制根节点和内容区等外层视觉。
  • 用 title-wrap-class、title-class、title-open-class、content-wrap-class、arrow-class、arrow-open-class 等 externalClass 覆盖标题区、内容外层和箭头样式。
  • 默认展开态和禁用态主要通过透明度表达，减少颜色覆盖时的交叉冲突。

# 注意

  • 本组件在Android上需HBuilderX 5.09+。在低版本上箭头变颜色+旋转时，在Android上会消失

# 兼容性

Web 微信小程序 Android Android(Vapor) iOS iOS(Vapor) HarmonyOS HarmonyOS(Vapor)
5.07 5.07 5.07 x 5.07 x 5.07 5.07

# 属性

名称 类型 默认值 兼容性 描述
title string "" - 折叠项标题文字
open boolean false - 是否默认展开
disabled boolean false - 是否禁用，禁用后点击标题不会展开或收起
titleWrapClass string(string.ClassString) "" - 标题行（整行容器）的样式类
titleClass string(string.ClassString) "" - 标题文字的基础样式类
titleOpenClass string(string.ClassString) "" - 展开状态下叠加到标题文字的样式类
titleDisabledClass string(string.ClassString) "" - 禁用状态下叠加到标题文字的样式类
contentWrapClass string(string.ClassString) "" - 内容外层容器的样式类
arrowClass string(string.ClassString) "" - 箭头图标的基础样式类
arrowOpenClass string(string.ClassString) "" - 展开状态下叠加到箭头图标的样式类
arrowDisabledClass string(string.ClassString) "" - 禁用状态下叠加到箭头图标的样式类
@change Event - - -

# 参见

本页导读
uni-collapse
基本用法
具名插槽标题
externalClass
Slots
uni-collapse-item
Events
uni-collapse-item
Expose
uni-collapse-item
暗黑模式适配
注意
兼容性
属性
示例
参见
uni-collapse-item
基本用法
具名插槽标题
externalClass
Slots
uni-collapse-item
Events
uni-collapse-item
Expose
uni-collapse-item
暗黑模式适配
注意
兼容性
属性
参见
uni-agent