react 中使用swiper

本文是官网翻译：https://swiperjs.com/react/

安装

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 (
     console.log('slide change')}
      onSwiper={(swiper) => console.log(swiper)}
    >
      Slide 1
      Slide 2
      Slide 3
      Slide 4
      ...
    
  );
};

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

可以引入的模块:

各模块的作用可参考 https://www.swiper.com.cn/api/index.html

• 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 (
     console.log(swiper)}
      onSlideChange={() => console.log('slide change')}
    >
      Slide 1
      Slide 2
      Slide 3
      Slide 4
      ...
    
  );
};

注意, 如果你没有传递相关的参数(例如 没有 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 参数 作为组件属性, 同时增加了一些额外属性:

Prop	Type	Default	Description
tag	string	'div'	Swiper 容器， 是一个HTML 元素标签
wrapperTag	string	'div'	Swiper wrapper HTML 元素标签
onSwiper	(swiper) => void		一个接收 Swiper实例的回调

他也接收所有的 Swiper 事件， 采用on{Eventname} 形式. 例如 slideChange 事件变成 onSlideChange 属性:

 {/*...*/}}
  onReachEnd={() => {/*...*/}}
  ...
>

SwiperSlide 属性

Prop	Type	Default	Description
tag	string	'div'	Swiper Slide HTML元素标签
zoom	boolean	false	为zoom 模式开启额外的wrapper

SwiperSlide render 函数

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

• isActive - 当前slide 是否active
• isPrev - 是否active slide 的前一个slide
• isNext - 是否active slide 的前后一个slide
• isVisible - 当前 slide 是否可见 (watchSlidesVisibility Swiper 参数必须开启)
• isDuplicate - 当前 slide 是否是一个复制slide (当loop 模式开启的时候)

例如:

  
    {({isActive}) => (
      
Current slide is {isActive ? 'active' : 'not active'}
    )}
  

Slots（占位符）

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

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

例如:

  Slide 1
  Slide 2
  Container Start
  Container End
  Wrapper Start
  Wrapper End

会渲染成:

  Container Start
  

    Wrapper Start
    
Slide 1
    
Slide 2
    Wrapper End
  
  Container End

虚拟滚动

你只需设置 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 (
    
      {slides.map((slideContent) => {
        {slideContent};
      })}
    
  );
};

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 Swiper -> 传入 controlled swiper 实例 */}
      
        {/* ... */}
      

      {/* Controlled Swiper -> 保存 swiper 实例 */}
      
        {/* ... */}
      
    
  )
}

   

 双向控制 (两个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 (
    

      
        {/* ... */}
      

      
        {/* ... */}
      
    
  )
}

缩略图

和 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 Swiper -> pass thumbs swiper instance */}
      
        {/* ... */}
      

      {/* Thumbs Swiper -> store swiper instance */}
      
        {/* ... */}
      
    
  )
}

动效

有下面动态效果:

• 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 (
    
      {[1, 2, 3].map((i, el) => {
        return Slide {el};
      })}
    
  );
};

快速开始视频

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

https://youtu.be/l4kFO6VQPfA