如何在Angular 17 SSR中处理Swiper 11 Web组件事件

问题背景 #

现有基于传统Swiper初始化的Angular代码运行正常，希望迁移到Swiper Web组件，重点解决以下需求：

• 替换原有DOM结构为Swiper官方Web组件标签
• 处理slideChangeTransitionStart、slideChangeTransitionEnd事件
• 在主轮播的slideChangeTransitionEnd触发时调用setupImageZoom方法
• 保持主轮播与缩略图轮播的联动逻辑

原代码如下：

原HTML代码 #

<div class="swiper-container-wrapper">
  <div class="swiper-container swiper">
      <div class="swiper-wrapper">
        <div *ngFor="let slide of slides" class="swiper-slide">
          <div class="swiper-zoom-container"><img style="width: 100%;" [src]="slide.image"></div>
        </div>
      </div>
      <div class="swiper-pagination"></div>
      <div class="swiper-button-prev"></div>
      <div class="swiper-button-next"></div>
  </div>
  <div class="swiper-container thumbs-swiper thumbs-hover">
    <div class="swiper-wrapper">
      <div *ngFor="let slide of slides" class="swiper-slide">
        <div class="swiper-zoom-container"><img style="width: 100%;" [src]="slide.image"></div>
      </div>
    </div>
  </div>
</div>

原TS代码 #

slides = [
    {image: '../../../../../assets/images/swiper-nature/nature-1.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-2.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-3.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-4.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-5.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-6.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-7.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-8.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-10.jpg'}
  ];

  ngAfterViewInit() {
    const thumbsSwiper = new Swiper(".thumbs-swiper", {
      loop: false,
      direction: 'vertical',
      spaceBetween: 10,
      slidesPerView: 6,
      watchSlidesProgress: true,
      centeredSlides: true,
      centeredSlidesBounds: true,
      watchOverflow: true,
      watchSlidesVisibility: true,
    });
    const mainSwiper = new Swiper('.swiper', {
      direction: 'horizontal',
      loop: false,
      speed: 400,
      spaceBetween: 100,
      mousewheel: {
        invert: true,
      },
      grabCursor: true,
      effect: 'creative',
      creativeEffect: {
        prev: {
          translate: [0, 0, -400],
        },
        next: {
          translate: ['100%', 0, 0],
        },
      },
      pagination: {
        el: '.swiper-pagination'
      },
      navigation: {
        nextEl: '.swiper-button-next',
        prevEl: '.swiper-button-prev',
      },
      zoom: {
        maxRatio: 10,
      },
      thumbs: {
        swiper: thumbsSwiper
      } 
    });
    mainSwiper.on("slideChangeTransitionStart",  () => {
      console.log('slideChangeTransitionStart');
      thumbsSwiper.slideTo(mainSwiper.activeIndex);
    });
    mainSwiper.on("slideChangeTransitionEnd", () => {
      console.log('mainSwiper slideChangeTransitionEnd');
      thumbsSwiper.slideTo(mainSwiper.activeIndex);
      this.setupImageZoom();
    });

    thumbsSwiper.on("slideChangeTransitionEnd", () => {
      console.log('thumbsSwiper slideChangeTransitionEnd');
      mainSwiper.slideTo(thumbsSwiper.activeIndex);
    });

  this.setupImageZoom();
  }

迁移步骤 #

1. 安装Swiper Web组件依赖 #

安装最新版Swiper（Web组件已内置）：

npm install swiper

2. 配置Angular允许自定义元素 #

在对应组件的模块文件（如app.module.ts）中，添加CUSTOM_ELEMENTS_SCHEMA以允许使用自定义Web组件：

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  // ...其他模块配置
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class YourModule { }

3. 修改HTML模板为Web组件结构 #

替换原有div结构为Swiper官方Web组件标签，属性采用kebab-case格式，并添加模板引用变量用于后续获取实例：

<div class="swiper-container-wrapper">
  <!-- 主轮播 -->
  <swiper-container 
    #mainSwiper
    class="swiper"
    direction="horizontal"
    loop="false"
    speed="400"
    space-between="100"
    mousewheel="true"
    mousewheel-invert="true"
    grab-cursor="true"
    effect="creative"
    [creative-effect]="{
      prev: { translate: [0, 0, -400] },
      next: { translate: ['100%', 0, 0] }
    }"
    (slide-change-transition-start)="onMainSlideStart($event)"
    (slide-change-transition-end)="onMainSlideEnd($event)"
  >
    <swiper-wrapper>
      <swiper-slide *ngFor="let slide of slides">
        <swiper-zoom-container>
          <img style="width: 100%;" [src]="slide.image">
        </swiper-zoom-container>
      </swiper-slide>
    </swiper-wrapper>
    <!-- 分页组件 -->
    <swiper-pagination slot="pagination"></swiper-pagination>
    <!-- 导航按钮 -->
    <swiper-navigation slot="navigation"></swiper-navigation>
    <!-- 缩放组件 -->
    <swiper-zoom max-ratio="10"></swiper-zoom>
  </swiper-container>

  <!-- 缩略图轮播 -->
  <swiper-container 
    #thumbsSwiper
    class="thumbs-swiper thumbs-hover"
    direction="vertical"
    loop="false"
    space-between="10"
    slides-per-view="6"
    watch-slides-progress="true"
    centered-slides="true"
    centered-slides-bounds="true"
    watch-overflow="true"
    watch-slides-visibility="true"
    (slide-change-transition-end)="onThumbsSlideEnd($event)"
  >
    <swiper-wrapper>
      <swiper-slide *ngFor="let slide of slides">
        <swiper-zoom-container>
          <img style="width: 100%;" [src]="slide.image">
        </swiper-zoom-container>
      </swiper-slide>
    </swiper-wrapper>
  </swiper-container>
</div>

4. 修改TS代码处理事件与联动逻辑 #

通过ViewChild获取swiper实例，处理事件并保持主轮播与缩略图的联动：

import { Component, ViewChild, AfterViewInit } from '@angular/core';
// 导入Swiper Web组件
import 'swiper/element/bundle';
import type { SwiperContainer } from 'swiper/element';

@Component({
  // ...组件元数据
})
export class YourComponent implements AfterViewInit {
  slides = [
    {image: '../../../../../assets/images/swiper-nature/nature-1.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-2.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-3.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-4.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-5.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-6.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-7.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-8.jpg'},
    {image: '../../../../../assets/images/swiper-nature/nature-10.jpg'}
  ];

  // 获取主轮播和缩略图轮播实例
  @ViewChild('mainSwiper') mainSwiper!: SwiperContainer;
  @ViewChild('thumbsSwiper') thumbsSwiper!: SwiperContainer;

  ngAfterViewInit(): void {
    // 关联主轮播与缩略图
    this.mainSwiper.thumbs = { swiper: this.thumbsSwiper.swiper };
    
    // 初始化调用一次图片缩放设置
    this.setupImageZoom();
  }

  // 主轮播slide切换开始事件
  onMainSlideStart(event: Event) {
    const swiper = (event.target as SwiperContainer).swiper;
    console.log('slideChangeTransitionStart');
    this.thumbsSwiper.swiper.slideTo(swiper.activeIndex);
  }

  // 主轮播slide切换结束事件
  onMainSlideEnd(event: Event) {
    const swiper = (event.target as SwiperContainer).swiper;
    console.log('mainSwiper slideChangeTransitionEnd');
    this.thumbsSwiper.swiper.slideTo(swiper.activeIndex);
    this.setupImageZoom();
  }

  // 缩略图轮播切换结束事件
  onThumbsSlideEnd(event: Event) {
    const swiper = (event.target as SwiperContainer).swiper;
    console.log('thumbsSwiper slideChangeTransitionEnd');
    this.mainSwiper.swiper.slideTo(swiper.activeIndex);
  }

  setupImageZoom() {
    // 你的原有缩放逻辑
  }
}

5. 样式适配 #

原有针对.swiper、.swiper-slide等类名的样式依然有效，Swiper Web组件会自动添加这些类名，无需额外修改样式文件。

关键说明 #

• Web组件的事件名采用kebab-case格式（如slide-change-transition-start对应原事件slideChangeTransitionStart）
• 通过swiper属性获取底层Swiper实例，调用slideTo等方法
• 缩略图关联通过设置thumbs属性实现，无需手动在初始化时传入
• 事件绑定直接在模板中通过(事件名)语法实现，无需调用on()方法

内容的提问来源于stack exchange，提问作者Vijai S