# @frctl/nunjucks 中文文档

规范地址：https://npmcn.com/package/%40frctl/nunjucks/

版本：2\.0\.15
npm 元数据更新时间：2022-08-17T18:45:05.106Z
中文译文更新时间：2026-11-15T13:10:33.353Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40frctl/nunjucks
原文对照：https://npmcn.com/package/%40frctl/nunjucks/?lang=original
项目主页：https://github.com/frctl/fractal/tree/main/packages/nunjucks
源码仓库：https://github.com/frctl/fractal

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：21.5 kB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：4 个
- peer 依赖：@frctl/fractal \>= 1\.1\.0-alpha\.0 \< 2
- 首次发布：2016-05-24T16:03:35.959Z
- 最新版本发布：2022-08-17T18:45:04.968Z
- 近 30 天下载量：4613（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 0 个）

## 中文简介

Nunjucks 分形模板适配器.

## 安装

```sh
npm install @frctl/nunjucks
```

也可以使用：`pnpm add @frctl/nunjucks`、`yarn add @frctl/nunjucks`、`bun add @frctl/nunjucks`

## README

# @frctl/ nunjucks (英语)

[纳尼亚克人](http://mozilla.github.io/nunjucks/) 模板引擎适配器 [分形](http://github.com/frctl/fractal)。 。 。 .

[![NPM Version](https://img.shields.io/npm/v/@frctl/nunjucks)](https://www.npmjs.com/package/@frctl/nunjucks)

## \* 打破 v2.0 中的变化

-   `render` 标记 - 上下文数据中的矩阵 **不再合并** 带有默认组件上下文的
-   **自动删除** - 这是现在 **默认禁用**。需要更新预览模板,以标记 `yield` 使用 Nunjucks 输出为安全 `safe` 过滤器 : `{{ yield | safe }}`或者,如果 [配置适配器](https://npmcn.com/package/%40frctl/nunjucks/#readme-customisation) (不建议).
-   **Nunjucks 版本 :** - 撞到3.x了 - 撞到3.x了 - 碰到3.x了 - 碰到3.x了 - 碰到3.x了 - 碰到3.x

## 安装

```bash
npm i @frctl/nunjucks --save
```

## 使用量

```javascript
fractal.components.engine("@frctl/nunjucks"); // register the Nunjucks adapter for your components
fractal.components.set("ext", ".njk"); // look for files with a .njk file extension
```

## 自定义

如果您想要注册自定义 [过滤器](https://mozilla.github.io/nunjucks/api.html#custom-filters),全局变量或 [扩展](https://mozilla.github.io/nunjucks/api.html#custom-tags) 到底部的 Nunjucks 引擎时, 您可以配置一个实例如下 :

```javascript
const nunj = require("@frctl/nunjucks")({
  env: {
    // Nunjucks environment opts: https://mozilla.github.io/nunjucks/api.html#configure
  },
  filters: {
    // filter-name: function filterFunc(){}
  },
  globals: {
    // global-name: global-val
  },
  extensions: {
    // extension-name: function extensionFunc(){}
  }
});

fractal.components.engine(
  nunj
); /* set as the default template engine for components */
```

例如,从 [数字文件](https://mozilla.github.io/nunjucks/api.html#custom-filters)数字 :

```javascript
const nunj = require("@frctl/nunjucks")({
  filters: {
    shorten: function(str, count) {
      return str.slice(0, count || 5);
    }
  }
});
```

然后可以在组件或文档视图中使用如下:

```nunjucks
{# Show the first 5 characters #}
A message for you: {{ message|shorten }}

{# Show the first 20 characters #}
A message for you: {{ message|shorten(20) }}
```

## 包括和扩展非组件视图模板

默认情况下, Nunjucks 适配器希望您使用分形组件 `@handle` 语法是指要包含或扩展到模板中的组件.

然而,如果您想要包含(或扩展)非组件模板,您也可以指定一个目录路径(或一系列路径),供 Nunjucks 在配置您的 Nunjucks 实例时搜索非组件模板 。 例如:

```javascript
const nunj = require("@frctl/nunjucks")({
  paths: ["path/to/files"]
});
```

```html
{% include 'foo.html' %}
```

在此示例中的文件 `foo.html` 将会在 `path/to/files` 如果找到,则包含目录.

> 以这种方式使用额外的搜索路径 **没有** 防止标准 `@handle` 语法包括工作.

## 扩展

下面的Nunjucks扩展到 **自动预安装**。这些在构建或记录基于分形的组件库时往往有用.

狦 **不希望这样** 包含这些扩展,设置 `pristine: true` 当配置您的 Nunjucks 适配器实例时.

### 提交

这个 `render` 扩展使用模板中提供给它的上下文数据来制作一个组件(由它的手柄参考). 如果没有提供数据,它将使用它配置文件中定义的上下文数据,如果存在的话.

**作为一种替代方法,这可能会非常有用 `include` 以导入子组件.** `Include`'d 组件不会在上下文中拉动所以使用 `render` 相反,可以帮助防止包含子组件的组件配置文件中的上下文数据重复.

```html
<!-- pass in data for rendering -->
{% render '@example', {title: 'An Example'} %} {% render '@example', someData %}

<!-- use the config file data for rendering -->
{% render '@example' %}
```

你也可以通过在一个 _部分_ 数据对象(即仅包含组件预期的一些属性),然后通过第三个参数: `true` 以添加默认上下文数据中缺失的项目。 这使得您仅可以覆盖您需要的此已渲染组件实例的项目 .

```html
<!-- will get any missing properties from the component context data -->
{% render '@another-example', {title: 'Another Example'}, true %}
```

### 上下文

为一个组件输出已解析的上下文数据.

```html
{% context '@example' %}

<!--
  Outputs:
  {
      "foo": "bar",
      "baz": "bar"
  }
-->
```

### 视图

输出指定组件的原始视图模板内容.

```html
{% view '@example' %}

<!--
  Outputs:
  <p>{{ text }}</p>
-->
```

## 过滤器

下面的Nunjucks过滤器来了 **自动预安装**。与扩展一样,设置 `pristine: true` 在 Nunjucks 适配器实例配置中,将防止添加它们.

### 路径

取出一个根相相通的路径,如果需要使其在静态的 HTML 导出中工作,则重新写入.

**强烈建议您在需要链接到模板中的任何静态资产时使用此过滤器 .**

```html
{{ '/css/my-stylesheet.css' | path }}
```

路径参数应该从斜线开始,并与网根相对. 在静态 HTML 导出期间,此路径将被重写成相对当前页面的路径 .

## 特殊变量

Nunjucks 适配器也为您的模板提供了一些特殊的变量. 它们都有名字前缀有下划线来帮助防止与用户设置的任何上下文数据变量相冲突.

请注意,使用这些模板可能会将模板更紧密地绑入分形,这样你就可以选择不使用它们.

### 配置( c)

包含完整的分形配置对象。 当您想要引用文档中的配置项目( 或组件) 时有用 .

```html
{{ _config.project.title }}
<!-- outputs the project title -->
{{ _config.components.ext }}
<!-- outputs the extension used for components -->
```

### 自定义( s)

包含一个简单的数据对象表示正在提供的顶级项目(即组件或页面).

```html
{{ _self.title }}
<!-- outputs 'Button' -->
```

### 目标( g)

此变量仅设定在组件预览布局中, 包含一个简单数据对象对正在提供的项目( 即组件或页面) 的表示 _在内部_ 预览布局.

```html
{{ _target.title }}
<!-- outputs 'Button' -->
```

## 常见问题

### @frctl/nunjucks 是什么？

Nunjucks 分形模板适配器\.

### 如何安装 @frctl/nunjucks？

在项目目录运行 npm install @frctl/nunjucks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@frctl/fractal（\>= 1\.1\.0-alpha\.0 \< 2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frctl/nunjucks 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/frctl\_\_nunjucks 是否存在。

### @frctl/nunjucks 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @frctl/nunjucks 可以商用吗？

@frctl/nunjucks 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @frctl/nunjucks 的下载量有多少？

根据 npm 官方下载统计，@frctl/nunjucks 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,613 次，日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @frctl/nunjucks 还在维护吗？

最新版本 2\.0\.15 发布于 2022/08/18（4 年前）；至今共发布 25 个版本，其中过去 12 个月发布了 0 个；首次发布于 2016/05/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。