跳到主要内容

📦 plugin-css-cascade-layers

实验性

本插件主要设计为通过 道格龙 future.v4.useCssCascadeLayers 标志在经典预设中内部使用，当然你也可以单独使用它。如果你有相关使用场景，请在这里留言，帮助我们设计更适合道格龙未来发展的 API。

这是一个用于将你道格龙（Docusaurus）站点的 CSS 模块包裹在 CSS Cascade Layers 中的插件。这一现代 CSS 特性已被所有主流浏览器广泛支持。它允许你将 CSS 规则分组到不同的层级中，从而更好地控制 CSS 的层叠顺序。

使用本插件可以：

  • 在任意 CSS 模块（包括未分层的第三方 CSS）外部包裹顶层 @layer myLayer { ... } 规则块。
  • 明确指定层级顺序。
警告

要正确使用本插件，建议你对 CSS Cascade Layers、CSS 层叠 和 优先级 有扎实的理解。

安装​

npm install --save @docusaurus/plugin-css-cascade-layers
提示

如果你使用了 @docusaurus/preset-classic 预设，则通过 siteConfig.future.v4.useCssCascadeLayers 标志会自动为你配置好本插件。

配置​

可用字段：

名称类型默认值说明
layersLayers内置层一个对象，表示你想用的所有 CSS 层，以及该层是否应用于指定文件路径。见下方示例和类型定义。

类型定义​

Layers​

type Layers = Record<
  string, // 层名称
  (filePath: string) => boolean // 层匹配函数
>;

layers 对象定义如下：

  • key：层的名称
  • value：一个函数，用于判断某个 CSS 模块文件是否属于该层
顺序很重要

对象的顺序很重要：

  • key 的顺序决定了 CSS 层的显式顺序
  • 当多个层匹配同一个文件路径时，只会应用第一个匹配的层

示例配置​

你可以通过插件选项配置本插件。

const options = {
  layers: {
    'docusaurus.infima': (filePath) =>
      filePath.includes('/node_modules/infima/dist'),
    'docusaurus.theme-classic': (filePath) =>
      filePath.includes('/node_modules/@docusaurus/theme-classic/lib'),
  },
};