# @atlassian/soy-loader 中文文档

规范地址：https://npmcn.com/package/%40atlassian/soy-loader/

版本：5\.3\.14
npm 元数据更新时间：2026-08-11T11:29:43.464Z
中文译文更新时间：2026-11-09T20:49:55.063Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40atlassian/soy-loader
原文对照：https://npmcn.com/package/%40atlassian/soy-loader/?lang=original
项目主页：https://bitbucket.org/atlassianlabs/fe-server
源码仓库：https://bitbucket.org/atlassianlabs/fe-server

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

- 包体积（解压后）：44.3 kB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=12
- 运行依赖：5 个
- peer 依赖：webpack ^4\.0\.0 \|\| ^5\.0\.0
- 首次发布：2019-06-24T04:22:12.765Z
- 最新版本发布：2026-08-11T11:29:43.321Z
- 近 30 天下载量：1736（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 1 个）

## 中文简介

使用 Atlassian Soy CLI 编译器进行网络包装的大豆装入器

## 安装

```sh
npm install @atlassian/soy-loader
```

也可以使用：`pnpm add @atlassian/soy-loader`、`yarn add @atlassian/soy-loader`、`bun add @atlassian/soy-loader`

## README

# @ atlassian/ soy-loader (英语)

![node version](https://img.shields.io/node/v/@atlassian/soy-loader.svg) ![webpack peer dependency version](https://img.shields.io/npm/dependency-version/@atlassian/soy-loader/peer/webpack.svg) ![npm downloads](https://img.shields.io/npm/dt/@atlassian/soy-loader.svg)

编译 [豆类模板](https://developer.atlassian.com/confdev/tutorials/writing-soy-templates-in-your-plugin) 模板为 [@atlassian/ soy-template-plugin-js (英语)](https://www.npmjs.com/package/@atlassian/soy-template-plugin-js) 软件包并允许装入 [网络软件包](https://webpack.js.org//)

## 安装

您可以使用 [**国家预防机制**](https://www.npmjs.com/)数字 :

```bash
npm install @atlassian/soy-loader
```

或通过 [**雅伦**](https://yarnpkg.com/)数字 :

```bash
yarn add @atlassian/soy-loader
```

## 用法实例

```js
// webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.soy/,
        use: [
          {
            loader: '@atlassian/soy-loader',
            options: {
              // ... see Options below ...
            },
          },
        ],
      },
    ],
  },
};
```

### 选项

#### `data` `<string`\> (可选)

示例 `'foo:bar,moo:goo'`

将数据传递给表单中的大豆渲染器(仅指所渲染):,

#### `functions` `<string>` (可选)

示例 `'/foo/bar/path'`

自定义豆类函数的位置,通常是一条通往 `*.jar` 文档.

#### `expose` `<boolean>` (可选)

默认 : `true`

说明生成的命名空间是否应当暴露在窗口中。 如果没有,则必须要求模块调用模板.

#### `modularize` `<boolean>` (可选)

默认 : `false`

说明是否将模板调用和定义转换为ES6模块进出口. 允许Webpack跟踪模板调用链,但假设一个命名惯例,将命名空间字符串映射到文件路径. 详见 \[#Using-modularization\] (Using 模块化).

#### `customModuleMap` `Map<string, string | boolean>` (可选)

示例 `{ 'foo.bar.Template': 'foo/baz', 'moo.foo': false }`

与 `modularize` 选项。 模块化时用于模块名称的对象映射命名空间 。 明确 `false` 忽略一个模块,将其作为全球参考。 其他病态值回落到默认分辨率处理.

#### `modulePathResolver` 数字 : `<Function>` (可选)

示例

```js
function customModulePathResolver(namespace, context) {
  return namespace.replace(/\./g, '/');
}

function customModuleRelativePathResolver(namespace, context) {
  return path.relative(context, namespace.replace(/\./g, '/'));
}
```

与 `modularize` 选项。 一个需要 `namespace` \[`string`\[, `context` \[`string`,并在使用模块化时输出模块路径. 您可以读取更多关于 `context` 这里: [https://webpack.js.org/api/loaders/# 这段康文本](https://webpack.js.org/api/loaders/#thiscontext)

返回一个明确的 `false` 忽略一个模块,将其作为全球参考。 返回其他恶性或 `undefined` 返回到默认分辨率处理的值.

## 食谱

### 使用方式 `*.properties` 网络包装加载器

此软件包可用于 [`@atlassian/i18n-properties-loader`](https://www.npmjs.com/package/@atlassian/i18n-properties-loader) 当你用 webpack dev 服务器运行代码时:

```js
// webpack.config.js
const myI18nFiles = [
  'foo/i18n/my-translation-file.properties',
  'foo/bar/i18n/my-other-translation-file.properties',
  'bar/i18n/some-translation-file.properties',
];

module.exports = {
  module: {
    rules: [
      {
        test: /\.soy/,
        use: [
          {
            loader: '@atlassian/i18n-properties-loader',
            options: {
              i18nFiles: myI18nFiles,
            },
          },

          {
            loader: '@atlassian/soy-loader',
          },
        ],
      },
    ],
  },
};
```

### 使用 `modularize`

模块化(Modularize)是一个特殊的案例,可以在您 {namespace} 和 Soy 文件为 1– 1 时使用. 它将任何外部模板引用的ES6模块导入(反之,任何被定义的模板都会从本模块中被命名为导出)转换出. 这使得Webpack可以追踪索伊文件之间的依赖关系,而不是需要手动指定.

默认情况下 `camelCase` 名称空间变为 `kebab-case`,点分隔器成为目录,以及 `.soy` 后缀为后缀.

**示例**编号: `{namespace a.bCD}` 名称空间转换为 `import 'a/b-c-d.soy';` 模块路径.

这可以被覆盖 使用 `customModuleMap` 一次性例外的选项,和/或 `modulePathResolver` 函数可以完全更改命名方案。 注:每个命名空间的模块都是独特的.

目前,AUI提供的命名空间被忽略并留作全局可变参考,因此对AUI的依赖无法被跟踪. 如果你想用不同方式处理,请检查 `DEFAULT_MAPPINGS` 输入 `modular-soy.js` 文件,并替换每个文件 `false` 带有模块名称.

## 其他链接

-   [https://www.npmjs.com/package/@atlassian/i18n-properties-loader (英语)](https://www.npmjs.com/package/@atlassian/i18n-properties-loader)
-   [https://www.npmjs.com/package/@atlassian/wrm-react-i18n (英语)](https://www.npmjs.com/package/@atlassian/wrm-react-i18n)
-   [https://www.npmjs.com/package/atlassian-webresources-webpack-plugin (中文(简体) )](https://www.npmjs.com/package/atlassian-webresource-webpack-plugin)

## 最低要求

此插件兼容 :

-   4.0+和 5.0+网络包装
-   节点12+

## 常见问题

### @atlassian/soy-loader 是什么？

使用 Atlassian Soy CLI 编译器进行网络包装的大豆装入器

### 如何安装 @atlassian/soy-loader？

在项目目录运行 npm install @atlassian/soy-loader，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：webpack（^4\.0\.0 \|\| ^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @atlassian/soy-loader 支持 TypeScript 吗？

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

### @atlassian/soy-loader 支持 ESM 还是 CommonJS？

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

### @atlassian/soy-loader 需要什么版本的 Node\.js？

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

### @atlassian/soy-loader 可以商用吗？

@atlassian/soy-loader 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlassian/soy-loader 的下载量有多少？

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

### @atlassian/soy-loader 还在维护吗？

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