🎠 快速定位 / 入口 >>>

• .swiper .swiper-wrapper .swiper-slide：-> ->
• new Swiper(...) swiper/react swiper/vue swiper/element：、、、
• Navigation Pagination Scrollbar Autoplay FreeMode Grid Thumbs Controller：、、、、、、、
• EffectFade EffectCube EffectCoverflow EffectFlip EffectCards EffectCreative：、、、、、
• slideChange reachEnd progress breakpoint：、、、
• document.querySelector('.swiper').swiper

import Swiper from 'swiper';
import { Navigation, Pagination } from 'swiper/modules';

import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';

const swiper = new Swiper('.swiper', {
  modules: [Navigation, Pagination],
  slidesPerView: 1,
  spaceBetween: 16,
  navigation: true,
  pagination: { clickable: true },
});

🧩 最小工作流：原生 JS >>>

• 先确认容器结构完整
• 再引入核心 CSS
• 需要按钮、分页、滚动条时，再装对应模块
• breakpoints
• allowTouchMove: false

<div class="swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    <div class="swiper-slide">Slide 3</div>
  </div>
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>
  <div class="swiper-pagination"></div>
</div>

import Swiper from 'swiper';
import { Navigation, Pagination, A11y } from 'swiper/modules';

import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';

const swiper = new Swiper('.swiper', {
  modules: [Navigation, Pagination, A11y],
  slidesPerView: 1,
  spaceBetween: 12,
  loop: true,
  speed: 450,
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
  pagination: {
    el: '.swiper-pagination',
    clickable: true,
  },
  a11y: true,
});

🎬 Recipe：基础轮播怎么配 >>>

• slidesPerView：每屏显示几张
• spaceBetween：卡片间距
• breakpoints：按屏宽切换布局
• centeredSlides：居中展示首屏
• watchOverflow：滑块太少时自动禁用交互
• grabCursor：桌面端更像可拖拽组件

const swiper = new Swiper('.swiper', {
  slidesPerView: 1.15,
  spaceBetween: 12,
  centeredSlides: false,
  grabCursor: true,
  watchOverflow: true,
  breakpoints: {
    640: { slidesPerView: 2, spaceBetween: 16 },
    1024: { slidesPerView: 3, spaceBetween: 20 },
  },
});

🖼️ Recipe：缩略图联动大图 >>>

• thumbs: { swiper: thumbsSwiper }
• watchSlidesProgress: true
• 缩略图通常关掉复杂交互，只保留点击切换
• loop watchOverflow

import Swiper from 'swiper';
import { Thumbs, FreeMode } from 'swiper/modules';
import 'swiper/css';

const thumbs = new Swiper('.thumbs', {
  modules: [FreeMode],
  slidesPerView: 5,
  spaceBetween: 8,
  freeMode: true,
  watchSlidesProgress: true,
});

const main = new Swiper('.main', {
  modules: [Thumbs],
  slidesPerView: 1,
  spaceBetween: 12,
  thumbs: {
    swiper: thumbs,
  },
});

🧮 Recipe：海量数据与虚拟列表 >>>

• virtual：开启虚拟滑块
• renderExternal：把渲染交给外部框架
• renderExternalUpdate：异步渲染后手动更新
• slidesPerView: 'auto' slidesPerViewAutoSlideSize
• update()

import Swiper from 'swiper';
import { Virtual } from 'swiper/modules';

const swiper = new Swiper('.swiper', {
  modules: [Virtual],
  virtual: {
    slides: Array.from({ length: 1000 }, (_, i) => `Slide ${i + 1}`),
  },
  slidesPerView: 3,
  spaceBetween: 12,
});

swiper.virtual.slides.push('New slide');
swiper.update();

✨ Recipe：特效和动效 >>>

• fade cube coverflow flip cards creative：、、、、、
• swiper/css/effect-fade
• fade creative cards

import Swiper from 'swiper';
import { EffectFade, EffectCreative } from 'swiper/modules';

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

const fadeSwiper = new Swiper('.fade-swiper', {
  modules: [EffectFade],
  effect: 'fade',
  fadeEffect: {
    crossFade: true,
  },
});

const creativeSwiper = new Swiper('.creative-swiper', {
  modules: [EffectCreative],
  effect: 'creative',
  creativeEffect: {
    prev: {
      shadow: true,
      translate: ['-20%', 0, -1],
    },
    next: {
      translate: ['100%', 0, 0],
    },
  },
});

🧱 Recipe：React / Vue / Web Components >>>

• swiper/react
• swiper/vue
• swiper/element swiper/element/bundle：或
• modules
• swiper/element register()

// React
import { Swiper, SwiperSlide } from 'swiper/react';
import { Navigation, Pagination } from 'swiper/modules';
import 'swiper/css';

export default function App() {
  return (
    <Swiper
      modules={[Navigation, Pagination]}
      spaceBetween={24}
      slidesPerView={3}
      navigation
      pagination={{ clickable: true }}
      onSlideChange={() => console.log('slide change')}
    >
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
    </Swiper>
  );
}

<!-- Vue -->
<template>
  <Swiper
    :modules="[Navigation, Pagination]"
    :slides-per-view="3"
    :space-between="24"
    navigation
    :pagination="{ clickable: true }"
    @slideChange="onSlideChange"
  >
    <SwiperSlide>Slide 1</SwiperSlide>
    <SwiperSlide>Slide 2</SwiperSlide>
    <SwiperSlide>Slide 3</SwiperSlide>
  </Swiper>
</template>

<script setup>
import { Swiper, SwiperSlide } from 'swiper/vue';
import { Navigation, Pagination } from 'swiper/modules';
import 'swiper/css';

const onSlideChange = () => {
  console.log('slide change');
};
</script>

<!-- Web Components -->
<swiper-container init="false"></swiper-container>

<script type="module">
  import { register } from 'swiper/element/bundle';

  register();

  const el = document.querySelector('swiper-container');
  Object.assign(el, {
    slidesPerView: 3,
    navigation: true,
    pagination: { clickable: true },
  });
  el.initialize();
</script>

🧭 Quick Ref：核心参数 >>>

📚 Quick Ref：模块、方法、事件 >>>

模块速查

方法速查

事件速查

⚠️ 常见坑 / 决策规则 >>>

• 只写 JS 不引 CSS，样式会直接不完整
• React / Vue / Element 都不是同一个入口，别混着用
• thumbs watchSlidesProgress
• loop rewind
• nextEl prevEl el
• virtual update()
• cssMode
• loading="lazy"