模板引擎

laytpl 是 Layui 内置的 JavaScript 模板引擎，采用原生控制流，在模板解析上有着比较出色的表现。

在线测试

对文本框中的模板或数据进行编辑，下方将呈现对应的渲染结果。注：自 ^2.11+ 版本开始，你可以设置 tagStyle: 'modern' 让模板采用新的标签风格。为了保持向下兼容，默认仍然采用旧版本的标签风格。

  
<style>
  .laytpl-demo{border: 1px solid #eee;}
  .laytpl-demo:first-child{border-right: none;}
  .laytpl-demo>textarea{position: relative; display: block; width:100%; height: 320px; padding: 11px; border: 0; box-sizing: border-box; resize: none; background-color: #fff; font-family: Courier New; font-size: 13px;}
  .laytpl-demo>div:first-child{height: 32px; line-height: 32px; padding: 6px 11px; border-bottom: 1px solid #eee; background-color: #F8F9FA;}
  .laytpl-demo .layui-tabs{top: -1px;}
  #ID-tpl-view-body {
    max-height: 320px; overflow: auto; clear: both;
  }
  #ID-tpl-view-body > div {
    display: none;
  }
  .laytpl-demo pre {
    margin: 0; padding: 16px; background-color: #1F1F1F; color: #F8F9FA; font-family: 'Courier New',Consolas, monospace;
  }
</style>
<div class="layui-row">
  <div class="layui-col-xs6 laytpl-demo">
    <div>
      <div style="cursor: pointer;" id="ID-tpl-src-title">
        <strong>模板（旧版本）</strong>
        <i class="layui-icon layui-icon-down layui-font-12"></i>
      </div>
    </div>
    <textarea id="ID-tpl-src"></textarea>
  </div>
  <div class="layui-col-xs6 laytpl-demo">
    <div><strong>数据</strong></div>
    <textarea id="ID-tpl-data">
{
  "title": "Layui 常用组件",
  "desc": "<a style=\"color:blue;\">一段带 HTML 的内容</a>",
  "list": [
    {
      "title": "弹层",
      "name": "layer"
    },
    {
      "title": "表单",
      "name": "form"
    },
    {
      "title": "表格",
      "name": "table"
    },
    {
      "title": "日期选择器",
      "name": "laydate"
    },
    {
      "title": "标签页",
      "name": "tabs"
    }
  ]
}
    </textarea>
  </div>
  <div class="layui-col-xs12 laytpl-demo" style="border-top: none;">
    <div class="layui-row">
      <div class="layui-col-xs6 layui-tabs" id="ID-tpl-view-header">
        <ul class="layui-tabs-header">
          <li><strong>渲染结果</strong></li>
          <li><strong>源码</strong></li>
        </ul>
      </div>
      <div class="layui-col-xs6" style="text-align: right">
        <span class="layui-badge" id="ID-tpl-view-time"></span>
      </div>
    </div>
    <div id="ID-tpl-view-body">
      <div class="layui-show layui-padding-3 layui-text" id="ID-tpl-view"></div>
      <div><pre id="ID-tpl-view-code"  ></pre></div>
    </div>
  </div>
</div>
<div class="layui-clear"></div>
<!-- 新版本模板 -->
<script type="text/html" id="ID-tpl-template-modern">
<p>转义输出：{{= d.desc }}</p>
<p>原文输出：{{- d.desc }}</p>
{{# 注释标签 - 仅在模板中显示，不在视图中输出 }}
<p>{{! 忽略标签，可显示原始标签：
{{ let a = 0; }} {{= escape }} {{- source }} {{# comments }} {{! ignore !}}
!}}</p>
{{# 标签空主体测试 }}
{{}} {{  }} {{   }} {{= }} {{=}} {{= }}
<p>
  条件语句：
  {{= d.list.length ? d.title : '' }}
  {{ if(d.title){}} - #AAAA{{='A'}}{{ } }}
</p>
<p>循环语句：</p>
<ul>
{{ d.list.forEach(function(item) { }}
  <li>
    <span>{{= item.title }}</span>
    <span>{{= item.name }}</span>
  </li>
{{ }); }}
</ul>
{{ if (d.list.length === 0) { }}
  无数据
{{} }}
</script>
<!-- 旧版本模板 -->
<script type="text/html" id="ID-tpl-template-legacy">
<p>转义输出：{{= d.desc }}</p>
<p>原文输出：{{- d.desc }}</p>
<p>
  条件语句：
  {{= d.list.length ? d.title : '' }}
  {{# if(d.title){}} - #AAAA{{='A'}}{{# } }}
</p>
<p>循环语句：</p>
<ul>
{{# d.list.forEach(function(item) { }}
  <li>
    <span>{{= item.title }}</span>
    <span>{{= item.name }}</span>
  </li>
{{# }); }}
</ul>
{{# if (d.list.length === 0) { }}
  无数据
{{# } }}
</script>
<!-- import layui -->
<script>
layui.use(['laytpl', 'util', 'tabs', 'dropdown'], function() {
  var laytpl = layui.laytpl;
  var util = layui.util;
  var tabs = layui.tabs;
  var dropdown = layui.dropdown;
  var $ = layui.$;
  // 默认设置
  laytpl.config({
    // tagStyle: 'modern' // 初始化标签风格
  });
  // 获取模板和数据
  var getData = function(type) {
    return {
      template: $('#ID-tpl-src').val(), // 获取模板
      data: function(){  // 获取数据
        try {
          return JSON.parse($('#ID-tpl-data').val());
        } catch(e) {
          $('#ID-tpl-view').html(e);
        }
      }()
    };
  };
  // 视图渲染
  var renderView = function(html, startTime) {
    timer(startTime);
    $('#ID-tpl-view').html(html);
    $('#ID-tpl-view-code').html(util.escape(html));
  };
  // 生成模板
  var createTemplate = function(opts) {
    opts = $.extend({
      tagStyle: 'legacy'
    }, opts);
    // 初始化模板
    var elem = $('#ID-tpl-template-'+ opts.tagStyle);
    $('#ID-tpl-src').val(elem.html().replace(/^\s+/g, ''));
    return opts;
  };
  var tplConfig = createTemplate();
  var data = getData();
  // 耗时计算
  var timer = function(startTime, title) {
    var endTime = new Date();
    $('#ID-tpl-view-time').html((title || '本次渲染总耗时：')+ (endTime - startTime) + 'ms');
  };
  var startTime = new Date();
  // 创建一个模板实例
  var templateInst = laytpl(data.template, {
    condense: false, // 不处理连续空白符，即保留模板原始结构
    tagStyle: tplConfig.tagStyle
  });
  // 初始渲染
  templateInst.render(data.data, function(html) {
    renderView(html, startTime);
  });
  // 编辑
  $('.laytpl-demo textarea').on('input', function() {
    var data = getData();
    var startTime = new Date();
    // 若模板有变化，则重新编译模板
    if (this.id === 'ID-tpl-src') {
      templateInst.compile(data.template);
    }
    // 若模板没变，数据有变化，则从模板缓存中直接渲染数据（效率大增）
    templateInst.render(data.data, function(html) {
      renderView(html, startTime);
    });
  });
  // 视图结果 tabs
  tabs.render({
    elem: '#ID-tpl-view-header',
    body: ['#ID-tpl-view-body', '>div']
  });
  // 切换模板
  dropdown.render({
    elem: '#ID-tpl-src-title',
    data: [{
      title: '新版本模板',
      tagStyle: 'modern'
    }, {
      title: '旧版本模板',
      tagStyle: 'legacy'
    }],
    click: function(obj){
      createTemplate({
        tagStyle: obj.tagStyle
      });
      this.elem.children('strong').html(obj.title);
      // 同步设置标签风格
      templateInst.config.tagStyle = obj.tagStyle;
      var data = getData();
      var startTime = new Date();
      // 重新渲染
      templateInst.compile(data.template).render(data.data, function(html) {
        renderView(html, startTime);
      });
    }
  })
});
</script>

API

API	描述
var laytpl = layui.laytpl	获得 `laytpl` 模块。
var templateInst = laytpl(template, options)	创建模板实例。
laytpl.config(options)	设置基础选项默认值
laytpl.extendVars(variables) ^2.11+	扩展模板内部变量

创建模板实例

var templateInst = laytpl(template, options)

参数 template : 原始模板字符
参数 options ^2.8+ : 当前模板实例的选项。详见下述：#基础选项

该方法返回一个模板编译器实例，用于对模板进行数据渲染等操作，实例对象的成员有：

实例成员	描述
templateInst.render(data, callback)	给模板实例进行数据渲染，返回渲染后的 HTML 字符
templateInst.compile(template) ^2.11+	编译新的模板，会强制清除旧模板缓存
templateInst.config ^2.11+	获取当前模板实例的配置选项

通过将模板编译与渲染两个环节分开，我们可以在模板仅编译一次的情况下，对其渲染不同的数据，如：

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: '架构师'
});

若每次需要对不同的模板进行编译和数据渲染，你也可以使用链式写法，如：

laytpl('{{= d.name }}是一名{{= d.role }}').render({
  name: '张三',
  role: '全栈开发者'
}, function(html) {
  console.log(html); // 张三是一名全栈开发者
});

若模板字符较大，你可以将模板存放在页面某个标签中，如：

<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>

实际使用时，若模板通用，而数据不同，为了避免对模板进行不必要的重复编译，推荐将创建模板实例与数据渲染分开书写。

基础选项

创建模板实例时，你还可以对其设置一些选项，如：

// 创建模板实例
var templateInst = laytpl(`
  {{ let role = d.role || '全栈开发者'; }}
  {{= d.name }}是一名{{= role }}
`, {
  tagStyle: 'modern' // 采用新版本的标签风格
});
var html = templateInst.render({ name: '张三' });

支持设置的完整选项如下：

标签	描述	类型	默认值
open	用于设置起始界定符	string	`{{`
close	用于设置结束界定符	string	`}}`
cache ^2.11+	是否开启模板缓存，以便下次渲染时不重新编译模板	boolean	`true`
condense ^2.11+	是否压缩模板空白符，如：将多个连续的空白符压缩为单个空格	boolean	`true`
tagStyle ^2.11+	设置标签风格。可选值： `legacy`: 采用 `< 2.11` 旧版本的标签风格 `modern`: 采用 `2.11+` 新版本的标签风格为了保持向下兼容，默认仍然采用旧版本的标签风格，但在后续版本可能会将默认值设置为 `modern`，因此，实际使用时，建议显式设置该选项值，以免升级时产生不兼容的问题。	string	`legacy`

标签规则

标签	描述
{{= }}	转义输出。若字段存在 HTML，将进行转义。
{{- }} ^2.8+	原文输出。即不对 HTML 字符进行转义，但需做好 XSS 防护。
{{# }} ^旧	旧版本风格（`< 2.11`）「Scriptlet 标签」。一般用于流程控制，如： `{{# if (d.title) { }} 标题：{{= d.title }} {{# } else { }} 默认标题 {{# } }}`
{{ }} ^新^2.11+	新版本风格「Scriptlet 标签」。一般用于流程控制，如： `{{ if (d.title) { }} 标题：{{= d.title }} {{ } else { }} 默认标题 {{ } }}` 需设置 `tagStyle: 'modern'` 后生效，否则模板会报错。
{{# }} ^新^2.11+	新版本风格「注释标签」。即仅在模板中显示，不在视图中输出。需设置 `tagStyle: 'modern'` 后生效，否则会被视为旧版本的 Scriptlet 标签。
{{! !}}	忽略标签。即该区域中的标签不会被解析，一般用于输出原始标签。如： `{{! 这里面的 {{= escape }} 等模板标签不会被解析 !}}`

⚡ 请注意：

开发者在使用模板标签时，需确保模板中待输出的内容在开发者自身的可控范围内，尤其对于用户输入的字符要做好 XSS 防护，否则请避免使用该模板引擎，以免产生 XSS 安全隐患。

导入子模板 ^2.11+

laytpl 支持在模板中通过添加 {{- include(id, data) }} 语句引入子模板。include 语句参数解释：

id : 子模板 ID
data : 向子模版传入的数据

为了引入的子模板不被转义，因此这里应该使用 {{- }}，即对子模板进行原文输出。示例：

  <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>

若在 Node.js 环境，可通过 laytpl.extendVars() 方法重置 include 语句实现模板文件的导入。

设置选项默认值

laytpl.config(options);

参数 options: 基础选项

你可以设置任意选项的默认值，如：

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); // 张三是一名全栈工程师
});

扩展模板内变量

laytpl.extendVars(variables)

参数 variables : 扩展的变量列表，变量值通常是一个函数

事实上 laytpl 内置了一些模板内部方法，如 _escape, include。你可以对它们进行重构，或扩展更多内部变量，如：

// 扩展模板内部变量
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 框架的视图引擎。