xtf-swiper

组件说明

xtf-swiper 是轮播组件，适用于图片、活动和内容卡片；支持多种布局、动画、指示器与自定义 item 渲染。核心能力以当前 xtf-swiper.vue 源码为准。

基础用法

1. 基础用法

最小配置下即可完成常见业务交互：

vue

<template>
  <xtf-swiper :items="items" v-model="value" @change="onEvent" />
</template>

<script>
export default {
  data() {
    return {
      value: 0,
      items: [
        { id: 'a', title: '新品推荐', desc: '限时优惠' },
        { id: 'b', title: '会员活动', desc: '立即参与' }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

2. 核心交互

监听组件事件并维护页面状态：

vue

<template>
  <xtf-swiper
    :items="items"
    layout="card"
    animation="coverflow"
    indicator="fraction"
    @item-click="onEvent"
  />
</template>

<script>
export default {
  data() {
    return {
      value: 0,
      items: [
        { id: 'a', title: '新品推荐', desc: '限时优惠' },
        { id: 'b', title: '会员活动', desc: '立即参与' }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

3. 进阶配置

组合布局、样式或插槽能力：

vue

<template>
  <xtf-swiper :items="items" layout="card" animation="coverflow">
    <template #item="{ item, active, layout, animation }">
      <view
        style="
          height: 100%;
          padding: 32rpx;
          box-sizing: border-box;
          background: #1677ff;
          color: #ffffff;
        "
      >
        <text>{{ item.title }}</text>
        <text style="display: block; margin-top: 16rpx">{{ active ? '当前展示' : item.desc }}</text>
        <text style="display: block; margin-top: 16rpx">{{ layout }} / {{ animation }}</text>
      </view>
    </template>
  </xtf-swiper>
</template>

<script>
export default {
  data() {
    return {
      value: 0,
      items: [
        { id: 'a', title: '新品推荐', desc: '限时优惠' },
        { id: 'b', title: '会员活动', desc: '立即参与' }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`items`	`Array, default() { return [] }`	`函数返回值`	控制组件的 `items` 行为。	按业务需要设置。
`modelValue`	`[String, Number], default: undefined`	`undefined`	控制组件的 `modelValue` 行为。	按业务需要设置。
`current`	`[String, Number], default: 0`	`0`	控制组件的 `current` 行为。	按业务需要设置。
`currentItemId`	`String, default: ''`	`''`	控制组件的 `currentItemId` 行为。	按业务需要设置。
`height`	`[String, Number], default: 320`	`320`	控制组件的 `height` 行为。	按业务需要设置。
`autoplay`	`Boolean, default: false`	`false`	控制组件的 `autoplay` 行为。	按业务需要设置。
`interval`	`Number, default: 3000`	`3000`	控制组件的 `interval` 行为。	按业务需要设置。
`duration`	`Number, default: 320`	`320`	控制组件的 `duration` 行为。	按业务需要设置。
`circular`	`Boolean, default: true`	`true`	控制组件的 `circular` 行为。	按业务需要设置。
`vertical`	`Boolean, default: false`	`false`	控制组件的 `vertical` 行为。	按业务需要设置。
`indicator`	`String, default: 'dots'`	`'dots'`	控制组件的 `indicator` 行为。	按业务需要设置。
`indicatorPosition`	`String, default: 'center'`	`'center'`	控制组件的 `indicatorPosition` 行为。	按业务需要设置。
`previousMargin`	`String, default: '0rpx'`	`'0rpx'`	控制组件的 `previousMargin` 行为。	按业务需要设置。
`nextMargin`	`String, default: '0rpx'`	`'0rpx'`	控制组件的 `nextMargin` 行为。	按业务需要设置。
`displayMultipleItems`	`[String, Number], default: 1`	`1`	控制组件的 `displayMultipleItems` 行为。	按业务需要设置。
`skipHiddenItemLayout`	`Boolean, default: false`	`false`	控制组件的 `skipHiddenItemLayout` 行为。	按业务需要设置。
`easingFunction`	`String, default: 'default'`	`'default'`	控制组件的 `easingFunction` 行为。	按业务需要设置。
`nativeIndicatorDots`	`Boolean, default: false`	`false`	控制组件的 `nativeIndicatorDots` 行为。	按业务需要设置。
`indicatorColor`	`String, default: 'rgba(0, 0, 0, .3)'`	`'rgba(0, 0, 0, .3)'`	控制组件的 `indicatorColor` 行为。	按业务需要设置。
`indicatorActiveColor`	`String, default: '#000000'`	`'#000000'`	控制组件的 `indicatorActiveColor` 行为。	按业务需要设置。
`disableTouch`	`Boolean, default: false`	`false`	控制组件的 `disableTouch` 行为。	按业务需要设置。
`layout`	`String, default: 'classic'`	`'classic'`	控制组件的 `layout` 行为。	按业务需要设置。
`animation`	`String, default: 'slide'`	`'slide'`	控制组件的 `animation` 行为。	按业务需要设置。
`animationDuration`	`[String, Number], default: 420`	`420`	控制组件的 `animationDuration` 行为。	按业务需要设置。
`animationTimingFunction`	`String, default: 'cubic-bezier(0.22, 1, 0.36, 1)'`	`'cubic-bezier(0.22`	控制组件的 `animationTimingFunction` 行为。	按业务需要设置。
`nativeDuration`	`[String, Number], default: 320`	`320`	控制组件的 `nativeDuration` 行为。	按业务需要设置。
`noAnimation`	`Boolean, default: false`	`false`	控制组件的 `noAnimation` 行为。	按业务需要设置。
`cardScale`	`[String, Number], default: 0.88`	`0.88`	控制组件的 `cardScale` 行为。	按业务需要设置。
`sideOpacity`	`[String, Number], default: 0.54`	`0.54`	控制组件的 `sideOpacity` 行为。	按业务需要设置。
`sideRotate`	`[String, Number], default: 10`	`10`	控制组件的 `sideRotate` 行为。	按业务需要设置。
`sideTranslate`	`[String, Number], default: 84`	`84`	控制组件的 `sideTranslate` 行为。	按业务需要设置。
`captionVariant`	`String, default: 'auto'`	`'auto'`	控制组件的 `captionVariant` 行为。	按业务需要设置。
`showOverlay`	`Boolean, default: true`	`true`	控制组件的 `showOverlay` 行为。	按业务需要设置。
`itemRadius`	`[String, Number], default: 28`	`28`	控制组件的 `itemRadius` 行为。	按业务需要设置。
`itemShadow`	`String, default: ''`	`''`	控制组件的 `itemShadow` 行为。	按业务需要设置。
`itemBackground`	`String, default: ''`	`''`	控制组件的 `itemBackground` 行为。	按业务需要设置。
`itemPadding`	`[String, Number], default: ''`	`''`	控制组件的 `itemPadding` 行为。	按业务需要设置。
`captionClass`	`String, default: ''`	`''`	控制组件的 `captionClass` 行为。	按业务需要设置。
`captionStyle`	`[String, Object], default: ''`	`''`	控制组件的 `captionStyle` 行为。	按业务需要设置。
`panelClass`	`String, default: ''`	`''`	控制组件的 `panelClass` 行为。	按业务需要设置。
`panelStyle`	`[String, Object], default: ''`	`''`	控制组件的 `panelStyle` 行为。	按业务需要设置。
`customAnimationClass`	`String, default: ''`	`''`	控制组件的 `customAnimationClass` 行为。	按业务需要设置。
`customAnimationStyle`	`[String, Object], default: ''`	`''`	控制组件的 `customAnimationStyle` 行为。	按业务需要设置。
`customClass`	`String, default: ''`	`''`	控制组件的 `customClass` 行为。	按业务需要设置。
`customStyle`	`[String, Object], default: ''`	`''`	控制组件的 `customStyle` 行为。	按业务需要设置。

数据项结构

字段	类型	默认值	说明
`id/key`	`String \| Number`	`index`	稳定键；列表、轮播和瀑布流项目建议提供。
`title/label/name`	`String`	`''`	展示名称，具体读取字段见组件对应 prop。
`disabled`	`Boolean`	`false`	禁用可交互项目。

事件

事件名称	触发时机	回调参数	参数说明
`update:modelValue`	对应交互或状态变化时触发。	`payload`	参数形状以源码 `$emit('update:modelValue', ...)` 为准。
`update:current`	对应交互或状态变化时触发。	`payload`	参数形状以源码 `$emit('update:current', ...)` 为准。
`update:currentItemId`	对应交互或状态变化时触发。	`payload`	参数形状以源码 `$emit('update:currentItemId', ...)` 为准。
`change`	对应交互或状态变化时触发。	`payload`	参数形状以源码 `$emit('change', ...)` 为准。
`animationfinish`	对应交互或状态变化时触发。	`payload`	参数形状以源码 `$emit('animationfinish', ...)` 为准。
`item-click`	对应交互或状态变化时触发。	`payload`	参数形状以源码 `$emit('item-click', ...)` 为准。

事件使用示例

vue

<template>
  <xtf-swiper @update:modelValue="onEvent" />
</template>
<script>
export default {
  methods: {
    onEvent(payload) {
      console.log('收到事件', payload)
    }
  }
}
</script>

插槽

插槽名	说明	作用域参数
`item`	自定义每个轮播项的内容。	`item`、`index`、`active`、`state`、`layout`、`animation`

方法

无公开实例方法，通过 modelValue / current 控制当前项。

主题说明

var(--xtf-swiper-side-scale) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-side-opacity) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-height) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-radius) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-item-padding) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-item-bg) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-item-shadow) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-animation-duration) 参与组件的颜色、背景、边框或动效呈现。
var(--xtf-swiper-animation-timing) 参与组件的颜色、背景、边框或动效呈现。
视觉变体的可选值以 variant、theme、layout 等属性在源码中的分支为准。

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

xtf-swiper ​

组件说明 ​

基础用法 ​

1. 基础用法 ​

2. 核心交互 ​

3. 进阶配置 ​

全部属性 ​

数据项结构 ​

事件 ​

事件使用示例 ​

插槽 ​

方法 ​

主题说明 ​