自定义 CSS & SCSS

通过 CSS 单独定制 Payload Admin Panel 是自定义仪表板外观最简单且最强大的方式之一。为了实现这种级别的定制，Payload：

  1. 提供了 root-level stylesheet 供你注入自定义选择器
  2. 提供了可轻松覆盖或扩展的 CSS library
  3. 采用 BEM 命名规范 使类名全局可访问

要定制 Admin UI 中的 CSS，首先确定需要修改的范围和内容，然后根据需要添加你自己的 CSS 或 SCSS 到配置中。

全局 CSS

全局 CSS 是指应用于整个 Admin Panel 的 CSS。通过几行代码，你就能对 Admin UI 的外观产生显著影响。

你可以通过应用的根目录 custom.scss 文件添加自己的全局 CSS。该文件会被加载到 Admin Panel 的根目录，可用于根据需要注入自定义选择器或样式。

以下是一个如何定位 Dashboard 视图并更改背景颜色的示例：

.dashboard {
  background-color: red; // highlight-line
}

注意： 如果你正在构建 Custom Components，最佳实践是直接将样式表导入到组件中，而不是使用全局样式表。你可以根据需要继续使用 CSS library。

特异性规则

所有 Payload CSS 都被封装在 @layer payload-default CSS 层中。任何自定义 CSS 现在都将具有最高的特异性。

我们还提供了一个 @layer payload 层，如果你想使用层并确保你的样式在 Payload 之后应用。

要以尊重先前特异性规则的方式覆盖现有样式，你可以像这样使用默认层：

@layer payload-default {
  // 在 Payload 特异性范围内的我的样式
}

重用 Payload SCSS 变量和工具

你可以通过从 UI 包中导入来在自己的样式表中重用 Payload 的 SCSS 变量和工具。

@import '~@payloadcms/ui/scss';

CSS 库

为了让开发者能够轻松覆盖默认样式，Payload 在 Admin UI 中所有 CSS 都采用了 BEM 命名规范。如果你提供自定义 CSS，可以轻松覆盖任何内置样式，包括针对嵌套组件及其各种状态的选择器。

你也可以覆盖 Payload 内置的 CSS 变量。这些变量被管理后台广泛使用，修改它们会对 Admin UI 的整体视觉效果产生显著影响。

以下是已定义并可被覆盖的变量：

  • 断点
  • 颜色
    • 基础色阶（默认为白色到黑色）
    • 成功/警告/错误色阶
    • 主题特定颜色（背景、输入框背景、文本颜色等）
    • 层级颜色（用于确定元素相对于背景的"亮度"）
  • 尺寸
    • 水平间距
    • 过渡速度
    • 字体大小
    • 等

要获取最新、完整的可用变量列表，请参考源代码。

警告： 如果你要覆盖颜色或主题层级，请务必考虑你的修改会如何影响暗黑模式。

暗黑模式

颜色设计会自动适应管理后台的主题。默认情况下，Payload 会自动覆盖所有 --theme-elevation 颜色，并反转所有成功/警告/错误色阶以适应暗黑模式。我们还会更新一些基础主题变量如 --theme-bg、--theme-text 等。