PaneFlow
隆重推出PaneFlow：视觉化创建精美幻灯片
现已集成 AI

Swiper v12

2025年9月11日

Swiper 一直致力于实现快速、轻量和易于集成。现代 CSS 现在提供了足够强大的功能，使我们可以在包本身中放弃预处理器，简化主题设置，并减少传输的字节数。我们还重新设计了导航图标，以消除字体图标的麻烦和 CSP 误报。最后，我们使虚拟幻灯片在需要 `slidesPerView: 'auto'` 的真实世界轮播中更加灵活。

接下来是快速浏览以及实用的升级指南。

样式：已移除 Less 和 SCSS，仅支持 CSS

  • Swiper 包不再提供 `.less` 或 `.scss` 源文件。
  • 所有官方样式都是标准 CSS，旨在开箱即用，并通过 CSS 自定义属性进行主题设置。

我们为什么要这样做

  • 现代 CSS 涵盖了大多数预处理器用例：变量、嵌套、级联层和改进的选择器。
  • 发布单一的规范 CSS 源可以避免重复，减少维护工作，并最大限度地减少关于“应该导入哪个文件”的困惑。

如何迁移

之前 (SCSS)

// remove these imports
@import 'swiper/scss';
@import 'swiper/scss/navigation';
@import 'swiper/scss/pagination';

之后 (CSS)

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

或

<link rel="stylesheet" href="https://unpkg.com/swiper/swiper-bundle.min.css" />

自定义外观 使用 CSS 变量而不是 SCSS 变量

:root {
  /* common Swiper variables (examples) */
  --swiper-theme-color: #111; /* primary accent */
  --swiper-navigation-size: 20px; /* icon size */
  --swiper-pagination-color: #111; /* bullets */
}

如果您之前依赖 SCSS mixins 或 maps 进行主题设置，请将它们移至您自己的构建步骤中，但将 Swiper 分发的 CSS 视为最终 API。您仍然可以在其之上构建自己的级联层或实用类。

Swiper 现在将 SVG 元素注入到导航按钮中，而不是使用自定义图标字体。

我们为什么要这样做

  • 更好的自定义： SVG 只是 DOM；您可以使用 CSS 设置 `fill`、`width`、`height` 样式并应用转换。
  • CSP 友好： 许多项目通过内容安全策略规则阻止内联字体或数据 URL。SVG 元素避免了这些字体加载陷阱。

如何使用和自定义

默认情况下，Swiper 会在 `prevEl` 和 `nextEl` 中渲染 SVG 箭头。您可以全局设置它们的样式

/* Size and color via CSS variables */
:root {
  --swiper-navigation-color: #0f172a;
  --swiper-navigation-size: 26px;
}

/* OR fine-grained control using selectors */
.swiper-button-next svg,
.swiper-button-prev svg {
  width: 26px;
  height: 26px;
  fill: #0f172a;
}

想要完全自定义的图标？提供您自己的按钮标记，这样 Swiper 就不会注入默认值

<div class="swiper-button-prev">
  <!-- your SVG -->
  <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M15 6l-6 6 6 6" /></svg>
</div>
<div class="swiper-button-next">
  <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M9 6l6 6-6 6" /></svg>
</div>

Swiper 会将交互附加到这些元素，而不会替换您的 SVG。

CSP 注意： 如果您强制执行严格的 CSP，新方法消除了之前字体面内联策略的顾虑。仅当您的应用程序在其他地方需要内联样式时才继续允许内联样式；Swiper 的默认 SVG 不需要内联样式。

虚拟幻灯片：部分支持 `slidesPerView: auto`

虚拟幻灯片是高效渲染大型列表的理想选择，但过去与 `slidesPerView: 'auto'` 存在冲突，因为自动调整大小需要测量实际 DOM 节点。

新增功能

Swiper v12 通过以下方式引入了部分兼容层

  • `virtual.slidesPerViewAutoSlideSize` - 一个固定的数字幻灯片宽度，**仅在虚拟模式下**当 `slidesPerView` 为 `'auto'` 时使用。它作为一个替代尺寸，以便虚拟引擎可以计算哪些幻灯片应该在视图中，而无需测量每个幻灯片。

当您的幻灯片大致均匀或您可以声明一个合理的平均宽度时，这尤其有用。

示例

import Swiper from 'swiper/bundle';
import 'swiper/css/bundle';

const swiper = new Swiper('.swiper', {
  slidesPerView: 'auto',
  spaceBetween: 12,
  virtual: {
    enabled: true,
    slides: Array.from({ length: 10000 }, (_, i) => `Slide #${i + 1}`),
    slidesPerViewAutoSlideSize: 320, // pixels (example)
  },
});

升级清单

  • 将所有 `scss`/`less` 导入替换为 `swiper/css/*` 导入。
  • 将主题覆盖移至 CSS 自定义属性和标准 CSS 规则。
  • 如果您依赖旧的图标字体，请删除相关的字体加载代码；样式化新的 SVG 箭头或提供您自己的 SVG。
  • 对于使用虚拟幻灯片和自动调整大小项目的大型轮播，添加 `virtual.slidesPerViewAutoSlideSize` 并调整您的幻灯片 CSS 以大致匹配该宽度。

常见问题

我仍然可以在我的应用程序中使用 SCSS/Less 吗？ 是的。您可以继续在构建中使用 SCSS/Less，但将 Swiper 的分布式 CSS 作为最终产物导入。将 Swiper 的 CSS 视为外部依赖项，就像其他任何库的 CSS 一样。

SVG 图标会破坏我现有的自定义按钮吗？ 不会。如果您提供带有内容的自定义 `prevEl`/`nextEl`，Swiper 不会覆盖它们。SVG 注入只在 Swiper 需要渲染默认图标时发生。

`slidesPerView: 'auto'` 现在完全支持虚拟幻灯片吗？ 这是一种实用的折中方案。如果您的自动调整大小幻灯片接近一个共同的宽度，新选项效果很好。如果每个幻灯片差异很大，请考虑限制宽度或使用非虚拟模式。

总结

Swiper v12 削减了旧有的功能，并向现代 Web 平台靠拢。纯 CSS 分发简化了主题和打包，SVG 图标消除了一类集成问题，并且虚拟幻灯片对于大规模自动调整大小的画廊变得更加有用。如果您在升级过程中遇到边缘情况，请分享一个最小的重现示例——我们致力于快速迭代。

接下来是什么？

一如既往，如果您喜欢 Swiper，请通过捐赠或认捐来支持项目

并查看我们的高级项目

您的支持对我们意义重大！

在 GitHub 上编辑此页面