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

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

插件

安装

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

进口

// 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() 规则为每个文件指定正确的层 :

/* 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数字 :

// 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 在您的工程根中 :

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

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

下一个.js

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

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

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

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

说明: 用于通用JS(postcss.config.js:

const { dbUxFlatten } = require("@db-ux/core-postcss-plugin");
module.exports = { plugins: [dbUxFlatten()] };

网络包装( 独立)

// 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 规则和未使用的中期声明

选项

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

如何运作

静态变量与动态变量

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

/* 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 文件中,在导入文件处理前先构建一个文件到层映射.

@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() 有倒计时

/* 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() 崩溃

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

/* 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);

示例

输入 :

@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);
    }
}

输出 :

: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 (静态)

软件包结构

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