lazysizes include 插件实战：按条件异步加载内容、CSS 与 AMD/ES6 模块的完整指南

• 前端
• Web性能

lazysizes include 插件（plugins/include/ls.include.js）是 lazySizes 生态中用于异步按需加载非关键内容（HTML 片段、CSS 样式、AMD/ES6 模块）的官方扩展。它借助懒加载、优先级队列与"加载后预取"等机制，比同类方案拥有更好的扩展性与性能表现。阅读本文后，你将掌握data-include属性驱动的条件化内容加载、通过 CSS 伪元素或 JS 配置条件规则、模块生命周期钩子（lazytransform/lazyload/lazyunload）、事件拦截与请求改造、多模块状态共享等完整实战能力。

一、插件定位与典型使用场景

include 插件的核心价值在于：把"何时加载"与"加载什么"彻底交给声明式属性与条件规则，让页面可以在不阻塞首屏的前提下，按需注入内容与行为。官方文档给出的典型场景包括：

• 根据条件懒加载不同的内容、样式或 JS 模块（响应式内容、响应式行为、媒体查询、DOM 元素是否存在、浏览器特性、用户偏好、元素查询等）；
• 延迟渲染成本高或不可缓存的内容（客户端或服务端）；
• 用 JS 增强文档时渐进式地注入新内容；
• 大型项目中大体积 JS/CSS 模块的拆分或延迟加载；
• 为（条件化）JS 行为的初始化/加载与销毁/卸载提供干净简洁的架构；
• DOM 行为的延迟自初始化。

从源码角度看，该插件通过监听核心的lazybeforeunveil事件挂载到 lazySizes 的加载流程（ls.include.js）：只要元素带有data-include属性，插件就会接管其"加载"动作并执行完整的候选条件匹配逻辑。插件文件同时支持 CommonJS、AMD 与全局安装三种形式，且在 lazySizes 尚未加载时会等待lazyunveilread事件自动完成安装（ls.include.js），因此直接在页面中引入 ls.include.min.js 即可使用。

二、基础用法：data-include声明式加载

最基本的用法是在带有lazyload类的元素上放置data-include属性，值为要加载的 URL：

<aside class="related-articles lazyload"><div class="dynamic-content lazyload" ><style> html:after { display: none; content: "small"; } @media (min-width: 760px){ html:after { content: "medium"; } } @media (min-width: 980px){ html:after { content: "large"; } } </style> <div class="dynamic-content lazyload" ><script> window.lazySizesConfig = { include: { conditions: { small: '(max-width: 480px)', custom: function(element, data){ return true || false; } } } }; </script> <div class="dynamic-content lazyload" ><div class="dynamic-content lazyload" ><script> document.addEventListener('lazyincluded', function(e){ // e.target has new content }); </script> <div class="dynamic-content lazyload"><div class="dynamic-content lazyload"><div class="slider lazyload" >define(function(){ // constructor var Slider = function(element,options) { }; Slider.prototype = { destroy: function(){} }; // lazysizes include features: // called with the DOM element (data.target) and some other useful data (data.detail) // useful to initialize with the DOM element Slider.lazyload = function(data){ var Slider = new Slider(data.target); // save instance for destroy / lazyunload // data.element._slider = Slider; }; // in case of a conditioned include and // the need to destroy the instance (i.e.: unbind global events) Slider.lazyunload = function(data){ // data.target._slider.destroy(); }; // gets invoked with the a simplified XHR object (data.detail) // and the dom element (data.target) Slider.lazytransform = function(data){ // var json = JSON.parse(data.detail.responseText); // data.detail.response = template(json); }; return Slider; });

源码中这三个钩子分别由unloadModule、transformInclude、loadModule三个内部函数按固定顺序调用：先卸载旧模块（lazyunload），再对新模块执行lazytransform，内容写入后执行lazyload（ls.include.js）。data对象在三个钩子之间共享，因此可以在卸载与初始化之间传递状态。

条件切换时的 HTML 重置（resetHTML）

当一个候选包含新标记、而另一个候选只包含 AMD 行为时，条件切换会自动重置初始内容：

<div class="lazyload">Slider.lazyunload = function(data){ // data.element._slider.destroy(); data.resetHTML = true; }; //or NewSlider.lazytransform = function(data){ // data.element._slider.destroy(); data.resetHTML = true; };

当内容中不存在需要迁移到新组件的可变状态（如输入框等）时，该选项让清理 HTML 变得极其简单。实现上，resetHTML会在模块卸载后触发detail.content回填为已保存的初始内容（ls.include.js）。

一个候选加载多个样式或模块

同一候选的多个样式或多个 AMD 模块可以用|,|分隔符配置：

<div class="slider lazyload" ><li> <a href="">Category 1 (articles: <span class="lazyload">const component = document.querySelector('.lazy-component'); // Modify the request headers when the targeted component kicks off an XHR component.addEventListener('lazyincludeload', function(event) { if (event.detail) { event.detail.xhrModifier = function(request, candidate) { request.setRequestHeader('Accept', 'application/json'); } } }); // Transform a JSON response into HTML before it is injected component.addEventListener('lazyincludeloaded', function(event) { if (event.detail.content) { var json = JSON.parse(event.detail.content); var html = '<h1>' + json.title + '</h1>'; html += '<div>' + json.body + '</div>'; event.detail.content = html; } });

从源码看，XHR 请求固定使用GET方法并带有X-Requested-With: XMLHttpRequest头，xhrModifier在request.send()之前被调用（ls.include.js）；lazyincludeloaded的detail还额外暴露text、response、xml、isSuccess等字段，便于对响应做精细化处理（ls.include.js）。注入判断遵循isSuccess && !event.defaultPrevented && content != null && content != elem.innerHTML，因此通过preventDefault取消lazyincludeloaded可阻止内容写入。

八、配置项总览

所有 include 配置都通过lazySizesConfig.include对象提供（插件的默认值见 ls.include.js）：

contentElement（默认："html"）

用于读取 CSScontent值以判定条件的元素选择器：

window.lazySizesConfig = { include: { contentElement: '#mediaqueries' // 'html' } };

conditions（默认：{}）

用于创建新的自定义条件（字符串媒体查询或函数），与 第四节 中的用法一致：

window.lazySizesConfig = { addClasses: true, // good to add loading styles include: { conditions: { small: '(max-width: 480px)', custom: function(elem, data){ return true || false; } } } };

addClasses是 lazySizes 核心的通用选项（lazyloading/lazyloaded等加载状态类，默认配置见 lazysizes-core.js），include 特性与它及所有普通 lazySizes 选项、事件、方法协同工作。

map（默认：{}）

map选项允许把data-include的值（或其解析后的部分）映射为另一个字符串，常用于将内容与行为分离：

<script> window.lazySizesConfig = { addClasses: true, // good to add loading styles include: { map: { slider: 'slider.html amd:path/slider (large)', amdSlider: 'jquery|,|path/ui-slick' } } }; </script> <div class="lazyload"><!-- markup has><div class="dynamic-content lazyload"><nav class="lazyload">define(function(){ // constructor var Nav = function(element,options) { }; Nav.prototype = { }; Nav.lazyunload = function(data){ //Reset HTML for mobileNav data.resetHTML = true; //share the value of the input field with mobileNav data.shareState = { searchValue: $('input.search', data.target).val(); }; }; Nav.lazyload = function(data){ //check wether mobileNav has shared some data if(data.shareState){ $('input.search', data.target).val(data.shareState.searchValue || ''); } }; return Nav; });

requireJs与systemJs配置

注意：要让 AMD 模块（amd:）或 ES6 模块（module:）真正走各自的模块加载器，必须提供requireJs与/或systemJs选项，否则插件会退化为普通的<script>标签加载：

window.lazySizesConfig = window.lazySizesConfig || {}; window.lazySizesConfig.requireJs = function(modules, cb){ window.require(modules, cb); }; window.lazySizesConfig.systemJs = function(module, cb){ window.System.import(module).then(cb); };

十一、小结：include 插件的工作流

一个典型的 include 加载流程可以概括为：

1. 带有data-include的.lazyload元素进入视口，触发核心lazybeforeunveil事件；
2. 插件解析data-include字符串为候选列表（含 URL、类型、条件），并按include.conditions→customMedia→ 媒体查询/伪元素 content 的顺序求值，选出第一个命中候选；
3. 派发可取消的lazyincludeload，允许通过xhrModifier改造 GET 请求；
4. 并行加载 HTML（XHR）、CSS（link）、AMD/ES6 模块，借助内部队列控制并发优先级；
5. 依次执行旧模块lazyunload（可设resetHTML重置内容）、新模块lazytransform（可转换响应）；
6. 派发可取消的lazyincludeloaded（可改写detail.content），随后写入innerHTML；
7. 派发lazyincluded通知完成，并调用新模块lazyload初始化行为。

这一套机制让"条件化、可回收、渐进增强"的内容加载成为可能。更多插件生态信息可参阅 plugins/README.md，插件源码与压缩版分别位于 ls.include.js 与 ls.include.min.js，lazySizes 核心的默认配置项定义在 lazysizes-core.js。

• 前端
• Web性能