如何将Swiper JS接入Astro.build并封装为组件？不使用React

1. 安装Swiper依赖 #

在项目根目录执行安装命令：

npm install swiper
# 或使用yarn/pnpm
# yarn add swiper
# pnpm add swiper

2. 创建可复用Swiper组件 #

在src/components目录下新建Swiper.astro文件，内容如下：

---
// 导入Swiper核心及所需模块、样式
import Swiper from 'swiper';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/autoplay';
import { Navigation, Pagination, Autoplay } from 'swiper/modules';

// 定义组件Props类型
export interface Props {
  // 幻灯片数据，支持纯文本、HTML或图片
  slides: Array<{
    content?: string;
    src?: string;
    alt?: string;
  }>;
  autoplay?: boolean; // 是否自动轮播
  pagination?: boolean; // 是否显示分页器
  navigation?: boolean; // 是否显示前后导航按钮
}

// 解构Props，设置默认值
const {
  slides,
  autoplay = false,
  pagination = false,
  navigation = false
} = Astro.props;
---

<!-- Swiper容器 -->
<div class="swiper">
  <div class="swiper-wrapper">
    {slides.map((slide, index) => (
      <div class="swiper-slide" key={index}>
        {/* 渲染图片类型幻灯片 */}
        {slide.src && <img src={slide.src} alt={slide.alt || `Slide ${index + 1}`} />}
        {/* 渲染HTML/文本类型幻灯片，使用set:html确保HTML正确解析 */}
        {slide.content && <span set:html={slide.content}></span>}
      </div>
    ))}
  </div>

  {/* 分页器 */}
  {pagination && <div class="swiper-pagination"></div>}
  {/* 导航按钮 */}
  {navigation && (
    <>
      <div class="swiper-button-prev"></div>
      <div class="swiper-button-next"></div>
    </>
  )}
</div>

<!-- 客户端初始化脚本 -->
<script is:inline use:client define:vars={{ autoplay, pagination, navigation }}>
  import Swiper from 'swiper';
  import { Navigation, Pagination, Autoplay } from 'swiper/modules';

  // 配置Swiper实例
  new Swiper('.swiper', {
    loop: true,
    autoplay: autoplay ? { delay: 3000, disableOnInteraction: false } : false,
    ...(pagination && { pagination: { el: '.swiper-pagination', clickable: true } }),
    ...(navigation && { navigation: { nextEl: '.swiper-button-next', prevEl: '.swiper-button-prev' } }),
    modules: [Autoplay, Navigation, Pagination]
  });
</script>

<!-- 自定义样式（按需调整） -->
<style>
  .swiper {
    width: 100%;
    height: 400px;
    margin: 2rem 0;
  }

  .swiper-slide {
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: #f8f9fa;
    overflow: hidden;
  }

  .swiper-slide img {
    width: 100%;
    height: 100%;
    object-fit: cover;
  }
</style>

3. 在页面/组件中使用Swiper #

比如在src/pages/index.astro中导入并使用：

---
import Swiper from '../components/Swiper.astro';

// 准备幻灯片数据
const slidesData = [
  { content: '<h2 class="text-2xl">欢迎使用Swiper + Astro</h2>' },
  { src: '/images/slide-1.jpg', alt: '风景图1' },
  { content: '<p>这是一个完全不依赖React的可复用轮播组件</p>' },
  { src: '/images/slide-2.jpg', alt: '风景图2' },
];
---

<!-- 使用组件，传入配置参数 -->
<Swiper 
  slides={slidesData} 
  autoplay={true} 
  pagination={true} 
  navigation={true} 
/>

关键注意事项 #

• use:client指令确保Swiper的初始化代码仅在客户端执行，符合Astro的静态站点特性。
• define:vars用于将组件的Props传递给客户端脚本，避免硬编码配置。
• 如果不需要某些模块（比如Autoplay），可以移除对应的导入和配置项，减少打包体积。
• 幻灯片内容使用set:html渲染HTML字符串时，确保内容是可信的，避免XSS风险。

内容的提问来源于stack exchange，提问作者Alexander Krupnitsky