EJS logo

<%= EJS %>

高效的嵌入式 JavaScript 模板引擎。

EJS 是什么?

“E” 代表什么?可以表示 “可嵌入(Embedded)”,也可以是“高效(Effective)”、“优雅(Elegant)”或者是“简单(Easy)”。EJS 是一套简单的模板语言,帮你利用普通的 JavaScript 代码生成 HTML 页面。EJS 没有如何组织内容的教条;也没有再造一套迭代和控制流语法;有的只是普通的 JavaScript 代码而已。

纯 JavaScript

我们热爱 JavaScript,他是一门友好的编程语言。所有模板语言都要成长为图灵完备的语言,也就是说要增加一个中间层。何必呢,直接用 JS 吧!

快速开发

无需浪费时间钻研那些所谓“优雅”的神秘语法,也不用研究数据究竟如何能够被正确处理。

语法简单

EJS 支持直接在标签内书写简单、直白的 JavaScript 代码。只需让 JavaScript 输出你所需要的 HTML ,完成工作很轻松!

执行迅速

我们都知道 V8 以及类似 JavaScript 引擎的速度有多快。EJS 能够缓存 JS 函数的中间代码,从而提升执行速度。

易于调试

调试 EJS 错误(error)很容易:所有错误都是普通的 JavaScript 异常,并且还能输出异常发生的位置。

社区活跃

EJS 背后是一个活跃用户组成的大规模社区,能够为 EJS 的演进提供大力支持。我们同时很高兴回答你的问题或提供帮助。

特性

入门

安装

利用 NPM 安装 EJS 很简单。

$ npm install ejs

用法

将模板字符串和一些数据作为参数传递给 EJS,Duang,HTML 出来了。

let ejs = require('ejs'),
    people = ['geddy', 'neil', 'alex'],
    html = ejs.render('<%= people.join(", "); %>', {people: people});

浏览器支持

从这里下载 最新的浏览器版本,然后引入页面即可。

<script src="ejs.js"></script>
<script>
  let people = ['geddy', 'neil', 'alex'],
      html = ejs.render('<%= people.join(", "); %>', {people: people});
</script>

文档

实例

<% if (user) { %>
  <h2><%= user.name %></h2>
<% } %>

用法

let template = ejs.compile(str, options);
template(data);
// => 输出渲染后的 HTML 字符串

ejs.render(str, data, options);
// => 输出渲染后的 HTML 字符串

ejs.renderFile(filename, data, options, function(err, str){
    // str => 输出渲染后的 HTML 字符串
});

参数

  • cache 缓存编译后的函数,需要指定 filename
  • filenamecache 参数用做键值,同时也用于 include 语句
  • context 函数执行时的上下文环境
  • compileDebug 当值为 false 时不编译调试语句
  • client 返回独立的编译后的函数
  • delimiter 放在角括号中的字符,用于标记标签的开与闭
  • debug 将生成的函数体输出
  • _with 是否使用 with() {} 结构。如果值为 false,所有局部数据将存储在 locals 对象上。
  • localsName 如果不使用 with ,localsName 将作为存储局部变量的对象的名称。默认名称是 locals
  • rmWhitespace 删除所有可安全删除的空白字符,包括开始与结尾处的空格。对于所有标签来说,它提供了一个更安全版本的 -%> 标签(在一行的中间并不会剔除标签后面的换行符)。
  • escape<%= 结构设置对应的转义(escape)函数。它被用于输出结果以及在生成的客户端函数中通过 .toString() 输出。(默认转义 XML)。
  • outputFunctionName 设置为代表函数名的字符串(例如 'echo''print')时,将输出脚本标签之间应该输出的内容。
  • async 当值为 true 时,EJS 将使用异步函数进行渲染。(依赖于 JS 运行环境对 async/await 是否支持)

标签含义

  • <% '脚本' 标签,用于流程控制,无输出。
  • <%_ 删除其前面的空格符
  • <%= 输出数据到模板(输出是转义 HTML 标签)
  • <%- 输出非转义的数据到模板
  • <%# 注释标签,不执行、不输出内容
  • <%% 输出字符串 '<%'
  • %> 一般结束标签
  • -%> 删除紧随其后的换行符
  • _%> 将结束标签后面的空格符删除

包含(include)

通过 include 指令将相对于模板路径中的模板片段包含进来。(需要提供 'filename' 参数。) 例如,如果存在 "./views/users.ejs" 和 "./views/user/show.ejs" 两个模板文件,你可以通过 <%- include('user/show'); %> 代码包含后者。

你可能需要能够输出原始内容的标签 (<%-) 用于 include 指令,避免对输出的 HTML 代码做转义处理。

<ul>
  <% users.forEach(function(user){ %>
    <%- include('user/show', {user: user}); %>
  <% }); %>
</ul>

自定义分隔符

可针对单个模板或全局使用自定义分隔符:

let ejs = require('ejs'),
    users = ['geddy', 'neil', 'alex'];

// 单个模板文件
ejs.render('<?= users.join(" | "); ?>', {users: users},
    {delimiter: '?'});
// => 'geddy | neil | alex'

// 全局
ejs.delimiter = '$';
ejs.render('<$= users.join(" | "); $>', {users: users});
// => 'geddy | neil | alex'

缓存

EJS 附带了一个基本的进程内缓存,用于缓在渲染模板过程中所生成的临时 JavaScript 函数。 通过 Node 的 `lru-cache` 库可以很容易地加入 LRU 缓存:

let ejs = require('ejs'),
    LRU = require('lru-cache');
ejs.cache = LRU(100); // 具有 100 条内容限制的 LRU 缓存

如果要清除 EJS 缓存,调用 ejs.clearCache 即可。如果你正在使用的是 LRU 缓存并且需要设置不同的限额,则只需要将 `ejs.cache` 重置为 一个新的 LRU 实例即可。

自定义文件加载器

默认的文件加载器是 fs.readFileSync,如果你想要的自定义它, 设置ejs.fileLoader 即可。

let ejs = require('ejs');
let myFileLoader = function (filePath) {
  return 'myFileLoader: ' + fs.readFileSync(filePath);
};

ejs.fileLoader = myFileLoad;

使用此功能,您可以在读取模板之前对其进行预处理。

布局(Layouts)

EJS 并未对块(blocks)提供专门的支持,但是可以通过 包含页眉和页脚来实现布局,如下所示:

<%- include('header'); -%>
<h1>
  Title
</h1>
<p>
  My page
</p>
<%- include('footer'); -%>

客户端支持

latest release 链接下载 ./ejs.js./ejs.min.js 文件。或者,你可以 clone 这个仓库并 通过执行 jake build 自己编译(或者执行 $(npm bin)/jake build,如果 jake 不是安装在全局环境的话)。

在页面中包含上面的任意一个文件,然后 ejs 就全局可用了

示例

<div id="output"></div>
<script src="ejs.min.js"></script>
<script>
  let people = ['geddy', 'neil', 'alex'],
      html = ejs.render('<%= people.join(", "); %>', {people: people});
  // With jQuery:
  $('#output').html(html);
  // Vanilla JS:
  document.getElementById('output').innerHTML = html;
</script>

注意事项

大多数情况下,EJS 将会按照我们的预期运行; 但是, 仍然需要注意:

  1. 显然, 如果你没有文件系统的访问权限, `ejs.renderFile` 将无法正常工作。
  2. 相同的原因, 除非为 include 设置一个回调函数,否则 include 无法正常工作。如下所示:
let str = "Hello <%= include('file', {person: 'John'}); %>",
      fn = ejs.compile(str, {client: true});

fn(data, null, function(path, d){ // include callback
  // path -> 'file'
  // d -> {person: 'John'}
  // Put your code here
  // Return the contents of file as a string
}); // returns rendered string

在 Express 中使用 EJS

此 GitHub Wiki 页面 介绍了几种向 Express 传递 EJS 参数的方式。

支持

Stack Overflow

Ask questions about specific problems you have faced, including details about what exactly you are trying to do. Make sure you tag your question with ejs. You can also read through existing ejs questions.

GitHub issues

The issue tracker is the preferred channel for bug reports, features requests and submitting pull requests.

许可证

EJS is licensed under the Apache License, version 2.0. Information can found here: http://www.apache.org/licenses/.