# @db-ux/core-postcss-plugin 中文文档

规范地址：https://npmcn.com/package/%40db-ux/core-postcss-plugin/

版本：6\.4\.0
npm 元数据更新时间：2026-11-12T10:10:19.421Z
中文译文更新时间：2026-11-13T04:00:54.584Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40db-ux/core-postcss-plugin
原文对照：https://npmcn.com/package/%40db-ux/core-postcss-plugin/?lang=original
源码仓库：https://github.com/db-ux-design-system/core-web

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

- 包体积（解压后）：51.1 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：postcss ^8\.0\.0
- 首次发布：2026-04-07T10:21:50.356Z
- 最新版本发布：2026-11-12T10:10:18.938Z
- 近 30 天下载量：2340（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

DB UX 设计系统的 PostCSS 插件

## 安装

```sh
npm install @db-ux/core-postcss-plugin
```

也可以使用：`pnpm add @db-ux/core-postcss-plugin`、`yarn add @db-ux/core-postcss-plugin`、`bun add @db-ux/core-postcss-plugin`

## README

# @db-ux/核心-后置插件

DB UX设计系统的后CSS插件.

## 插件

| 插件 | 说明 |
| --- | --- |
| `dbUxFlatten` | 通过解析平整 CSS 自定义属性 `var()`, (中文(简体) ), `@property`, (中文(简体) ), `calc()`, (中文(简体) ), `color-mix()`,以及 `light-dark()` |

## 安装

```shell
npm install @db-ux/core-postcss-plugin --save-dev
```

## 进口

```ts
// Named import (recommended)
import { dbUxFlatten } from "@db-ux/core-postcss-plugin";

// Default import (backward compatible — exports dbUxFlatten)
import dbUxFlatten from "@db-ux/core-postcss-plugin";
```

## CSS 设置

使用 `@layer` 以确保主题覆盖基础组件样式。 插件检测 `@import ... layer()` 规则为每个文件指定正确的层 :

```css
/* styles.css */
@layer db-ux, db-theme;
@import "@db-ux/db-theme/build/styles/rollup.css" layer(db-theme);
@import "@db-ux/core-components/build/styles/rollup.css" layer(db-ux);
```

## 框架整合

### Vite (反应, Vue, Svelte等)

直接在其中配置插件 `vite.config.ts`数字 :

```ts
// vite.config.ts
import { defineConfig } from "vite";
import { dbUxFlatten } from "@db-ux/core-postcss-plugin";

export default defineConfig({
    css: {
        transformer: "postcss", // required for Vite 8+ (default: 'lightningcss')
        postcss: {
            plugins: [dbUxFlatten()]
        }
    }
});
```

> **说明**: Vite 8+ 用途 `lightningcss` 作为默认的 CSS 变压器,它不运行 PostCSS 插件。 设定 `css.transformer: 'postcss'` 以启用 PostCSS 处理。 Vite 7 并默认提前使用 PostCSS, 不需要此选项 .

工作在 Dev 和 构建模式.

### 角质

创建一个 `postcss.config.json` 在您的工程根中 :

```json
{
    "plugins": {
        "@db-ux/core-postcss-plugin": {}
    }
}
```

角 CLI (英语:`@angular/build:application`)只支持基于 JSON 的 PostCSS 配置和加载插件 `require()`两者都起作用 `ng build` 财务报告和审定财务报表 `ng serve`。 。 。 .

### 下一个.js

创建一个 `postcss.config.mjs` 在您的工程根中 :

```js
// postcss.config.mjs
import { dbUxFlatten } from "@db-ux/core-postcss-plugin";

export default {
    plugins: [dbUxFlatten()]
};
```

工作与网络包装和涡轮包装.

> **说明**: 用于通用JS(`postcss.config.js`:
> 
> ```js
> const { dbUxFlatten } = require("@db-ux/core-postcss-plugin");
> module.exports = { plugins: [dbUxFlatten()] };
> ```

### 网络包装( 独立)

```js
// webpack.config.js
const { dbUxFlatten } = require("@db-ux/core-postcss-plugin");

module.exports = {
    module: {
        rules: [
            {
                test: /\.css$/,
                use: [
                    "style-loader",
                    "css-loader",
                    {
                        loader: "postcss-loader",
                        options: {
                            postcssOptions: {
                                plugins: [dbUxFlatten()]
                            }
                        }
                    }
                ]
            }
        ]
    }
};
```

* * *

## `dbUxFlatten`

Flattens DB UX 设计系统 CSS 通过解析自定义属性 `var()`, (中文(简体) ), `@property`, (中文(简体) ), `calc()`, (中文(简体) ), `color-mix()`,以及 `light-dark()`。 。 。 .

### 它会做什么

1.  **收藏** 全部 `@property` 声明及其 `initial-value` 作为分辨率缓存
2.  **探测器 `@layer` 优先级** 从 `@layer` 命令声明和 `@import ... layer()` 规则——主题值凌驾于基础值之上,无论处理顺序如何
3.  **检测动态变量** 必须保持为 `var()` 参考文献 :
    -   在非`:root`编号 :`:host` 选择器(例如). `[data-density=functional]`(中文(简体) )
    -   内部重新声明变量 `@media` 查询
    -   匹配变量 `dynamicPrefixes` (默认 : `--db-adaptive-*`(中文(简体) )
4.  **决定:** 所有静态 `var()` 递归性参考——包括嵌入式参考 `var()` 倒计时 `var(--a, var(--b))`
5.  **评价** `calc()` 当所有值都是静态时表达式
6.  **评价** `color-mix(in srgb, ...)` 当所有颜色都解决时
7.  **折叠** `light-dark(x, y)` 改为 `x` 当两个论点在解决后相同时
8.  **删除** `@property` 规则和未使用的中期声明

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `removeAtProperty` | `boolean` | `true` | 删除 `@property` 解析后的规则 |
| `removeResolved` | `boolean` | `true` | 删除声明从 `@property` 不再引用 |
| `dynamicPrefixes` | `string[]` | `['--db-adaptive-']` | 总是被视为动态且从未解决的可变前缀 |

```ts
dbUxFlatten({
    removeAtProperty: true,
    removeResolved: true,
    dynamicPrefixes: ["--db-adaptive-", "--my-custom-dynamic-"]
});
```

### 如何运作

#### 静态变量与动态变量

-   **静态**: 仅公布于 `:root`编号 :`:host` 财务报告和审定财务报表 `@property` ——安全地融入各地
-   **动态**:在类选择器,数据属性中重新声明, `@media` 查询或匹配 `dynamicPrefixes` ——必须保持 `var()` 参考文献

```css
/* Static — will be resolved */
@property --db-neutral-0 {
    syntax: "<color>";
    initial-value: #0d0e10;
    inherits: true;
}

/* Dynamic — stays as var() */
:root {
    --db-spacing-fixed-sm: 0.75rem;
}
[data-density="functional"] {
    --db-spacing-fixed-sm: 0.5rem; /* re-declared → dynamic */
}
```

#### `@layer` 财务报告和审定财务报表 `@import layer()` 支助

插件从两个来源检测层优先级:

1.  **`@layer` 命令声明**数字 : `@layer db-ux, db-theme;` ——列表后期=高优先级
2.  **`@import ... layer()` 规则**数字 : `@import "file.css" layer(db-theme);` ——将每个导入的文件映射到其图层

这即使在捆绑器独立处理每个导入的文件(例如Angular)时也是有效的,因为插件看到 `@import` 规则在条目 CSS 文件中,在导入文件处理前先构建一个文件到层映射.

```css
@layer db-ux, db-theme;
@import "@db-ux/db-theme/build/styles/rollup.css" layer(db-theme);
@import "@db-ux/core-components/build/styles/rollup.css" layer(db-ux);
```

未分层的 CSS 总是在所有层取胜,匹配 CSS 的 spec.

#### 嵌入 `var()` 有倒计时

```css
/* Input */
font-family: var(--db-icon-font-family, var(--db-icon-default-font-family));

/* Output (--db-icon-font-family unknown, --db-icon-default-font-family resolved) */
font-family: var(--db-icon-font-family, "db-default", icon-font-fallback);
```

#### `light-dark()` 崩溃

当两个参数解决到相同值时,函数会崩溃:

```css
/* Input */
--db-color: light-dark(
    var(--db-neutral-origin-light-default),
    var(--db-neutral-origin-dark-default)
);

/* Output (both resolve to #232529) */
--db-color: #232529;

/* Output (different values — kept) */
--db-color: light-dark(#232529, #f0f0f0);
```

### 示例

**输入 :**

```css
@layer db-ux, db-theme;

@layer db-theme {
    @property --db-brand-origin-light-default {
        syntax: "<color>";
        initial-value: #ec0016;
        inherits: true;
    }
    @property --db-brand-origin-dark-default {
        syntax: "<color>";
        initial-value: #ec0016;
        inherits: true;
    }
}

@layer db-ux {
    :root {
        --db-brand-origin-default: light-dark(
            var(--db-brand-origin-light-default),
            var(--db-brand-origin-dark-default)
        );
    }
    .button {
        color: var(--db-adaptive-on-bg-basic-emphasis-100-default);
        border-radius: var(--db-border-radius-xs);
    }
}
```

**输出 :**

```css
:root {
    --db-brand-origin-default: #ec0016;
}
.button {
    color: var(--db-adaptive-on-bg-basic-emphasis-100-default);
    border-radius: 0.25rem;
}
```

-   `--db-brand-origin-default`:双方都决心 `#ec0016` (主题价值) `light-dark()` 崩溃
-   `--db-adaptive-*`: 保持为 `var()` (动态前缀)
-   `--db-border-radius-xs`: 解决于 `@property` (静态)

* * *

## 软件包结构

```text
src/
├── index.ts                              # barrel export
└── plugins/
    └── flatten/
        ├── index.ts                      # dbUxFlatten plugin
        ├── data.ts                       # types & constants
        └── helpers/
            ├── css-parser.ts             # generic CSS string parsing
            ├── resolve.ts                # var(), calc(), color-mix() resolution
            ├── collect.ts                # PostCSS AST collection (layers, vars, imports)
            └── transform.ts             # transformRoot + collapseLightDark
```

## 常见问题

### @db-ux/core-postcss-plugin 是什么？

DB UX 设计系统的 PostCSS 插件

### 如何安装 @db-ux/core-postcss-plugin？

在项目目录运行 npm install @db-ux/core-postcss-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：postcss（^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @db-ux/core-postcss-plugin 支持 TypeScript 吗？

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

### @db-ux/core-postcss-plugin 支持 ESM 还是 CommonJS？

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

### @db-ux/core-postcss-plugin 可以商用吗？

@db-ux/core-postcss-plugin 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @db-ux/core-postcss-plugin 的下载量有多少？

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

### @db-ux/core-postcss-plugin 还在维护吗？

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