# @ama-styling/style-dictionary 中文文档

规范地址：https://npmcn.com/package/%40ama-styling/style-dictionary/

版本：15\.2\.4
npm 元数据更新时间：2026-11-05T10:47:13.563Z
中文译文更新时间：2026-11-05T23:20:10.617Z
软件包许可：BSD-3-Clause

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

原始 npm 页面：https://www.npmjs.com/package/%40ama-styling/style-dictionary
原文对照：https://npmcn.com/package/%40ama-styling/style-dictionary/?lang=original
项目主页：https://amadeusitgroup.github.io/otter/
源码仓库：https://github.com/AmadeusITGroup/otter

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

- 包体积（解压后）：111 kB，102 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.22\.3 \|\| ^24\.15\.0 \|\| ^26\.0\.0
- 运行依赖：5 个
- peer 依赖：@o3r/core ~15\.2\.4，type-fest ^5\.3\.1，@o3r/telemetry ~15\.2\.4，@o3r/schematics ~15\.2\.4，style-dictionary ^5\.0\.0
- 首次发布：2025-06-20T10:31:14.568Z
- 最新版本发布：2026-11-05T10:47:13.008Z
- 近 30 天下载量：24372（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：748（近 12 个月 545 个）

## 中文简介

样式词典软件包曝光模块和钩子

## 安装

```sh
npm install @ama-styling/style-dictionary
```

也可以使用：`pnpm add @ama-styling/style-dictionary`、`yarn add @ama-styling/style-dictionary`、`bun add @ama-styling/style-dictionary`

## README

# Otter 样式词典

![Super cute Otter!](https://raw.githubusercontent.com/AmadeusITGroup/otter/main/assets/logo/otter.png)

此软件包是 [Otter 框架模块](https://github.com/AmadeusITGroup/otter/tree/main/docs/core/MODULE.md)。 。 。 .  
  

## 说明

[![Stable Version](https://img.shields.io/npm/v/@ama-styling/style-dictionary?style=for-the-badge)](https://www.npmjs.com/package/@ama-styling/style-dictionary) [![Bundle Size](https://img.shields.io/bundlephobia/min/@ama-styling/style-dictionary?color=green&style=for-the-badge)](https://www.npmjs.com/package/@ama-styling/style-dictionary)

这个软件包暴露了一组 **钩子** 财务报告和审定财务报表 **模块** 联 合 国 [样式词典](https://styledictionary.com/) 提高Tokens设计的能力.

## 开始

准备你的 [样式词典](https://styledictionary.com/) 感谢命令:

```shell
ng add @ama-styling/style-dictionary
```

默认情况下, 命令会进行以下更新 :

-   将 dev 依赖添加到 [样式词典包](https://www.npmjs.com/package/style-dictionary)。 。 。 .
-   创建最小值 [配置( mjs)](https://styledictionary.com/reference/config/#_top) cSS和元数据生成所需的配置文件.
-   添加数据 `generate:theme` 财务报告和审定财务报表 `generate:metadata` 项目中的脚本 _软件包.json_。 。 。 .

然后您就可以根据您的项目规格定制此设置 :

-   自定义 [样式词典配置](https://styledictionary.com/reference/config/#_top) 在生成时 _配置( mjs)_ 文档.
-   添加 [扩展](https://tr.designtokens.org/format/#extensions) 通过 [增强机制](https://npmcn.com/package/%40ama-styling/style-dictionary/#readme-enhancement)。 。 。 .
-   配置输出文件 [`getTargetFiles` 帮助者](https://npmcn.com/package/%40ama-styling/style-dictionary/#readme-gettargetfiles)。 。 。 .

## 增强

### 设计托肯扩展

这个 [设计托肯斯](https://tr.designtokens.org/format/#extensions) 格式允许提供 `$extensions` 属性来增强它应用的托肯.  
财产可直接适用于Token:

```json5
// colors.token.json
{
  "colors": {
    "primary": {
      "$value": "#000000",
      "$extensions": {
        "o3rPrivate": true
      }
    }
  }
}
```

或在一个专用 `.extensions.json` 文件( 当 [ama/json-parser/扩展](https://npmcn.com/package/%40ama-styling/style-dictionary/#readme-parsers) 解析器已装入 :

```json5
// color.token.json
{
  "colors": {
    "primary": {
      "$value": "#000000"
    }
  }
}
```

```json5
// custom.extensions.json
{
  "colors.primary": {
    "$description": "Primary private color",
    "$extensions": {
      "o3rPrivate": true
    }
  }
}
```

### 可用的 Otter 扩展

| 扩展 | 类型 | 说明 | 需要的钩子 |
| --- | --- | --- | --- |
| o3r 隐私 | `boolean` | 确定符号是否标为私有 | 预处理器 : **ama/预处理/扩展**  
主题 : **ama/cs/可变** |
| 机会 | `boolean` | 确定是否在生成时将符号标记为重要 | 预处理器 : **ama/预处理/扩展**  
主题 : **ama/cs/可变** |
| o3rScope 选项 | `string` | 适用于生成变量的范围 | 预处理器 : **ama/预处理/扩展**  
主题 : **ama/cs/可变** |
| o3r 元数据 | [CMS 元数据](https://github.com/AmadeusITGroup/otter/blob/main/packages/%40ama-styling/style-dictionary/src/interfaces/style-dictionary-interface.mts) | 生成后应向元数据提供的额外信息 | 预处理器 : **ama/预处理/扩展**  
主题 : **ama/json/元数据** |
| o3r 单位 | `string` | 将指定单位的数值转换为新单位。 它会在未指定单位的"编号"型号符号上添加一个单位.  
在复杂类型(如阴影,过渡等)的情况下,该单位会被应用于它们所包含的所有数字类型. | 预处理器 : **ama/预处理/扩展**  
变换 : **地图/转换/单位** |
| o3rRRatio 数据 | `number` | 适用于上个数值的比率。 该比例将仅适用于"数"类型的符号,或像类型一样适用于"字符串"中确定的第一个数字.  
对于复杂类型(如阴影,过渡等),该比率将适用于它们包含的所有数字类型. | 预处理器 : **ama/预处理/扩展**  
变换 : **地图/转换/比例** |
| o3rexpect 覆盖 | `boolean` | 指出该标志预计将被外部规则所压倒 | 预处理器 : **ama/预处理/扩展** |

> \[尖叫声\] 这个 **需要的钩子** 需要注册到 [样式词典配置](https://styledictionary.com/reference/config/) 以充分支持延期.

## 模块

### [解析器](https://styledictionary.com/reference/hooks/parsers/)

| 名称 | 匹配文件 | 说明 |
| --- | --- | --- |
| ama/json-parser/一行端 | `**/*.json` | 允许 _标记_ 在 JSON 文件中键入 |
| ama/json-parser/扩展 | `**/*.extensions.json` | 解析包含的文件 `$extensions` 在设计托肯顶部应用的指令 |

### [预处理器](https://styledictionary.com/reference/hooks/preprocessors/)

| 名称 | 说明 |
| --- | --- |
| ama/预处理/扩展 | 添加支持的预处理器 `$extensions` 脚本中的指令(或专用) `extensions.json` 存档). 此预处理器对任何Otter钩是强制的. |

### [变换](https://styledictionary.com/reference/hooks/transforms/)

| 名称 | 类型 | 标准 | 说明 |
| --- | --- | --- | --- |
| 地图/转换/比例 | `value` | `o3rRatio` 提供扩展名 | 应用给定 `o3rRatio` 改为它所指的托肯(s)的数值. |
| 地图/转换/单位 | `value` | `o3rUnit` 提供扩展名 | 将它所指的托肯值的单位替换为所提供的 `o3rUnit`。 。 。 . |

### [变形组](https://styledictionary.com/reference/hooks/transform-groups/)

| 名称 | 说明 |
| --- | --- |
| ama/cs/建议 | 扩展官员 [CSS 变换组](https://styledictionary.com/reference/hooks/transform-groups/predefined/#css) 通过添加 `ama/transform/ratio` 财务报告和审定财务报表 `ama/transform/unit` |

### [格式](https://styledictionary.com/reference/hooks/formats/)

| 名称 | 选项 | 说明 |
| --- | --- | --- |
| ama/cs/可变 | 见 [cs/可变选项](https://styledictionary.com/reference/hooks/formats/predefined/#cssvariables) | Render CSS 变量块(基于 [内建格式](https://styledictionary.com/reference/hooks/formats/predefined/#cssvariables)(a) 支持增加 [Otter 扩展特性](https://npmcn.com/package/%40ama-styling/style-dictionary/#readme-enhancement)。 。 。 . |
| ama/json/元数据 | 见 [cs/可变选项](https://styledictionary.com/reference/hooks/formats/predefined/#cssvariables) _(适用于 `defaultValue`(中文(简体) )_  
\- 说吧 **保持隐私**: 包括私有变量 | Render CMS风格元数据(CSS变量及其相关的CMS集成定制属性). |

### 登记程序

不同的钩/模块可以通过不同的钩/模块单独注册 [注册... ()](https://styledictionary.com/getting-started/using_the_npm_module/) 从 `StyleDictionary` 或全部同时与 `register` 函数如下:

```typescript
import { register, baseConfig } from '@ama-styling/style-dictionary';

const sd = new StyleDictionary({
  ...baseConfig,
  // custom configs ...
});

register(sd); // Register all Otter modules
```

> \[大 为了能够使用任何所列模块/套接字,它们必须登记在 `StyleDefinition` 举个例子.

> \[TIP\] 帮手 `baseConfig` 将为Otter扩展支持提供最小配置.

### 帮助者

增强和便利《公约》的配置 `StyleDictionary` 实例 `@ama-styling/style-dictionary` 揭露出一批帮手.

#### 获取目标文件

这个 `getTargetFiles` 函数用于参数化基于 Design Token 生成的文件(遵循与 `$extensions`:

```javascript
// Example to generate the `color-primary-**` variables in `my-color-primary.css`

import { getTargetFiles } from '@ama-styling/style-dictionary';

const rule = {
  'color.primary': 'my-color-primary.css'
};

// or `const rule = {color: {primary: 'my-color-primary.css'}}`
// or `const rule = {'color.primary': {$extensions: {o3rTargetFile: 'my-color-primary.css'}}}`
// or `const rule = {'color: {primary': {$extensions: {o3rTargetFile: 'my-color-primary.css'}}}}`

const sd = new StyleDictionary({
  //...
  plateforms: {
    css: {
      files: [
        ...getTargetFiles({ rule, { format: 'css', defaultFile: 'default-file.css' } })
      ]
    }
  }
});

register(sd); // Register all Otter modules
```

> \[注\] 这个 `format` 选项将应用到提供给 `getTargetFiles` 函数(包括 `defaultFile`) (中文(简体) ). `defaultFile` 定义生成不匹配任何规则的变量的默认文件.

帮助函数 `getTargetFiles` 正在将过滤器注册到 `StyleDictionary` 带着独一无二的身份证.  
此ID可检索如下:

```javascript
import { getTargetFiles } from '@ama-styling/style-dictionary';

const sd = new StyleDictionary();
const files = getTargetFiles({ rules, { styleDictionary: sd } });

/**
 * Filter IDs registered in {@link sd} Style Dictionary instance
 * @type {string[]}
 **/
const filterIds = files.map(({ filter }) => filter);
```

## 高级

### 基本节点配置示例

```typescript
// style-builder.mjs

import { register, getTargetFiles, baseConfiguration } from '@ama-styling/style-dictionary';
import StyleDictionary from 'style-dictionary';

// Rules to generate different CSS files according to Token name
const fileRules = {
  colors: 'style/colors.tokens.css',
  'components.panel': 'components/panel/panel.tokens.css'
}

const sd = new StyleDictionary({
  ...baseConfiguration, // Use basic Otter configuration setup
  usesDtcg: true, // Use Design Token Standard format

  source: ['tokens/*.tokens.json'], // Design Token files
  include: ['token.extensions.json'], // Custom extensions

  platforms: {
    // Generate CSS Files
    css: {
      options: {
        outputReferences: true // to output `--var: var(--other-var)` instead of the value of `--other-var`
      },
      transformGroup: 'ama/css/recommended',
      files: [
        ...getTargetFiles(fileRules, { format: 'css' }),
        // default CSS file where generate variables
        { destination: 'style/default.tokens.css', format: 'css' }
      ]
    },
    cms: {
      options: {
        outputReferences: true
      },
      transformGroup: 'ama/css/recommended',
      files: [
        { destination: 'style.metadata.json', format: 'ama/json/metadata' }
      ]
    }
  }
});

// Register otter hooks/modules
register(sd);

if (process.env.CSS_ONLY){
  sd.buildPlatform('css');
} else {
  sd.buildAllPlatforms();
}
```

可用以下命令运行 :

```bash
node ./style-builder.mjs
```

## 常见问题

### @ama-styling/style-dictionary 是什么？

样式词典软件包曝光模块和钩子

### 如何安装 @ama-styling/style-dictionary？

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

### @ama-styling/style-dictionary 支持 TypeScript 吗？

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

### @ama-styling/style-dictionary 支持 ESM 还是 CommonJS？

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

### @ama-styling/style-dictionary 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.22\.3 \|\| ^24\.15\.0 \|\| ^26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ama-styling/style-dictionary 可以商用吗？

@ama-styling/style-dictionary 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @ama-styling/style-dictionary 的下载量有多少？

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

### @ama-styling/style-dictionary 还在维护吗？

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