# @c2n/theme 中文文档

规范地址：https://npmcn.com/package/%40c2n/theme/

版本：1\.0\.23
npm 元数据更新时间：2026-11-07T18:02:54.219Z
中文译文更新时间：2026-11-08T22:36:15.765Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40c2n/theme
原文对照：https://npmcn.com/package/%40c2n/theme/?lang=original
项目主页：https://github.com/code2nguyen/web-components#readme
源码仓库：https://github.com/code2nguyen/web-components

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

- 包体积（解压后）：1.7 MB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-10T16:54:34.283Z
- 最新版本发布：2026-11-07T18:02:53.964Z
- 近 30 天下载量：3009（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

设计符号(--c2-主题-\*)和生成的基准主题,将每个 @c2n 组件 CSS 变量映射到它们上

## 安装

```sh
npm install @c2n/theme
```

也可以使用：`pnpm add @c2n/theme`、`yarn add @c2n/theme`、`bun add @c2n/theme`

## README

# @c2n/主题

设计符号 `@c2n/*` 网络组件,加a **生成的基础主题** 将每个组件 CSS 变量映射到它们上.

组件通过它们自己的CSS自定义属性(`--c2-button__container--background-color`大约总共700个). `@c2n/theme` 在上方添加一个便利层: ~35 共享的代币命名 `--c2-theme--<name>`。基准主题设置每个组件变量到 `var(--c2-theme--<token>, <component default>)` 时间 `:root`,所以应用程序只需要定义符号。 任何您设定的元件变量仍然会获胜 .

```bash
npm install @c2n/theme
```

```ts
import '@c2n/theme/theme.css' // tokens + base theme
```

```css
/* Your app: override a few tokens, every component follows. */
:root {
  --c2-theme--color-primary: #7c3aed;
  --c2-theme--radius-md: 10px;
  --c2-theme--font-family: 'Inter', system-ui, sans-serif;
}
```

## 文件

| 导出 | 内容 |
| --- | --- |
| `@c2n/theme/theme.css` | `tokens.css` + 键 `base.css` |
| `@c2n/theme/tokens.css` | 脚本默认值: 打开灯 `:root`, 暗处 `[data-theme='dark']` 编号 : `.c2-dark` 作为 `prefers-color-scheme: dark` 倒计时 |
| `@c2n/theme/base.css` | `--c2-<component>…: var(--c2-theme--…, <default>)` 用于每个映射组件变量。 如果您的应用程序已经定义了符号, 请单独使用 |
| `@c2n/theme/tokens.js` | 符号表作为 TypeScript ()`tokens`, (中文(简体) ), `TokenDef`(中文(简体) ) |
| `@c2n/theme/tokens.json` | 键+ `component variable → token` 绘图 |
| `@c2n/theme/report.json` | 每个软件包的覆盖范围和未映射的变量列表 |

## 黑暗模式

设定 `data-theme="dark"` (或 `c2-dark` 上课) `<html>` 或任何树下;没有它,OS优先. `data-theme="light"` 编号 : `c2-light` 选择出子树 .

## 叠加层

`tokens.css` 财务报告和审定财务报表 `base.css` 把每个规则都放进 `c2n-theme` [级联层](https://developer.mozilla.org/docs/Web/CSS/@layer)。一个无层规则比一个分层规则强,无论它的具体或源顺序如何,所以一个平地 `:root { --c2-theme--color-primary: … }` 在光线模式下覆盖符号 `data-theme="dark"` 在操作系统暗黑的倒计时下 你设定的元件变量也是一样 如果您的应用程序将自己的样式分层, 请声明 `c2n-theme` 首先,在一个 `@layer` 任何导入前的语句,所以它保持最低: `@layer c2n-theme, base, components;`在主题离开前导入的分层框架 `c2n-theme` 在它的地层上.

## 层

1.  **键** —— 说 `--c2-theme--*`,由应用程序设置.
2.  **基础主题** - 生成地图,船在这里.
3.  **构成部分变量** —— 说 `--c2-<component>__<part>[__<state>]--<property>`精良的逃生舱门.
4.  **App 变体组件** 重复的外观包裹在自己的组件中(见文件站点指南).

## 发展

`npm run build -w packages/tools/theme` 编译 `src/tokens.ts` 运行 `scripts/theme-generator`读取 `@c2n/*/custom-elements.json`,将每个文档的 CSS 变量分类(`scripts/theme-generator/classify.ts`除外情况 `overrides.ts`)并写作 `dist/`。构建取决于每个组件的构建,因此列表是新鲜的;控制台打印一个覆盖表和 `dist/report.json` 列出哪些内容没有被修改和原因.

一个组件可以记录其侧面变量背后的短手变量(`--c2-details--border` 后面 `--c2-details--border-top` 和另外三个,编为 `var(--c2-details--border-top, var(--c2-details--border, …))`) (中文(简体) ). 发电机读取了包裹的倒数 `dist/` 当每个侧面的可变地图精确到其短手地图的数值时,只将短手写到 `base.css` (单位:千美元)`scripts/theme-generator/shorthands.ts`:写出双方会让短手在主题下无法接触. 您设置的平方变量仍然取胜; `dist/report.json` 列出在 `coveredByShorthand`。 。 。 . `npm test -w packages/tools/theme` 运行发电机组测试.

`npm run dev -w packages/tools/theme` 打开 Vite 带 (`index.html`) 有主题组件, 暗相切换和符号覆盖 .

## 常见问题

### @c2n/theme 是什么？

设计符号\(--c2-主题-\*\)和生成的基准主题,将每个 @c2n 组件 CSS 变量映射到它们上

### 如何安装 @c2n/theme？

在项目目录运行 npm install @c2n/theme，或使用 pnpm add / yarn add / bun add。

### @c2n/theme 支持 TypeScript 吗？

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

### @c2n/theme 支持 ESM 还是 CommonJS？

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

### @c2n/theme 可以商用吗？

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

### @c2n/theme 的下载量有多少？

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

### @c2n/theme 还在维护吗？

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