# @cdx-ui/theme-editor 中文文档

规范地址：https://npmcn.com/package/%40cdx-ui/theme-editor/

版本：0\.3\.12
npm 元数据更新时间：2026-11-04T15:36:40.436Z
中文译文更新时间：2026-11-09T13:21:46.346Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cdx-ui/theme-editor
原文对照：https://npmcn.com/package/%40cdx-ui/theme-editor/?lang=original
项目主页：https://github.com/dfh-candescent/forge-design-system#readme
源码仓库：https://github.com/dfh-candescent/forge-design-system

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

- 包体积（解压后）：354 kB，115 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，uniwind \>=1\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0，react-native-web \>=0\.19\.0
- 首次发布：2026-06-18T19:35:08.533Z
- 最新版本发布：2026-11-04T15:36:40.255Z
- 近 30 天下载量：2563（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：159（近 12 个月 159 个）

## 中文简介

![coverage](https://unpkg.com/@cdx-ui/theme-editor/coverage.svg)

## 安装

```sh
npm install @cdx-ui/theme-editor
```

也可以使用：`pnpm add @cdx-ui/theme-editor`、`yarn add @cdx-ui/theme-editor`、`bun add @cdx-ui/theme-editor`

## README

# @cdx-ui/主题编辑器

![coverage](https://unpkg.com/@cdx-ui/theme-editor/coverage.svg)

用于编写 Forge 设计系统的 仅限网页的导读编辑器 `ThemeOverride` 贾森。 金融机构通过Forge UI控制选择基因输入和包自有语义选择,而活面板则预览真实的Forge UI组件. 编辑器只发布 FI 的意向; 消费应用程序持续它并在运行时应用它 `@cdx-ui/styles`。 。 。 .

> **网易一览.** 编辑器使用浏览器API和回放原生网络. 它没有在本地平台上提供.

## 安装

```bash
pnpm add @cdx-ui/theme-editor @cdx-ui/components @cdx-ui/styles
```

`react`, (中文(简体) ), `react-dom`, (中文(简体) ), `react-native-web`,以及 `uniwind` 是同伴的依赖性——应用已经消耗 `@cdx-ui/components` 将会有这些。 声明 `@cdx-ui/components` 财务报告和审定财务报表 `@cdx-ui/styles` 当直接导入其提供者和类型如下所示时;编辑器自动解决其内部的Forge UI依赖性.

## 使用量

### 1\. 将编辑器添加到您的 Tailwind 源头

预览使Forge UI组件具有Uniwind 工具类. 喜欢 其他项目 `@cdx-ui/*` 包,这个包船 **没有预先编译的 CSS 或令牌** —— 说 联合国 `./styles.css` 是尾风 v4 `@source` 添加编辑器的指令 源到您的内容扫描, 从而生成预览的功能 。 导入 在您的 Tailwind 条目样式表中, 与其它设计系统一起 :

```css
@import 'tailwindcss';
@import 'uniwind';

@import '@cdx-ui/styles/theme.css';
@import '@cdx-ui/styles/utilities.css';
@import '@cdx-ui/components/styles.css';
@import '@cdx-ui/theme-editor/styles.css';
```

### 2\. 装入编辑器

`onChange` 用户编辑带有有效目标的控件后起火( 已失效, ~ 200ms) `ThemeOverride`它没有被调用。 坚持有效载荷从 `onChange`; 生产 消费者在应用程序启动时应用一次 :

```tsx
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { ThemeEditor } from '@cdx-ui/theme-editor';
import { ForgeDesignProvider } from '@cdx-ui/components';
import type { ThemeOverride } from '@cdx-ui/styles';

function ThemeConfigPage() {
  const handleChange = (override: ThemeOverride) => {
    void persistOverride(override); // your save (e.g. POST /api/themes)
  };

  return (
    <SafeAreaProvider>
      <ForgeDesignProvider>
        <ThemeEditor onChange={handleChange} showGetCode showThemeModeToggle />
      </ForgeDesignProvider>
    </SafeAreaProvider>
  );
}
```

`showGetCode` 打开 Forge 用户界面 `Dialog`。在应用程序根附近挂载一个门户网站主机: `ForgeDesignProvider` 自动包含,必须留在应用程序内 `SafeAreaProvider`。如果应用程序不使用 Forge 提供者,请保留 `SafeAreaProvider` 挂载 一个 `PortalHost` 从 `@cdx-ui/primitives` 换句话说 不要同时挂载;没有其中之一 对话框在状态中打开但不会弹出 .

编辑器解析并扩展到 `@cdx-ui/styles`,评估共享规则,并驱动预览 通过一个很好的覆盖会议。 清除不倾倒地恢复管理的基准值 无关变量。 重装仍然是物理写作失败后的恢复边界.

### 3\. 编辑已有的覆盖

通过先前保存的覆盖为 `initialValue` ; 控制种子 `inputs`数字 :

```tsx
<ThemeEditor initialValue={savedOverride} onChange={handleChange} />
```

## 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `onChange` | `(override: ThemeOverride) => void` | —— 说 | **要求.** 在用户编辑当前控件后调用( 已取消, ~ 200ms) `ThemeOverride`。在彩色输入无效的情况下,不调用挂载. |
| `initialValue` | `unknown` | —— 说 | 解析用于编辑模式的持久值,并显示无效或不支持的有效载荷诊断. |
| `showGetCode` | `boolean` | `false` | 显示一个“ 获取代码” 按钮, 打开一个带有覆盖输出的对话框和一个复制到剪贴板按钮 . |
| `showThemeModeToggle` | `boolean` | `false` | 显示一个光/ 暗切换预览表面 . |

这个 `ThemeOverride` 形状和运行时间在 [`@cdx-ui/styles`](https://www.npmjs.com/package/@cdx-ui/styles)。 。 。 .

## 行为说明

-   **专意出出.** 未触及预览默认值、 衍生出碱基、 食谱成员并生成 调色板被省略。 进取添加剂未知字段被保留.
-   **基础.** Base 来源于 Brand 直至明确被钉入; 解接去除 `basePrimary` 意图.
-   **字相会.** 每个目录家族都有。 选择 **默认** 清除写入的字体意图和 恢复生成的基线家族.
-   **规矩.** 核准结构/源设置错误块输出。 临时视觉校准 仍然只发出警告.
-   **现场预览.** 覆盖的会话写着当前零星的意向和混凝土倒计时 清除先前管理过的写法所需的值.
-   **预览隔离.** 预览被包裹在 `ScopedTheme` 因此光/暗切只会影响预览表面,而不是编辑器的铬.

## 软件包结构

```
theme-editor/
├── src/
│   ├── index.ts            # Public exports (ThemeEditor, ThemeEditorProps)
│   ├── styles.css          # `@source` directive — published as the ./styles.css export
│   ├── ThemeEditor.tsx     # Top-level component: state, debounced apply/emit, Dialog, toggle
│   ├── PreviewPanel.tsx    # Live preview surface (ScopedTheme + banking artboard)
│   ├── override/           # Draft provenance, serialization, controls, rules/runtime handoff
│   ├── validation.ts       # Hex validation
│   ├── fonts.ts            # Exact Google Fonts loading for display/platform families
│   ├── controls/           # FontControl, ColorControl, catalog-driven renderer
│   ├── components/         # ColorPickerInput
│   └── previews/           # Forge UI sample cards rendered in the preview
├── global.css              # Tailwind/Uniwind entry for the build (not published)
├── vite.config.ts
└── package.json
```

## 大楼

```bash
pnpm --filter @cdx-ui/theme-editor build
```

虚拟捆绑 `src/index.ts` 改为 `dist/index.js` (外部化 React、React 原生网络、 Uniwind 和 `@cdx-ui/*` 软件包; `tsc` 发表声明。 没有发射CSS—— `src/styles.css` (单位:千美元) `@source` communicipality)作为-is发布,并和消费者的"尾风"(Tailwind building)一起作曲.

## 进一步阅读

-   [设计符号](https://design.candescent.com/docs/foundations/styles/tokens/what-are-tokens) 标志和主题如何运作
-   [`@cdx-ui/styles`](https://www.npmjs.com/package/@cdx-ui/styles) ——基准令牌,覆接和运行时间应用程序
-   存放处的代号-存档文件记录了超载有效载荷合同和建造/运行时间界限.

## 许可证

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

麻省理工学院 2026 Digital First Holdings LLC. 包装的许可证全文 `LICENSE`。 。 。 .

## 常见问题

### 如何安装 @cdx-ui/theme-editor？

在项目目录运行 npm install @cdx-ui/theme-editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、uniwind（\>=1\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）、react-native-web（\>=0\.19\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cdx-ui/theme-editor 支持 TypeScript 吗？

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

### @cdx-ui/theme-editor 支持 ESM 还是 CommonJS？

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

### @cdx-ui/theme-editor 可以商用吗？

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

### @cdx-ui/theme-editor 的下载量有多少？

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

### @cdx-ui/theme-editor 还在维护吗？

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