Swiper React 组件

Swiper React 组件很可能在未来版本中被移除。建议改为迁移到 Swiper Element。

如果你要从 Swiper 9 升级到 Swiper 10，请查看 Swiper 10 迁移指南

如果你正在寻找 v9 文档，它们在这里 v9.swiperjs.com

安装

Swiper React 仅作为主 Swiper 库的一部分通过 NPM 提供

  npm i swiper

用法

swiper/react 导出了 2 个组件：Swiper 和 SwiperSlide

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

// Import Swiper styles
import 'swiper/css';

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

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

以下是来自 swiper/modules 的其他模块导入列表

Virtual - 虚拟幻灯片模块
键盘 - 键盘控制模块
鼠标滚轮 - 鼠标滚轮控制模块
导航 - 导航模块
分页 - 分页模块
滚动条 - 滚动条模块
视差 - 视差模块
自由模式 - 自由模式模块
网格 - 网格模块
操作 - 幻灯片操作模块（仅适用于核心版本）
缩放 - 缩放模块
控制器 - 控制器模块
无障碍 - 无障碍模块
历史记录 - 历史记录导航模块
哈希导航 - 哈希导航模块
自动播放 - 自动播放模块
淡入淡出效果 - 淡入淡出效果模块
立方体效果 - 立方体效果模块
翻转效果 - 翻转效果模块
Coverflow 效果 - Coverflow 效果模块
卡片效果 - 卡片效果模块
创意效果 - 创意效果模块
缩略图 - 缩略图模块

// import Swiper core and required modules
import { Navigation, Pagination, Scrollbar, A11y } from 'swiper/modules';

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

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/scrollbar';

export default () => {
  return (
    <Swiper
      // install Swiper modules
      modules={[Navigation, Pagination, Scrollbar, A11y]}
      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 组件将为导航、分页和滚动条创建所需的元素。

样式

Swiper 包含不同的 CSS、Less 和 SCSS 样式集

swiper/css - 仅核心 Swiper 样式
swiper/css/bundle - 所有 Swiper 样式，包括所有模块样式（如导航、分页等）

模块样式（如果你已经导入了捆绑样式，则不需要）

swiper/css/a11y - 无障碍模块所需的样式
swiper/css/autoplay - 自动播放模块所需的样式
swiper/css/controller - 控制器模块所需的样式
swiper/css/effect-cards - 卡片效果模块所需的样式
swiper/css/effect-coverflow - Coverflow 效果模块所需的样式
swiper/css/effect-creative - 创意效果模块所需的样式
swiper/css/effect-cube - 立方体效果模块所需的样式
swiper/css/effect-fade - 淡入淡出效果模块所需的样式
swiper/css/effect-flip - 翻转效果模块所需的样式
swiper/css/free-mode - 自由模式模块所需的样式
swiper/css/grid - 网格模块所需的样式
swiper/css/hash-navigation - 散列导航模块所需的样式
swiper/css/history - 历史记录模块所需的样式
swiper/css/keyboard - 键盘模块所需的样式
swiper/css/manipulation - 操作模块所需的样式
swiper/css/mousewheel - 鼠标滚轮模块所需的样式
swiper/css/navigation - 导航模块所需的样式
swiper/css/pagination - 分页模块所需的样式
swiper/css/parallax - 视差模块所需的样式
swiper/css/scrollbar - 滚动条模块所需的样式
swiper/css/thumbs - 缩略图模块所需的样式
swiper/css/virtual - 虚拟模块所需的样式
swiper/css/zoom - 缩放模块所需的样式

对于 Less 样式，请在导入路径中将 css 替换为 less，例如

import 'swiper/less';
import 'swiper/less/navigation';
import 'swiper/less/pagination';

对于 SCSS 样式，请在导入路径中将 css 替换为 scss，例如

import 'swiper/scss';
import 'swiper/scss/navigation';
import 'swiper/scss/pagination';

Swiper 属性

Swiper React 组件接收所有 Swiper 参数作为组件属性，以及一些额外的属性

属性	类型	默认值	说明
`tag`	`字符串`	`'div'`	Swiper 容器 HTML 元素标签
`wrapperTag`	`字符串`	`'div'`	Swiper 包装 HTML 元素标签
`onSwiper`	`(swiper) => void`	`'div'`	接收 Swiper 实例的回调

它还支持所有 Swiper 事件，格式为 on{Eventname}。例如，slideChange 事件变为 onSlideChange 属性

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

SwiperSlide 属性

属性	类型	默认值	说明
`tag`	`字符串`	`'div'`	Swiper 幻灯片 HTML 元素标签
`zoom`	`布尔值`	`false`	启用缩放模式所需的附加包装
`virtualIndex`	`数字`		实际的 swiper 幻灯片索引。需要为虚拟幻灯片设置

SwiperSlide 渲染函数

SwiperSlide 组件可以接受一个渲染函数，该函数接收一个包含以下属性的对象

isActive - 当前幻灯片处于活动状态时为 true
isPrev - 当前幻灯片是活动幻灯片的前一个幻灯片时为 true
isNext - 当前幻灯片是活动幻灯片的下一个幻灯片时为 true
isVisible - 当前幻灯片可见时为 true（必须启用 watchSlidesProgress Swiper 参数）
isDuplicate - 当前幻灯片是重复幻灯片时为 true（当启用 loop 模式时）。例如

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

useSwiper

Swiper React 提供 useSwiper 钩子，以便轻松获取 Swiper 中组件内的 Swiper 实例

// some-inner-component.jsx
import { React } from 'react';
import { useSwiper } from 'swiper/react';

export default function SlideNextButton() {
  const swiper = useSwiper();

  return (
    <button onClick={() => swiper.slideNext()}>Slide to the next slide</button>
  );
}

useSwiperSlide

useSwiperSlide 是 Swiper 幻灯片内组件的另一个钩子，用于获取幻灯片数据（与 SwiperSlide 渲染函数中的数据相同）

// some-inner-component.jsx
import { React } from 'react';
import { useSwiperSlide } from 'swiper/react';

export default function SlideTitle() {
  const swiperSlide = useSwiperSlide();

  return (
    <p>Current slide is {swiperSlide.isActive ? 'active' : 'not active'}</p>
  );
}

插槽

Swiper React 使用“插槽”进行内容分发。有 4 个可用的插槽

container-start - 元素将添加到 swiper-container 的开头
container-end（默认） - 元素将添加到 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">
  <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>

虚拟幻灯片

此处虚拟幻灯片的渲染完全由 React 处理，除了设置 virtual:true 属性和在幻灯片上设置 virtualIndex 之外，不需要任何其他操作

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

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/virtual';

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

  return (
    <Swiper modules={[Virtual]} spaceBetween={50} slidesPerView={3} virtual>
      {slides.map((slideContent, index) => (
        <SwiperSlide key={slideContent} virtualIndex={index}>
          {slideContent}
        </SwiperSlide>
      ))}
    </Swiper>
  );
};

控制器

控制器需要将一个 Swiper 实例传递给另一个实例

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

  const App = () => {
    // store controlled swiper instance
    const [controlledSwiper, setControlledSwiper] = useState(null);

    return (
      <main>
        {/* Main Swiper -> pass controlled swiper instance */}
        <Swiper modules={[Controller]} controller={{ control: controlledSwiper }} ...>
          {/* ... */}
        </Swiper>

        {/* Controlled Swiper -> store swiper instance */}
        <Swiper modules={[Controller]} onSwiper={setControlledSwiper} ...>
          {/* ... */}
        </Swiper>
      </main>
    )
  }

对于双向控制（当两个 Swiper 相互控制时），它应该如下所示

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

const App = () => {
  // store swiper instances
  const [firstSwiper, setFirstSwiper] = useState(null);
  const [secondSwiper, setSecondSwiper] = useState(null);

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

      <Swiper
        modules={[Controller]}
        onSwiper={setSecondSwiper}
        controller={{ control: firstSwiper }}
      >
        {/* ... */}
      </Swiper>
    </main>
  );
};

缩略图

与控制器相同，我们需要存储缩略图实例并将其传递给主图库

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

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

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

        {/* Thumbs Swiper -> store swiper instance */}
        {/* It is also required to set watchSlidesProgress prop */ }
        <Swiper
          modules={[Thumbs]}
          watchSlidesProgress
          onSwiper={setThumbsSwiper}
          ...
        >
          {/* ... */}
        </Swiper>
      </main>
    )
  }

效果

以下效果可用

淡入淡出
立方体
封面流
翻转
卡片
创意

要使用效果，您必须先导入并安装它们（与所有其他模块一样）。

您可以在此处找到正在运行的效果演示。

全淡入淡出效果示例

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

import 'swiper/css';
import 'swiper/css/effect-fade';

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

与 Create React App 配合使用

Create React App 还不支持纯 ESM 包。仍然可以使用 Swiper（7.2.0+）配合使用。

在这种情况下，我们需要使用直接文件导入

// Core modules imports are same as usual
import { Navigation, Pagination } from 'swiper/modules';
// Direct React component imports
import { Swiper, SwiperSlide } from 'swiper/swiper-react.mjs';

// Styles must use direct files imports
import 'swiper/swiper.scss'; // core Swiper
import 'swiper/modules/navigation.scss'; // Navigation module
import 'swiper/modules/pagination.scss'; // Pagination module

接下来是什么？

正如您所见，将 Swiper 集成到您的网站或应用中非常容易。因此，以下是您的下一步

转到 API 文档以了解有关所有 Swiper API 以及如何控制它的更多信息。
查看可用的演示。
如果您对 Swiper 有疑问，请在 StackOverflow 或 Swiper 讨论中提问。
如果您发现错误，请在 GitHub 上创建问题。
如果您正在寻求支持，我们为 Swiper 赞助人提供了一个私密的 Discord 支持聊天室。

在 GitHub 上编辑此页面