# @civitai/theme 中文文档

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

版本：0\.5\.2
npm 元数据更新时间：2026-10-03T23:43:57.371Z
中文译文更新时间：2026-11-09T22:32:39.141Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40civitai/theme
原文对照：https://npmcn.com/package/%40civitai/theme/?lang=original
项目主页：https://github.com/civitai/civitai-app-starters/tree/main/packages/civitai-theme#readme
源码仓库：https://github.com/civitai/civitai-app-starters

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

- 包体积（解压后）：95.3 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-07-22T16:06:20.712Z
- 最新版本发布：2026-10-03T23:43:57.073Z
- 近 30 天下载量：17179（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

框架-不可知 -- Civitai-\* 设计标志 从 Civitai 真实的曼汀主题衍生出构建时间. CSS+打入了JS+W3C DTCG.

## 安装

```sh
npm install @civitai/theme
```

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

## README

# @civitai/主题

框架不可知性 **设计符号**,在建时从 civitai 的真实 曼汀主题 3个相同的船 `--civitai-*` 契约 :

-   `dist/tokens.css` a 包括: `:root` + 键 `[data-theme='light'|'dark']` 样式表 (单位:千美元)`--civitai-*` 自定义属性; `<color>` 通过 `@property`) (中文(简体) ).
-   联合来文: `import { tokens, darkTokens, tokenVars, tokensCss } from '@civitai/theme'`。 。 。 .
-   `dist/tokens.dtcg.json` - 一个W3C **设计托肯斯社区小组** 导出 (单位:千美元)`$value`编号 :`$type`编号 :`$description`)用于与符号工具相接.

## 为什么生成( 非手写)

信使通过提供 销售复制品Civitai的 `createTheme` 覆盖( r)`src/theme.source.ts`通过曼汀的 **公开** 输油管- `mergeMantineTheme` → `defaultCssVariablesResolver` \* 过境 `var()` —— 重命名空格 `--civitai-*`这是同样的原始 Civitai 用于 `mantine-css-variables.ts`。 。 。 . `--mantine-*` 完全解决了,所以 `--civitai-*` 合同是独立的.

两种代号都从中消失了。 这个 **断点比例** 绕过 曼汀管线全通(见下文),少数标志声明明确 **轻/暗对** -见下一节.

四卫守之以正`pnpm --filter @civitai/theme test`:

-   **漂移护卫** - 读出civitai/civitai的现场 `ThemeProvider.tsx` 失败 如果售出调色板/`white`编号 :`black` 差异( 设置 `CIVITAI_REPO`; 跳过 ,当退出时,有明确的信息.
-   **断点漂移守护** - 同样,反对civitai `src/utils/breakpoints.json`。 。 。 .
-   **生成平价** ——承诺产生的来源+已建成的文物必须 byte-match a first generation,所以一出僵硬的手版不能滑过.
-   **px -not -em 守卫** ——自成一体;将断点符号钉入px 缩放并声明没有em值.

## 计划代号

自定义财产跨越阴影边界继承;祖先选择者这样做 而不是交叉一个。 因此,一个想要"光线下,地表下"的组件可以 只说成 `[data-theme='dark'] <descendant>` 内 `@civitai/components`,哪个 阴影根永远无法匹配( name`:host-context()` 从未运入过Firefox.

这些决定现在是象征性的—— `--civitai-card-border-width`, (中文(简体) ), `--civitai-color-track`, (中文(简体) ), `--civitai-color-segmented-bg` 财务报告和审定财务报表 `--civitai-color-media-placeholder`曼汀也没有随身携带 这些对的一面,所以 `TokenSpec.source` 财务报告和审定财务报表 `.literal` 每个接受a `{ light, dark }` 组合,根据它自己的方案可变地图解决.

`--civitai-card-border-width` 是一个 **宽度**,而非颜色: 暗去默认值 发线的盒子,透明颜色仍然会占据每张卡片的1px.

## 断点——px尺度,不是曼汀的em尺度

civitai已经 **两个** 并且他们同意一个关键:

| 缩放 | 页:1 | 静态 | 数字 | 长 | 页:1 |
| --- | --- | --- | --- | --- | --- |
| **ưμ㼯a** —— 说 `src/utils/breakpoints.json`由泰风和 `mantineContainerSizes`。 。 。 . **这个包裹发出这个.** | 480个 | 768 (英语) | 第1024号 | 第1184号 | 第1440号 |
| 曼汀的股票 **计划** 比例——在civitai中从未被压倒;每个Mantine响应道具的用途 | 576个 | 768 (英语) | 992号 | 1200号 | 1408号 |

仅 `sm` 匹配,所以执行错误 _看着_ 直观和 测试针头 `sm` 单靠着错的尺度 px 缩放为 因此,在自己的单元中销售`src/breakpoints.source.ts`),被守卫 直接反对 `breakpoints.json`,并作为 **字义** 符号规格 永远不要碰 `mergeMantineTheme` -通过曼汀解析器 确切地说,一个未被推翻的密钥 如何会悄悄地作为价值回来.

```ts
import { breakpoints, BREAKPOINT_KEYS, tokens } from '@civitai/theme';
breakpoints.md;          // 1024   ← use this for a JS width comparison
tokens.bpMd;             // "1024px"
// CSS: var(--civitai-bp-md)
```

使用 **数字** `breakpoints` 宽度比较: CSS 自定义属性 无法在其中显示 `@media`编号 :`@container` 条件,所以 `--civitai-bp-*` 实值 长度(`max-width`, (中文(简体) ), `grid-template-columns`),条件并非如此. 反应 块应该使用 `useBlockBreakpoint()` 从 `@civitai/blocks-react`,哪个 解析此块的自测量宽度 .

## 使用量

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@civitai/theme/styles.css" />
```

目的未转换:它跟踪 `latest` dot -tag,所以你装的标志 总是包括上面提到的那些 固定的 URL 继续返回 **200个 带有旧样式表** —— 说 `@0.2.0`,这个读取器的版本直到现在, 携带 **零** `--civitai-bp-*` 标志,所以每个 `var(--civitai-bp-md)` 打开 此页面已解为空 。 只有需要可复制的构件时,才使用平面 升级时重新检查指针.

```ts
import { injectTokens, tokens } from '@civitai/theme';
injectTokens();          // inject the stylesheet at runtime (JS consumers)
tokens.colorPrimary;     // "#228BE6"
```

设定主题 `data-theme="light" | "dark"` 任何祖先都一样.

**黑暗是基地,这里没有 咨询操作系统.** `:root` 带着黑暗 调色板外加 `color-scheme: dark`因此,一个元素没有 `data-theme` 上边是 黑暗——在任何机器上,在任何OS偏好下. `[data-theme='light']` 是一个完整的 光调色板的镜子 是唯一能放回光线的东西; `[data-theme='dark']` 恢复光子树内部的黑暗. 属性是 胜过它,无论它坐在哪里 它都胜过它 因为一个更接近祖先的代号继承 在更远的地方.

### 重排一个符号( 品牌覆盖)

🔴 **在SPOPE上安装一个符号控制器,永远不要打开 `:root`。 。 。 .** 此工作表没有 级联层及其 `:root` 编号 : `[data-theme='…']` 块坐到特定位置 `0-1-0` 所以一个消费者的 `:root { --civitai-color-primary: … }` 没有 胜过他们,它 **链接**,则文档中最后一个样式表获胜.

```css
.my-block { --civitai-color-primary: #a259ff; }   /* ✅ wins in either order */
:root     { --civitai-color-primary: #a259ff; }   /* ⚠️ wins only if this sheet loaded FIRST */
```

内线也一样 `style="--civitai-color-primary: …"`范围 数值达到 **内部** 组件阴影根, 因为自定义属性交叉 边界.

⚠️ **这个 `:root` 形式在框架产生的顺序中无声地失败.** `@civitai/blocks-react`是因为 `useBlocksStyles()` 电话 `injectTokens()` 从a `useEffect`,因此这些符号被附上 **之后** 捆绑注入的应用程序 样式表。 在铬中测量:a `:root` 以此顺序覆盖 此主题本身的值没有出错——无论是否 `data-theme` 现在,所以 主题属性不是原因。 完整命令×路线矩阵被固定在 `@civitai/components`' `test/token-override-order.browser.test.ts`。 。 。 .

**你无法做的事:** 定义您自己的主题。 此软件包导出代号 _数值_ 财务报告和审定财务报表 `injectTokens(doc?)`发电机是内部的,只有 字符串 `light` 财务报告和审定财务报表 `dark` 选择一个符号块 - `data-theme="mybrand"` 选择无并继承暗基。 重新显示符号集; 没有 命名主题 API.

这是故意的 **没有** `@media (prefers-color-scheme: …)` 块, 在任意 向上转 浏览器不能决定 Civitai 表面的主题: civitai.com 是 黑暗,而App Block的靴子也暗了,只从宿主身上取出光. ⚠️至 `0.5.0` 事实恰恰相反—— `:root` 轻而易举的黑暗通过 `@media (prefers-color-scheme: dark) { :root:not([data-theme]) { … } }` 所以,每一个 不可遵循操作系统设置的表面 `data-theme` 直接说到 打败它。 如果仅因为这个原因添加了这样的属性,就可以放弃.

关于联署材料出口的说明,其中指出: **没有** 更改: `tokens` 仍然是光线 地图和 `darkTokens` 黑暗的那个 这么说吧 `tokens` 不再描述什么 `:root` 发音——读作" `[data-theme='light']` 价值"。 这个名字保留下来了 故意的,所以这种释放打破了一件事(CSS默认)而不是两件事.

## 构建

`pnpm --filter @civitai/theme build` 重新生成 `src/tokens.generated.ts`, (中文(简体) ), `dist/tokens.css`,以及 `dist/tokens.dtcg.json`,然后汇编为 `tsc`。 。 。 .

## 常见问题

### @civitai/theme 是什么？

框架-不可知 -- Civitai-\* 设计标志 从 Civitai 真实的曼汀主题衍生出构建时间\. CSS\+打入了JS\+W3C DTCG\.

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

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

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

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

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

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

### @civitai/theme 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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