xtf-collapse-animation

组件说明

xtf-collapse-animation 是折叠动画组件，用于内容展开/收起时的过渡动画。支持最大高度限制、透明度/缩放动画、懒渲染、销毁关闭、变更拦截和自动滚动，适用于手风琴面板、筛选面板和详情展开等场景。

基础用法

1. 最简示例

通过 v-model 或 show 控制展开/收起：

vue

<template>
  <view>
    <xtf-button :label="expanded ? '收起' : '展开'" size="sm" @click="expanded = !expanded" />
    <xtf-collapse-animation v-model="expanded">
      <view style="padding: 24rpx; background: var(--xtf-color-surface)">
        <xtf-text level="body" text="这是可折叠的内容区域，展开时带有平滑的过渡动画。" />
      </view>
    </xtf-collapse-animation>
  </view>
</template>

<script>
export default {
  data() {
    return {
      expanded: false
    }
  }
}
</script>

2. 动画配置

通过 duration 设置动画时长，通过 easing 设置缓动函数，通过 animateOpacity 和 animateScale 控制附加动画：

vue

<template>
  <view>
    <xtf-button label="切换" size="sm" @click="show = !show" />
    <xtf-collapse-animation
      v-model="show"
      :duration="400"
      easing="ease-in-out"
      animate-opacity
      :animate-scale="true"
      :scale-from="0.96"
    >
      <view style="padding: 24rpx; background: var(--xtf-color-surface)">
        <xtf-text level="body" text="带透明度和缩放动画的折叠内容。" />
      </view>
    </xtf-collapse-animation>
  </view>
</template>

<script>
export default {
  data() {
    return {
      show: true
    }
  }
}
</script>

3. 懒渲染与销毁

通过 lazyRender 延迟渲染内容，通过 destroyOnClose 关闭时销毁内容：

vue

<template>
  <view>
    <xtf-button label="切换" size="sm" @click="visible = !visible" />
    <xtf-collapse-animation v-model="visible" lazy-render destroy-on-close>
      <view style="padding: 24rpx; background: var(--xtf-color-surface)">
        <xtf-text level="body" text="首次展开时才渲染，关闭后销毁 DOM。" />
      </view>
    </xtf-collapse-animation>
  </view>
</template>

<script>
export default {
  data() {
    return {
      visible: false
    }
  }
}
</script>

4. 变更拦截

通过 beforeChange 拦截展开/收起操作：

vue

<template>
  <xtf-collapse-animation v-model="open" :before-change="onBeforeChange">
    <view style="padding: 24rpx; background: var(--xtf-color-surface)">
      <xtf-text level="body" text="需要确认才能折叠的内容。" />
    </view>
  </xtf-collapse-animation>
</template>

<script>
export default {
  data() {
    return {
      open: true
    }
  },
  methods: {
    onBeforeChange({ nextExpanded }) {
      if (!nextExpanded) {
        uni.showModal({
          title: '提示',
          content: '确定要收起吗？',
          success: (res) => {
            if (res.confirm) {
              this.open = false
            }
          }
        })
        return false
      }
      return true
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`show`	`Boolean`	`true`	是否展开（Vue 2 v-model）	控制展开
`modelValue`	`Boolean`	`undefined`	是否展开（Vue 3 v-model）	控制展开
`duration`	`Number \| String`	`300`	动画时长（ms）	动画速度
`easing`	`String`	`'ease'`	缓动函数	缓动效果
`maxHeight`	`Number \| String`	`2400`	展开时最大高度（rpx）	限制高度
`collapsedHeight`	`Number \| String`	`0`	收起时高度（rpx）	收起高度
`autoScroll`	`Boolean`	`false`	展开时是否自动滚动到可视区	自动滚动
`scrollOffset`	`Number \| String`	`0`	自动滚动偏移量（rpx）	滚动偏移
`scrollDuration`	`Number \| String`	`300`	滚动动画时长（ms）	滚动速度
`animateOpacity`	`Boolean`	`true`	是否启用透明度动画	透明度动画
`animateScale`	`Boolean`	`false`	是否启用缩放动画	缩放动画
`scaleFrom`	`Number \| String`	`0.98`	缩放起始值	缩放范围
`disabled`	`Boolean`	`false`	是否禁用动画	禁用动画
`lazyRender`	`Boolean`	`false`	是否懒渲染	延迟渲染
`destroyOnClose`	`Boolean`	`false`	关闭时是否销毁内容	销毁 DOM
`beforeChange`	`Function`	`null`	变更拦截函数，返回 `false` 阻止	变更拦截
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`open` / `close` / `opened` / `closed` / `change`	事件名已在 `emits` 声明	-	当前实现未调用 `$emit`，因此不会在运行时触发
`input`	Vue 2 双向绑定更新	`(visible: Boolean)`	新的可见状态
`update:show`	Vue 3 双向绑定更新	`(visible: Boolean)`	新的可见状态
`update:modelValue`	Vue 3 双向绑定更新	`(visible: Boolean)`	新的可见状态

事件使用示例

vue

<template>
  <view>
    <xtf-button label="展开" @click="$refs.collapse.open()" />
    <xtf-button label="收起" @click="$refs.collapse.close()" />
    <xtf-collapse-animation
      ref="collapse"
      :show="expanded"
      @input="onVisibleChange"
      @update:show="onVisibleChange"
      @update:modelValue="onVisibleChange"
    >
      <view style="padding: 24rpx">可折叠内容</view>
    </xtf-collapse-animation>
  </view>
</template>

<script>
export default {
  data() {
    return { expanded: false }
  },
  methods: {
    onVisibleChange(value) {
      this.expanded = value
      console.log('展开状态：', value)
    }
  }
}
</script>

open、close、opened、closed 和 change 虽已声明，但当前实现不会触发；请仅监听上表中的双向绑定更新事件。

方法

方法名	参数	返回值	说明
`open`	-	-	展开内容
`close`	-	-	收起内容
`toggleCollapse`	-	-	切换展开/收起
`refresh`	-	-	刷新状态

主题说明

折叠动画通过 max-height 过渡实现
透明度动画通过 opacity 过渡实现
缩放动画通过 transform: scale() 过渡实现
动画时长和缓动函数可通过属性自定义

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

xtf-collapse-animation ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. 动画配置 ​

3. 懒渲染与销毁 ​

4. 变更拦截 ​

全部属性 ​

事件 ​

事件使用示例 ​

方法 ​

主题说明 ​