Angular 17 SSR中Swiper嵌套Material GridList渲染异常排查

你遇到的确实是渲染时序冲突导致的问题。在SSR场景下，Swiper自定义元素会在服务器端或客户端早期初始化，但此时MatGridList还没完成布局计算（比如容器尺寸、网格位置），Swiper无法获取正确的父容器尺寸，最终导致幻灯片布局错乱、无法正常滑动等异常。

以下是几种可行的解决方案：

1. 延迟Swiper初始化，等待MatGridList布局完成 #

利用Angular的AfterViewChecked钩子，监听父容器尺寸变化，确保MatGridList布局稳定后再初始化Swiper：

import { Component, CUSTOM_ELEMENTS_SCHEMA, AfterViewChecked, ElementRef, ViewChild } from '@angular/core';
import { MatGridListModule } from '@angular/material/grid-list';
import Swiper from 'swiper';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MatGridListModule],
  template: `
    <p>Swipe to change slides</p>
    <mat-grid-list cols="2" rowHeight="100px">
      <mat-grid-tile [colspan]="2" [rowspan]="2">
        <swiper-container #swiperContainer>
          <swiper-slide>Slide 1</swiper-slide>
          <swiper-slide>Slide 2</swiper-slide>
          <swiper-slide>Slide 3</swiper-slide>
          <swiper-slide>Slide 4</swiper-slide>
        </swiper-container>
      </mat-grid-tile>
    </mat-grid-list>`,
  styles: [
    `swiper-slide {
      height: 400px
    }
    swiper-slide:nth-of-type(1) {
      background-color: red;
    }
    swiper-slide:nth-of-type(2) {
      background-color: green;
    }
    swiper-slide:nth-of-type(3) {
      background-color: blue;
      color: white;
    }
    swiper-slide:nth-of-type(4) {
      background-color: yellow;
    }`,
  ],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class App implements AfterViewChecked {
  @ViewChild('swiperContainer') swiperContainer!: ElementRef<HTMLElement>;
  private swiperInitialized = false;

  ngAfterViewChecked() {
    // 确保只在客户端执行，且父容器尺寸已稳定
    if (!this.swiperInitialized && typeof window !== 'undefined' && this.swiperContainer.nativeElement.offsetWidth > 0) {
      new Swiper(this.swiperContainer.nativeElement, {
        slidesPerView: 1,
        spaceBetween: 10,
        // 可添加其他Swiper配置
      });
      this.swiperInitialized = true;
    }
  }
}

2. 强制设置Swiper容器尺寸 #

给swiper-container显式设置宽高，避免依赖MatGridList的布局计算结果：

/* 在组件styles中添加 */
swiper-container {
  width: 100%;
  height: 400px;
  display: block;
}

3. 仅在客户端渲染Swiper #

如果不需要SSR渲染Swiper内容，可利用isPlatformBrowser判断环境，只在客户端加载Swiper元素：

import { Component, CUSTOM_ELEMENTS_SCHEMA, Inject, PLATFORM_ID } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import { MatGridListModule } from '@angular/material/grid-list';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MatGridListModule],
  template: `
    <p>Swipe to change slides</p>
    <mat-grid-list cols="2" rowHeight="100px">
      <mat-grid-tile [colspan]="2" [rowspan]="2">
        <swiper-container *ngIf="isBrowser">
          <swiper-slide>Slide 1</swiper-slide>
          <swiper-slide>Slide 2</swiper-slide>
          <swiper-slide>Slide 3</swiper-slide>
          <swiper-slide>Slide 4</swiper-slide>
        </swiper-container>
      </mat-grid-tile>
    </mat-grid-list>`,
  styles: [/* 原有样式 */],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class App {
  isBrowser = false;

  constructor(@Inject(PLATFORM_ID) private platformId: Object) {
    this.isBrowser = isPlatformBrowser(platformId);
    if (this.isBrowser) {
      import('swiper/element/bundle');
    }
  }
}

问题根源说明 #

MatGridList的布局依赖客户端的DOM尺寸计算，而SSR是在服务器端生成静态HTML，无法获取客户端的尺寸信息。Swiper自定义元素初始化时需要容器的宽高来计算幻灯片布局，两者的时序不匹配就会导致渲染异常。上述方案通过延迟初始化、强制尺寸或客户端专属渲染，解决了这个时序冲突。

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