# @ctrl/golang-template 中文文档

规范地址：https://npmcn.com/package/%40ctrl/golang-template/

版本：2\.0\.1
npm 元数据更新时间：2026-05-18T05:22:28.197Z
中文译文更新时间：2026-11-11T03:48:03.673Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ctrl/golang-template
原文对照：https://npmcn.com/package/%40ctrl/golang-template/?lang=original
项目主页：https://github.com/scttcper/golang-template#readme
源码仓库：https://github.com/scttcper/golang-template

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

- 包体积（解压后）：25 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2019-01-04T22:58:23.211Z
- 最新版本发布：2026-05-18T05:22:27.896Z
- 近 30 天下载量：29770（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 2 个）

## 中文简介

基本 golang 模板在 js 中解析

## 安装

```sh
npm install @ctrl/golang-template
```

也可以使用：`pnpm add @ctrl/golang-template`、`yarn add @ctrl/golang-template`、`bun add @ctrl/golang-template`

## README

# golang- template (golang- template) (英语) [![npm](https://img.shields.io/npm/v/@ctrl/golang-template.svg?maxAge=3600)](https://www.npmjs.com/package/@ctrl/golang-template)

> 类型脚本执行 [跳转到模板](https://pkg.go.dev/text/template) 语法.

## 安装

```sh
npm install @ctrl/golang-template
```

## 使用量

```ts
import { compile, parse } from '@ctrl/golang-template';

// One-shot
parse('{{ if .keywords }}{{ .keywords }}!!{{ else }}nothing{{ end }}', { keywords: '123' });
// '123!!'

// Compile once, render many times (better for hot paths)
const tmpl = compile('{{ if .name }}Hello {{ .name }}!{{ end }}');
tmpl.render({ name: 'World' }); // 'Hello World!'
tmpl.render({ name: 'Alice' }); // 'Hello Alice!'
```

## 支持的语法

### 变量

```ts
parse('{{ .foo }}', { foo: 'bar' });
// 'bar'

parse('{{ .user.name }}', { user: { name: 'Alice' } });
// 'Alice'
```

### 如果/ 其它情况

```ts
parse('{{ if .keywords }}{{ .keywords }}{{ else }}nothing{{ end }}', { keywords: 'swag' });
// 'swag'
```

### 如果有和/或/没有

```ts
parse('{{ if and .a .b }}both{{ else }}no{{ end }}', { a: 'x', b: 'y' });
// 'both'

parse('{{ if or .a .b }}either{{ else }}neither{{ end }}', { a: '', b: 'y' });
// 'either'

parse('{{ if not .disabled }}enabled{{ end }}', { disabled: false });
// 'enabled'
```

### 与

设定 `.` 改为区块持续时间的值;如果区块值为虚构,则跳过区块.

```ts
parse('{{ with .user }}Hello {{ . }}!{{ end }}', { user: 'World' });
// 'Hello World!'

parse('{{ with .user }}Hello {{ . }}{{ else }}nobody{{ end }}', { user: '' });
// 'nobody'
```

### 范围

```ts
const categories = ['a', 'b', 'c'];
parse('{{ range .categories }}{{ . }};{{ end }}', { categories });
// 'a;b;c;'

const items = [{ name: 'alice' }, { name: 'bob' }];
parse('{{ range .items }}{{ .name }};{{ end }}', { items });
// 'alice;bob;'
```

内部 `range`, (中文(简体) ), `{{ .Field }}` 仅针对当前项目. `{{ $.RootVar }}` 仍然不支持.

### 指数

```ts
const data = {
  object: { value: 'foo' },
  array: ['bar'],
};
parse('{{ index .object "value" }}', data); // 'foo'
parse('{{ index .array 0 }}', data); // 'bar'
```

### 加入 {{}

```ts
const categories = ['a', 'b', 'c'];
parse('{{ join .categories "," }}', { categories });
// 'a,b,c'
```

### 替换( r)

```ts
parse('{{ re_replace .category "[^a-zA-Z0-9]+" "%" }}', { category: '123$special' });
// '123%special'
```

† 非标准扩展,在Go's没有 `text/template`。 。 。 .

## 兼容性

| 特性 | 支助 |
| --- | --- |
| `{{ .Variable }}` | ✅ |
| `{{ .nested.path }}` | ✅ |
| `{{ if }}` 编号 : `{{ else }}` 编号 : `{{ end }}` | ✅ |
| `{{ if and .a .b }}` 编号 : `{{ if or .a .b }}` 编号 : `{{ if not .a }}` | ✅ |
| `{{ with }}` | ✅ |
| `{{ range }}` 与 `{{ . }}` | ✅ |
| `{{ index .arr 0 }}` 编号 : `{{ index .obj "key" }}` | ✅ |
| `{{ join }}` (电话分机) | ✅ |
| `{{ re_replace }}` (电话分机) | ✅ |
| `{{ range }}` 与 `{{ .Field }}` 关于项目 | ✅ |
| `{{ if eq .a .b }}` 编号 : `{{ if gt .a .b }}` 包括:. | ❌ |
| `{{ $var := .val }}` 可变任务 | ❌ |
| `{{ $.RootVar }}` 从内部范围/与 | ❌ |
| `{{ len .val }}` | ❌ |
| `{{ printf }}` 编号 : `{{ html }}` 编号 : `{{ js }}` | ❌ |
| `{{ template }}` 编号 : `{{ block }}` | ❌ |

## 警告

不要完全不可信的模板 。 这个 `re_replace` tag运行模板提供的JavaScript regex模式,因此恶意或粗心的模式仍然会导致CPU使用过度.

## 常见问题

### @ctrl/golang-template 是什么？

基本 golang 模板在 js 中解析

### 如何安装 @ctrl/golang-template？

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

### @ctrl/golang-template 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ctrl/golang-template 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ctrl/golang-template 需要什么版本的 Node\.js？

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

### @ctrl/golang-template 可以商用吗？

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

### @ctrl/golang-template 的下载量有多少？

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

### @ctrl/golang-template 还在维护吗？

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