@db-ux/ 核心视频插件

用于优化DB UX设计系统 CSS导入的Vite插件. 自动只包含基于应用程序中使用的组件和类的 CSS .

安装

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

使用量

基本用途

将插件添加到您的 vite.config.js 或者说 vite.config.ts数字 :

import { defineConfig } from "vite";
import dbUxPlugin from "@db-ux/core-vite-plugin";

export default defineConfig({
    plugins: [dbUxPlugin()]
});

然后导入您的 CSS 文件的插件 :

/* styles.css or main.css */
@import "@db-ux/core-vite-plugin/index.css";

插件会自动处理主题检测,组件 CSS,以及基础样式.

移徙

如果您正在使用手动 CSS 层导入, 您可以用插件的单导入替换 :

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

/* After */
@import "@db-ux/core-vite-plugin/index.css";

高级使用

对于更多的控制,您可以配置插件 :

import { defineConfig } from "vite";
import dbUxPlugin from "@db-ux/core-vite-plugin";

export default defineConfig({
    plugins: [
        dbUxPlugin({
            include: {
                components: ["button", "input"], // Force include specific components
                foundations: ["helpers", "animations", "icons"], // Force include foundation features
                colors: ["neutral", "brand"], // Force include color schemes
                densities: ["regular", "functional"], // Force include densities
                fontSizes: ["body-md", "headline-lg"] // Force include font sizes
            },
            exclude: {
                components: ["tooltip"], // Exclude specific components
                foundations: ["elevation"], // Exclude foundation features
                colors: ["critical"], // Exclude color schemes
                densities: ["expressive"], // Exclude densities
                fontSizes: ["body-3xs"] // Exclude font sizes
            },
            optimize: true, // Remove unused CSS variable declarations to reduce bundle size (default: true).
            theme: "db-theme", // Specify preferred theme package name (e.g., "db-theme")
            additionalLayers: { after: ["ri-extension"] }, // Append custom layers to the auto-generated order
            debug: false // Generate detection report for debugging (default: false)
        })
    ]
});

配置

include

• 类型 : { components?: Component[], foundations?: FoundationFeature[], colors?: ColorScheme[], densities?: Density[], fontSizes?: FontSize[] }
• 强制包括特定组件、基础特征、颜色方案、密度或字体大小
• 基金会特征: icons, (中文(简体) ), helpers, (中文(简体) ), elevation, (中文(简体) ), animations, (中文(简体) ), code

exclude

• 类型 : { components?: Component[], foundations?: FoundationFeature[], colors?: ColorScheme[], densities?: Density[], fontSizes?: FontSize[] }
• 不包括特定组件、基础特征、颜色方案、密度或字体大小

optimize

• 类型 : boolean
• 默认 : true
• 删除未使用的 CSS 变量声明以缩小捆绑大小

theme

• 类型 : string
• 默认 : undefined
• 指定首选的主题包名称(例如, "db-theme") (中文(简体) ). 插件自动检测已安装的主题包 @db-ux/*-theme 或者说 @db-ux-inner-source/*-theme中选择特定主题.

additionalLayers

• 类型 : { before?: string[], after?: string[] }
• 默认 : undefined
• 在自动生成的层顺序之前或之后追加自定义 CSS 级联层 。 当您的工程在 DB UX 上定义自己的地层时有用 .

// Adds layers around the auto-generated ones
dbUxPlugin({
    additionalLayers: {
        before: ["reset"],
        after: ["ri-extension"]
    }
});
// → @layer reset, db-theme, db-ux, ri-extension;

overrideLayers

• 类型 : string[]
• 默认 : undefined
• 完全替换自动生成 @layer 带有自定义层顺序的语句。 设定时, additionalLayers 被忽略.

dbUxPlugin({
    overrideLayers: ["db-theme", "db-ux", "ri-extension"]
});
// → @layer db-theme, db-ux, ri-extension;

debug

• 类型 : boolean
• 默认 : false
• 生成 a db-ux-detection-report.json 用于调试目的。 本报告包含所有检测到的组件、颜色、密度和字体大小。 用于解决问题优化问题.

如何运作

插件分析您的源文件以检测 :

• DB UX 组件用法( 例如, ), class="db-button"(中文(简体) )
• 使用设计符号的自定义类
• 明确配置包括/不包括

然后生成一个最优化的 CSS 捆绑,只包含:

• 必需的基础样式(主题、字体、图标)
• 检测到组件的组件样式
• 基于配置的可选特性

解决问题

带有 Tailwind CSS 的插件顺序

如果你用Tailwind CSS 和这个插件一起, 命令事项编辑 @db-ux/core-vite-plugin 必须放置 在此之前 您 Vite 配置中的尾风插件 :

import { defineConfig } from "vite";
import dbUxPlugin from "@db-ux/core-vite-plugin";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
    plugins: [
        dbUxPlugin(), // Must come before tailwindcss()
        tailwindcss()
    ]
});

在你的CSS文件中:

@import "tailwindcss";
@import "@db-ux/core-vite-plugin/index.css";

为什么? DB UX 插件需要处理和替换 @import "@db-ux/core-vite-plugin/index.css" 在 Tailwind 处理文件之前使用 CSS 的语句。 Tailwind会剥出未识别的导入,所以DB UX插件必须先运行,才能将导入转换为有效的CSS,然后Tailwind可以处理.

支助科 @property 警告

您可以在您的构建输出或 IDE 中看到“ 规则未知 : @ property ” 的警告 。 这是来自CSS分析器的信息警告 还没有完全支持CSS胡迪尼 @property 规则。 这些警告不影响功能 - the @property 规则是有效的CSS,在现代浏览器中工作正确. 您可以安全忽略这些警告或配置您的 CSS 接口以压制它们 .

样式不装入 Dev 模式 <link> 标记

如果你通过一个 <link> 标记在 index.html数字 :

<!-- ❌ This won't work with the plugin in dev mode -->
<link rel="stylesheet" href="/src/styles.css" />

该插件的 transform 钩子只运行于属于Vite模块图的CSS. 静态 <link> 标记由 Vite 的 Dev 服务器提供,所以 @import "@db-ux/core-vite-plugin/index.css" cSS 文件内部从未处理过.

解决方案 : 从您的 JavaScript/ TypeScript 条目文件导入 CSS :

// main.ts or main.tsx
import "./styles.css";

这把CSS拉入了Vite的模块图中,插件可以在其中转换. 生产建设不受这一问题的影响.

许可证

这个项目的许可证根据 阿帕奇 - 2.0。 。 。 .