PrimeNG Styled Mode 主题定制完全指南设计令牌驱动的样式架构与实战【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng本文基于本仓库中 Styled Mode 官方文档结合 themes 包 与 showcase 主题配置 等源码展开。读完本文你将掌握 PrimeNG Styled Mode 的base preset架构、设计令牌design token三层体系、内置预设Aura/Material/Lara/Nora的选择以及如何通过definePreset、updatePreset、usePreset等工具实现从颜色体系、深色模式到作用域令牌的完整定制全程无需手写 CSS。PrimeNG 是一款设计无关design agnostic的 Angular UI 组件库。与强制 Material Design 等固定视觉风格的库不同PrimeNG 将样式与组件本身解耦组件只负责结构与行为外观完全由主题theme接管。Structured Mode 正是这套解耦体系的落地形态——它由基础样式base与预设preset两部分组成核心概念是设计令牌design token。掌握本文内容后你可以为任意业务场景定制出与品牌一致的主题并能在运行时动态切换预设与颜色。架构总览base 与 preset 如何协作Styled Mode 的主题由两部分构成base基础一组以 CSS 变量作为占位符的样式规则定义了组件通用的排版、圆角、阴影等结构样式但不绑定任何具体颜色或数值。preset预设一组设计令牌将令牌映射为 CSS 变量后喂给 base从而决定每个变量的实际取值。同一个 base 可以搭配不同的 preset。目前仓库内置了四种预设Aura、Material、Lara、Nora。它们的定义位于 packages/themes/src/presets 目录下例如 aura 预设 按组件拆分为button、card、inputtext等子目录每个子目录如 aura/button/index.ts最终从primeuix/themes/aura/*导出对应组件的令牌定义。整个样式架构的核心是一个名为设计令牌的概念。preset 将令牌配置组织为三个层级Primitive Tokens原始令牌原始令牌不含任何上下文。最典型的例子就是调色板blue-50到blue-900。仅凭blue-500这个名字你无法判断它是用于主色、消息背景还是别的什么名字本身不携带语义。它们通常被语义令牌引用。Semantic Tokens语义令牌语义令牌定义内容且名字直接表明用途最知名的例子是primary.color。语义令牌可以映射到原始令牌也可以映射到其他语义令牌。其中colorScheme令牌组是一个特殊分组它允许你根据应用当前激活的配色方案如深色模式定义不同的令牌值。Component Tokens组件令牌组件令牌是每个组件各自隔离的令牌例如inputtext.background、button.color它们映射到语义令牌。举例来说button.background组件令牌→ 映射到primary.color语义令牌→ 映射到green.500原始令牌。令牌使用最佳实践定义核心调色板时使用原始令牌指定焦点环、主色、surface 等通用设计元素时使用语义令牌组件令牌仅在你需要定制某个特定组件时才使用通过自定义预设定义自己的设计令牌即可在不触碰 CSS 的情况下定义自己的风格用样式类去覆盖 PrimeNG 组件不是最佳实践应作为最后手段设计令牌才是推荐方案。内置预设Aura、Material、Lara、Nora四种内置预设被设计用来展示设计无关主题化体系的能力见 Styled Mode 文档预设定位AuraPrimeTek 自己的设计愿景也是 showcase 中大量示例的默认选择Material遵循 Google Material Design v2Lara基于 Bootstrap 风格Nora灵感来自企业级应用你可以开箱即用地直接使用它们也可以在其基础上做修改或者在需要从零构建自己的 preset 时把它们当作参考。要了解 preset 的内部结构可以查看 presets 目录 中各预设的base、semantic、components定义。初始化主题providePrimeNG 与 theme 配置theme属性用于定制应用初始主题。典型配置如下取自 Styled Mode 文档import { ApplicationConfig } from angular/core; import { providePrimeNG } from primeng/config; import Aura from primeuix/themes/aura; export const appConfig: ApplicationConfig { providers: [ providePrimeNG({ theme: { preset: Aura } }) ] };从源码看providePrimeNG接收一系列配置对象通过PRIME_NG_CONFIG注入令牌暴露并用provideAppInitializer在应用启动时把配置写入PrimeNG服务见 provideprimeng.ts。配置最终进入 PrimeNG.setConfig其中theme部分被转交给setThemeConfig见 themeprovider.ts由Theme.setTheme实际应用主题并按需加载 primitive、semantic、global 等 CSS 变量与全局样式。ThemeConfigType的类型定义见 primeng.types.tstheme也支持传none或布尔值如false来完全禁用主题。定制现有预设definePresetdefinePreset用于在 PrimeNG 初始化阶段定制现有预设。第一个参数是待定制的预设第二个参数是要覆盖的设计令牌。例如将主色调从默认的 emerald 换成 indigo取自 primary-doc.tsconst MyPreset definePreset(Aura, { semantic: { primary: { 50: {indigo.50}, 100: {indigo.100}, 200: {indigo.200}, 300: {indigo.300}, 400: {indigo.400}, 500: {indigo.500}, 600: {indigo.600}, 700: {indigo.700}, 800: {indigo.800}, 900: {indigo.900}, 950: {indigo.950} } } });注意其中{indigo.50}这样的写法是令牌引用语法表示引用原始令牌indigo.50而非直接写死色值。修改 primary 与 surfaceprimary定义主色调色板默认值映射到emerald原始令牌。上面的示例即完成替换。surface定义随明暗模式变化的配色板。例如亮色模式用zinc灰阶色调、深色模式用slate偏蓝调取自 surface-doc.tsconst MyPreset definePreset(Aura, { semantic: { colorScheme: { light: { surface: { 0: #ffffff, 50: {zinc.50}, 100: {zinc.100}, 200: {zinc.200}, 300: {zinc.300}, 400: {zinc.400}, 500: {zinc.500}, 600: {zinc.600}, 700: {zinc.700}, 800: {zinc.800}, 900: {zinc.900}, 950: {zinc.950} } }, dark: { surface: { 0: #ffffff, 50: {slate.50}, // ... 依次映射 slate.100 ~ slate.950 } } } } });颜色体系Colors、Palette 与 CSS 变量preset 的调色板由primitive 设计令牌组定义。访问颜色有两种方式取自 colors-doc.ts// 通过 CSS 变量 var(--p-blue-500) // 通过 $dt 工具JS 侧 $dt(blue.500).value$dt函数返回某个令牌的完整信息如完整路径与值当需要以编程方式访问令牌时非常有用。$dt由 base 样式上下文注入在definePreset的css回调见下文扩展主题或组件样式中可用。此外palette 工具函数接收一个颜色返回从50 到 950 的明暗色阶数组可用于程序化生成色板。深色模式colorScheme 与 darkModeSelector按配色方案定义令牌令牌可以通过colorScheme属性的light与dark两个属性针对当前配色方案分别取值const MyPreset definePreset(Aura, { semantic: { colorScheme: { light: { /* 亮色模式下的令牌值 */ }, dark: { /* 深色模式下的令牌值 */ } } } });常见陷阱定制现有 preset 时如果未正确处理配色方案变体令牌覆盖可能被忽略。具体规则如下如果原 preset 用colorScheme属性定义某令牌而你的定制只提供了直接值你的覆盖会被忽略——因为colorScheme属性优先级高于直接值系统会继续使用原 preset 按方案区分的取值如果原 preset 中该令牌没有用colorScheme定义则无论你以直接值还是放在colorScheme下覆盖都会生效。最佳实践定制前先查看源 preset 中令牌的定义方式始终与原 preset 保持相同的结构直接值或colorScheme覆盖依赖方案的令牌时同时考虑亮色与深色两套值。这样无论用户选择哪种配色方案你的定制都能正确生效。darkModeSelector 与深色模式开关PrimeNG 在主题配置中默认使用system作为darkModeSelector即media (prefers-color-scheme: dark)。如果你的应用有自己的深色模式开关应将darkModeSelector设置为你的选择器例如.my-app-dark让 PrimeNG 无缝融入你的配色体系取自 darkmode-doc.tsprovidePrimeNG({ theme: { preset: Aura, options: { darkModeSelector: .my-app-dark } } })一个极简的深色模式切换实现取自 darkmode-doc.tsp-button labelToggle Dark Mode (onClick)toggleDarkMode()/toggleDarkMode() { const element document.querySelector(html); element.classList.toggle(my-app-dark); }在此基础上你还可以结合prefers-color-scheme先从系统读取初始偏好再配合localStorage持久化选择使其成为有状态的完整方案。其他两种用法始终深色模式初始化时就把darkModeSelector对应的类加在根元素上之后不再变更html classmy-app-dark完全禁用深色模式将选择器值设为false或noneprovidePrimeNG({ theme: { preset: Aura, options: { darkModeSelector: false || none } } })主题选项prefix、darkModeSelector、cssLayeroptions属性定义如何从 preset 的设计令牌生成 CSS。三个核心配置项见 Styled Mode 文档配置项说明默认值prefixCSS 变量的前缀p。例如primary.color设计令牌会生成var(--p-primary-color)darkModeSelector包裹深色模式 CSS 变量的规则system即生成media (prefers-color-scheme: dark)。若需基于用户选择切换深色模式可定义类选择器如.app-dark并在文档根元素上切换该类cssLayer是否将样式定义在 CSS layer 内false。启用后便于声明自定义级联层从而更轻松地定制样式运行时主题 APIupdatePreset 与 usePreset除了初始化时定制PrimeNG 还提供运行时动态修改主题的能力updatePreset将提供的令牌合并到当前 preset。典型场景是动态更换主色调取自 updatepreset-doc.tsimport { updatePreset } from primeuix/themes; changePrimaryColor() { updatePreset({ semantic: { primary: { 50: {indigo.50}, 100: {indigo.100}, // ... 依次到 950 } } }) }updatePrimaryPalette更新主色是使用updatePreset完成同一件事的快捷方式。updateSurfacePalette更新 surface 色同样是updatePreset的快捷方式。usePreset完全替换当前预设常见场景是运行时动态切换预设取自 usepreset-doc.tsimport { usePreset } from primeuix/themes; onButtonClick() { usePreset(MyPreset); }这些工具与definePreset一样统一由 themes 包 从primeuix/styled重新导出属于主题化体系的标准 API。扩展主题自定义令牌与附加样式extend主题系统可以通过添加自定义设计令牌和附加样式进行扩展这提供了高度的定制自由——你不受默认令牌的限制。示例 preset 配置新增了一个 accent 按钮带有自定义的button.accent.color与button.accent.inverse.color令牌也可以全局添加令牌让组件之间共享取自 extend-doc.tsconst MyPreset definePreset(Aura, { components: { // 自定义 button 令牌与附加样式 button: { extend: { accent: { color: #f59e0b, inverseColor: #ffffff } }, css: ({ dt }) .p-button-accent { background: ${dt(button.accent.color)}; color: ${dt(button.accent.inverse.color)}; transition-duration: ${dt(my.transition.fast)}; } } }, // 全局令牌与样式 extend: { my: { transition: { slow: 0.75s, normal: 0.5s, fast: 0.25s } } }, css: ({ dt }) /* Global CSS */ img { display: ${dt(my.image.display)}; } });注意这里css回调接收dt函数可以在自定义样式中引用令牌值——这就是上文提到的$dt工具在预设上下文中的形态。作用域令牌为单个组件定制dt 属性设计令牌可以借助dt属性作用域化到某个组件。下面的例子中第一个开关使用全局令牌第二个开关用自身令牌覆盖全局值取自 scopedtokens-doc.tsp-toggleswitch [(ngModel)]checked1 / p-toggleswitch [(ngModel)]checked2 [dt]amberSwitch /amberSwitch { handle: { borderRadius: 4px }, colorScheme: { light: { root: { checkedBackground: {amber.500}, checkedHoverBackground: {amber.600}, borderRadius: 4px }, handle: { checkedBackground: {amber.50}, checkedHoverBackground: {amber.100} } }, dark: { root: { checkedBackground: {amber.400}, checkedHoverBackground: {amber.300}, borderRadius: 4px }, handle: { checkedBackground: {amber.900}, checkedHoverBackground: {amber.800} } } } };这种方式优于::ng-deep它提供更干净的 API同时避免了 CSS 规则覆盖的种种麻烦。同理组件级令牌的全局配置会作用于所有该组件实例例如所有 card 组件如果你只需在页面局部定制某个组件就使用上面的 Scoped CSS 方案。表单令牌form.field 语义组表单输入组件的设计令牌均派生自form.field令牌组。下面的定制把悬停时的边框颜色改为 primary见 Styled Mode 文档const MyPreset definePreset(Aura, { semantic: { form: { field: { hoverBorderColor: {primary.color} } } } });由于dropdown.hover.border.color、textarea.hover.border.color等组件令牌都依赖该语义令牌所有依赖它的组件会自动同步获得这个变化——这正是语义令牌一处修改、全局生效的价值所在。焦点环Focus Ring焦点环focus ring定义轮廓的宽度、样式、颜色与偏移量。下面的示例使用 primary 颜色、更粗的焦点环const MyPreset definePreset(Aura, { semantic: { focusRing: { width: 2px, style: solid, color: {primary.color}, offset: 1px } } });该语义令牌会被所有组件统一引用保证键盘导航的可访问性体验一致。字体继承应用设置字体方面没有专门设计UI 组件从应用继承字体设置。因此你无需也不应在主题中配置字体只需在应用根样式或index.html中定义html/body的字体族所有 PrimeNG 组件自动跟随。排版比例rem 与根字号PrimeNG UI 组件使用rem单位。1rem等于html元素的字体大小浏览器默认 16px。因此可以通过修改根字号来全局调整组件尺寸html { font-size: 14px; /* 全局缩小组件比例 */ }文档中说明本 showcase 网站使用 14px 作为基础字号所以如果你的应用基础字号不同最终视觉比例可能与示例有差异。定制主题时如需微调组件密度优先考虑 root font-size 而非逐组件改尺寸。CSS 层与特异性layer、Reset CSS 与 Bootstraplayer 与 cssLayerlayer是标准 CSS 特性用于定义级联层以获得可控的优先级顺序。cssLayer默认关闭在主题配置中启用后PrimeNG 会将内置样式类包裹在primeng级联层下使库样式易于覆盖见 options-doc.tsoptions: { cssLayer: { name: primeng, order: app-styles, primeng, another-css-library } }关键在于应用中不带 layer 的 CSS 拥有最高特异性因此无论位置在哪、类的写法多强你都能覆盖库样式。Reset CSS 的冲突与解法如果 PrimeNG 组件在你的应用中出现视觉异常Reset CSS 可能是罪魁祸首。CSS 层是高效解决方案启用 PrimeNG layer将 Reset CSS 包裹在另一个 layer 中定义 layer 顺序让 PrimeNG 层排在 Reset 之后。这样 Reset CSS 就不会干扰 PrimeNG 组件。类似地Bootstrap有一个reboot工具用来重置标准元素样式。如果你引入了该工具可以在导入时给它分配一个 layer从而与 PrimeNG 的级联层共存。常见 CSS 库的层配置Styled Mode 文档提供了面向主流 CSS 库的示例 layer 配置见 Libraries 一节核心思路是把你的库样式声明为一个具名 layer并把该 layer 放在order中合适的位置如app-styles之后、primeng之前或之后取决于你希望谁优先从而在不依赖选择器特异性博弈的情况下管理优先级。Noir 模式以 surface 为主色的变体Noir是一种变体的昵称它使用surface 色调作为 primary且必须附加colorScheme配置才能实现。以下是黑、白两版作为主色的示例预设取自 noir-doc.tsconst Noir definePreset(Aura, { semantic: { primary: { 50: {zinc.50}, 100: {zinc.100}, // ... 依次到 950 }, colorScheme: { light: { primary: { color: {zinc.950}, inverseColor: #ffffff, hoverColor: {zinc.900}, activeColor: {zinc.800} }, highlight: { background: {zinc.950}, focusBackground: {zinc.700}, color: #ffffff, focusColor: #ffffff } }, dark: { primary: { color: {zinc.50}, inverseColor: {zinc.950} // ... } } } } });本仓库的 showcase 应用就实际使用了 Noir 变体——见 app-theme.ts它以 Aura 为基础将 primary 各色阶映射到surface.*并在colorScheme.light/dark中分别定义primary.color、contrastColor、hoverColor、activeColor以及highlight背景色同时通过options.darkModeSelector: .p-dark接入应用自身的深色模式。这份真实配置可作为实现 Noir 模式的直接参考。组件层令牌与定制边界特定组件的设计令牌定义在components 层。例如const MyPreset definePreset(Aura, { components: { card: { root: { background: {surface.0}, borderRadius: 12px } } } });需要强调的是如果你要构建自己的完整风格覆盖组件令牌并不是推荐做法优先构建自己的 preset。组件层配置是全局的如上面的配置会作用于所有 card 组件当只需要在某个页面局部定制特定组件时请使用上一节的 Scoped CSSdt属性方案。小结与源码索引Styled Mode 的核心脉络可概括为一条链原始令牌调色板→ 语义令牌primary/surface/form.field/focusRing→ 组件令牌button.color 等→ CSS 变量--p-*→ base 样式规则 → 最终渲染初始化定制入口providePrimeNG、ThemeProvider.setThemeConfig配置类型定义ThemeConfigType / ThemeType内置预设源码presets 目录如 Aura、Material、Lara、Nora主题工具统一出口packages/themes/src/index.tsdefinePreset、updatePreset、updatePrimaryPalette、updateSurfacePalette、usePreset、palette等真实应用示例showcase 主题配置Noir .p-dark深色选择器各小节配套演示源码theming/styled 文档目录包括 primary-doc.ts、surface-doc.ts、darkmode-doc.ts、extend-doc.ts、scopedtokens-doc.ts、options-doc.ts 等。实践建议先从四种内置预设中选一个作为起点用definePreset调整primary与surface再按需接入colorScheme支持深色模式当品牌元素超出默认令牌时用extend添加自定义令牌需要动态换肤时调用updatePreset/usePreset。整个过程保持令牌驱动、CSS 兜底的边界即可获得干净、可维护、可扩展的主题体系。【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PrimeNG Styled Mode 主题定制完全指南：设计令牌驱动的样式架构与实战
PrimeNG Styled Mode 主题定制完全指南设计令牌驱动的样式架构与实战【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng本文基于本仓库中 Styled Mode 官方文档结合 themes 包 与 showcase 主题配置 等源码展开。读完本文你将掌握 PrimeNG Styled Mode 的base preset架构、设计令牌design token三层体系、内置预设Aura/Material/Lara/Nora的选择以及如何通过definePreset、updatePreset、usePreset等工具实现从颜色体系、深色模式到作用域令牌的完整定制全程无需手写 CSS。PrimeNG 是一款设计无关design agnostic的 Angular UI 组件库。与强制 Material Design 等固定视觉风格的库不同PrimeNG 将样式与组件本身解耦组件只负责结构与行为外观完全由主题theme接管。Structured Mode 正是这套解耦体系的落地形态——它由基础样式base与预设preset两部分组成核心概念是设计令牌design token。掌握本文内容后你可以为任意业务场景定制出与品牌一致的主题并能在运行时动态切换预设与颜色。架构总览base 与 preset 如何协作Styled Mode 的主题由两部分构成base基础一组以 CSS 变量作为占位符的样式规则定义了组件通用的排版、圆角、阴影等结构样式但不绑定任何具体颜色或数值。preset预设一组设计令牌将令牌映射为 CSS 变量后喂给 base从而决定每个变量的实际取值。同一个 base 可以搭配不同的 preset。目前仓库内置了四种预设Aura、Material、Lara、Nora。它们的定义位于 packages/themes/src/presets 目录下例如 aura 预设 按组件拆分为button、card、inputtext等子目录每个子目录如 aura/button/index.ts最终从primeuix/themes/aura/*导出对应组件的令牌定义。整个样式架构的核心是一个名为设计令牌的概念。preset 将令牌配置组织为三个层级Primitive Tokens原始令牌原始令牌不含任何上下文。最典型的例子就是调色板blue-50到blue-900。仅凭blue-500这个名字你无法判断它是用于主色、消息背景还是别的什么名字本身不携带语义。它们通常被语义令牌引用。Semantic Tokens语义令牌语义令牌定义内容且名字直接表明用途最知名的例子是primary.color。语义令牌可以映射到原始令牌也可以映射到其他语义令牌。其中colorScheme令牌组是一个特殊分组它允许你根据应用当前激活的配色方案如深色模式定义不同的令牌值。Component Tokens组件令牌组件令牌是每个组件各自隔离的令牌例如inputtext.background、button.color它们映射到语义令牌。举例来说button.background组件令牌→ 映射到primary.color语义令牌→ 映射到green.500原始令牌。令牌使用最佳实践定义核心调色板时使用原始令牌指定焦点环、主色、surface 等通用设计元素时使用语义令牌组件令牌仅在你需要定制某个特定组件时才使用通过自定义预设定义自己的设计令牌即可在不触碰 CSS 的情况下定义自己的风格用样式类去覆盖 PrimeNG 组件不是最佳实践应作为最后手段设计令牌才是推荐方案。内置预设Aura、Material、Lara、Nora四种内置预设被设计用来展示设计无关主题化体系的能力见 Styled Mode 文档预设定位AuraPrimeTek 自己的设计愿景也是 showcase 中大量示例的默认选择Material遵循 Google Material Design v2Lara基于 Bootstrap 风格Nora灵感来自企业级应用你可以开箱即用地直接使用它们也可以在其基础上做修改或者在需要从零构建自己的 preset 时把它们当作参考。要了解 preset 的内部结构可以查看 presets 目录 中各预设的base、semantic、components定义。初始化主题providePrimeNG 与 theme 配置theme属性用于定制应用初始主题。典型配置如下取自 Styled Mode 文档import { ApplicationConfig } from angular/core; import { providePrimeNG } from primeng/config; import Aura from primeuix/themes/aura; export const appConfig: ApplicationConfig { providers: [ providePrimeNG({ theme: { preset: Aura } }) ] };从源码看providePrimeNG接收一系列配置对象通过PRIME_NG_CONFIG注入令牌暴露并用provideAppInitializer在应用启动时把配置写入PrimeNG服务见 provideprimeng.ts。配置最终进入 PrimeNG.setConfig其中theme部分被转交给setThemeConfig见 themeprovider.ts由Theme.setTheme实际应用主题并按需加载 primitive、semantic、global 等 CSS 变量与全局样式。ThemeConfigType的类型定义见 primeng.types.tstheme也支持传none或布尔值如false来完全禁用主题。定制现有预设definePresetdefinePreset用于在 PrimeNG 初始化阶段定制现有预设。第一个参数是待定制的预设第二个参数是要覆盖的设计令牌。例如将主色调从默认的 emerald 换成 indigo取自 primary-doc.tsconst MyPreset definePreset(Aura, { semantic: { primary: { 50: {indigo.50}, 100: {indigo.100}, 200: {indigo.200}, 300: {indigo.300}, 400: {indigo.400}, 500: {indigo.500}, 600: {indigo.600}, 700: {indigo.700}, 800: {indigo.800}, 900: {indigo.900}, 950: {indigo.950} } } });注意其中{indigo.50}这样的写法是令牌引用语法表示引用原始令牌indigo.50而非直接写死色值。修改 primary 与 surfaceprimary定义主色调色板默认值映射到emerald原始令牌。上面的示例即完成替换。surface定义随明暗模式变化的配色板。例如亮色模式用zinc灰阶色调、深色模式用slate偏蓝调取自 surface-doc.tsconst MyPreset definePreset(Aura, { semantic: { colorScheme: { light: { surface: { 0: #ffffff, 50: {zinc.50}, 100: {zinc.100}, 200: {zinc.200}, 300: {zinc.300}, 400: {zinc.400}, 500: {zinc.500}, 600: {zinc.600}, 700: {zinc.700}, 800: {zinc.800}, 900: {zinc.900}, 950: {zinc.950} } }, dark: { surface: { 0: #ffffff, 50: {slate.50}, // ... 依次映射 slate.100 ~ slate.950 } } } } });颜色体系Colors、Palette 与 CSS 变量preset 的调色板由primitive 设计令牌组定义。访问颜色有两种方式取自 colors-doc.ts// 通过 CSS 变量 var(--p-blue-500) // 通过 $dt 工具JS 侧 $dt(blue.500).value$dt函数返回某个令牌的完整信息如完整路径与值当需要以编程方式访问令牌时非常有用。$dt由 base 样式上下文注入在definePreset的css回调见下文扩展主题或组件样式中可用。此外palette 工具函数接收一个颜色返回从50 到 950 的明暗色阶数组可用于程序化生成色板。深色模式colorScheme 与 darkModeSelector按配色方案定义令牌令牌可以通过colorScheme属性的light与dark两个属性针对当前配色方案分别取值const MyPreset definePreset(Aura, { semantic: { colorScheme: { light: { /* 亮色模式下的令牌值 */ }, dark: { /* 深色模式下的令牌值 */ } } } });常见陷阱定制现有 preset 时如果未正确处理配色方案变体令牌覆盖可能被忽略。具体规则如下如果原 preset 用colorScheme属性定义某令牌而你的定制只提供了直接值你的覆盖会被忽略——因为colorScheme属性优先级高于直接值系统会继续使用原 preset 按方案区分的取值如果原 preset 中该令牌没有用colorScheme定义则无论你以直接值还是放在colorScheme下覆盖都会生效。最佳实践定制前先查看源 preset 中令牌的定义方式始终与原 preset 保持相同的结构直接值或colorScheme覆盖依赖方案的令牌时同时考虑亮色与深色两套值。这样无论用户选择哪种配色方案你的定制都能正确生效。darkModeSelector 与深色模式开关PrimeNG 在主题配置中默认使用system作为darkModeSelector即media (prefers-color-scheme: dark)。如果你的应用有自己的深色模式开关应将darkModeSelector设置为你的选择器例如.my-app-dark让 PrimeNG 无缝融入你的配色体系取自 darkmode-doc.tsprovidePrimeNG({ theme: { preset: Aura, options: { darkModeSelector: .my-app-dark } } })一个极简的深色模式切换实现取自 darkmode-doc.tsp-button labelToggle Dark Mode (onClick)toggleDarkMode()/toggleDarkMode() { const element document.querySelector(html); element.classList.toggle(my-app-dark); }在此基础上你还可以结合prefers-color-scheme先从系统读取初始偏好再配合localStorage持久化选择使其成为有状态的完整方案。其他两种用法始终深色模式初始化时就把darkModeSelector对应的类加在根元素上之后不再变更html classmy-app-dark完全禁用深色模式将选择器值设为false或noneprovidePrimeNG({ theme: { preset: Aura, options: { darkModeSelector: false || none } } })主题选项prefix、darkModeSelector、cssLayeroptions属性定义如何从 preset 的设计令牌生成 CSS。三个核心配置项见 Styled Mode 文档配置项说明默认值prefixCSS 变量的前缀p。例如primary.color设计令牌会生成var(--p-primary-color)darkModeSelector包裹深色模式 CSS 变量的规则system即生成media (prefers-color-scheme: dark)。若需基于用户选择切换深色模式可定义类选择器如.app-dark并在文档根元素上切换该类cssLayer是否将样式定义在 CSS layer 内false。启用后便于声明自定义级联层从而更轻松地定制样式运行时主题 APIupdatePreset 与 usePreset除了初始化时定制PrimeNG 还提供运行时动态修改主题的能力updatePreset将提供的令牌合并到当前 preset。典型场景是动态更换主色调取自 updatepreset-doc.tsimport { updatePreset } from primeuix/themes; changePrimaryColor() { updatePreset({ semantic: { primary: { 50: {indigo.50}, 100: {indigo.100}, // ... 依次到 950 } } }) }updatePrimaryPalette更新主色是使用updatePreset完成同一件事的快捷方式。updateSurfacePalette更新 surface 色同样是updatePreset的快捷方式。usePreset完全替换当前预设常见场景是运行时动态切换预设取自 usepreset-doc.tsimport { usePreset } from primeuix/themes; onButtonClick() { usePreset(MyPreset); }这些工具与definePreset一样统一由 themes 包 从primeuix/styled重新导出属于主题化体系的标准 API。扩展主题自定义令牌与附加样式extend主题系统可以通过添加自定义设计令牌和附加样式进行扩展这提供了高度的定制自由——你不受默认令牌的限制。示例 preset 配置新增了一个 accent 按钮带有自定义的button.accent.color与button.accent.inverse.color令牌也可以全局添加令牌让组件之间共享取自 extend-doc.tsconst MyPreset definePreset(Aura, { components: { // 自定义 button 令牌与附加样式 button: { extend: { accent: { color: #f59e0b, inverseColor: #ffffff } }, css: ({ dt }) .p-button-accent { background: ${dt(button.accent.color)}; color: ${dt(button.accent.inverse.color)}; transition-duration: ${dt(my.transition.fast)}; } } }, // 全局令牌与样式 extend: { my: { transition: { slow: 0.75s, normal: 0.5s, fast: 0.25s } } }, css: ({ dt }) /* Global CSS */ img { display: ${dt(my.image.display)}; } });注意这里css回调接收dt函数可以在自定义样式中引用令牌值——这就是上文提到的$dt工具在预设上下文中的形态。作用域令牌为单个组件定制dt 属性设计令牌可以借助dt属性作用域化到某个组件。下面的例子中第一个开关使用全局令牌第二个开关用自身令牌覆盖全局值取自 scopedtokens-doc.tsp-toggleswitch [(ngModel)]checked1 / p-toggleswitch [(ngModel)]checked2 [dt]amberSwitch /amberSwitch { handle: { borderRadius: 4px }, colorScheme: { light: { root: { checkedBackground: {amber.500}, checkedHoverBackground: {amber.600}, borderRadius: 4px }, handle: { checkedBackground: {amber.50}, checkedHoverBackground: {amber.100} } }, dark: { root: { checkedBackground: {amber.400}, checkedHoverBackground: {amber.300}, borderRadius: 4px }, handle: { checkedBackground: {amber.900}, checkedHoverBackground: {amber.800} } } } };这种方式优于::ng-deep它提供更干净的 API同时避免了 CSS 规则覆盖的种种麻烦。同理组件级令牌的全局配置会作用于所有该组件实例例如所有 card 组件如果你只需在页面局部定制某个组件就使用上面的 Scoped CSS 方案。表单令牌form.field 语义组表单输入组件的设计令牌均派生自form.field令牌组。下面的定制把悬停时的边框颜色改为 primary见 Styled Mode 文档const MyPreset definePreset(Aura, { semantic: { form: { field: { hoverBorderColor: {primary.color} } } } });由于dropdown.hover.border.color、textarea.hover.border.color等组件令牌都依赖该语义令牌所有依赖它的组件会自动同步获得这个变化——这正是语义令牌一处修改、全局生效的价值所在。焦点环Focus Ring焦点环focus ring定义轮廓的宽度、样式、颜色与偏移量。下面的示例使用 primary 颜色、更粗的焦点环const MyPreset definePreset(Aura, { semantic: { focusRing: { width: 2px, style: solid, color: {primary.color}, offset: 1px } } });该语义令牌会被所有组件统一引用保证键盘导航的可访问性体验一致。字体继承应用设置字体方面没有专门设计UI 组件从应用继承字体设置。因此你无需也不应在主题中配置字体只需在应用根样式或index.html中定义html/body的字体族所有 PrimeNG 组件自动跟随。排版比例rem 与根字号PrimeNG UI 组件使用rem单位。1rem等于html元素的字体大小浏览器默认 16px。因此可以通过修改根字号来全局调整组件尺寸html { font-size: 14px; /* 全局缩小组件比例 */ }文档中说明本 showcase 网站使用 14px 作为基础字号所以如果你的应用基础字号不同最终视觉比例可能与示例有差异。定制主题时如需微调组件密度优先考虑 root font-size 而非逐组件改尺寸。CSS 层与特异性layer、Reset CSS 与 Bootstraplayer 与 cssLayerlayer是标准 CSS 特性用于定义级联层以获得可控的优先级顺序。cssLayer默认关闭在主题配置中启用后PrimeNG 会将内置样式类包裹在primeng级联层下使库样式易于覆盖见 options-doc.tsoptions: { cssLayer: { name: primeng, order: app-styles, primeng, another-css-library } }关键在于应用中不带 layer 的 CSS 拥有最高特异性因此无论位置在哪、类的写法多强你都能覆盖库样式。Reset CSS 的冲突与解法如果 PrimeNG 组件在你的应用中出现视觉异常Reset CSS 可能是罪魁祸首。CSS 层是高效解决方案启用 PrimeNG layer将 Reset CSS 包裹在另一个 layer 中定义 layer 顺序让 PrimeNG 层排在 Reset 之后。这样 Reset CSS 就不会干扰 PrimeNG 组件。类似地Bootstrap有一个reboot工具用来重置标准元素样式。如果你引入了该工具可以在导入时给它分配一个 layer从而与 PrimeNG 的级联层共存。常见 CSS 库的层配置Styled Mode 文档提供了面向主流 CSS 库的示例 layer 配置见 Libraries 一节核心思路是把你的库样式声明为一个具名 layer并把该 layer 放在order中合适的位置如app-styles之后、primeng之前或之后取决于你希望谁优先从而在不依赖选择器特异性博弈的情况下管理优先级。Noir 模式以 surface 为主色的变体Noir是一种变体的昵称它使用surface 色调作为 primary且必须附加colorScheme配置才能实现。以下是黑、白两版作为主色的示例预设取自 noir-doc.tsconst Noir definePreset(Aura, { semantic: { primary: { 50: {zinc.50}, 100: {zinc.100}, // ... 依次到 950 }, colorScheme: { light: { primary: { color: {zinc.950}, inverseColor: #ffffff, hoverColor: {zinc.900}, activeColor: {zinc.800} }, highlight: { background: {zinc.950}, focusBackground: {zinc.700}, color: #ffffff, focusColor: #ffffff } }, dark: { primary: { color: {zinc.50}, inverseColor: {zinc.950} // ... } } } } });本仓库的 showcase 应用就实际使用了 Noir 变体——见 app-theme.ts它以 Aura 为基础将 primary 各色阶映射到surface.*并在colorScheme.light/dark中分别定义primary.color、contrastColor、hoverColor、activeColor以及highlight背景色同时通过options.darkModeSelector: .p-dark接入应用自身的深色模式。这份真实配置可作为实现 Noir 模式的直接参考。组件层令牌与定制边界特定组件的设计令牌定义在components 层。例如const MyPreset definePreset(Aura, { components: { card: { root: { background: {surface.0}, borderRadius: 12px } } } });需要强调的是如果你要构建自己的完整风格覆盖组件令牌并不是推荐做法优先构建自己的 preset。组件层配置是全局的如上面的配置会作用于所有 card 组件当只需要在某个页面局部定制特定组件时请使用上一节的 Scoped CSSdt属性方案。小结与源码索引Styled Mode 的核心脉络可概括为一条链原始令牌调色板→ 语义令牌primary/surface/form.field/focusRing→ 组件令牌button.color 等→ CSS 变量--p-*→ base 样式规则 → 最终渲染初始化定制入口providePrimeNG、ThemeProvider.setThemeConfig配置类型定义ThemeConfigType / ThemeType内置预设源码presets 目录如 Aura、Material、Lara、Nora主题工具统一出口packages/themes/src/index.tsdefinePreset、updatePreset、updatePrimaryPalette、updateSurfacePalette、usePreset、palette等真实应用示例showcase 主题配置Noir .p-dark深色选择器各小节配套演示源码theming/styled 文档目录包括 primary-doc.ts、surface-doc.ts、darkmode-doc.ts、extend-doc.ts、scopedtokens-doc.ts、options-doc.ts 等。实践建议先从四种内置预设中选一个作为起点用definePreset调整primary与surface再按需接入colorScheme支持深色模式当品牌元素超出默认令牌时用extend添加自定义令牌需要动态换肤时调用updatePreset/usePreset。整个过程保持令牌驱动、CSS 兜底的边界即可获得干净、可维护、可扩展的主题体系。【免费下载链接】primengThe Most Complete Angular UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primeng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
