在 React 中使用 Swiper Element

2023 年 7 月 3 日

於 2023 年 7 月 28 日更新 - 新增虛擬幻燈片實作

讓我們仔細看看如何在 React 中使用 Swiper Web 元件。

參數

React 尚未原生支援自訂元素（Web 元件），因此這段程式碼

<swiper-container
  slides-per-view={3}
  breakpoints={{
    768: {
      slidesPerView: 4,
    },
  }}
>
  ...
</swiper-container>

實際上會渲染成以下內容

<swiper-container slides-per-view="3" breakpoints="[object Object]">
  ...
</swiper-container>

這並不是我們預期的結果。

這就是為什麼需要在 React 中透過傳遞參數作為 props並使用自訂初始化來使用 Swiper Element 的原因

import { useEffect, useRef } from 'react';
import { register } from 'swiper/element/bundle';

export default function App() {
  const swiperRef = useRef(null);

  useEffect(() => {
    // Register Swiper web component
    register();

    // Object with parameters
    const params = {
      slidesPerView: 3,
      breakpoints: {
        768: {
          slidesPerView: 4,
        },
      },
    };

    // Assign it to swiper element
    Object.assign(swiperRef.current, params);

    // initialize swiper
    swiperRef.current.initialize();
  }, []);

  return (
    <swiper-container init="false" ref={swiperRef}>
      ...
    </swiper-container>
  );
}

事件

事件也是如此，它們無法使用 React 的 on[Event] 語法來指定，應該使用 .addEventListener 方法或在參數中的 on 中傳遞它們

import { useEffect, useRef } from 'react';
import { register } from 'swiper/element/bundle';

export default function App() {
  const swiperRef = useRef(null);

  useEffect(() => {
    // Register Swiper web component
    register();

    // Add event listener
    swiperRef.current.addEventListener('swiperslidechange', (e) => {
      console.log(e.detail);
    });

    // Object with parameters
    const params = {
      // or pass it in on
      on: {
        slideChange(s) {
          console.log(s);
        },
      },
    };

    // Assign it to swiper element
    Object.assign(swiperRef.current, params);

    // initialize swiper
    swiperRef.current.initialize();
  }, []);

  return (
    <swiper-container init="false" ref={swiperRef}>
      ...
    </swiper-container>
  );
}

自訂包裝元件

如果您的專案中有很多 Swiper，我們可以建立一個簡單的 React 元件，基本上會包裝一個 Swiper Element

import { useEffect, useRef } from 'react';
import { register } from 'swiper/element/bundle';

export function Swiper(props) {
  const swiperRef = useRef(null);
  const {
    children,
    ...rest
  } = props;

  useEffect(() => {
    // Register Swiper web component
    register();

    // pass component props to parameters
    const params = {
      ...rest
    };

    // Assign it to swiper element
    Object.assign(swiperRef.current, params);

    // initialize swiper
    swiperRef.current.initialize();
  }, []);

  return (
    <swiper-container init="false" ref={swiperRef}>
      {children}
    </swiper-container>
  );
}
export function SwiperSlide(props) {
  const {
    children,
    ...rest
  } = props;

  return (
    <swiper-slide {...rest}>
      {children}
    </swiper-slide>
  );
}

現在我們可以在整個應用程式中以以下方式使用它

import { Swiper, SwiperSlide } from 'path/to/my-swiper.jsx';

export default function App() {
  return (
    <Swiper
      slidesPerView={3}
      breakpoints={{ 768: { slidesPerView: 4 } }}
      on={{
        slideChange: () => console.log('slide changed'),
        progress: (s, progress) => console.log(`progress is ${progress}`),
      }}
    >
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
    </Swiper>
  );
}

虛擬幻燈片

如果您使用虛擬幻燈片，我們可以更深入地以 React 的方式實作虛擬幻燈片。我們需要以以下方式稍微修改 Swiper 元件

import React, { useEffect, useState, useRef } from 'react';
import { register } from 'swiper/element/bundle';

export function Swiper(props) {
  const swiperRef = useRef(null);
  const {
    children,
    virtual, // specify virtual prop
    ...rest
  } = props;

  // store virtual data
  const [virtualData, setVirtualData] = useState({
    from: 0,
    to: 0,
    offset: 0,
    slides: [],
  });

  useEffect(() => {
    // Register Swiper web component
    register();

    // pass component props to parameters
    const params = {
      ...rest
    };

    // if we have virtual prop passed add virtual prameters
    if (virtual) {
      params.virtual = {
        enabled: true,
        // pass component children (slides) in `slides` array
        slides: children,
        // set virtual data on renderExternal
        renderExternal(vd) {
          setVirtualData(vd);
        },
      };
    }

    // Assign it to swiper element
    Object.assign(swiperRef.current, params);

    // initialize swiper
    swiperRef.current.initialize();
  }, []);

  // calc slides to render
  const slides = virtual
    ? virtualData.slides.map((slide, index) =>
        // clone slide
        React.cloneElement(slide, {
          // add key
          key: virtualData.from + index,
          // set slides offset
          style: {
            [props.direction === "vertical" ? "top" : "left"]:
              virtualData.offset,
          },
          // add and swiper slide index to data attribute
          ["data-swiper-slide-index"]: virtualData.from + index,
        })
      )
    : children; // return children if virtual is disabled

  return (
    <swiper-container init="false" ref={swiperRef}>
      {slides}
    </swiper-container>
  );
}

// SwiperSlide component stays the same
export function SwiperSlide(props) {
  const {
    children,
    ...rest
  } = props;

  return (
    <swiper-slide {...rest}>
      {children}
    </swiper-slide>
  );
}

現在我們可以輕鬆地在 React 中建立具有虛擬幻燈片的 Swiper

import { Swiper, SwiperSlide } from 'path/to/my-swiper.jsx';

export default function App() {
  return (
    <Swiper virtual navigation>
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
      ...
      <SwiperSlide>Slide 1000</SwiperSlide>
    </Swiper>
  );
}

附註

一如既往，如果您喜歡 Swiper，請透過捐款或承諾來支持專案

在 Patreon 上：https://www.patreon.com/swiperjs
在 Open Collective 上：https://opencollective.com/swiper

並查看我們的進階專案

您的支持對我們意義重大！

在 GitHub 上編輯此頁面