Mozilla/Nunjucks 模板引擎 API 深度解析-优快云博客

Mozilla/Nunjucks 模板引擎 API 深度解析

nunjucks A powerful templating engine with inheritance, asynchronous control, and more (jinja2 inspired) 项目地址: https://gitcode.com/gh_mirrors/nu/nunjucks

Nunjucks 是一个功能强大、灵活的 JavaScript 模板引擎，由 Mozilla 开发并维护。本文将深入解析 Nunjucks 的核心 API，帮助开发者全面掌握其使用方法。

安全警告：用户自定义模板风险

在使用 Nunjucks 时，绝对不要运行用户定义的模板或将用户内容注入模板定义。这会导致严重的安全问题：

服务器端：可能导致数据泄露和代码执行风险
客户端：即使使用预编译模板，也可能存在跨站脚本问题

基础 API 快速入门

对于不需要深度定制的场景，Nunjucks 提供了一组简单易用的高级 API。

模板渲染方法

`render` - 渲染模板文件

// 同步方式
const result = nunjucks.render('template.html', { username: '张三' });

// 异步方式
nunjucks.render('template.html', { username: '李四' }, (err, res) => {
  if (err) console.error(err);
  else console.log(res);
});

`renderString` - 渲染字符串模板

const result = nunjucks.renderString('你好 {{ name }}', { name: '王五' });

`compile` - 预编译模板

const template = nunjucks.compile('{{ greeting }} 世界!');
template.render({ greeting: '你好' });  // 输出: "你好 世界!"

环境配置

configure 方法用于设置模板路径和配置选项：

nunjucks.configure('views', {
  autoescape: true,      // 自动转义HTML
  trimBlocks: true,      // 去除块后的换行符
  lstripBlocks: true,    // 去除块前的空格
  watch: true            // 监听文件变化(需安装chokidar)
});

常用配置选项说明：

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | autoescape | boolean | true | 自动转义HTML特殊字符 | | throwOnUndefined | boolean | false | 遇到未定义变量时抛出错误 | | trimBlocks | boolean | false | 去除模板标签后的换行符 | | lstripBlocks | boolean | false | 去除模板标签前的空格 | | watch | boolean | false | 监听模板文件变化 | | noCache | boolean | false | 禁用模板缓存 |

高级环境控制

对于需要精细控制的场景，可以直接操作 Environment 类。

创建环境实例

// Node.js环境
const env = new nunjucks.Environment(
  new nunjucks.FileSystemLoader('views'),
  { autoescape: false }
);

// 浏览器环境
const env = new nunjucks.Environment(
  new nunjucks.WebLoader('/templates')
);

加载器(Loader)详解

Nunjucks 提供了几种内置加载器：

FileSystemLoader - 文件系统加载器(Node.js专用)

new nunjucks.FileSystemLoader('views', {
  watch: true,    // 监听文件变化
  noCache: true   // 禁用缓存
})

WebLoader - 网络加载器(浏览器专用)

new nunjucks.WebLoader('/templates', {
  useCache: false,  // 禁用缓存
  async: true       // 异步加载
})

NodeResolveLoader - Node模块解析加载器
```
new nunjucks.NodeResolveLoader()
```

自定义扩展

添加全局变量

env.addGlobal('companyName', 'Acme Inc.');

添加自定义过滤器

// 同步过滤器
env.addFilter('shorten', str => str.slice(0,50));

// 异步过滤器
env.addFilter('asyncFilter', asyncFunc, true);

添加自定义标签

env.addExtension('customTag', {
  tags: ['custom'],
  parse: function(parser, nodes) {
    // 解析逻辑
  },
  run: function(context) {
    // 执行逻辑
  }
});

模板继承与包含

Nunjucks 支持强大的模板继承系统：

<!-- base.html -->
<html>
<head>
  {% block head %}
  <title>{% block title %}默认标题{% endblock %}</title>
  {% endblock %}
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

<!-- child.html -->
{% extends "base.html" %}

{% block title %}子页面标题{% endblock %}

{% block content %}
  <h1>页面内容</h1>
{% endblock %}

异步支持

Nunjucks 提供了完整的异步支持：

// 异步渲染
env.render('async.html', { data }, (err, res) => {
  // 处理结果
});

// 异步过滤器
env.addFilter('asyncLookup', function(name, callback) {
  database.lookup(name, callback);
}, true);