Skip to main content
Version: 3.8.0

📦 plugin-css-cascade-layers

实验性

此插件主要设计为通过 Docusaurus future.v4.useCssCascadeLayers 标志 由经典预设内部使用，但它也可以作为独立插件使用。如果你有使用案例，请告知 请在此处告知我们，并帮助我们设计一个对 Docusaurus 未来有意义的 API。

¥This plugin is mostly designed to be used internally by the classic preset through the Docusaurus future.v4.useCssCascadeLayers flag, although it can also be used as a standalone plugin. Please let us know here if you have a use case for it and help us design an API that makes sense for the future of Docusaurus.

用于在 CSS 级联层 中封装 Docusaurus 站点 CSS 模块的插件。这项现代 CSS 功能已得到所有浏览器的广泛支持。它允许按优先级对 CSS 规则进行分组，并让你更好地控制 CSS 级联。

¥A plugin for wrapping CSS modules of your Docusaurus site in CSS Cascade Layers. This modern CSS feature is widely supported by all browsers. It allows grouping CSS rules in layers of specificity and gives you more control over the CSS cascade.

使用此插件可以：

¥Use this plugin to:

  • 在任何 CSS 模块（包括未分层的第三方 CSS）周围应用顶层 @layer myLayer { ... } 块规则。

    ¥apply a top-level @layer myLayer { ... } block rule around any CSS module, including un-layered third-party CSS.

  • 定义明确的图层顺序

    ¥define an explicit layer ordering

提醒

要正确使用此插件，建议你对 CSS 级联层、CSS 级联 和 specificity 有深入的了解。

¥To use this plugin properly, it's recommended to have a solid understanding of CSS Cascade Layers, the CSS Cascade and specificity.

安装​

¥Installation

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

如果你使用预设的 @docusaurus/preset-classic，此插件将自动为你配置 siteConfig.future.v4.useCssCascadeLayers 标志。

¥If you use the preset @docusaurus/preset-classic, this plugin is automatically configured for you with the siteConfig.future.v4.useCssCascadeLayers flag.

配置​

¥Configuration

接受的字段：

¥Accepted fields:

名称类型默认描述
layersLayers内置层一个表示你要使用的所有 CSS 级联层的对象，以及是否应将该层应用于给定文件路径。请参阅下面的示例和类型。

类型​

¥Types

Layers​

type Layers = Record<
  string, // layer name
  (filePath: string) => boolean // layer matcher
>;

layers 对象由以下项定义：

¥The layers object is defined by:

  • 键：图层的名称

    ¥key: the name of a layer

  • 值：一个函数，用于定义给定的 CSS 模块文件是否应该位于该层

    ¥value: a function to define if a given CSS module file should be in that layer

顺序很重要

对象顺序很重要：

¥The object order matters:

  • 键的顺序定义了明确的 CSS 图层顺序

    ¥the keys order defines an explicit CSS layer order

  • 当多个图层与文件路径匹配时，仅应用第一个图层

    ¥when multiple layers match a file path, only the first layer will apply

配置示例​

¥Example configuration

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

¥You can configure this plugin through plugin options.

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