跳到主要内容
版本号：Next

主题插件

什么是主题插件？​

Verdaccio 默认使用 自定义 UI，它提供了一套很好的软件包可视化功能，但您的团队可能需要一些自定义的额外功能，这时自定义主题就是一个选择。 该插件存储的静态资源将在页面渲染时加载到客户端。

主题插件加载阶段如何工作？​

主题的资源文件如何加载？​

:::警告

默认情况下，应用程序在 http://localhost:4873 上加载，但在涉及带有自定义域的反向代理时，资产将根据属性 __VERDACCIO_BASENAME_UI_OPTIONS.base 和 __VERDACCIO_BASENAME_UI_OPTIONS.basename 加载，因此只能使用一种域配置。

:::警告

主题仅在客户端加载，应用程序渲染带有 <script> 标签 HTML 来渲染应用程序，捆绑器负责任何其他资源的加载 svg、图像或chunks。

__VERDACCIO_BASENAME_UI_OPTIONS 对象​

window.__VERDACCIO_BASENAME_UI_OPTIONS 在浏览器全局上下文中可用，结构定义在文档这里，TemplateUIOptions 的类型定义中。

// 输出示例
{
    "darkMode": false,
    "basename": "/",
    "base": "https://registry.my.org/",
    "primaryColor": "#4b5e40",
    "version": "5.20.1",
    "pkgManagers": [
        "yarn",
        "pnpm",
        "npm"
    ],
    "login": true,
    "logo": "",
    "title": "Verdaccio Registry",
    "scope": "",
    "language": "es-US"
}

主题配置​

默认情况下，verdaccio 会加载捆绑在主软件包中的 @verdaccio/ui-theme 插件。


$> npm install --global verdaccio-theme-dark

:::注意 插件名称前缀必须以 verdaccio-theme-xxx 开头，否则插件将被忽略。 :::警告

您可以一次只加载 一个主题（如果提供多个主题，则选择第一个主题），并在需要时传递选项。

theme:
  dark:
    option1: foo
    option2: bar

这些选项将生效

插件结构​

如果您有自定义的用户界面主题，必须遵循特定的结构：

{
  "name": "verdaccio-theme-xxxx",
  "version": "1.0.0",
  "description": "my custom user interface",
  "main": "index.js",
}

主文件 index.js 应包含以下内容。

module.exports = () => {
  return {
    // 静态文件的位置，webpack 输出
    staticPath: path.join(__dirname, 'static'),
    // webpack manifest json 文件
    manifest: require('./static/manifest.json'),
    // 要加载的主要清单文件
    manifestFiles: {
      js: ['runtime.js', 'vendors.js', 'main.js'],
    },
  };
};

如果以下任何属性不可用，插件将无法加载，因此请遵循此结构。

  • staticPath：是静态文件的绝对/相对位置，可以是使用 require.resolve 或构建您自己的任何路径，重要的是需要让包内部或任何 Express.js 中间件能够找到的位置，被后台的 res.sendFile 使用。
  • manifest：Webpack manifest 对象。
  • manifestFiles：具有一个属性 js 的对象和要动态加载到模板中的清单 id 的数组（顺序很重要）。
  • manifestFiles 指的是必须作为 html 脚本的一部分加载的主文件才能加载页面，由于 chunks 是由捆绑程序动态加载的，因此您不必将其包括在内。

Manifest 文件​

Verdaccio 需要 manifest 对象来动态渲染 html，与 manifestFiles 结合使用，应用程序就能了解要呈现的内容。

目前仅支持js，但是如果您也需要 css, 我们愿意一起讨论并进一步改进。

const { WebpackManifestPlugin } = require('webpack-manifest-plugin');

  plugins: [
    ...
    new WebpackManifestPlugin({
      // 这是可选的，取决于您的实现
      removeKeyHash: true,
    }),
    ...
  ],

其他打包程序的 Manifest​

当前没有使用其他打包工具打包主题插件的反馈，但使用 esbuild 可以生成清单。

替代方案：

组件 UI​

:::注意

组件 UI 是一项实验性功能，自 verdccio@5.x 起即可使用，它可以接受更改，并且欢迎提供反馈。

:::注意

从头开始创建一个新的用户界面是一项巨大的工作，为了方便这项任务，这里有 @verdaccio/ui-components 包。 这些组件基于 React 库和 Material UI。

软件包导出了可重复使用的部分用户界面：

  • React Hooks
  • Providers (React Context API)
  • 组件
  • 各部分：（侧边栏、详细信息、页头、主页和页脚）

https://ui-components.verdaccio.org