# @elg/tscodegen 中文文档

规范地址：https://npmcn.com/package/%40elg/tscodegen/

版本：0\.5\.0
npm 元数据更新时间：2026-04-23T04:38:02.208Z
中文译文更新时间：2026-11-13T12:24:02.836Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：54.5 kB，21 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.18\.0
- 运行依赖：1 个
- peer 依赖：prettier 3\.x
- 首次发布：2020-05-28T12:09:01.298Z
- 最新版本发布：2026-04-23T04:38:02.089Z
- 近 30 天下载量：14159（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

TypeScript 字符串基于代码生成工具,其中包含散列文件和可手动编辑的部分

## 安装

```sh
npm install @elg/tscodegen
```

也可以使用：`pnpm add @elg/tscodegen`、`yarn add @elg/tscodegen`、`bun add @elg/tscodegen`

## README

# tscodegen 码

[![CircleCI](https://circleci.com/gh/taneliang/tscodegen.svg?style=svg)](https://circleci.com/gh/taneliang/tscodegen) [![codecov](https://codecov.io/gh/taneliang/tscodegen/branch/master/graph/badge.svg)](https://codecov.io/gh/taneliang/tscodegen) [![Maintainability](https://api.codeclimate.com/v1/badges/bbc025c3c4e1ce23b002/maintainability)](https://codeclimate.com/github/taneliang/tscodegen/maintainability)

[tscodegen 码](https://www.npmjs.com/package/@elg/tscodegen) 是一个最小的 类型脚本端口 [脸书包 代码](https://hhvm.github.io/hack-codegen)它提供流利的API 允许您从 : 代码,可选择可手动编辑的段落和篡改检测.

## 关键特性

-   生成文件中可手动编辑的段落 。 这种行为差不多了 和Hack Codegen惊人的一样 [部分生成 文件](https://hhvm.github.io/hack-codegen/docs/overview/partially-generated-files/)。 。 。 . 与大多数其他代码生成工具不同,tscodegen(和Hack Codegen)是 能够生成可编辑的文件, 允许您的代码源输出轻松 量身定制和扩展,不给猴子打草惊蛇或子分类。 这些编辑 当代码被重新生成时将保留.
    
-   基于字符串的代码生成. 我们回避处理AST(例如: ts-morph 或 TypeScript 编译器 API),支持字符串操纵. 这样你就可以自然地写出生成的代码,不用知道 typeScript的AST的细节.
    
-   密码锁篡改检测。 将散列添加到每个块的多克块中 生成文件, 以方便检测外部已更改的文件 生成的手动部分。 将来,这可以 [以 ESLint规则](https://github.com/taneliang/tscodegen/issues/1) (百分数) 欢迎.
    
-   没有模板文件 。 tscodegen 用途 [模板 字节](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) 和 TypeScript 方法调用,允许您使用循环和条件 无需学习另一种诱人的语言.
    
-   自动格式化为 Pretier, 使用您的工程的 Pretier 配置 . 生成的代码很少如此可读.
    
-   干净,流利,最小的API.
    

## 安装

```sh
npm install @elg/tscodegen prettier # NPM
yarn add @elg/tscodegen prettier # Yarn
```

## 使用量

1.  `import { CodeFile } from '@elg/tscodegen';`
2.  证据 `CodeFile`。 。 。 .
3.  打电话 `build` 以 `CodeBuilder` 举个例子.
4.  将已建文件写入磁盘 `saveToFile`。 。 。 .

## 样本

### 代码脚本

```typescript
new CodeFile("./file.ts")
  .build((builder) =>
    builder
      .addLine("import path from 'path';")
      .addLine("import fs from 'fs'")
      .addLine()
      .addManualSection("custom_imports", (builder) => builder)
      .addLine()
      .addBlock("class Steam extends Water", (builder) =>
        builder
          .addBlock("constructor()", (builder) =>
            builder.addLine("this.boil();"),
          )
          .addLine()
          .addBlock("boil()", (b) =>
            b.addManualSection("boil_body", (builder) =>
              builder.add("this.temp = 100;"),
            ),
          ),
      )
      .format(),
  )
  .lock()
  .saveToFile();
```

### 产出

```typescript
/**
 * This file is generated with manually editable sections. Only make
 * modifications between BEGIN MANUAL SECTION and END MANUAL SECTION
 * designators.
 *
 * @generated-editable Codelock<<jF8gPj9IVq16NXBAtEzJj0rrD9HR7Q6V>>
 */

import path from "path";
import fs from "fs";

/* BEGIN MANUAL SECTION custom_imports */
/* END MANUAL SECTION */

class Steam extends Water {
  constructor() {
    this.boil();
  }

  boil() {
    /* BEGIN MANUAL SECTION boil_body */
    new Magician().magic(); // This line was retrieved from the original file.ts
    /* END MANUAL SECTION */
  }
}
```

## 生成非 TypeScript 文件

默认, `CodeFile` 散发JSDoc/C型的Doc块和手动部分 标记。 传出 a `commentSyntax` 选项 支持行注释(例如). `.gitattributes` 与 `#` 评论, shell 脚本, 或一个 `.ts` 您喜欢的文件 `//` 文档块 :

```typescript
export type CommentSyntax =
  | { kind: "jsdoc" } // default — JSDoc/C-style
  | { kind: "line"; prefix: string }; // e.g. "# " or "// "
```

示例 `.gitattributes` 生成器 :

```typescript
new CodeFile(".gitattributes", {
  commentSyntax: { kind: "line", prefix: "# " },
})
  .build((b) =>
    b
      .addManualSection("manual", (m) => m.addLine("# add custom rules here"))
      .addLine("path/to/generated.ts linguist-generated=true"),
  )
  .lock("\nTo update this file, run: npm run generate:gitattributes\n")
  .saveToFile();
```

样本输出 :

```
# This file is generated with manually editable sections. Only make
# modifications between BEGIN MANUAL SECTION and END MANUAL SECTION
# designators.
#
# To update this file, run: npm run generate:gitattributes
#
# @generated-editable Codelock<<...>>

# BEGIN MANUAL SECTION manual
# add custom rules here
# END MANUAL SECTION
path/to/generated.ts linguist-generated=true
```

其他一切都一样: `verify()` 探测到在 手动部分, `lock()` 添加散列,以及 `saveToFile()` 写入 结果。 手动分割键仍然必须是非空和白空的.

## 生成缩进敏感语言( Python, YAML, Makefile,...)

对于缩进为同步的语言,使用 `CodeBuilder.indent(amount, fn)` 打开每个发射线(包括手动部分)的嵌入范围 标记和正文)的前缀为 `amount`缩进范围 添加: `indent(" ", b => b.indent(" ", bb => …))` 生成四个空格 缩入.

```typescript
new CodeFile("compute.py", { commentSyntax: { kind: "line", prefix: "# " } })
  .build((b) =>
    b
      .addLine("def compute(x: int) -> int:")
      .indent("    ", (fn) =>
        fn
          .addLine("result = x + 1")
          .addManualSection("postprocess", (m) => m.addLine("return result")),
      ),
  )
  .lock()
  .saveToFile();
```

输出 :

```python
# This file is generated with manually editable sections. Only make
# modifications between BEGIN MANUAL SECTION and END MANUAL SECTION
# designators.
#
# @generated-editable Codelock<<...>>

def compute(x: int) -> int:
    result = x + 1
    # BEGIN MANUAL SECTION postprocess
    return result
    # END MANUAL SECTION
```

手动分会 整洁地穿过再生过程: 被储存的身体是 _语义_ (栏-0内容),构建者重新应用环境缩进 离开的路上。 因此,一个人谁编辑 一节,并添加行 匹配缩进 :

```python
    # BEGIN MANUAL SECTION postprocess
    if result > 100:
        raise ValueError(result)
    return result
    # END MANUAL SECTION
```

将在再生后看到其编辑内容保存的逐字记录,否 巢穴收缩的再转移 `if`编号 :`raise` 配对保持其4个空间 相对缩进).

`indent()` 接受任意字符串——通常是空格或 `"\t"` -所以也一样 覆盖 Makefile 食谱、 YAML 映射、 Terraform/ HCL 块、 INI 类 格式,或列位置关系的任何其他布局.

### 支持的文件类型 `CommentSyntax`

tscodegen将注释前缀视为不透明字符串,所以任何 语言,其注释适合支持的形状之一 那个盒子 下表列出共同目标的配置 文件类型.

| 文件类型 | `CommentSyntax` |
| --- | --- |
| 类型脚本 / Java 脚本 / TSX / JSX | `{ kind: "jsdoc" }` (默认) |
| 去吧,鲁斯特,斯威夫特,克特林,爪哇 | `{ kind: "jsdoc" }` |
| C, C++ 数据 | `{ kind: "jsdoc" }` |
| CSS / SCSS / 低温 | `{ kind: "jsdoc" }` |
| 普罗托布夫 | `{ kind: "jsdoc" }` |
| TS/JS(首选线条评论) | `{ kind: "line", prefix: "// " }` |
| 鲁比活佛 | `{ kind: "line", prefix: "# " }` |
| 贝壳 / 巴什 / zsh | `{ kind: "line", prefix: "# " }` |
| YAML, TOML 语言 | `{ kind: "line", prefix: "# " }` |
| 多克档案, `.env` | `{ kind: "line", prefix: "# " }` |
| 地平面 / HCL, 图QL | `{ kind: "line", prefix: "# " }` |
| 创建文件 | `{ kind: "line", prefix: "# " }` + 标签缩进 |
| `.gitattributes`, (中文(简体) ), `.gitignore` | `{ kind: "line", prefix: "# " }` |
| nginx.conf, 系统化单位 | `{ kind: "line", prefix: "# " }` |
| SQL 组合键 | `{ kind: "line", prefix: "-- " }` |

Python/YAML/Terraform/Makefile/SQL快照输入 `src/__snapshots__/integration.test.ts.snap` 是一个活的目录 每一个都会产生什么样的输出.

### 已知的限制

-   **JSON 没有评论语法**,所以无法锁定。 如果你需要的话 生成 JSON 和其他文件, 要么释放一个同伴 元数据文件或使用 JSONC (`{ kind: "line", prefix: "// " }`) (中文(简体) ).
-   **XML / HTML / SVG / 马克下架 / Vue SFCs / MDX** 使用情况 `<!-- ... -->` 关闭注释, 无法在 `CommentSyntax`。 。 。 .
-   **Shebangs必须是一号线.** `lock()` 预花它的多克块,所以 锁定 shell 脚本 `#!/usr/bin/env bash` 最终低于 医生 对于作为可执行文件引用的脚本,请在 锁上门或通过译员调用后自杀 直接说.

## 常见问题

### @elg/tscodegen 是什么？

TypeScript 字符串基于代码生成工具,其中包含散列文件和可手动编辑的部分

### 如何安装 @elg/tscodegen？

在项目目录运行 npm install @elg/tscodegen，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：prettier（3\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @elg/tscodegen 支持 TypeScript 吗？

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

### @elg/tscodegen 支持 ESM 还是 CommonJS？

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

### @elg/tscodegen 需要什么版本的 Node\.js？

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

### @elg/tscodegen 可以商用吗？

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

### @elg/tscodegen 的下载量有多少？

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

### @elg/tscodegen 还在维护吗？

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