mirror of https://github.com/layui/layui
276 lines
8.3 KiB
Markdown
276 lines
8.3 KiB
Markdown
---
|
||
title: 模板引擎 laytpl
|
||
toc: true
|
||
---
|
||
|
||
# 模板引擎
|
||
|
||
> `laytpl` 是 Layui 内置的 JavaScript 模板引擎，采用原生控制流，在模板解析上有着比较出色的表现。
|
||
|
||
<h2 id="test" lay-toc="{hot: true}" style="margin-bottom: 0;">在线测试</h2>
|
||
|
||
对文本框中的*模板*或*数据*进行编辑，下方将呈现对应的*渲染结果*。注：自 <sup>2.11+</sup> 版本开始，你可以设置 `tagStyle: 'modern'` 让模板采用新的标签风格。为了保持向下兼容，默认仍然采用旧版本的标签风格。
|
||
|
||
<div>
|
||
{{- d.include("/laytpl/detail/demo.md") }}
|
||
</div>
|
||
|
||
<h2 id="api" lay-toc="{}">API</h2>
|
||
|
||
| API | 描述 |
|
||
| --- | --- |
|
||
| var laytpl = layui.laytpl | 获得 `laytpl` 模块。 |
|
||
| [var templateInst = laytpl(template, options)](#laytpl) | 创建模板实例。 |
|
||
| [laytpl.config(options)](#config) | 设置基础选项默认值 |
|
||
| [laytpl.extendVars(variables)](#variables) <sup>2.11+</sup> | 扩展模板内部变量 |
|
||
|
||
<h3 id="laytpl" lay-toc="{level: 2, hot: true}">创建模板实例</h3>
|
||
|
||
`var templateInst = laytpl(template, options)`
|
||
|
||
- 参数 `template` : 原始模板字符
|
||
- 参数 `options` <sup>2.8+</sup> : 当前模板实例的选项。详见下述：[#基础选项](#options)
|
||
|
||
该方法返回一个模板编译器实例，用于对模板进行数据渲染等操作，实例对象的成员有：
|
||
|
||
| 实例成员 | 描述 |
|
||
| --- | --- |
|
||
| templateInst.render(data, callback) | 给模板实例进行数据渲染，返回渲染后的 HTML 字符 |
|
||
| templateInst.compile(template) <sup>2.11+</sup> | 编译新的模板，会强制清除旧模板缓存 |
|
||
| templateInst.config <sup>2.11+</sup> | 获取当前模板实例的配置选项 |
|
||
|
||
通过将模板编译与渲染两个环节分开，我们可以在模板仅编译一次的情况下，对其渲染不同的数据，如：
|
||
|
||
{{!
|
||
```js
|
||
var laytpl = layui.laytpl;
|
||
|
||
// 创建模板实例
|
||
var templateInst = laytpl('{{= d.name }}是一名{{= d.role }}');
|
||
|
||
// 数据渲染 1
|
||
templateInst.render({
|
||
name: '张三',
|
||
role: '全栈开发者'
|
||
}, function(html) {
|
||
console.log(html); // 张三是一名全栈开发者
|
||
});
|
||
|
||
// 数据渲染 2
|
||
var html = templateInst.render({
|
||
name: '王五',
|
||
role: '架构师'
|
||
});
|
||
```
|
||
!}}
|
||
|
||
若每次需要对不同的模板进行编译和数据渲染，你也可以使用链式写法，如：
|
||
|
||
{{!
|
||
```js
|
||
laytpl('{{= d.name }}是一名{{= d.role }}').render({
|
||
name: '张三',
|
||
role: '全栈开发者'
|
||
}, function(html) {
|
||
console.log(html); // 张三是一名全栈开发者
|
||
});
|
||
```
|
||
!}}
|
||
|
||
若模板字符较大，你可以将模板存放在页面某个标签中，如：
|
||
|
||
{{!
|
||
```js
|
||
<script id="ID-demo-tpl" type="text/html">
|
||
<h3>{{= d.name }}</h3>
|
||
<p>角色：{{= d.role }}</p>
|
||
</script>
|
||
|
||
<div id="ID-demo-view"></div>
|
||
|
||
<!-- import layui -->
|
||
<script>
|
||
layui.use(function(){
|
||
var laytpl = layui.laytpl;
|
||
|
||
var template = document.getElementById('ID-demo-tpl').innerHTML; // 获取模板字符
|
||
var target = document.getElementById('ID-demo-view'); // 输出结果的目标元素
|
||
var data = { // 数据
|
||
"name": "张三",
|
||
"role": "全栈开发者"
|
||
};
|
||
// 渲染并输出结果
|
||
laytpl(template).render(data, function(html) {
|
||
target.innerHTML = html;
|
||
});
|
||
});
|
||
</script>
|
||
```
|
||
!}}
|
||
|
||
实际使用时，若模板通用，而数据不同，为了避免对模板进行不必要的重复编译，推荐将创建模板实例与数据渲染分开书写。
|
||
|
||
<h3 id="options" lay-toc="{level: 2, hot: true}">基础选项</h3>
|
||
|
||
创建模板实例时，你还可以对其设置一些选项，如：
|
||
|
||
{{!
|
||
```js
|
||
// 创建模板实例
|
||
var templateInst = laytpl(`
|
||
{{ let role = d.role || '全栈开发者'; }}
|
||
{{= d.name }}是一名{{= role }}
|
||
`, {
|
||
tagStyle: 'modern' // 采用新版本的标签风格
|
||
});
|
||
var html = templateInst.render({ name: '张三' });
|
||
```
|
||
!}}
|
||
|
||
支持设置的完整选项如下：
|
||
|
||
<div>
|
||
{{- d.include("/laytpl/detail/options.md") }}
|
||
</div>
|
||
|
||
<h3 id="tags" lay-toc="{level: 2, hot: true}">标签规则</h3>
|
||
|
||
<div>
|
||
{{- d.include("/laytpl/detail/tags.md") }}
|
||
</div>
|
||
|
||
#### ⚡ 请注意：
|
||
> *开发者在使用模板标签时，需确保模板中待输出的内容在开发者自身的可控范围内，尤其对于用户输入的字符要做好 XSS 防护，否则请避免使用该模板引擎，以免产生 XSS 安全隐患*。
|
||
|
||
<h3 id="include" lay-toc="{level: 2, hot: true}">导入子模板 <sup>2.11+</sup></h3>
|
||
|
||
{{!
|
||
laytpl 支持在模板中通过添加 `{{- include(id, data) }}` 语句引入子模板。`include` 语句参数解释：
|
||
|
||
- `id` : 子模板 ID
|
||
- `data` : 向子模版传入的数据
|
||
|
||
为了引入的子模板不被转义，因此这里应该使用 `{{- }}`，即对子模板进行原文输出。示例：
|
||
|
||
<pre class="layui-code" lay-options="{preview: true, layout: ['code', 'preview'], codeStyle: 'max-height: 520px;', tools: ['full']}">
|
||
<textarea>
|
||
<script id="ID-demo-tpl-header" type="text/html">
|
||
<div>头部公共模板</div>
|
||
</script>
|
||
<script id="ID-demo-tpl-list" type="text/html">
|
||
<ul>
|
||
{{ d.items.forEach(function(item, index) { }}
|
||
<li>
|
||
<span>{{= item.title }}</span>
|
||
{{ if(item.children) { }}
|
||
{{- include('ID-demo-tpl-list', { items: item.children }) }}
|
||
{{ } }}
|
||
</li>
|
||
{{ }); }}
|
||
</ul>
|
||
</script>
|
||
<script id="ID-demo-tpl-main" type="text/html">
|
||
{{- include('ID-demo-tpl-header') }}
|
||
<h3>循环输出：</h3>
|
||
{{- include('ID-demo-tpl-list', { items: d.items }) }}
|
||
</script>
|
||
<div id="ID-demo-view"></div>
|
||
|
||
<!-- import layui -->
|
||
<script>
|
||
layui.use(function() {
|
||
var laytpl = layui.laytpl;
|
||
|
||
var template = document.getElementById('ID-demo-tpl-main').innerHTML; // 获取模板字符
|
||
var target = document.getElementById('ID-demo-view'); // 输出结果的目标元素
|
||
var data = {
|
||
items: [{"title": "list 1", "children": [{"title": "list 1-1", "children": [{"title": "list 1-1-1"}]}, {"title": "list 1-2"}]},{"title": "list 2", "children": [{"title": "list 2-1"}]},{"title": "list 3"}]
|
||
};
|
||
|
||
// 创建模板实例
|
||
var templateInst = laytpl(template, {
|
||
tagStyle: 'modern' // 采用新版本的标签风格
|
||
});
|
||
|
||
// 渲染并输出结果
|
||
templateInst.render(data, function(html) {
|
||
target.innerHTML = html;
|
||
});
|
||
});
|
||
</script>
|
||
</textarea>
|
||
</pre>
|
||
|
||
!}}
|
||
|
||
若在 Node.js 环境，可通过 `laytpl.extendVars()` 方法重置 `include` 语句实现模板文件的导入。
|
||
|
||
<h3 id="config" lay-toc="{level: 2}">设置选项默认值</h3>
|
||
|
||
`laytpl.config(options);`
|
||
|
||
- 参数 `options`: 基础选项
|
||
|
||
你可以设置任意选项的默认值，如：
|
||
|
||
{{!
|
||
```js
|
||
laytpl.config({
|
||
open: '<%', // 自定义起始界定符
|
||
close: '%>', // 自定义起始界定符
|
||
tagStyle: 'modern' // 采用新版本的标签风格
|
||
});
|
||
|
||
// 创建模板实例
|
||
var templateInst = laytpl(`
|
||
<% var roles = ["前端工程师","全栈工程师","架构师"]; %>
|
||
<%= d.name %>是一名<%= roles[d.role] %>
|
||
`);
|
||
// 渲染
|
||
templateInst.render({
|
||
name: '张三',
|
||
role: 1
|
||
}, function(string){
|
||
console.log(string); // 张三是一名全栈工程师
|
||
});
|
||
```
|
||
!}}
|
||
|
||
<h3 id="variables" lay-toc="{level: 2}">扩展模板内变量</h3>
|
||
|
||
`laytpl.extendVars(variables)`
|
||
|
||
- 参数 `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 为数不多的一个纯功能型的模块，laytpl 承载了一些重要组件的功能支撑，如 table, dropdown 等，使得它们也能够自定义动态模板，增强了组件的可定制化。当然，laytpl 也可以作为前端单页面应用及 Express 等 Web 框架的视图引擎。
|
||
|