企业官网建设流程全解析

• UI组件
• 前端

ng-zorro-antd（Angular UI 组件库）在传统的 less 定制主题 之外，提供了一套基于 CSS Variable 的动态主题方案：通过替换一个入口样式文件、注入一份NzConfig全局配置，即可在不重新编译 less、不刷新页面的前提下，于运行时动态切换主色等主题变量。阅读本文后，你将掌握如何引入 CSS Variable 版本样式、通过静态配置与NzConfigService.set()两种方式驱动主题、处理多份 CSS 前缀冲突，并理解这套方案在仓库源码中的底层实现原理与适用边界。

一、动态主题是什么：与 less 定制主题的区别

传统的 less 主题定制思路是在编译期用自定义的 less 变量覆盖默认值，因此主题在构建时就被“固化”进了 CSS 产物，想换一套主题就必须重新编译。ng-zorro-antd 提供的 CSS Variable（动态主题）方案则把关键颜色（主色、成功色、警告色、错误色、信息色）抽离为运行时可覆盖的 CSS 自定义属性，所有组件样式统一引用这些变量，从而实现了运行时换肤的能力。

从仓库的入口文件可以清楚看到两者的差异。普通版本入口 components/ng-zorro-antd.less 引入的是./style/default.less，而 CSS Variable 版本入口 components/ng-zorro-antd.variable.less 引入的是./style/variable.less：

// components/ng-zorro-antd.variable.less @import './style/variable.less'; @import './style/patch.less'; @import './components.less';

而 components/style/variable.less 的核心工作有两件：声明入口标识@root-entry-name: variable;，并导入 components/style/themes/variable.less。后者正是 CSS 变量的“大本营”——它在html选择器下集中定义了--ant-primary-color、--ant-success-color、--ant-error-color等一批 CSS 变量，同时用~'var(--@{ant-prefix}-primary-color)'这样的字符串把原先硬编码的 less 变量（如@primary-color）改造成对 CSS 变量的引用，从而让整库组件样式都“跟随”变量变化。

重要限制：该功能依赖浏览器原生 CSS Variable 能力，在 IE 中页面将无法正常展示，使用时需注意目标浏览器环境。

二、第一步：引入 CSS Variable 版本样式

使用动态主题的第一步是替换项目中的样式引入。找到当前引入样式文件的地方，将其从普通版本替换为 CSS Variable 版本：

- @import "~ng-zorro-antd/ng-zorro-antd.min.css"; + @import "~ng-zorro-antd/ng-zorro-antd.variable.min.css";

配套的入口文件是 components/ng-zorro-antd.variable.less（源码入口）以及由它编译产出的.variable.min.css（构建产物）。

需要特别留意的是：如果你使用了babel-plugin-import做按需引入，必须将其去除。原因在于babel-plugin-import会把组件样式按需单独引入为普通版本的 less 文件，与全局的 CSS Variable 版本样式混用后，会造成同一组件同时存在两套样式体系，导致变量主题无法生效或样式冲突。

三、静态方式配置主题：通过 NZ_CONFIG 注入

替换完样式文件后，主题还不会自动生效，需要主动告诉 ng-zorro-antd 你要使用哪个主题颜色。仓库利用全局配置项功能：在根注入器中根据注入令牌NZ_CONFIG提供一个符合NzConfig接口的对象，其中theme字段用来描述主题。

以 Angular 的ApplicationConfig为例：

import { NzConfig, provideNzConfig } from 'ng-zorro-antd/core/config'; const ngZorroConfig: NzConfig = { // 注意组件名称没有 nz 前缀 theme: { primaryColor: '#1890ff' } }; export const appConfig: ApplicationConfig = { providers: [provideNzConfig(ngZorroConfig)] };

这些全局配置项会被注入到NzConfigService中并保存。从源码看，NzConfigService的构造函数会立即检查config.theme是否存在（参见 components/core/config/config.service.ts），一旦存在就会调用registerTheme()把主题对应的 CSS 变量动态写入页面，确保样式在应用启动时就处于正确的主题状态：

constructor() { if (this.config.theme) { // If theme is set with NZ_CONFIG, register theme to make sure css variables work registerTheme(this.getConfig().prefixCls?.prefixCls || defaultPrefixCls, this.config.theme, this.cspNonce); } }

Theme接口在 components/core/config/config.ts 中定义，包含以下可选颜色字段（均以颜色字符串赋值）：

注意NzConfig中的键名（如theme、button、table等）都是不带nz前缀的组件名，而theme是其中专门负责主题颜色的一个配置键。

四、运行时动态变更：NzConfigService.set()

静态配置只解决“启动即生效”。CSS Variable 方案真正的价值在于运行时换肤——通过调用NzConfigService的set方法来动态改变主题配置：

import { NzConfigService } from 'ng-zorro-antd/core/config'; @Component({ selector: 'app-change-zorro-config' }) export class ChangeZorroConfigComponent { private nzConfigService = inject(NzConfigService); onChangeConfig() { this.nzConfigService.set('theme', { primaryColor: '#1890ff' }); } }

执行set('theme', ...)后，仓库的NzConfigService内部做了三件事（参见 config.service.ts）：

1. 合并配置：this.config[componentName] = { ...this.config[componentName], ...value }，只覆盖传入的字段，未传入的主题字段保持原值；
2. 注册主题：当变更的键是theme时，调用registerTheme()重新计算全部 CSS 变量并写入页面样式；
3. 广播事件：通过configUpdated$流发出theme变更事件，供依赖方响应。

只要组件没有被单独赋值（例如组件实例上显式设置了对应输入属性），所有的组件实例都会响应这些改变。这得益于WithConfig装饰器 /withConfigFactory的取值逻辑：组件属性取值优先级为“用户显式赋值 > 全局配置 > 默认值”，因此全局主题变化能自动传播到所有未覆盖的组件实例上。

动态主题的底层实现：css-variables.ts

运行时主题不是简单地把某个 CSS 变量替换掉，而是由 components/core/config/css-variables.ts 中的getStyle()依据传入的颜色，通过@ctrl/tinycolor与ng-zorro-antd/core/color的颜色生成算法，计算出一整组衍生色变量再写入页面：

• 主色会生成--ant-primary-color、--ant-primary-1至--ant-primary-7的完整色阶（例如浅色背景primary-1、hover 用primary-5、active 用primary-7），保证按钮、选中态、表格行等各场景的颜色协调；
• 同时生成一批兼容旧版语义的 deprecated 变量（如--ant-primary-color-deprecated-l-35、--ant-primary-color-active-deprecated-f-30等），让老版本 less 变量引用能平滑过渡；
• success / warning / error / info 四类语义色则通过fillColor()统一生成各自的 color、hover、active、outline、deprecated-bg、deprecated-border 变量。

生成的样式最终以:root { --ant-xxx: ...; }的形式，通过updateCSS()动态注入<style>标签（支持 CSPnonce）。在 SSR 环境下，registerTheme()会输出警告：NzConfigService: SSR do not support dynamic theme with css variables.——即服务端渲染场景不支持基于 CSS Variable 的动态主题，这也是方案的一个重要边界。

五、冲突解决：自定义 CSS 变量前缀

默认情况下，CSS Variable 以--ant作为前缀（对应 less 变量@ant-prefix: ant，定义见 components/style/themes/variable.less）。当你的项目中同时引用了多份 CSS 文件（例如同时存在其他基于 Ant Design 的样式体系，或自建了一套--ant-*变量），就可能发生变量名冲突，此时可以通过修改前缀来规避。

编译 less 生成自定义前缀的 CSS

由于前缀变更后原有.variable.min.css不再适用，需要重新编译一份对应前缀的 CSS 文件。使用lessc配合--modify-var覆盖ant-prefix变量即可：

lessc --js --modify-var="ant-prefix=custom" ng-zorro-antd/ng-zorro-antd.variable.less modified.css

编译完成后，页面中生成的主题变量会变成--custom-primary-color、--custom-success-color等。同时，代码层面的配置也需要保持一致：NzConfig中提供prefixCls.prefixCls字段来声明自定义前缀，NzConfigService在调用registerTheme()时会读取它作为 CSS 变量的实际前缀（未配置时回退到默认值ant，参见 config.service.ts 与 css-variables.ts）。

六、相关变更说明：@root-entry-name 入口注入

为了实现 CSS Variable 并保持与原始用法的兼容，仓库在各ng-zorro-antd.xxx.less入口文件中添加了@root-entry-name: xxx;这一入口注入变量，用于在 less 编译期动态加载对应的 less 文件。

以本仓库为例：

• components/ng-zorro-antd.less → 经 components/style/default.less 声明@root-entry-name: default;；
• components/ng-zorro-antd.variable.less → 经 components/style/variable.less 声明@root-entry-name: variable;。

@root-entry-name相当于给入口文件打的“身份标签”，less 编译器据此在themes/目录下选择default.less还是variable.less作为主题变量来源（两者并列存放于 components/style/themes）。对于绝大多数使用者而言，只需按照文档替换样式入口即可，一般不需要关注该变化；只有在自行基于源码 less 重新编译或做深度定制时才可能接触到这一机制。

七、总结与注意事项

CSS Variable 动态主题方案的使用链路可以概括为三步：替换样式入口 → 注入NZ_CONFIG全局配置 → （可选）运行时调用set('theme', ...)换肤。落地时请重点确认以下几点：

1. 浏览器兼容：依赖原生 CSS Variable，IE 无法正常展示；
2. 按需引入冲突：若使用babel-plugin-import必须移除，避免混用普通版按需样式；
3. SSR 限制：服务端渲染场景下registerTheme()不生效，动态主题仅在浏览器端可用；
4. 前缀冲突：多份 CSS 并存时，可通过lessc --modify-var="ant-prefix=xxx"重新编译并配套配置prefixCls；
5. 组件实例优先级：被组件实例单独赋值的属性不会被全局主题覆盖，这是设计使然而非缺陷。

相关源码均可直接在仓库中查看：样式入口 components/ng-zorro-antd.variable.less、CSS 变量定义 components/style/themes/variable.less、运行时主题注册 components/core/config/css-variables.ts、全局配置服务 components/core/config/config.service.ts。

• UI组件
• 前端