# @fylgja/props-builder 中文文档

规范地址：https://npmcn.com/package/%40fylgja/props-builder/

版本：2\.3\.0
npm 元数据更新时间：2026-10-15T08:40:56.706Z
中文译文更新时间：2026-11-15T19:46:08.603Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fylgja/props-builder
原文对照：https://npmcn.com/package/%40fylgja/props-builder/?lang=original
项目主页：https://fylgja.dev/
源码仓库：https://github.com/fylgja/fylgja

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

- 包体积（解压后）：103 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2022-06-05T14:44:00.659Z
- 最新版本发布：2026-10-15T08:40:56.045Z
- 近 30 天下载量：38214（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 3 个）

## 中文简介

从 JavaScript 对象中不费力地生成 Design Tokens (CSS自定义属性).

## 安装

```sh
npm install @fylgja/props-builder
```

也可以使用：`pnpm add @fylgja/props-builder`、`yarn add @fylgja/props-builder`、`bun add @fylgja/props-builder`

## README

# Fylgja - 推进器构建器

[![NPM version](https://img.shields.io/npm/v/@fylgja/props-builder)](https://www.npmjs.com/package/@fylgja/props-builder) [![NPM Downloads](https://img.shields.io/npm/dt/%40fylgja%2Fprops-builder)](https://www.npmjs.com/package/@fylgja/props-builder) [![License](https://img.shields.io/github/license/fylgja/fylgja?color=%23234)](https://github.com/fylgja/fylgja/blob/main/LICENSE)

Fylgja Propals 构建器简化了 Design Tokens (CSS自定义属性)的创建 通过将JavaScript对象或JSON文件转换为CSS变量或其他符号格式.

这个工具可以使您轻松地构建全面的 Design Token 设置 .

## 安装

您可以通过 npm 或其他基于节点的软件包管理器如 pnpm 或 bun 安装 Fylgja Props 构建器 :

```sh
npm install @fylgja/props-builder
```

## 使用量

### 基本使用 JavaScript

将道具Builder 函数导入您的节点. js 脚本 :

```js
import { propsBuilder } from "@fylgja/props-builder";
```

然后,根据您的配置使用它生成输出文件 :

```js
import { propsBuilder } from "@fylgja/props-builder";

propsBuilder(
  props, // Required: JavaScript object containing your design tokens.
  filename, // Required: Name of the output file.
  {
    parseAs: "auto", // Optional: Specifies the output format. Defaults to "auto".
    writeToFile: true, // Optional: If false, outputs the generated content to the console. Defaults to true.
    selector: ":where(:root)", // Optional: CSS selector for custom property declarations (CSS output only).
    wrapper: "", // Optional: Wrapper for design system-specific formatting (e.g., Figma).
    name: "Design Tokens", // Optional: Name of the Design Tokens Resolver (dtcg output only).
    description: "", // Optional: Description of the Design Tokens Resolver (dtcg output only).
    inputTypeTokens: false, // Optional: Set to true if the input `props` are in a design token format. Defaults to false.
    inputTypeSyntax: "default", // Optional: Specifies the syntax of the input tokens if `inputTypeTokens` is true.
    stripPrefix: "", // Optional: Dot/dash separated key path (or array of keys) to unwrap, dropping wrapping keys (e.g. "tokens.values").
    rename: null, // Optional: Map of `{ [currentKey]: newKey }` applied recursively, to align naming (e.g. `{ colors: "color" }`).
  },
);
```

就基本用途而言 `props` 财务报告和审定财务报表 `filename` 论据是必要的.

可选参数为先进的情景提供了灵活性.

```js
import { propsBuilder } from "@fylgja/props-builder";

propsBuilder(
  {
    color: {
      red: "#f00",
      green: "#0f0",
      blue: "#00f",
    },
  },
  "output.css",
);
```

这将生成输出.cs,其内容如下:

```css
:where(:root) {
  --color-red: #f00;
  --color-green: #0f0;
  --color-blue: #00f;
}
```

此示例显示一个简单 JavaScript 对象的简单用例 .

### 输出格式

输出格式取自文件名, 除非 `parseAs` 已经设定.

| 文件名 | `parseAs` | 产出 |
| --- | --- | --- |
| `*.css` | `css` | CSS 自定义属性 |
| `*.scss` | `scss` | SCSS 变量 |
| `*.js`, (中文(简体) ), `*.mjs`, (中文(简体) ), `*.cjs`, (中文(简体) ), `*.json` | `mjs`, (中文(简体) ), `cjs`, (中文(简体) ), `json` | 道具现在 |
| `*.resolver.json` | `dtcg` | 设计 Tokens Resolutionr (2025. 10) |
| `*tokens.json` | `tokens` | 设计 Tokens(语法草案) |
| `*figma-tokens.json` | `figma` | 图片 |
| `*style-dictionary-tokens.json` | `style-dictionary` | 样式词典符号 |
|  | `css-jit` | JIT 工具的平面对象, 如 jit- props |

### 设计托肯斯2025.10

这个 `dtcg` 输出跟随 [设计托肯斯2025.10规格](https://www.designtokens.org/tr/2025.10/)。 。 。 . 值被转换成打入符值,例如. `0.5rem` 变成一个 `dimension` 符号 `{ "value": 0.5, "unit": "rem" }`, (中文(简体) ), 财务报告和审定财务报表 `var(--shadow-color)` 变成一个 `{shadow-color.$root}` 参考文献.

```js
propsBuilder(props, "tokens/fylgja.resolver.json", { name: "Fylgja" });
```

所有符号都用一个单一的解析器文档进行。 暗模式值( R)`@media:dark`)被排除在外.

规格无法表达一些 CSS 值, 例如 `calc()`, (中文(简体) ), `clamp()`, (中文(简体) ), `var()` 在颜色内,或除 `px` 财务报告和审定财务报表 `rem` (或 `ms` 财务报告和审定财务报表 `s` 页:1. 警告和任何引用这些迹象的标志.

关于更高级的情景,包括如何使用不同的JSON文件格式,见下文"从设计托肯斯到CSS"部分.

### 从设计托肯斯到CSS

使用带有 JSON 文件的Propals 构建器是一个常用案例. 过程是直截了当的,根据您的 JSON 文件格式进行小调整.

#### 1\. 创建您的 Design Tokens 文件

您的JSON文件可以是一个简单的密钥值对象,也可以遵循像W3C Design Tokens spec或由Figma Tokens插件所导出的格式这样的标准格式.

#### 2\. 创建构建脚本

创建一个Node.js脚本(例如, `build.js`)读取您的令牌文件并运行构建器.

```js
import { readFileSync } from "node:fs";
import { propsBuilder } from "@fylgja/props-builder";

// Read and parse the JSON file
const tokens = JSON.parse(readFileSync("path/to/your/tokens.json", "utf-8"));

// 👇 Configure the builder based on your token format
const options = {
  // inputTypeTokens: ...,
  // inputTypeSyntax: ...,
};

// Build the CSS file
propsBuilder(tokens, "tokens.css", options);

console.log("Successfully built tokens.css!");
```

#### 3\. 配置构建器

关键步骤是配置 `options` 对象基于您的 JSON 文件格式.

-   **对于一个简单,密钥值的JSON文件:** 你不需要任何特别的选择 建造者默认处理.
    
    ```js
    const options = {};
    ```
    
-   **对于一个W3C Design Tokens spec文件(包括2025.10和Resolter文件):** 设定 `inputTypeTokens` 改为 `true`。 。 。 .
    
    ```js
    const options = { inputTypeTokens: true };
    ```
    
    Design Tokens 2025.10 数值,如彩色对象或维度被转换为 CSS 值. 综合符号成为CSS的简称(`border`, (中文(简体) ), `shadow`, (中文(简体) ), `transition`,而渐变颜色停止), 除外 `typography`,它成为每个部分的自定义属性(例如. `--heading-font-size`) (中文(简体) ). 团体支助 `$type` 遗产, `$root` 标志,和 `$extends`。 。 。 . 两者 `{token.path}` 参考文献 `$ref` 贾森 支持同一文件中的指针.
    
    对于解析器文件,所有集按解析顺序合并,每个修改器使用其 `default` 上下文. A 类 `$ref` 不支持其它文件,而是先将这些文件合并为一个文档.
    
-   **对于 Figma Tokens 文件 :** 设定 `inputTypeTokens` 改为 `true` 财务报告和审定财务报表 `inputTypeSyntax` 改为 `'figma'`。 。 。 .
    
    ```js
    const options = {
      inputTypeTokens: true,
      inputTypeSyntax: "figma",
    };
    ```
    
-   **对于一个 Google Stitch Markdown 导出:** 设定 `inputTypeTokens` 改为 `true` 财务报告和审定财务报表 `inputTypeSyntax` 改为 `'stitch'`。 。 。 . 传出原始 Markdown 文件内容( a string) 为 `props`,不是解析对象. 仅使用YAML前题,其中的每个密钥被转换为符号,只有已知的元数据密钥除外(`name`, (中文(简体) ), `description`) (中文(简体) ). 这个 `colors` 组自动更名为单数 `color` (除非 `color` 组已经存在).
    
    ```js
    const options = {
      inputTypeTokens: true,
      inputTypeSyntax: "stitch",
    };
    ```
    

#### 4\. 运行构建脚本

最后,从终端运行您的脚本:

```sh
node build.js
```

这将生成一个 `tokens.css` 带有 CSS 自定义属性的文件.

## 常见问题

### @fylgja/props-builder 是什么？

从 JavaScript 对象中不费力地生成 Design Tokens \(CSS自定义属性\)\.

### 如何安装 @fylgja/props-builder？

在项目目录运行 npm install @fylgja/props-builder，或使用 pnpm add / yarn add / bun add。

### @fylgja/props-builder 支持 TypeScript 吗？

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

### @fylgja/props-builder 支持 ESM 还是 CommonJS？

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

### @fylgja/props-builder 可以商用吗？

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

### @fylgja/props-builder 的下载量有多少？

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

### @fylgja/props-builder 还在维护吗？

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