# @divriots/style-dictionary-to-figma 中文文档

规范地址：https://npmcn.com/package/%40divriots/style-dictionary-to-figma/

版本：0\.4\.0
npm 元数据更新时间：2025-09-03T07:24:08.699Z
中文译文更新时间：2026-11-12T11:54:04.794Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40divriots/style-dictionary-to-figma
原文对照：https://npmcn.com/package/%40divriots/style-dictionary-to-figma/?lang=original
项目主页：https://github.com/divriots/style-dictionary-to-figma#readme
源码仓库：https://github.com/divriots/style-dictionary-to-figma

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

- 包体积（解压后）：22.1 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-02-10T09:50:22.359Z
- 最新版本发布：2022-09-15T09:04:50.994Z
- 近 30 天下载量：54418（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 0 个）

## 中文简介

将样式词典对象转换成 Figma Tokens 插件所理解的东西的工具

## 安装

```sh
npm install @divriots/style-dictionary-to-figma
```

也可以使用：`pnpm add @divriots/style-dictionary-to-figma`、`yarn add @divriots/style-dictionary-to-figma`、`bun add @divriots/style-dictionary-to-figma`

## README

![style dictionary playground logo](https://raw.githubusercontent.com/divriots/style-dictionary-to-figma/main/.github/logo.png)

[带给你的  
](https://divriots.com/) [![‹div›RIOTS](https://divriots.com/divriots.svg)](https://divriots.com/#gh-light-mode-only)[![‹div›RIOTS](https://divriots.com/divriots-dark.svg)](https://divriots.com/#gh-dark-mode-only)

# 图像样式词典

变形的公用设备 [样式词典](https://amzn.github.io/style-dictionary/#/) 对象为某物 [图片 托肯斯插件](https://www.figma.com/community/plugin/843461159747178978) 明白吗.

用于设计系统 [后灯](https://backlight.dev/) 使用设计符号 [样式词典](https://amzn.github.io/style-dictionary/) ,可以通过 [图片 托肯斯插件](https://www.figma.com/community/plugin/843461159747178978)。 。 。 .

> 该工具目前假定使用Figma Tokens插件的同步特性. JSON 输出被满足于此,因为它是一个包含符号集信息的单一文件.

## 特征

-   支持将一个符号组标记为自定义符号集,使其在Figma中作为单独的符号集出现. 默认, `"global"` 用作符号集,您的符号将被放入其中, 但你可以覆盖它。 如果您想要将许多基本符号组合成一个“ 全球” 组合, 但针对主题的符号组合组合组合成一个“主题黑暗”组合, 这一点将是有益的 。 您可以这样配置 :
    
    ```json
    {
      "color": {
        "tokenset": "custom",
        "primary": {
          "base": {
            "type": "color",
            "value": "#14b8a6"
          }
        }
      }
    }
    ```
    
    `color.primary.base` 符号将出现在 `custom` 现在在插件中 . 您也可以通过路过配置或关闭此自动符号集映射 `defaultTokenset: false` 或为此配置字符串 `defaultTokenset: 'default'`
    
-   曲线 `.value` 由于 Figma Tokens 插件不使用此后缀, 故从引用值中选择 .
    
-   调整 `name` 由于 Figma Tokens 插件使用此属性来命名其符号, 但是, 没有名称属性, 它会用对象结构来创建自己的命名/消除, 这样会更好.
    
-   使用参考值而不是它的解析值。 打开 `ignoreUseRefValue: true` 如果想要破例并保留为已解析的值,则作为与道具值相比的属性.
    
-   允许通过一些可选选项来调整对象转换 :
    
    -   清洁Meta,如果 `true`,将清理一些样式词典所创建的元信息,Figma Tokens插件对此并不关心。 也可以通过一个 `string[]` 如果您想要配置一个元道具的黑名单, 您想要过滤自己
    
    ```js
    transform(obj, { cleanMeta: ['foo', 'bar'] });
    ```
    

## 使用量

```sh
npm i @divriots/style-dictionary-to-figma
```

```js
import { transform } from '@divriots/style-dictionary-to-figma';

const sdObject = { ... };
const figmaObj = transform(sdObject);
```

需要单独进口的,可以单独进口.

```js
import {
  trimValue,
  trimName,
  useRefValue,
  markTokenset,
  cleanMeta,
} from '@divriots/style-dictionary-to-figma';
```

一旦你把对象转换成Figma,一个建议是把它推到GitHub并使用 [图片 托肯斯插件](https://www.figma.com/community/plugin/843461159747178978) 与它同步,以使用 Figma 中的符号.

## 用于 [后灯](https://backlight.dev/) 编号 : [样式词典](https://amzn.github.io/style-dictionary/#/)

导入 `transform` 工具并创建样式词典格式:

```js
const { transform } = require('@divriots/style-dictionary-to-figma');
const StyleDictionary = require('style-dictionary');

StyleDictionary.registerFormat({
  name: 'figmaTokensPlugin',
  formatter: ({ dictionary }) => {
    const transformedTokens = transform(dictionary.tokens);
    return JSON.stringify(transformedTokens, null, 2);
  },
});
```

或者您也可以直接将前置物放入配置中,而不必须注册:

```js
const { transform } = require('@divriots/style-dictionary-to-figma');

module.exports = {
  source: ['**/*.tokens.json'],
  format: {
    figmaTokensPlugin: ({ dictionary }) => {
      const transformedTokens = transform(dictionary.tokens);
      return JSON.stringify(transformedTokens, null, 2);
    },
  },
  platforms: {
    json: {
      transformGroup: 'js',
      buildPath: '/tokens/',
      files: [
        {
          destination: 'tokens.json',
          format: 'figmaTokensPlugin',
        },
      ],
    },
  },
};
```

这上面有文件 `/tokens/tokens.json` figma Tokens 插件可以导入(例如通过 GitHub) .

自兹 [后灯](https://backlight.dev/) 已经 [GitHub 图像](https://github.com/) 财务报告和审定财务报表 [样式词典](https://amzn.github.io/style-dictionary/#/) 这个过程非常简单.

## 为每个符号集创建 JSON

也许你想用这个工具 生成一个单独的JSON文件 对于每个符号集, 然后手动粘贴到 Figma Tokens 插件 JSON 视图中. 例如,当你不使用 Figma Tokens 插件同步功能时.

为了这个, [引用来自此问题的代码片断](https://github.com/divriots/style-dictionary-to-figma/issues/15#issuecomment-1127797022)。 。 。 .

## 常见问题

### @divriots/style-dictionary-to-figma 是什么？

将样式词典对象转换成 Figma Tokens 插件所理解的东西的工具

### 如何安装 @divriots/style-dictionary-to-figma？

在项目目录运行 npm install @divriots/style-dictionary-to-figma，或使用 pnpm add / yarn add / bun add。

### @divriots/style-dictionary-to-figma 支持 TypeScript 吗？

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

### @divriots/style-dictionary-to-figma 支持 ESM 还是 CommonJS？

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

### @divriots/style-dictionary-to-figma 可以商用吗？

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

### @divriots/style-dictionary-to-figma 的下载量有多少？

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

### @divriots/style-dictionary-to-figma 还在维护吗？

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