Swiper 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/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/modules 匯入的額外模組清單

• Virtual - 虛擬投影片模組
• Keyboard - 鍵盤控制模組
• Mousewheel - 滑鼠滾輪控制模組
• Navigation - 導覽模組
• Pagination - 分頁模組
• Scrollbar - 捲軸模組
• Parallax - 視差模組
• FreeMode - 自由模式模組
• Grid - 格線模組
• Manipulation - 投影片操作模組（僅適用於核心版本）
• Zoom - 縮放模組
• Controller - 控制器模組
• A11y - 無障礙模組
• History - 歷史導覽模組
• HashNavigation - 雜湊導覽模組
• Autoplay - 自動播放模組
• EffectFade - 淡入淡出效果模組
• EffectCube - 立方體效果模組
• EffectFlip - 翻轉效果模組
• EffectCoverflow - Coverflow 效果模組
• EffectCards - 卡片效果模組
• EffectCreative - 創意效果模組
• Thumbs - 縮圖模組

// 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>
  );
};

樣式

Swiper 套件包含不同的 CSS、Less 和 SCSS 樣式集

• swiper/css - 僅限核心 Swiper 樣式
• swiper/css/bundle - 所有 Swiper 樣式，包括所有模組樣式（如導覽、分頁等）

模組樣式（如果您已匯入套件樣式，則非必要）

• swiper/css/a11y - 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{事件名稱}。例如，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 Hook，方便在 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 投影片內部組件的另一個 Hook，用於取得投影片資料（與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>
    )
  }

效果

以下效果可供使用

• 淡入淡出
• 立方體
• Coverflow
• 翻轉
• 卡片
• 創意

若要使用效果，您必須先匯入並安裝它們（如同所有其他模組）。

您可以在此處找到執行的效果示範。

完整的淡入淡出效果範例

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 Discussions中提出。
• 如果您發現錯誤，請在GitHub上建立 issue。
• 如果您需要支援，我們為Swiper Patreon 贊助者提供了一個私人的 Discord 支援聊天室。