# @embroider/template-tag-codemod 中文文档

规范地址：https://npmcn.com/package/%40embroider/template-tag-codemod/

版本：1\.4\.2
npm 元数据更新时间：2026-10-22T13:21:22.347Z
中文译文更新时间：2026-11-14T12:26:19.003Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：188 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>= 20\.19\.\*
- 运行依赖：20 个
- 首次发布：2025-01-07T19:13:29.034Z
- 最新版本发布：2026-10-22T13:21:21.143Z
- 近 30 天下载量：2049（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：176（近 12 个月 5 个）

## 中文简介

转换为 HBS 为 GJS

## 安装

```sh
npm install @embroider/template-tag-codemod
```

也可以使用：`pnpm add @embroider/template-tag-codemod`、`yarn add @embroider/template-tag-codemod`、`bun add @embroider/template-tag-codemod`

## README

# @embroider/template-tag-codemod (英语)

这个代码mod将Emberapp中所有非限制性手柄栏的用法转换为更新,更严格的Template Tag语法. 它利用Embroider构建的基础设施来完成所有组件,帮助器和修饰器的构建时间解析,这样你就不需要自己去解析.

## 说明

1.  决定要传递给编码器的选项 。 见下文"重要选项".
2.  确保您的应用程序具备使用模板标签的前提条件 。 见下文"先入后出".
3.  从净源控制入手. 我们要改变你所有的档案 用Git来控制变化.
4.  通过编码器运行 `npx @embroider/template-tag-codemod YOUR_OPTIONS_HERE`
5.  使用 `prettier` 对结果应用良好的格式.
6.  交出结果.
7.  _可选但建议:_ 使用该 `merge-history` 命令以调整 Git 历史,使您的 GJS 文件能够正确继承 _两者_ 联合来文和HBS文件的创建。 见下文.

## 重要选项

本节解释在决定何时以及如何运行代码mod之前,您应该知道的重要选项. 可通过互动方式获得其他选项 `--help`。 。 。 .

### \--相接的本地图片

默认情况下, 应用程序中的导入会使用相对路径 _与_ 文件扩展名。 这是节点对于有效的ES模块的标准,也是最能防止未来的输出,因为自动映射文件扩展可能很复杂.

但有几个原因,你可能更喜欢传统的无扩展导入 从应用程序的模块命名空间

-   经典建筑需要它
-   `@embroider/webpack` 3.x 不支持使用一些文件类型的真实文件扩展名, 如. gjs

为了得到你的行为,你可以通过 `--relativeLocalPaths false`。 。 。 .

```js
// relativeLocalPaths true (default):
import TheButton from './components/the-button.js';

// relativeLocalpaths false:
import TheButton from 'your-app/components/the-button';
```

### \- 内生轮盘

从Ember 6.3.0开始,您的路由模板(`app/templates/**/*.hbs`)被允许直接导出组件,这意味着您可以将其写入 `.gjs` 或者说 `.gts` 文档。 代码模型默认会生成此输出.

然而,如果想要支持早期的 Ember 版本,你可以通过 `--nativeRouteTemplates false` 并安装 `ember-route-template` 塞顿.

```js
// app/templates/example.gjs

// nativeRouteTemplates true (default)
import MessageBox from '../components/message-box.js';
<template>
  <MessageBox>Hello world</MessageBox>
</template>

// nativeRouteTemplates false
import MessageBox from '../components/message-box.js';
import RouteTemplate from 'ember-route-template'
export default RouteTemplate(
  <template>
    <MessageBox>Hello world</MessageBox>
  </template>
)
```

### \-- 本地语言

这面旗帜是Ember < 6.4.0中一个虫子的工作轮廓. 这些版本有一个错误,阻碍您访问逻辑范围 `this` 在用作表达式的模板标签中。 典型的使用案例是渲染测试:

```js
// Input example:
test("some test", function(assert) {
  this.set('message', 'hi');
  render(hbs`{{this.message}}`);
})

// nativeLexicalThis true (default)
test("some test", function(assert) {
  this.set('message', 'hi');
  render(<template>{{this.message}}</template>);
})

// nativeLexicalThis false
test("some test", function(assert) {
  this.set('message', 'hi');
  const self = this;
  render(<template>{{self.message}}</template>);
})
```

如果您想要您的代码在 Ember < 6. 4.0 上工作, 请通过 `--nativeLexicalThis false`。如果您不想用这些额外线路污染您的测试,请先升级Ember并保留旗的默认值.

### \-- 默认格式

当转换已有时 `.js` 文件到模板标签, 编码器总是生成一个 `.gjs` 输出文件 。 当转换已有时 `.ts` 文件,代码总是生成 `.gts` 文档。 但有一些模棱两可的情况:

-   仅包含 `.hbs` 没有相应的 `.js` 或者说 `.ts`。 。 。 .
-   一个路由模板, 它传统上总是一个独立的 `.hbs` 文件

在这种情况下,编码器的输出由 `--defaultFormat`。 。 。 .

`--defaultFormat gjs` 默认值.

过 `--defaultFormat gts` 如果你更喜欢制作打字符。 另见交互式文件 `--routeTemplateSignature` 财务报告和审定财务报表 `--templateOnlyComponentSignature` 如果您想要自定义由编码器释放的默认类型签名.

## 先决条件

1.  您的构建必须支持模板标记 .
    
    在经典的建筑或之上 `@embroider/core` 3.x 这意味着安装 `ember-template-imports` 塞顿.
    
    打开 `@embroider/core` 4.x 由本地支持.
    
    为确认此步骤有效, 您应该可以在 . gjs 文件里写出一个新的组件, 并在您的应用中看到它有效 .
    
2.  您的更漂亮的配置应该支持模板标记 。 这被添加到Ember-cli 6.1.0的默认Ember应用蓝图中,但也可以在更早的蓝图版本上手动设置. 你需要依赖 `prettier-plugin-ember-template-tag` 和配置在 `.prettierrc.js` 这与它有关.
    
3.  您的 ESLint 配置应该支持模板标记 。 这被添加到Ember-cli 6.1.0的默认Ember应用蓝图中,但也可以在更早的蓝图版本上手动设置. 如果使用ember-cli 6.1.0作为向导,请注意整个eslint配置被升级为更新的平面配置风格. 要在更古老的配置风格中使用模板标签支持,您需要这样的区域:
    
    ```
    overrides: [
      {
        files: ['**/*.{gts,gjs}'],
        parser: 'ember-eslint-parser',
      },
    ```
    

```
And the `ember-eslint-parser` dependency.
```

4.  升级 @ ember/ test- helpers 到\\ 5.0.1 (因为您可能需要) [此特性](https://github.com/emberjs/ember-test-helpers/pull/1527/)) (中文(简体) ).
    
5.  如果你计划使用 `--nativeRouteTemplates false` 支持 Ember < 6.3.0, 确保您已经安装了 `ember-route-template` 塞顿.
    
6.  _可选_:如果您仍然有非同一位置的组件模板(`app/templates/components/**/*.hbs`)这个代码mod会让那些人一个人,他们不会被升级到模板标记. 您应考虑将他们迁至合用同一地点(`app/components/templates/**/*.hbs`相反。 有一个 [代码](https://www.npmjs.com/package/ember-component-template-colocation-migrator)。这也是实现 `ember-source` >= 6.0.0.
    
7.  _可选_:如果您仍然有不使用本地类语法的组件(`Component.extend({})` 改为 `class extends Component`),这个代码mod将离开这些孤独,他们不会被升级到模板标记. 有一个 [本地类代码](https://www.npmjs.com/package/ember-native-class-codemod) 在使用这个编码器之前,您可以使用它.
    

## 合并历史

这个 `merge-history` 命令取一个已经应用了代码模块的分支,并生成一个内容相同的新分支,只是 Git 历史已被调整,以使您的 GJS 文件能够正确继承 _两者_ 他们取代的JS和HBS档案.

**关键是:** 命令只包含更改 `.gjs` 财务报告和审定财务报表 `.gts` 从您分支到新分支的文件,这意味着如果您只合并新分支,则原分支中的所有其它更改都会丢失.

示例

```sh
npx @embroider/template-tag-codemod merge-history --help
npx @embroider/template-tag-codemod merge-history main your-codemodded-branch --outputBranch better-codemodded-branch
git push -u origin better-codemodded-branch
```

命令还生成 [.git-blame-ignore-revs 文件 存档副本](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#ignore-commits-in-the-blame-view),它由 GitHub 默认支持,可以让您看到过代码化格式.

# 已知的兼容性问题

## 模块

如果编码器以 :

`BuildError: BroccoliBridge placeholder 'modules' was never fulfilled.`

这也许是因为你有 [模块](https://github.com/salsify/ember-css-modules)它在经典的建筑管道里 极度地诅咒事物 你可以绕着这个问题工作 **暂时从您的包中移除。 json** 当你运行代码时.

## 常见问题

### @embroider/template-tag-codemod 是什么？

转换为 HBS 为 GJS

### 如何安装 @embroider/template-tag-codemod？

在项目目录运行 npm install @embroider/template-tag-codemod，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 template-tag-codemod，可以用 npx template-tag-codemod 直接运行。

### @embroider/template-tag-codemod 支持 TypeScript 吗？

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

### @embroider/template-tag-codemod 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @embroider/template-tag-codemod 需要什么版本的 Node\.js？

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

### @embroider/template-tag-codemod 可以商用吗？

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

### @embroider/template-tag-codemod 的下载量有多少？

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

### @embroider/template-tag-codemod 还在维护吗？

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