# @ahmadnassri/template-literals-engine 中文文档

规范地址：https://npmcn.com/package/%40ahmadnassri/template-literals-engine/

版本：2\.0\.4
npm 元数据更新时间：2023-09-05T15:09:38.881Z
中文译文更新时间：2026-11-06T09:43:39.357Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ahmadnassri/template-literals-engine
原文对照：https://npmcn.com/package/%40ahmadnassri/template-literals-engine/?lang=original
项目主页：https://github.com/ahmadnassri/node-template-literals-engine
源码仓库：https://github.com/ahmadnassri/node-template-literals-engine

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

- 包体积（解压后）：11.8 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=14
- 运行依赖：1 个
- 首次发布：2020-10-24T21:16:59.554Z
- 最新版本发布：2023-09-05T15:09:38.741Z
- 近 30 天下载量：3542（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 0 个）

## 中文简介

给它喂JSON Spec, 它会吐出一个轻量级的HTTP客户端!

## 安装

```sh
npm install @ahmadnassri/template-literals-engine
```

也可以使用：`pnpm add @ahmadnassri/template-literals-engine`、`yarn add @ahmadnassri/template-literals-engine`、`bun add @ahmadnassri/template-literals-engine`

## README

# JS 模板文学引擎

使用 JS Template 字节直接到点模板引擎

[![license](https://badgen.net/github/license/ahmadnassri/node-template-literals-engine)](https://npmcn.com/package/%40ahmadnassri/template-literals-engine/LICENSE) [![release](https://badgen.net/github/release/ahmadnassri/node-template-literals-engine)](https://github.com/ahmadnassri/node-template-literals-engine/releases) [![semantic](https://badgen.net/badge/%F0%9F%93%A6/semantically%20released/blue)](https://github.com/ahmadnassri/node-template-literals-engine/actions?query=workflow%3Arelease)

## 为什么

[模板字元](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) _(又称"Template string")_ 是一种熟悉而简单的方法来运行嵌入式表达式和字符串插入,这是模板引擎的主要功能.

这个库用传统技术包装模板文字 _(排出,分出,助出等_ 通过结构化文件格式为使用提供便利(`.jstl`(中文(简体) )

## 什麽

特征 :

-   布局:布局的本地支持
-   支持:方便地包括文件和通过数据
-   快: 模板默认被缓存
-   可扩展:可扩展自定义助手

## 怎么样

### 使用量

###### `template.jstl`

```text
hello ${data.name}
```

###### `index.js`

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine(options)

engine.render('template', { name: 'ahmad' })
```

#### 字符串内插

由于模板被解析为标准 JavaScript [模板字元](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) 需要同样的功能

可访问变量 `data` 上下文

示例

###### `index.js`

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine()

const result = engine.render('template', { name: 'ahmad' })

console.log(result)
```

###### `template.jstl`

```text
Hello ${data.name}
```

###### 结果

```bash
$ node index.js
Hello ahmad
```

#### 辅助功能

帮助者基本上是可以在模板内调用的功能.

所有助手功能都可通过 `fn` 上下文

示例

###### `index.js`

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine({
  helpers: { 
    capitalize : str => string[0].toUpperCase() + string.slice(1)
  }
})

const result = engine.render('template', { name: 'ahmad' })

console.log(result)
```

###### `template.jstl`

```text
Hello ${fn.capitalize(data.name)}
```

###### 结果

```bash
$ node index.js
Hello Ahmad
```

#### 内建帮助者

##### `fn.render(templateName, [dataObject])`

行为就像 `Engine.render` 通过包含其他模板文件: `templateName` 内入

##### `fn.apply(templateName, [dataArray])`

列出 `dataArray` 并将每个项目适用于新提出的 `templateName`

示例

###### `index.js`

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine()

const actors = [
  { name: 'William Hartnell', year: '1963' },
  { name: 'Patrick Troughton', year: '1966' },
  { name: 'Jon Pertwee', year: '1970' },
  { name: 'Tom Baker', year: '1974' },
  { name: 'Peter Davison', year: '1981' },
  { name: 'Colin Baker', year: '1984' },
  { name: 'Sylvester McCoy', year: '1987' },
  { name: 'Paul McGann', year: '1996' },
  { name: 'Christopher Eccleston', year: '2005' },
  { name: 'David Tennant', year: '2005' },
  { name: 'Matt Smith', year: '2010' },
  { name: 'Peter Capaldi', year: '2013' },
  { name: 'Jodie Whittaker', year: '2017' }
]

const result = engine.render('page', { actors })

console.log(result)
```

###### `page.jstl`

```text
${ fn.include('header') }

<h1>List of actors who have played the Doctor</h1>

<ul>
  ${ fn.apply('doctor', data.actors) }
</ul>

${ fn.include('footer') }
```

##### `doctor.jstl`

```text
<li>${data.name} - first appeared in ${data.year}</li>
```

###### 结果

```text
$ node index.js
<body>

<h1>List of actors who have played the Doctor</h1>

<ul>
<li>William Hartnell - first appeared in 1963</li>
<li>Patrick Troughton - first appeared in 1966</li>
<li>Jon Pertwee - first appeared in 1970</li>
<li>Tom Baker - first appeared in 1974</li>
<li>Peter Davison - first appeared in 1981</li>
<li>Colin Baker - first appeared in 1984</li>
<li>Sylvester McCoy - first appeared in 1987</li>
<li>Paul McGann - first appeared in 1996</li>
<li>Christopher Eccleston - first appeared in 2005</li>
<li>David Tennant - first appeared in 2005</li>
<li>Matt Smith - first appeared in 2010</li>
<li>Peter Capaldi - first appeared in 2013</li>
<li>Jodie Whittaker - first appeared in 2017</li>
</ul>

</body>
```

#### 前题

每个模板文件都可以选择包含一个前题块,它被解析并包含在 `data` 上下文

示例

###### `index.js`

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine()

const result = engine.render('template')

console.log(result)
```

###### `template.jstl`

```text
---
name: ahmad
---
Hello ${data.name}
```

###### 结果

```bash
$ node index.js
Hello ahmad
```

#### 布局

定义 a `layout` 属性在模板的Front Matter块中,将首先渲染出该布局,并将当前模板作为内容.

布局可以无限地升级, 唯一的限制是你的系统资源!

示例

###### `index.js`

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine()

const result = engine.render('template', { name: 'ahmad' })

console.log(result)
```

###### `template.jstl`

```text
---
layout: layouts/welcome
---

<h2>${data.name}</h2>
```

###### `layouts/welcome.jstl`

```text
---
layout: layouts/base
---

<h1>Welcome!</h1>

${data.content}
```

###### `layouts/base.jstl`

```text
<html>
  <body>
    ${data.content}
  </body>
</html>
```

###### 结果

```text
$ node index.js
<html>
  <body>
    <h1>Welcome</h1>
    <h2>ahmad</h2>
  </body>
</html>
```

## API 密码

#### 构造器 `new Engine([optionsObject])`

返回模板引擎类的新实例

| 名称 | 类型 | 所需经费 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| **`root`** | `String` | ✖ | `process.cwd()` | 查找模板文件的路径 |
| **`extension`** | `String` | ✖ | `jstl` | 模板文件扩展名 |
| **`helpers`** | `Object` | ✖ | `{}` | `key => function` 要传递到模板的助手地图 |
| **`matter`** | `Object` | ✖ | `{}` | [选项](https://github.com/jonschlinkert/gray-matter#options) 传递给 [`gray-matter`](https://github.com/jonschlinkert/gray-matter) |

###### 示例:

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine({
  root: 'templates',
  extension: 'html'
  helpers: {
    capitalize : str => string[0].toUpperCase() + string.slice(1),
    ...
  }
})
```

#### 方法 : `render(templateName, [dataObject])`

解析文件的内容 : `${templateName}.jstl` 和通过 `dataObject` 返回已处理的输出字符串

###### 示例:

```js
const Engine = require('@ahmadnassri/template-literals-engine')

const engine = new Engine({ root: 'templates' })

engine.render('a-template') // => ./templates/a-template.jstl
engine.render('nested/template', { foo: 'bar' }) // => ./templates/nested/template.jstl
```

* * *

> 作者 : [艾哈迈德·纳斯里](https://www.ahmadnassri.com/) 二. 支助 微博: [@ AhmadNassri (英语)](https://twitter.com/AhmadNassri)

## 常见问题

### @ahmadnassri/template-literals-engine 是什么？

给它喂JSON Spec, 它会吐出一个轻量级的HTTP客户端\!

### 如何安装 @ahmadnassri/template-literals-engine？

在项目目录运行 npm install @ahmadnassri/template-literals-engine，或使用 pnpm add / yarn add / bun add。

### @ahmadnassri/template-literals-engine 支持 TypeScript 吗？

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

### @ahmadnassri/template-literals-engine 支持 ESM 还是 CommonJS？

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

### @ahmadnassri/template-literals-engine 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ahmadnassri/template-literals-engine 可以商用吗？

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

### @ahmadnassri/template-literals-engine 的下载量有多少？

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

### @ahmadnassri/template-literals-engine 还在维护吗？

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