博客

本文是官网翻译：

Swiper React Components

配置项含义可参考​​​​​​​

Swiper中文网-轮播图幻灯片js插件,H5页面前端开发

安装

Swiper React 只能够通过 NPM 安装，作为Swiper 主库的一部分:

npm i swiper

用法


swiper/react

暴露了 2 个组件:

Swiper

和

SwiperSlide

:

// Import Swiper React components
import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/swiper.scss';

export default () => {
  return (
    <Swiper
      spaceBetween={50}
      slidesPerView={3}
      initialSlide={1} // 初始化显示哪一个
      loop={true} // 是否循环
      onSlideChange={() => console.log('slide change')}
      onSwiper={(swiper) => console.log(swiper)}
      threshold={40}
    >
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
      <SwiperSlide>Slide 4</SwiperSlide>
      ...
    </Swiper>
  );
};

默认情况下，Swiper React使用Swiper的核心版本（没有任何附加组件）。如果要使用导航、分页和其他组件，必须先安装它们。

可以引入的模块:

各模块的作用可参考

中文api – Swiper中文网

• 
Virtual

  – Virtual Slides module
• 
Keyboard

  – Keyboard Control module
• 
Mousewheel

  – Mousewheel Control module
• 
Navigation

  – Navigation module
• 
Pagination

  – Pagination module
• 
Scrollbar

  – Scrollbar module
• 
Parallax

  – Parallax module
• 
Zoom

  – Zoom module
• 
Lazy

  – Lazy module
• 
Controller

  – Controller module
• 
A11y

  – Accessibility module
• 
History

  – History Navigation module
• 
HashNavigation

  – Hash Navigation module
• 
Autoplay

  – Autoplay module
• 
EffectFade

  – Fade Effect module
• 
EffectCube

  – Cube Effect module
• 
EffectFlip

  – Flip Effect module
• 
EffectCoverflow

  – Coverflow Effect module
• 
Thumbs

  – Thumbs module

// 引入 Swiper core 和必须的组件
import SwiperCore, { Navigation, Pagination, Scrollbar, A11y } from 'swiper';

import { Swiper, SwiperSlide } from 'swiper/react';

// 引入 Swiper 样式
import 'swiper/swiper.scss';
import 'swiper/components/navigation/navigation.scss';
import 'swiper/components/pagination/pagination.scss';
import 'swiper/components/scrollbar/scrollbar.scss';

// 安装 Swiper 组件
SwiperCore.use([Navigation, Pagination, Scrollbar, A11y]);

export default () => {
  return (
    <Swiper
      spaceBetween={50}
      slidesPerView={3}
      navigation
      pagination={{ clickable: true }}
      scrollbar={{ draggable: true }}
      onSwiper={(swiper) => console.log(swiper)}
      onSlideChange={() => console.log('slide change')}
    >
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
      <SwiperSlide>Slide 4</SwiperSlide>
      ...
    </Swiper>
  );
};

注意, 如果你没有传递相关的参数(例如 没有

navigation.nextEl

,

pagination.el

, 等.) ，Swiper React 组件会为Navigation、Pagination 和 Scrollbar创建必要的元素。

Styles

Swiper 包包含不同的  CSS, Less 和 SCSS 样式:

CSS 样式

CSS 样式用于 bundle 版:

• 
swiper-bundle.css

  – 包含全部样式，包括模块样式  (如 Navigation, Pagination, 等.)
• 
swiper-bundle.min.css

  – 跟上面的相同，不过是压缩过后的min版

Less 样式

Less 样式分为核心部分和组件部分:

• 
swiper.less

  – 核心 Swiper 样式

下面是模块样式：

• 
components/a11y/a11y.less

  – A11y 组件样式
• 
components/controller/controller.less

  – styles required for Controller component
• 
components/effect-coverflow/effect-coverflow.less

  – styles required for Coveflow Effect component
• 
components/effect-cube/effect-cube.less

  – styles required for Cube Effect component
• 
components/effect-fade/effect-fade.less

  – styles required for Fade Effect component
• 
components/effect-flip/effect-flip.less

  – styles required for Flip Effect component
• 
components/lazy/lazy.less

  – styles required for Lazy component
• 
components/navigation/navigation.less

  – styles required for Navigation component
• 
components/pagination/pagination.less

  – styles required for Pagination component
• 
components/scrollbar/scrollbar.less

  – styles required for Scrollbar component
• 
components/thumbs/thumbs.less

  – styles required for Thumbs component
• 
components/zoom/zoom.less

  – styles required for Zoom component

SCSS 样式

SCSS 样式分为核心部分和组件部分:

• 
swiper.scss

  – 核心 Swiper 样式

下面是模块样式

• 
components/a11y/a11y.scss

  – styles required for A11y component
• 
components/controller/controller.scss

  – styles required for Controller component
• 
components/effect-coverflow/effect-coverflow.scss

  – styles required for Coveflow Effect component
• 
components/effect-cube/effect-cube.scss

  – styles required for Cube Effect component
• 
components/effect-fade/effect-fade.scss

  – styles required for Fade Effect component
• 
components/effect-flip/effect-flip.scss

  – styles required for Flip Effect component
• 
components/lazy/lazy.scss

  – styles required for Lazy component
• 
components/navigation/navigation.scss

  – styles required for Navigation component
• 
components/pagination/pagination.scss

  – styles required for Pagination component
• 
components/scrollbar/scrollbar.scss

  – styles required for Scrollbar component
• 
components/thumbs/thumbs.scss

  – styles required for Thumbs component
• 
components/zoom/zoom.scss

  – styles required for Zoom component


Swiper

属性


Swiper

组件接收所有

Swiper 参数

作为组件属性, 同时增加了一些额外属性:

他也接收所有的

Swiper 事件

， 采用

on{Eventname}

形式. 例如

slideChange

事件变成

onSlideChange

属性:

<Swiper
  onSlideChange={() => {/*...*/}}
  onReachEnd={() => {/*...*/}}
  ...
>


SwiperSlide

属性


SwiperSlide

render 函数


SwiperSlide

组件可以接受render 函数，该函数会接收到一个对象，包含如下属性:

• 
isActive

  – 当前slide 是否active
• 
isPrev

  – 是否active slide 的前一个slide
• 
isNext

  – 是否active slide 的前后一个slide
• 
isVisible

  – 当前 slide 是否可见 (
  
watchSlidesVisibility

  Swiper 参数必须开启)
• 
isDuplicate

  – 当前 slide 是否是一个复制slide (当
  
loop

  模式开启的时候)

例如:

<Swiper>
  <SwiperSlide>
    {({isActive}) => (
      <div>Current slide is {isActive ? 'active' : 'not active'}</div>
    )}
  </SwiperSlide>
</Swiper>

Slots（占位符）

Swiper 使用占位符控制内容分布. 有4个可用的占位符

• 
container-start

  – 元素会被添加到 swiper-container前面
• 
container-end

  (default) – e元素会被添加到 swiper-container后面
• 
wrapper-start

  – 元素会被添加到swiper-wrapper前面
• 
wrapper-end

  -元素会被添加到swiper-wrapper后面

例如:

<Swiper>
  <SwiperSlide>Slide 1</SwiperSlide>
  <SwiperSlide>Slide 2</SwiperSlide>
  <span slot="container-start">Container Start</span>
  <span slot="container-end">Container End</span>
  <span slot="wrapper-start">Wrapper Start</span>
  <span slot="wrapper-end">Wrapper End</span>
</Swiper>

会渲染成:

<div class="swiper-container">
  <span slot="container-start">Container Start</span>
  <div class="swiper-wrapper">
    <span slot="wrapper-start">Wrapper Start</span>
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    <span slot="wrapper-end">Wrapper End</span>
  </div>
  <span slot="container-end">Container End</span>
</div>

虚拟滚动

你只需设置

virtual:true

，其他的由react进行处理

import SwiperCore, { Virtual } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';

// 安装 Virtual 模块
SwiperCore.use([Virtual]);

export default () => {
  // Create array with 1000 slides
  const slides = Array.from({ length: 1000 }).map((el, index) => `Slide ${index + 1}`);

  return (
    <Swiper spaceBetween={50} slidesPerView={3} virtual>
      {slides.map((slideContent) => {
        <SwiperSlide key={slideContent}>{slideContent}</SwiperSlide>;
      })}
    </Swiper>
  );
};

Controller

Controller 需要传递一个Swiper 实例到另一个:

import React, { useState } from 'react';
import SwiperCore, { Controller } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';

// 安装 Swiper Controller 组件
Swiper.use([Controller]);

const App = () => {
  // 保存 controlled swiper 实例
  const [controlledSwiper, setControlledSwiper] = useState(null);

  return (
    <main>
      {/* Main Swiper -> 传入 controlled swiper 实例 */}
      <Swiper controller={{ control: controlledSwiper }} ...>
        {/* ... */}
      </Swiper>

      {/* Controlled Swiper -> 保存 swiper 实例 */}
      <Swiper onSwiper={setControlledSwiper} ...>
        {/* ... */}
      </Swiper>
    </main>
  )
}

双向控制 (两个Swipers 相互控制) 它应该像这样:

import React, { useState } from 'react';
import SwiperCore, { Controller } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';

// 安装 Swiper's Controller 组件
Swiper.use([Controller]);

const App = () => {
  // 保存 swiper 实例
  const [firstSwiper, setFirstSwiper] = useState(null);
  const [secondSwiper, setSecondSwiper] = useState(null);

  return (
    <main>
      <Swiper onSwiper={setFirstSwiper} controller={{ control: secondSwiper }}>
        {/* ... */}
      </Swiper>

      <Swiper onSwiper={setSecondSwiper} controller={{ control: firstSwiper }}>
        {/* ... */}
      </Swiper>
    </main>
  )
}

缩略图

和 controller 一样，我们需要保存 thumbs 实例，并将他传递给main gallery:

import React, { useState } from 'react';
import SwiperCore, { Thumbs } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';

// install Swiper's Thumbs component
Swiper.use([Thumbs]);

const App = () => {
  // store thumbs swiper instance
  const [thumbsSwiper, setThumbsSwiper] = useState(null);

  return (
    <main>
      {/* Main Swiper -> pass thumbs swiper instance */}
      <Swiper thumbs={{ swiper: thumbsSwiper }} ...>
        {/* ... */}
      </Swiper>

      {/* Thumbs Swiper -> store swiper instance */}
      <Swiper onSwiper={setThumbsSwiper} ...>
        {/* ... */}
      </Swiper>
    </main>
  )
}

动效

有下面动态效果:

• Fade
• Cube
• Overflow
• Flip

安装并引入 (Fade 的例子):

import SwiperCore, {EffectFade} from 'swiper';
SwiperCore.use([EffectFade]);

你可以运行这个

例子

.

淡入淡出动效例子

import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import SwiperCore, {EffectFade} from 'swiper';

import 'swiper/swiper.scss';
import 'swiper/components/effect-fade/effect-fade.scss';

SwiperCore.use([EffectFade]);

export default () => {
  return (
    <Swiper effect="fade">
      {[1, 2, 3].map((i, el) => {
        return <SwiperSlide>Slide {el}</SwiperSlide>;
      })}
    </Swiper>
  );
};

快速开始视频

要获得更全面的实践教程，请看这段15分钟的入门视频

https://youtu.be/l4kFO6VQPfA