跳到主要内容

2、插件

插件​

插件是 Docusaurus 站点中功能的构建块。每个插件都有自己独特的功能。插件可以通过预设作为打包包的一部分来运行和分发。

创建插件​

插件是一个带有两个参数的函数：context 和 options。它返回一个插件实例对象（或一个 promise）。你可以将插件创建为函数或模块。有关详细信息，请参阅 插件方法参考部分。

函数定义​

你可以使用插件作为直接包含在 Docusaurus 配置文件中的函数：

docusaurus.config.js

export default {
  // ...
  plugins: [
    async function myPlugin(context, options) {
      // ...
      return {
        name: 'my-plugin',
        async loadContent() {
          // ...
        },
        async contentLoaded({content, actions}) {
          // ...
        },
        /* other lifecycle API */
      };
    },
  ],
};

模块定义​

你可以使用插件作为引用单独文件或 npm 包的模块路径：

docusaurus.config.js

export default {
  // ...
  plugins: [
    // without options:
    './my-plugin',
    // or with options:
    ['./my-plugin', options],
  ],
};

然后在文件夹 my-plugin 中，你可以创建一个 index.js，如下所示：

my-plugin/index.js

export default async function myPlugin(context, options) {
  // ...
  return {
    name: 'my-plugin',
    async loadContent() {
      /* ... */
    },
    async contentLoaded({content, actions}) {
      /* ... */
    },
    /* other lifecycle API */
  };
}

你可以使用 调试插件的元数据面板.conf 查看站点中安装的所有插件。

插件有多种类型：

  • package：你安装的外部软件包
  • project：你在项目中创建的插件，作为本地文件路径提供给 Docusaurus
  • local：使用函数定义创建的插件
  • synthetic：内部创建了 "假插件" Docusaurus，因此我们利用了模块化架构，并且不让核心执行太多特殊工作。你不会在元数据中看到它，因为它是一个实现细节。

你可以在客户端使用 useDocusaurusContext().siteMetadata.pluginVersions 访问它们。

插件设计​

Docusaurus 插件系统的实现为我们提供了一种方便的方法来钩子网站的生命周期，以修改开发/构建期间发生的事情，其中涉及（但不限于）扩展 webpack 配置、修改加载的数据以及创建 页面中使用的新组件。

主题设计​

当插件加载其内容时，数据将通过 createData + addRoute 或 setGlobalData 等操作提供给客户端。该数据必须序列化为纯字符串，因为 插件和主题在不同的环境中运行。一旦数据到达客户端，React 开发者就会熟悉其余的内容：数据沿着组件传递，组件与 Webpack 打包在一起，通过 ReactDOM.render 渲染到窗口...

主题提供一组 UI 组件来渲染内容。大多数内容插件需要与主题配对才能真正有用。UI 是与数据模式分开的层，这使得交换设计变得容易。

例如，Docusaurus 博客可能由博客插件和博客主题组成。

注意

这是一个人为的例子：实际上，@docusaurus/theme-classic 提供了文档、博客和布局的主题。

docusaurus.config.js

export default {
  themes: ['theme-blog'],
  plugins: ['plugin-content-blog'],
};

如果你想使用 Bootstrap 样式，你可以用 theme-blog-bootstrap （另一个虚构的不存在的主题）替换主题：

docusaurus.config.js

export default {
  themes: ['theme-blog-bootstrap'],
  plugins: ['plugin-content-blog'],
};

现在，尽管主题从插件接收相同的数据，但主题选择将数据渲染为 UI 的方式可能截然不同。

虽然主题与插件共享完全相同的生命周期方法，但主题 '实现可能看起来与基于主题的插件的实现非常不同' 设计了目标。

主题旨在完成 Docusaurus 站点的构建，并提供站点、插件和主题本身使用的组件。主题仍然像插件一样运行并公开一些生命周期方法，但很可能它们不会使用 loadContent，因为它们只从插件接收数据，但本身不生成数据；主题通常还伴随着一个充满组件的 src/theme 目录，这些组件通过 getThemePath 生命周期为核心所知。

总结一下：

  • 主题与插件共享相同的生命周期方法
  • 主题在所有现有插件之后运行
  • 主题通过提供 getThemePath 来添加组件别名。
最后由 One 于 更新
0%