xtf-collapse

组件说明

xtf-collapse 是折叠面板组件，用于将内容分组折叠/展开展示。支持手风琴模式、箭头位置切换、无边框模式、内容最大高度限制和插槽自定义，适用于 FAQ、帮助中心和设置分组等场景。

基础用法

1. 最简示例

通过 items 传入面板数据，value 绑定展开项：

vue

<template>
  <xtf-collapse v-model="active" :items="items" />
</template>

<script>
export default {
  data() {
    return {
      active: ['faq1'],
      items: [
        {
          title: '如何注册账号？',
          content: '点击登录页面的"注册"按钮，按照提示填写手机号和验证码即可完成注册。',
          name: 'faq1'
        },
        {
          title: '如何修改密码？',
          content: '进入"设置 > 账号安全 > 修改密码"，输入原密码和新密码即可。',
          name: 'faq2'
        },
        {
          title: '如何注销账号？',
          content: '进入"设置 > 账号安全 > 注销账号"，确认后7天内可撤回。',
          name: 'faq3'
        }
      ]
    }
  }
}
</script>

2. 手风琴模式

通过 accordion 限制同时只能展开一个面板：

vue

<template>
  <xtf-collapse v-model="active" :items="items" accordion />
</template>

<script>
export default {
  data() {
    return {
      active: '',
      items: [
        {
          title: '配送说明',
          content: '下单后48小时内发货，偏远地区3-5个工作日送达。',
          name: 'delivery'
        },
        {
          title: '退换政策',
          content: '签收后7天内可申请退换，商品需保持原包装完好。',
          name: 'return'
        },
        { title: '发票说明', content: '支持电子发票，下单时备注发票抬头即可。', name: 'invoice' }
      ]
    }
  }
}
</script>

3. 箭头位置与无边框

通过 iconPosition 切换箭头位置，通过 borderless 移除边框和背景：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx">
    <xtf-text level="caption" color="secondary">箭头在左侧</xtf-text>
    <xtf-collapse v-model="active1" :items="items" icon-position="left" />

    <xtf-text level="caption" color="secondary">无边框模式</xtf-text>
    <xtf-collapse v-model="active2" :items="items" borderless />
  </view>
</template>

<script>
export default {
  data() {
    return {
      active1: [],
      active2: [],
      items: [
        { title: '常见问题一', content: '这是常见问题一的详细解答。', name: 'q1' },
        { title: '常见问题二', content: '这是常见问题二的详细解答。', name: 'q2' },
        { title: '常见问题三', content: '这是常见问题三的详细解答。', name: 'q3' }
      ]
    }
  }
}
</script>

4. 插槽自定义与禁用

通过 title 和 content 插槽自定义内容，通过 disabled 禁用某项：

vue

<template>
  <xtf-collapse v-model="active" :items="items">
    <template #title="{ item, index }">
      <view style="display: flex; align-items: center; gap: 12rpx">
        <xtf-icon :name="item.icon" theme="primary" size="sm" />
        <xtf-text level="body" :bold="true" :text="item.title" />
      </view>
    </template>
    <template #content="{ item }">
      <xtf-text level="body" color="secondary" :text="item.content" />
    </template>
  </xtf-collapse>
</template>

<script>
export default {
  data() {
    return {
      active: ['info'],
      items: [
        {
          title: '个人信息',
          content: '你可以在这里查看和编辑个人资料。',
          name: 'info',
          icon: 'person'
        },
        {
          title: '安全设置',
          content: '管理密码、绑定手机和邮箱。',
          name: 'security',
          icon: 'lock'
        },
        {
          title: '系统维护中',
          content: '该功能正在维护，暂时不可用。',
          name: 'disabled',
          icon: 'build',
          disabled: true
        }
      ]
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`value`	`String \| Number \| Array`	`''`	展开项，手风琴模式为字符串，多选模式为数组	控制展开
`items`	`Array`	`[]`	面板数据，每项支持 `{ title, desc, content, name, disabled, contentHeight }`	面板数据
`accordion`	`Boolean`	`false`	是否手风琴模式（同时只展开一个）	手风琴
`borderless`	`Boolean`	`false`	是否无边框模式	无边框
`iconPosition`	`String`	`'right'`	箭头位置：`'left'` / `'right'`	切换箭头位置
`radius`	`String \| Number`	`28`	圆角（rpx）	控制圆角
`contentMaxHeight`	`String \| Number`	`720`	内容区最大高度（rpx）	限制内容高度
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`change`	展开/折叠变更时触发	`(value)`	新的展开值
`toggle`	展开/折叠变更时触发（含详情）	`({ item, index, value })`	`item` 为当前项数据，`index` 为索引，`value` 为新展开值
`input`	Vue 2 双向绑定更新	`(value)`	新的展开值
`update:value`	Vue 3 双向绑定更新	`(value)`	新的展开值

事件使用示例

vue

<template>
  <xtf-collapse v-model="active" :items="items" @change="onChange" @toggle="onToggle" />
</template>

<script>
export default {
  data() {
    return {
      active: [],
      items: [{ name: 'account', title: '账号安全', content: '请定期更新密码。' }]
    }
  },
  methods: {
    onChange(value) {
      console.log('展开项', value)
    },
    onToggle({ item, index, value }) {
      console.log('切换项', item.name, index, value)
    }
  }
}
</script>

插槽

插槽名	作用域参数	说明
`title`	`{ item, index }`	替换面板标题区域。
`content`	`{ item, index }`	替换面板内容区域。

主题说明

面板背景使用 var(--xtf-card-bg)，边框使用 var(--xtf-card-border)，阴影使用 var(--xtf-shadow-card)
分割线颜色使用 var(--xtf-color-border)
无边框模式背景透明、无边框无阴影
箭头旋转动画使用 transform: rotate(90deg)，时长 300ms
内容展开动画使用 max-height 过渡，时长 320ms

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

xtf-collapse ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. 手风琴模式 ​

3. 箭头位置与无边框 ​

4. 插槽自定义与禁用 ​

全部属性 ​

事件 ​

事件使用示例 ​

插槽 ​

主题说明 ​