WXT浏览器插件开发中文教程(22)----WXT模块详解

前言

大家好，我是倔强青铜三 。是一名热情的软件工程师，我热衷于分享和传播IT技术，致力于通过我的知识和技能推动技术交流与创新，欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！

WXT 模块 [​](#WXT 模块 "#wxt-modules")

WXT 提供了一个"模块系统"，允许你在构建过程的不同步骤中运行代码以进行修改。

• 添加模块
• 模块选项
• 执行顺序
• 编写模块
  • 示例
  • 示例模块

添加模块 ​

有两种方法可以将模块添加到你的项目中：

1. NPM : 安装一个 NPM 包，例如 @wxt-dev/auto-icons，并将其添加到你的配置中：

   wxt.config.ts

   export default defineConfig({
     modules: ['@wxt-dev/auto-icons'],
   });

   在 NPM 上搜索 "wxt module" 是找到已发布的 WXT 模块的好方法。

2. 本地 : 将文件添加到项目的 modules/ 目录中：

   <rootDir>/
     modules/
       my-module.ts

   要了解有关编写自己的模块的更多信息，请阅读 编写模块 文档。

模块选项 ​

WXT 模块可能需要或允许设置自定义选项以更改其行为。有两类选项：

1. 构建时: 在构建过程中使用的任何配置，如功能标志
2. 运行时: 在运行时访问的任何配置，如回调函数

构建时选项放在你的 wxt.config.ts 中，而运行时选项则放在 app.config.ts 文件中。请参阅每个模块的文档，了解所需选项及其应放置的位置。

如果你使用 TypeScript，模块会增强 WXT 的类型，因此如果缺少或错误的选项，你将收到类型错误。

执行顺序 ​

模块的加载顺序与钩子的执行顺序相同。有关更多详细信息，请参阅 钩子文档。

编写模块 ​

以下是一个基本的 WXT 模块的样子：

import { defineWxtModule } from 'wxt/modules';
export default defineWxtModule({
  setup(wxt) {
    // 你的模块代码...
  },
});

每个模块的 setup 函数在 wxt.config.ts 文件加载后执行。wxt 对象提供了编写模块所需的一切：

• 使用 wxt.hook(...) 钩入构建生命周期并进行修改
• 使用 wxt.config 获取项目 wxt.config.ts 文件中的解析配置
• 使用 wxt.logger 向控制台记录消息
• 等等！

请参阅 API 参考 以获取可用属性和函数的完整列表。

此外，务必阅读所有 可用的钩子 - 它们对于编写模块至关重要。

示例 ​

模块是复杂的，需要对 WXT 的代码及其工作原理有更深入的了解。最好的学习方法是通过示例。

更新解析配置 ​

import { defineWxtModule } from 'wxt/modules';
export default defineWxtModule({
  setup(wxt) {
    wxt.hook('config:resolved', () => {
      wxt.config.outDir = 'dist';
    });
  },
});

添加构建时配置 ​

import { defineWxtModule } from 'wxt/modules';
import 'wxt';
export interface MyModuleOptions {
  // 添加你的构建时选项...
}
declare module 'wxt' {
  export interface InlineConfig {
    // 在 wxt.config.ts 中为 "myModule" 键添加类型
    myModule: MyModuleOptions;
  }
}
export default defineWxtModule<AnalyticModuleOptions>({
  configKey: 'myModule',
  // 构建时配置通过 setup 的第二个参数可用
  setup(wxt, options) {
    console.log(options);
  },
});

添加运行时配置 ​

import { defineWxtModule } from 'wxt/modules';
import 'wxt/utils/define-app-config';
export interface MyModuleRuntimeOptions {
  // 添加你的运行时选项...
}
declare module 'wxt/utils/define-app-config' {
  export interface WxtAppConfig {
    myModule: MyModuleOptions;
  }
}

运行时选项在调用时返回

const config = useAppConfig();
console.log(config.myModule);

这在 生成运行时代码 时非常有用。

生成输出文件 ​

import { defineWxtModule } from 'wxt/modules';
export default defineWxtModule({
  setup(wxt) {
    // 相对于输出目录
    const generatedFilePath = 'some-file.txt';
    wxt.hook('build:publicAssets', (_, assets) => {
      assets.push({
        relativeDest: generatedFilePath,
        contents: 'some generated text',
      });
    });
    wxt.hook('build:manifestGenerated', (_, manifest) => {
      manifest.web_accessible_resources ??= [];
      manifest.web_accessible_resources.push({
        matches: ['*://*'],
        resources: [generatedFilePath],
      });
    });
  },
});

然后可以在运行时加载此文件：

const res = await fetch(browser.runtime.getURL('/some-text.txt'));

添加自定义入口点 ​

一旦发现 entrypoints/ 目录下的现有文件，可以使用 entrypoints:found 钩子来添加自定义入口点。

INFO

entrypoints:found 钩子在对入口点列表进行验证之前触发。因此，任何自定义入口点仍会被检查是否有重复名称，并在调试时记录。

import { defineWxtModule } from 'wxt/modules';
export default defineWxtModule({
  setup(wxt) {
    wxt.hook('entrypoints:found', (_, entrypointInfos) => {
      // 添加你的新入口点
      entrypointInfos.push({
        name: 'my-custom-script',
        inputPath: 'path/to/custom-script.js',
        type: 'content-script',
      });
    });
  },
});

生成运行时模块 ​

在 .wxt 中创建一个文件，添加别名以导入它，并为导出的变量添加自动导入。

import { defineWxtModule } from 'wxt/modules';
import { resolve } from 'node:path';
export default defineWxtModule({
  imports: [
    // 添加自动导入
    { from: '#analytics', name: 'analytics' },
    { from: '#analytics', name: 'reportEvent' },
    { from: '#analytics', name: 'reportPageView' },
  ],
  setup(wxt) {
    const analyticsModulePath = resolve(
      wxt.config.wxtDir,
      'analytics/index.ts',
    );
    const analyticsModuleCode = `
      import { createAnalytics } from 'some-module';
      export const analytics = createAnalytics(useAppConfig().analytics);
      export const { reportEvent, reportPageView } = analytics;
    `;
    addAlias(wxt, '#analytics', analyticsModulePath);
    wxt.hook('prepare:types', async (_, entries) => {
      entries.push({
        path: analyticsModulePath,
        text: analyticsModuleCode,
      });
    });
  },
});

生成声明文件 ​

import { defineWxtModule } from 'wxt/modules';
import { resolve } from 'node:path';
export default defineWxtModule({
  setup(wxt) {
    const typesPath = resolve(wxt.config.wxtDir, 'my-module/types.d.ts');
    const typesCode = `
      // 声明全局类型，进行类型增强
    `;
    wxt.hook('prepare:types', async (_, entries) => {
      entries.push({
        path: 'my-module/types.d.ts',
        text: `
          // 声明全局类型，进行类型增强等
        `,
        // 重要 - 没有这一行，你的声明文件将不会成为 TS 项目的一部分：
        tsReference: true,
      });
    });
  },
});

示例模块 ​

你还应该查看其他人编写的并发布的模块代码。这里有一些示例：

• @wxt-dev/auto-icons
• @wxt-dev/i18n
• @wxt-dev/module-vue
• @wxt-dev/module-solid
• @wxt-dev/module-react
• @wxt-dev/module-svelte

最后感谢阅读！欢迎关注我，微信公众号 ：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！