diff --git a/docs/laytpl/detail/demo.md b/docs/laytpl/detail/demo.md
index bb77a7a0..f0027251 100644
--- a/docs/laytpl/detail/demo.md
+++ b/docs/laytpl/detail/demo.md
@@ -1,59 +1,59 @@
-
+
+!}}
diff --git a/docs/laytpl/detail/options.md b/docs/laytpl/detail/options.md
index b26499cc..4f689ea3 100644
--- a/docs/laytpl/detail/options.md
+++ b/docs/laytpl/detail/options.md
@@ -7,72 +7,85 @@
| 标签 |
描述 |
-
+ 类型 |
+ 默认值 |
+
{{!
-| {{= }} |
+open |
-
-转义输出。若字段存在 HTML，将进行转义。
-```
-{{= d.title }}
-```
+用于设置起始界定符
+
+ |
+string |
+
+
+`{{`
|
-| {{- }} 2.8+ |
+close |
-
-原始输出。若字段存在 HTML，将正常渲染。
-```
- {{- d.content }}
-```
+用于设置结束界定符
-该语句一般在需要正常渲染 HTML 时用到，但若字段存在 script 等标签，为防止 xss 问题，可采用 `{{= }}` 进行转义输出。
+ |
+string |
+
-> ### 注意
-> 由于 `2.6.11` 版本对 laytpl 语句进行了重要调整，原 `{{ }}` 语法即等同 `{{- }}`，升级版本时，请进行相应调整。可参考：https://gitee.com/layui/layui/issues/I5AXSP
+`}}`
|
-| {{# }} |
+cache 2.11+ |
-
- JavaScript 语句。一般用于逻辑处理。
- ```
-
-{{#
- var fn = function(){
- return '2017-08-18';
- };
-}}
-{{# if(true){ }}
- 开始日期：{{= fn() }}
-{{# } else { }}
- 已截止
-{{# } }}
-
- ```
+是否开启模板缓存，以便下次渲染时不重新编译模板
|
-
!}}
-
-| {{!{{! !}}!}} |
+boolean |
-
-对一段指定的模板区域进行过滤，即不解析该区域的模板。
-```
-{{! {{! 这里面的模板不会被解析 !}} !}}
-```
+`true`
|
-
+
+| condense 2.11+ |
+
+
+是否压缩模板空白符，如：将多个连续的空白符压缩为单个空格
+
+ |
+boolean |
+
+
+`true`
+
+ |
+
+
+tagStyle
2.11+ |
+
+
+设置标签风格。可选值：
+
+- `legacy`: 采用 `< 2.11` 旧版本的标签风格
+- `modern`: 采用 `2.11+` 新版本的标签风格
+
+为了保持向下兼容，默认仍然采用旧版本的标签风格，但在后续版本可能会将默认值设置为 `modern`，因此，**实际使用时，建议显式设置该选项值，以免升级时产生不兼容的问题**。
+
+ |
+string |
+
+
+`legacy`
+
+ |
+
+ !}}
diff --git a/docs/laytpl/detail/tags.md b/docs/laytpl/detail/tags.md
new file mode 100644
index 00000000..0def79d4
--- /dev/null
+++ b/docs/laytpl/detail/tags.md
@@ -0,0 +1,86 @@
+
+
+
+
+
+
+
+ | 标签 |
+ 描述 |
+
+
+ {{!
+
+| {{= }} |
+
+
+转义输出。若字段存在 HTML，将进行转义。
+
+ |
+
+
+| {{- }} 2.8+ |
+
+
+原文输出。即不对 HTML 字符进行转义，但需做好 XSS 防护。
+
+ |
+
+
+| {{# }} 旧 |
+
+
+**旧版本风格**（`< 2.11`）「Scriptlet 标签」。一般用于流程控制，如：
+
+ ```js
+{{#if (d.title) { }}
+ 标题：{{= d.title }}
+{{#} else { }}
+ 默认标题
+{{#} }}
+ ```
+
+ |
+
+
+| {{ }} 新2.11+ |
+
+
+**新版本风格**「Scriptlet 标签」。一般用于流程控制，如：
+
+ ```js
+{{ if (d.title) { }}
+ 标题：{{= d.title }}
+{{ } else { }}
+ 默认标题
+{{ } }}
+ ```
+
+需设置 `tagStyle: 'modern'` 后生效，否则模板会报错。
+
+ |
+
+
+| {{# }} 新2.11+ |
+
+
+**新版本风格**「注释标签」。即仅在模板中显示，不在视图中输出。
+
+需设置 `tagStyle: 'modern'` 后生效，否则会被视为旧版本的 Scriptlet 标签。
+
+ |
+
!}}
+
+| {{!{{! !}}!}} |
+
+
+忽略标签。即该区域中的标签不会被解析，一般用于输出原始标签。如：
+
+```js
+{{! {{! 这里面的 {{= escape }} 等模板标签不会被解析 !}} !}}
+```
+
+ |
+
+
+
diff --git a/docs/laytpl/index.md b/docs/laytpl/index.md
index 4ade28ad..ea5808c2 100644
--- a/docs/laytpl/index.md
+++ b/docs/laytpl/index.md
@@ -5,11 +5,11 @@ toc: true
# 模板引擎
-> `laytpl` 是 Layui 的一款轻量 JavaScript 模板引擎，在字符解析上有着比较出色的表现。
+> `laytpl` 是 Layui 内置的 JavaScript 模板引擎，采用原生控制流，在模板解析上有着比较出色的表现。
在线测试
-在以下*模板*或*数据*中进行编辑，下方*视图*将呈现对应结果。
+对文本框中的*模板*或*数据*进行编辑，下方将呈现对应的*渲染结果*。注：自 2.11+ 版本开始，你可以设置 `tagStyle: 'modern'` 让模板采用新的标签风格。为了保持向下兼容，默认仍然采用旧版本的标签风格。
{{- d.include("/laytpl/detail/demo.md") }}
@@ -20,135 +20,256 @@ toc: true
| API | 描述 |
| --- | --- |
| var laytpl = layui.laytpl | 获得 `laytpl` 模块。 |
-| [laytpl(str, options).render(data, callback)](#render) | laytpl 组件渲染，核心方法。 |
-| [laytpl.config(options)](#config) | 配置 laytpl 全局属性 |
+| [var templateInst = laytpl(template, options)](#laytpl) | 创建模板实例。 |
+| [laytpl.config(options)](#config) | 设置基础选项默认值 |
+| [laytpl.extendVars(variables)](#variables)
2.11+ | 扩展模板内部变量 |
-
模板解析和渲染
+
创建模板实例
-`laytpl(str, options).render(data, callback);`
+`var templateInst = laytpl(template, options)`
-- 参数 `str` : 模板原始字符
-- 参数 `options`
2.8+ : 当前模板实例的属性选项。可选项详见：[#属性选项](#config)
-- 参数 `data` : 模板数据
-- 参数 `callback` : 模板渲染完毕的回调函数，并返回渲染后的字符
+- 参数 `template` : 原始模板字符
+- 参数 `options`
2.8+ : 当前模板实例的选项。详见下述：[#基础选项](#options)
+
+该方法返回一个模板编译器实例，用于对模板进行数据渲染等操作，实例对象的成员有：
+
+| 实例成员 | 描述 |
+| --- | --- |
+| templateInst.render(data, callback) | 给模板实例进行数据渲染，返回渲染后的 HTML 字符 |
+| templateInst.compile(template)
2.11+ | 编译新的模板，会强制清除旧模板缓存 |
+| templateInst.config
2.11+ | 获取当前模板实例的配置选项 |
+
+通过将模板编译与渲染两个环节分开，我们可以在模板仅编译一次的情况下，对其渲染不同的数据，如：
{{!
+```js
+var laytpl = layui.laytpl;
-```
-layui.use('laytpl', function(){
- var laytpl = layui.laytpl;
+// 创建模板实例
+var templateInst = laytpl('{{= d.name }}是一名{{= d.role }}');
- // 直接解析字符
- laytpl('{{= d.name }}是一名前端工程师').render({
- name: '张三'
- }, function(str){
- console.log(str); // 张三是一名前端工程师
- });
+// 数据渲染 1
+templateInst.render({
+ name: '张三',
+ role: '全栈开发者'
+}, function(html) {
+ console.log(html); // 张三是一名全栈开发者
+});
- // 同步写法
- var str = laytpl('{{= d.name }}是一名前端工程师').render({
- name: '张三'
- });
- console.log(str); // 张三是一名前端工程师
+// 数据渲染 2
+var html = templateInst.render({
+ name: '王五',
+ role: '架构师'
});
```
+!}}
-若模板字符较大，可存放在页面某个标签中，如：
+若每次需要对不同的模板进行编译和数据渲染，你也可以使用链式写法，如：
+{{!
+```js
+laytpl('{{= d.name }}是一名{{= d.role }}').render({
+ name: '张三',
+ role: '全栈开发者'
+}, function(html) {
+ console.log(html); // 张三是一名全栈开发者
+});
```
-
-
+
```
-
!}}
-在实际使用时，若模板通用，而数据不同，为减少模板解析的开销，可将语句分开书写，如。
+实际使用时，若模板通用，而数据不同，为了避免对模板进行不必要的重复编译，推荐将创建模板实例与数据渲染分开书写。
-```
-var compile = laytpl(str); // 模板解析
-compile.render(data, callback); // 模板渲染
-```
+
基础选项
-
标签语法
+创建模板实例时，你还可以对其设置一些选项，如：
+
+{{!
+```js
+// 创建模板实例
+var templateInst = laytpl(`
+ {{ let role = d.role || '全栈开发者'; }}
+ {{= d.name }}是一名{{= role }}
+`, {
+ tagStyle: 'modern' // 采用新版本的标签风格
+});
+var html = templateInst.render({ name: '张三' });
+```
+!}}
+
+支持设置的完整选项如下：
{{- d.include("/laytpl/detail/options.md") }}
-> ### 注意
-> 开发者在使用模板语法时，需确保模板中的 JS 语句不来自于页面用户输入，即必须在页面开发者自身的可控范围内，否则请避免使用该模板引擎。
+
-
选项配置
+
+{{- d.include("/laytpl/detail/tags.md") }}
+
+
+#### ⚡ 请注意：
+> *开发者在使用模板标签时，需确保模板中待输出的内容在开发者自身的可控范围内，尤其对于用户输入的字符要做好 XSS 防护，否则请避免使用该模板引擎，以免产生 XSS 安全隐患*。
+
+
导入子模板 2.11+
+
+{{!
+laytpl 支持在模板中通过添加 `{{- include(id, data) }}` 语句引入子模板。`include` 语句参数解释：
+
+- `id` : 子模板 ID
+- `data` : 向子模版传入的数据
+
+为了引入的子模板不被转义，因此这里应该使用 `{{- }}`，即对子模板进行原文输出。示例：
+
+
+
+
+
+!}}
+
+若在 Node.js 环境，可通过 `laytpl.extendVars()` 方法重置 `include` 语句实现模板文件的导入。
+
+
设置选项默认值
`laytpl.config(options);`
-- 参数 `options` : 属性选项。可选项详见下表
+- 参数 `options`: 基础选项
-| 属性 | 描述 |
-| --- | --- |
-| open | 标签符前缀 |
-| close | 标签符后缀 |
+你可以设置任意选项的默认值，如：
-### 全局配置
-
-若模板默认的标签符与其他模板存在冲突，可通过该方法重新设置标签符，如：
-
-```
+{{!
+```js
laytpl.config({
- open: '<%',
- close: '%>'
+ open: '<%', // 自定义起始界定符
+ close: '%>', // 自定义起始界定符
+ tagStyle: 'modern' // 采用新版本的标签风格
});
-// 模板语法将默认采用上述定义的标签符书写
-laytpl(`
- <%# var job = ["前端工程师"]; %>
- <%= d.name %>是一名<%= job[d.type] %>。
-`).render({
+// 创建模板实例
+var templateInst = laytpl(`
+ <% var roles = ["前端工程师","全栈工程师","架构师"]; %>
+ <%= d.name %>是一名<%= roles[d.role] %>
+`);
+// 渲染
+templateInst.render({
name: '张三',
- type: 0
+ role: 1
}, function(string){
- console.log(string); // 张三是一名前端工程师。
+ console.log(string); // 张三是一名全栈工程师
});
```
+!}}
-### 局部配置
2.8+
+
扩展模板内变量
-若不想受到上述全局配置的影响，可在 `laytpl(str, options)` 方法的第二个参数中设置当前模板的局部属性，如：
+`laytpl.extendVars(variables)`
-```
-laytpl('<%= d.name %>是一名前端工程师', {
- open: '<%',
- close: '%>'
-}).render({name: '张三'}, function(string){
- console.log(string); // 张三是一名前端工程师。
+- 参数 `variables` : 扩展的变量列表，变量值通常是一个函数
+
+事实上 laytpl 内置了一些模板内部方法，如 `_escape, include`。你可以对它们进行重构，或扩展更多内部变量，如：
+
+{{!
+```js
+// 扩展模板内部变量
+laytpl.extendVars({
+ // 重构 include 方法，实现引入模板文件
+ include: function(filename, data) {
+ // …
+ },
+ // 添加 toDataString 方法
+ toDataString: function(date) {
+ date = date || new Date();
+ return new Date(date).toLocaleDateString();
+ }
+});
+
+// 在模板中使用扩展的变量
+var templateInst = laytpl('日期：{{= toDataString(d.time) }}');
+templateInst.render({ time: 1742745600000 }, function(html) {
+ console.log(html);
});
```
+!}}
+## 💖 心语
-## 贴士
+我们在 `2.11` 版本对 laytpl 完成了重要重构，使其能够具备应对更多复杂模板结构的解析能力。同时，为了与业界常用的 JavaScript 模板引擎 ejs 对齐，我们新增了与 ejs 相同的标签规则，这意味着同一套模板可以在 laytpl 和 ejs 中任意切换。
-> Layui table 等组件的动态模板功能，均采用 laytpl 驱动。 laytpl 亦可承载单页面应用开发中的视图模板。
+作为 Layui 为数不多的一个纯功能型的模块，laytpl 承载了一些重要组件的功能支撑，如 table, dropdown 等，使得它们也能够自定义动态模板，增强了组件的可定制化。当然，laytpl 也可以作为前端单页面应用及 Express 等 Web 框架的视图引擎。
diff --git a/docs/modules.md b/docs/modules.md
index a03b3b62..8864c832 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -3,7 +3,7 @@ title: 模块系统
toc: true
---
-
模块系统
+
模块系统
> Layui 制定了一套适合自身应用场景的轻量级模块规范，以便在不同规模的项目中，也能对前端代码进行很好的管理或维护。 Layui 的轻量级模块系统，并非有意违背 CommonJS 和 ES Module ，而是试图以更简单的方式去诠释高效，这种对*返璞归真*的执念源于在主流标准尚未完全普及的前 ES5 时代，后来也成为 Layui 独特的表达方式，而沿用至今。
@@ -13,20 +13,20 @@ toc: true
// 定义模块（通常单独作为一个 JS 文件）
layui.define([mods], function(exports){
// …
-
+
exports('mod1', api); // 输出模块
-});
-
+});
+
// 使用模块
layui.use(['mod1'], function(args){
var mod1 = layui.mod1;
-
+
// …
});
```
我们可以将其视为「像使用普通 API 一样来管理模块」，在此前提下，组件的承载也变得轻松自如，我们完全可以游刃在以浏览器为宿主的原生态的 HTML/CSS/JavaScript 的开发模式中，而不必卷入层出不穷的主流框架的浪潮之中，给心灵一个栖息之所。
-
+
当然，Layui 自然也不是一个模块加载器，而是一套相对完整的 UI 解决方案，但与 Bootstrap 又并不相同，除了 HTML+CSS 本身的静态化处理，Layui 的组件更倾向于 JavaScript 的动态化渲染，并为之提供了相对丰富和统一的 API，使用时，只需稍加熟悉，便可在各种交互中应付自如。
@@ -41,42 +41,42 @@ layui.use(['mod1'], function(args){
/** demo.js **/
layui.define(function(exports){
// do something
-
+
// 输出 demo 模块
exports('demo', {
msg: 'Hello Demo'
});
});
-
+
// 若该模块需要依赖别的模块，则在 `mods` 参数中声明即可：
// layui.define(['layer', 'form'], callback);
```
如上所示，`callback` 返回的 `exports` 参数是一个函数，它接受两个参数：参数一为*模块名*，参数二为*模块接口*。
-
+
另外， `callback` 将会在初次加载该模块时被自动执行。而有时，在某些特殊场景中可能需要再次执行该 `callback`，那么可以通过 `layui.factory(mod)` 方法获得。如：
```
var demoCallback = layui.factory('demo'); // 得到定义 demo 模块时的 `callback`
-```
+```
- **模块命名空间**
Layui 定义的模块将会被绑定在 `layui` 对象下，如：`var demo = layui.demo;` 每个模块都有一个特定命名，且无法被占用，所以你无需担心模块的命名空间被污染，除非通过 `layui.disuse([mods])` 方法弃用已定义的模块。
-
+
以下是定义一个「依赖 Layui 内置模块」的模块示例：
```
layui.define(['layer', 'laydate'], function(exports){
var layer = layui.layer // 获得 layer 模块
var laydate = layui.laydate; // 获得 laydate 模块
-
+
// 输出模块
exports('demo', {}); // 模块名 demo 未被占用，此时模块定义成功
// exports('layer', {}); // 模块名 layer 已经存在，此时模块定义失败
-});
+});
```
-
+
同样的，在「扩展模块」时，也同样不能命名已经存在的模块名。
@@ -94,17 +94,17 @@ layui.define(['layer', 'laydate'], function(exports){
layui.use(['layer', 'table'], function(){
var layer = layui.layer;
var table = layui.table;
-
+
// do something
});
-
+
// 使用所有内置模块（layui v2.6 开始支持）
layui.use(function(){
var layer = layui.layer;
var table = layui.table;
var laydate = layui.laydate;
// …
-
+
// do something
});
```
@@ -115,7 +115,7 @@ layui.use(function(){
layui.use(['layer', 'table'], function(layer, table){
// 使用 layer
layer.msg('test');
-
+
// 使用 table
table.render({});
});
@@ -127,64 +127,97 @@ layui.use(['layer', 'table'], function(layer, table){
```
// 在单页面视图碎片渲染时，再次调用「定义模块」时的 `callback`
-layui.use('demo', layui.factory('demo'));
+layui.use('demo', layui.factory('demo'));
```
-
扩展模块
+
扩展模块
-`layui.extend(obj);`
+`layui.extend(settings);`
-- 参数 `obj` 是一个对象，必选，用于声明模块别名。
+- 参数 `settings` : 扩展模块的相关配置，如模块名、模块路径等。
-除了 Layui 的内置模块，在实际项目开发时，必不可少也需要扩展模块（可以简单理解为符合 layui 模块规范的 JS 文件）。 现在，让我们尝试着扩展一个 Layui 第三方模块：
+除了 Layui 的内置模块，在实际项目开发时，必不可少也需要扩展模块。我们在前文的「模块命名空间」提到，模块名具有唯一性，即不可被占用，因此我们扩展的模块必须是一个未被定义过的模块名。
-1. **创建模块**
+现在，让我们尝试扩展一个 Layui 第三方模块。
-我们在前文的「模块命名空间」提到，模块名具有唯一性，即不可被占用，因此我们扩展的模块必须是一个未被定义过的模块名。假设为：`firstMod`，然后新建一个 `firstMod.js` 文件并放入项目的任意目录中（最好不要放入到 Layui 原始目录）
+### 扩展遵循 Layui 规范的模块
-2. **编写模块**
+1. **创建模块和定义模块**
-接下来我们开始定义 `firstMod` 模块，并编写该模块主体代码。
+假设创建一个模块名为 `testModule` 的模块，新建 `testModule.js` 文件并放入项目的任意目录中（但应避免放入到 Layui 原始目录）。接着我们开始定义 `testModule` 模块，并编写该模块主体代码。
-```
+```js
/**
- * 编写一个 firstMod 模块
+ * 定义 testModule 模块
**/
layui.define(function(exports){ // 也可以依赖其他模块
var obj = {
hello: function(str){
- alert('Hello '+ (str || 'firstMod'));
+ alert('Hello '+ (str || 'TestModule'));
}
};
-
- // 输出 firstMod 接口
- exports('firstMod', obj);
+
+ // 输出 testModule 接口
+ exports('testModule', obj);
});
```
-3. **声明模块**
+2. **声明模块和使用模块**
现在，我们只需声明模块名及模块文件路径，即完成模块扩展。
-```
-// 假设 firstMod 模块文件所在路径在： /js/layui_exts/firstMod.js
+```js
+// 假设 testModule 模块文件所在路径在：/js/layui_exts/testModule.js
layui.config({
- base: '/js/layui_exts/' // 配置 Layui 第三方扩展模块存放的基础目录
+ base: '/js/layui_exts/' // 设置用于扩展模块的基础路径
}).extend({
- firstMod: 'firstMod', // 定义模块名和模块文件路径，继承 layui.config 的 base 路径
- // mod2: 'mod2' // 可同时声明其他更多模块
+ testModule: 'testModule', // 定义模块名和模块路径，会前置追加 base 基础路径
+ // test1: 'test1' // 还可同时声明其他更多模块
});
-
-// 也可以不继承 layui.config 的 base 路径，即单独指定路径
+
+// 也可以不前置追加 base 基础路径，即设置单独路径
layui.extend({
- firstMod: '{/}/js/layui_exts/firstMod' // 开头特定符 {/} 即代表采用单独路径
+ testModule: '{/}/js/layui_exts/testModule' // 开头特定符 {/} 即代表采用单独路径
});
-
+
// 然后我们就可以像使用内置模块一样使用扩展模块
-layui.use(['firstMod'], function(){
- var firstMod = layui.firstMod;
-
- firstMod.hello('World');
+layui.use(['testModule', 'test1'], function(){
+ var testModule = layui.testModule;
+ // var test1 = layui.test1;
+
+ testModule.hello('World');
+});
+```
+
+
扩展任意外部模块 2.11+
+
+我们在 `2.11.0` 版本新增了无缝扩展任意外部模块的支持，即无需遵循 Layui 模块规范的第三方库也能通过 Layui 去加载，并且无需对外部模块做任何的代码改动，只需在 `layui.extend()` 方法中声明模块名、路径和接口即可。
+
+当声明的模块接受的是一个 `object` 类型时，即意味着声明任意外部模块。声明外部模块的对象由以下选项组成：
+
+- `src` : 模块路径，可以是项目的相对路径，也可以是任意外部模块的公共 CDN 地址；
+- `api` : 接口名称，通常是模块提供的全局对象
+
+下面是一个扩展任意外部模块的示例：
+
+```js
+// 扩展任意外部模块
+layui.extend({
+ marked: {
+ src: 'https://cdnjs.cloudflare.com/ajax/libs/marked/15.0.7/marked.min.js', // 模块路径
+ api: 'marked' // 接口名称
+ },
+ Prism: {
+ src: 'https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js',
+ api: 'Prism'
+ }
+});
+
+// 加载扩展模块
+layui.use(['marked', 'Prism'], function() {
+ console.log('任意外部模块 loaded: ')
+ console.log(' > marked: ', layui.marked);
+ console.log(' > Prism: ', layui.Prism);
});
```
@@ -196,7 +229,7 @@ layui.use(['firstMod'], function(){
在不同的页面中，可能需要用到不同的业务模块。以首页为例：
```
-
+
+
-
-
+ // 加载外部样式
+ layui.link('https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css', function(link) {
+ console.log('prism.min.css loaded');
+ }, 'prism');
+
+