Vanilla Lazyload 版本升级指南：从旧版本平滑迁移

Vanilla Lazyload 版本升级指南：从旧版本平滑迁移

vanilla-lazyload LazyLoad is a lightweight, flexible script that speeds up your website by deferring the loading of your below-the-fold images, backgrounds, videos, iframes and scripts to when they will enter the viewport. Written in plain "vanilla" JavaScript, it leverages IntersectionObserver, supports responsive images and enables native lazy loading. 项目地址: https://gitcode.com/gh_mirrors/va/vanilla-lazyload

前言

Vanilla Lazyload 是一个轻量级的图片懒加载库，随着版本的迭代，API 和配置项也在不断优化。本文将详细解析从旧版本升级到新版本时需要注意的关键变更点，帮助开发者顺利完成迁移。

从 v16 升级到 v17

元素选择器变更

问题背景：v17 版本对元素选择逻辑进行了优化，默认情况下需要为懒加载元素添加 lazy 类。

解决方案：

1. 推荐方案：为所有懒加载元素添加 lazy 类

<img class="lazy" data-src="image.jpg" alt="示例图片">

2. 替代方案：显式配置选择器（保持原有行为）

new LazyLoad({
  elements_selector: "img"  // 明确指定选择所有img标签
});

取消退出观察配置

变更说明：移除了 cancel_on_exit 配置项，改为内部自动处理。

操作建议：

// 移除以下配置
new LazyLoad({
  cancel_on_exit: true  // 删除此行
});

从 v15 升级到 v16

回调函数重命名

变更说明：callback_reveal 更名为 callback_loading，更准确反映其触发时机。

迁移示例：

// 旧版
new LazyLoad({ callback_reveal: myCallback });

// 新版
new LazyLoad({ callback_loading: myCallback });

加载方法变更

重大变更：实例方法 load() 改为静态方法，需独立调用。

代码对比：

const lazyLoader = new LazyLoad();

// 旧版
lazyLoader.load(someElement);

// 新版
LazyLoad.load(someElement, {
  // 可选配置（与实例配置可不同）
});

观察行为配置

语义优化：auto_unobserve 更名为 unobserve_completed，逻辑反转。

配置转换：

// 旧版（false表示不自动取消观察）
auto_unobserve: false

// 新版（false表示不自动取消观察）
unobserve_completed: false

延迟加载优化

行为变更：load_delay 被 cancel_on_exit 替代，实现更智能的加载控制。

// 旧版（固定延迟）
load_delay: 300

// 新版（动态判断）
cancel_on_exit: true

从 v14 升级到 v15

背景图属性变更

规范统一：明确区分普通图片和背景图的属性。

1. 单背景图规范：

<!-- 旧版 -->
<div data-src="bg.jpg"></div>

<!-- 新版 -->
<div data-bg="bg.jpg"></div>

2. 多背景图规范：

<!-- 必须使用专用属性 -->
<div data-bg-multi="url(1.jpg), url(2.jpg)"></div>

兼容方案：可通过配置保持旧属性

new LazyLoad({
  data_bg: "src"  // 继续识别data-src
});

从 v13 升级到 v14

回调函数弃用警告

前瞻性变更：callback_reveal 将被移除，应改用 callback_loading。

// 立即迁移建议
new LazyLoad({
  callback_loading: () => { /* 加载中回调 */ }
});

从 v12 升级到 v13

回调函数语义优化

命名优化：callback_set 更名为 callback_reveal，更符合实际触发时机。

// 旧版
new LazyLoad({ callback_set: elementRevealed });

// 新版
new LazyLoad({ callback_reveal: elementRevealed });

升级建议

1. 逐步测试：建议分版本逐步升级，每次升级后充分测试
2. 查看控制台：新版本会输出废弃警告，帮助定位需要修改的代码
3. 性能优化：利用版本升级机会重新评估配置，如：
   • 考虑使用 unobserve_completed 优化内存
   • 评估 cancel_on_exit 对复杂页面的影响

通过遵循本指南，您可以确保在享受新版本性能优化和功能增强的同时，保持现有功能的稳定运行。

vanilla-lazyload LazyLoad is a lightweight, flexible script that speeds up your website by deferring the loading of your below-the-fold images, backgrounds, videos, iframes and scripts to when they will enter the viewport. Written in plain "vanilla" JavaScript, it leverages IntersectionObserver, supports responsive images and enables native lazy loading. 项目地址: https://gitcode.com/gh_mirrors/va/vanilla-lazyload