Swiper 轮播

介绍

用于循环播放一组图片或内容。

引入

import { Swiper } from "@taroify/core"

代码演示

基础用法

每个 Swipe.Item 代表一张轮播卡片，可以通过 autoplay 属性设置自动轮播的间隔。

function BasicSwiper() {
  return (
    <Swiper className="basic-swiper" autoplay={4000}>
      <Swiper.Indicator />
      <Swiper.Item>1</Swiper.Item>
      <Swiper.Item>2</Swiper.Item>
      <Swiper.Item>3</Swiper.Item>
      <Swiper.Item>4</Swiper.Item>
    </Swiper>
  )
}

.basic-swiper {
  .taroify-swiper-item {
    color: #fff;
    font-size: 20px * 2;
    background: #39a9ed;
    display: flex;
    justify-content: center;
    align-items: center;
  }
}

懒加载

当 Swiper 中含有图片时，可以通过 lazyRender 属性来开启懒加载模式。在懒加载模式下，只会渲染当前页和下一页。

function ImageSwiper() {
  return (
    <Swiper className="image-swiper" lazyRender autoplay={4000}>
      <Swiper.Indicator />
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-1.jpg" />
      </Swiper.Item>
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-2.jpg" />
      </Swiper.Item>
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-3.jpg" />
      </Swiper.Item>
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-4.jpg" />
      </Swiper.Item>
    </Swiper>
  )
}

.image-swiper {
  .image {
    display: block;
    box-sizing: border-box;
    width: 100%;
    height: 240px * 2;
    padding: 30px * 2 60px * 2;
    background: #fff;
    pointer-events: none;
  }
}

监听 change 事件

在每一页轮播结束后，会触发 change 事件。

function SwiperWithOnChange() {
  return (
    <>
      <Toast id="toast" />
      <Swiper
        className="onchange-swiper"
        onChange={(value) => Toast.open(`当前 Swipe 索引：${value}`)}
      >
        <Swiper.Indicator />
        <Swiper.Item>1</Swiper.Item>
        <Swiper.Item>2</Swiper.Item>
        <Swiper.Item>3</Swiper.Item>
        <Swiper.Item>4</Swiper.Item>
      </Swiper>
    </>
  )
}

纵向滚动

设置 vertical 属性后滑块会纵向排列，此时需要指定滑块容器的高度。

<Swiper className="vertical-swiper" direction="vertical">
  <Swiper.Item>1</Swiper.Item>
  <Swiper.Item>2</Swiper.Item>
  <Swiper.Item>3</Swiper.Item>
  <Swiper.Item>4</Swiper.Item>
</Swiper>

.vertical-swiper {
  .taroify-swiper-item {
    color: #fff;
    font-size: 20px * 2;
    background: #39a9ed;
    display: flex;
    justify-content: center;
    align-items: center;
  }
}

自定义滑块大小

滑块默认宽度为 100%，可以通过 width 属性设置单个滑块的宽度。纵向滚动模式下，可以通过 height 属性设置单个滑块的高度。

function SwiperWithCustomWidth() {
  return (
    <Swiper loop={false} width={300}>
      <Swiper.Indicator />
      <Swiper.Item>1</Swiper.Item>
      <Swiper.Item>2</Swiper.Item>
      <Swiper.Item>3</Swiper.Item>
      <Swiper.Item>4</Swiper.Item>
    </Swiper>
  )
}

目前不支持在循环滚动模式下自定义滑块大小，因此需要将 loop 设置为 false。

自定义指示器

通过 Swiper.Indicator 组件可以自定义指示器的样式。

function SwiperWithCustomIndicator() {
  const [value, setValue] = useState(0)

  return (
    <Swiper autoplay={4000} onChange={setValue}>
      <Swiper.Item>1</Swiper.Item>
      <Swiper.Item>2</Swiper.Item>
      <Swiper.Item>3</Swiper.Item>
      <Swiper.Item>4</Swiper.Item>
      <Swiper.Indicator className="custom-indicator">{value + 1}/4</Swiper.Indicator>
    </Swiper>
  )
}

.custom-indicator {
  position: absolute;
  right: 5px * 2;
  bottom: 5px * 2;
  padding: 2px * 2 5px * 2;
  font-size: 12px * 2;
  color: #ffffff;
  background: rgba(0, 0, 0, 0.1)_ | - |
}

API

Swiper Props

参数	说明	类型	默认值
defaultValue	默认位置索引值	number	`0`
value	位置索引值	number	`0`
autoplay	自动轮播间隔，单位为 ms	number	-
duration	动画时长，单位为 ms	number	`500`
width	滑块宽度，单位为 `px`	number	`auto`
height	滑块高度，单位为 `px`	number	`auto`
direction	轮播方向，可选值为 `vertical`	string	`horizontal`
touchable	是否可以通过手势滑动	boolean	`true`
lazyRender	是否延迟渲染未展示的轮播	boolean	`false`
stopPropagation	是否阻止滑动事件冒泡	boolean	`true`

Swiper Events

事件名	说明	回调参数
onChange	每一页轮播结束后触发	(index: number)

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--swiper-indicators-margin	var(--padding-sm)	-
--swiper-indicator-size	6px $hd*	-
--swiper-indicator-width	var(--swiper-indicator-size)	-
--swiper-indicator-height	var(--swiper-indicator-size)	-
--swiper-indicator-opacity	0.3	-
--swiper-indicator-background-color	var(--border-color)	-
--swiper-indicator-transition-duration	var(--animation-duration-fast)	-
--swiper-indicator-active-opacity	1	-
--swiper-indicator-active-background-color	var(--blue)	-

#Swiper 轮播

#介绍

#引入

#代码演示

#基础用法

#懒加载

#监听 change 事件

#纵向滚动

#自定义滑块大小

#自定义指示器

#API

#Swiper Props

#Swiper Events

#主题定制

#样式变量