Chrome 扩展程序 101 - 环境设置

我想在浏览器中添加一些有趣的功能。也许我可以用一个简单的扩展来添加它？它不存在，但是自己编写它应该很容易，对吧？

几天前我就是这么想的。虽然我没有错，但开发过程的某些部分比我预期的要耗费更多时间。我不会说很难，但使用现有文档很难弄清楚。虽然 API 文档、核心概念等在 developer.chrome.com 上描述得相当好，但我希望获得特定的开发人员体验：

正确键入 chrome 命名空间的 TypeScript

将代码拆分为多个文件并导入/导出必要的内容

使用简单的 console.log 和/或调试器调试我的代码

我的 manifest.json 中的自动完成

设置简单，无需任何打包器，我的 node_modules 中只有一半的互联网资源

在浏览器中更新和测试扩展的简单方法

不管怎样，我设法按照自己的意愿设置了一切。在这篇文章中，我将简要解释一般的扩展概念，并向您展示我如何设置我的开发环境。在接下来的一两篇文章中，我将重点介绍我的简单页面音频扩展的实现细节。

总结：

如果你只是想要代码，这里是样板仓库：

Voodu / chromium-extension-boilerplate

Chrominium 扩展样板

这个存储库旨在成为开发 Chromium 扩展的起点。

它尽可能简约，但带有预先配置：

manifest.json 的自动完成

将 TypeScript 从 ts 文件夹转译到 dist 目录

chrome 命名空间的类型

导出和导入工作正常（使用 VS Code 工作区设置以获得正确的自动导入格式）

示例 manifest.json

相关博客文章：https://dev.to/voodu/chrome-extension-101-environment-setup-4536

祝你编码愉快！

在 GitHub 上查看

ℹ️ℹ️

扩展简介

让我们从一般扩展概念的速成课程开始。

每个扩展都有一个 `manifest.json` 文件，其中定义了其名称、版本、所需权限和使用的文件。扩展可以通过多种不同的方式提供功能：

通过弹出窗口 - 扩展弹出窗口是当您单击扩展栏中的扩展图标时打开的小窗口，

通过内容脚本（直接注入网站并具有 DOM 访问权限的脚本），

通过后台（服务工作者）脚本 - 脚本在单独的上下文中运行，独立于打开的网站

还有其他方法，但在本指南中我将坚持使用这三种方法。

另一个重要概念是**消息传递**。通常，我们需要结合使用上述方法，因为它们都有不同的限制。例如，后台脚本不依赖于打开的选项卡，并且更适合用于持久化状态，但无法访问任何网站的 DOM。因此，我们可能需要从后台脚本获取一些扩展范围的数据，使用消息将其传递给内容脚本，然后从那里修改网站。

了解一些有关权限的基础知识也很有用。简而言之，如果 `manifest.json` 没有指定正确的权限，某些 API 将无法按预期工作。例如，如果我们不指定 `“tabs”` 权限，则从 `tabs` API 返回的对象将没有 `url` 字段。另一方面，我们不应该请求太多权限 - 如果扩展程序要公开，用户可能会担心授予太多访问权限。

创建一个简单的扩展

让我们首先使用一个非常简单的扩展来理解我们开发工作流程的核心概念，该扩展仅在弹出窗口中显示一些文本。

文件

首先，我们需要一个 `manifest.json` 文件：

// manifest.json
{
  "name": "Hello World",
  "description": "Shows Hello World text",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "icon.png"
  }
}

`name`、`description`、`version` 和 `manifest_version` 可能不言自明。`action.default_popup` 是单击扩展图标时将呈现的 HTML 文件的路径。`default_icon` 是扩展图标的路径。这两个路径都相对于 `manifest.json` 位置。

现在，在与“manifest.json”相同的目录中添加“icon.png”（例如这个）和“hello.html”文件。

`hello.html` 看起来是这样的：

Hello world

你的整个目录看起来应该是这样的：

.
├── hello.html
├── icon.png
└── manifest.json

激活扩展

要激活您的扩展程序：

前往 edge://extensions/

在左侧边栏中，启用“开发者模式”，可能还需要“允许来自其他商店的扩展”

在扩展列表上方单击“加载已解压的扩展”

选择包含扩展文件的文件夹

您的扩展程序应出现在列表中，其图标也出现在扩展程序工具栏中 🥳

现在，单击图标后，它将显示一个带有“Hello world”文本的小弹出窗口。

这涵盖了最重要的基础知识。让我们讨论一些更有趣的内容。

Page-Audio 扩展环境设置

manifest.json 中的自动完成功能

我们将从“manifest.json”和空目录重新开始。

如果在编写 `manifest.json` 文件时有自动完成功能就太好了，不是吗？幸运的是，这是一个定义明确的标准，并且在 https://json.schemastore.org/chrome-manifest 上有一个 JSON 模式。我们只需要在 `manifest.json` 开头的“$schema”键下使用它：

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest"
}

VS Code 会立即开始帮助我们，建议字段名称并在缺少必填字段时显示警告。太棒了！🔥

为了测试我们的设置，请使用如下所示的“manifest.json”：

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest",
    "name": "Page Audio",
    "version": "0.0.0.1",
    "manifest_version": 3,
    "icons": {
        "16": "icons/logo16x16.png",
        "32": "icons/logo32x32.png",
        "48": "icons/logo48x48.png",
        "128": "icons/logo128x128.png"
    },
    "background": {
        "service_worker": "dist/background.js",
        "type": "module"
    }
}

图标 - 这只是指定扩展图标的不同方式

背景部分 - 指定服务工作线程 JS 文件的路径及其类型；它是模块，因为代码稍后将使用导出和导入

TypeScript

使用 TypeScript... 嗯，需要 TypeScript。如果你没有安装它，请先安装

npm install -g typescript

基本配置

为了使内容井然有序但又不至于太复杂，我将把 `.ts` 源文件保存在 `ts` 目录中。转译器将从那里取出它们，并将其作为 `.js` 文件放入 `dist` 目录中。

以下 `.tsconfig` 描述了这一点：

// .tsconfig
{
    "compilerOptions": {
        "target": "ES6",
        "module": "ES6",
        "outDir": "./dist",
        "rootDir": "./ts",
        "strict": true,
    }
}

最重要的部分是“compiler.rootDir”和“compiler.outDir”。其他字段可以具有不同的值或被完全删除（至少其中一些）。

这是基本配置 - 将一些文件放在 `ts` 目录中，然后在根目录中运行 `tsc` 将在 `dist` 中创建相应的 `.js` 文件。但是，我们缺少一个重要部分 - 我们将使用的 `chrome` 命名空间的类型。最简单的解决方案是通过 npm 添加它们。

添加 chrome 类型

创建一个空的 `package.json`，只带有括号：

// package.json
{
}

并在命令行运行：

npm i -D chrome-types

您还可以添加“脚本”来运行“tsc”构建并处于监视模式。最终的“package.json”应如下所示：

// package.json
{
    "scripts": {
        "build": "tsc",
        "watch": "tsc -w"
    },
    "devDependencies": {
        "chrome-types": "^0.1.327"
    }
}

ℹ️ℹ️

添加类型后，我们需要让 TypeScript 知道它们。为此，只需更新 `.tsconfig.json`：

// .tsconfig.json
{
    "compilerOptions": {
        "target": "ES6",
        "module": "ES6",
        "outDir": "./dist",
        "rootDir": "./ts",
        "strict": true,
        "types": ["chrome-types"] // Add this line!
    }
}

要测试我们的设置是否正常工作：

在 ts 文件夹中，创建 background.ts 文件，内容如下 // ts/background.ts chrome.runtime.onInstalled.addListener(() => { console.log('Service Worker Installed'); });

在命令行中运行 npm run watch

验证 dist 目录是否已创建且 background.js 文件是否出现在那里

在 ts/background.ts 文件中的 console.log 字符串中更改一些内容并保存

检查它是否自动更新了 dist/background.js。

如果成功了，太棒了！我们几乎已经设置好了一切 🎉

您还可以验证您的目录结构是否与以下内容类似：

.
├── dist
│   └── background.js
├── icons
│   ├── logo128x128.png
│   ├── logo16x16.png
│   ├── logo32x32.png
│   └── logo48x48.png
├── manifest.json
├── node_modules
│   └── chrome-types
│       └── ... some stuff inside ...
├── package-lock.json
├── package.json
├── ts
│   └── background.ts
└── tsconfig.json

进出口

正如我所提到的，我想将代码拆分成更小的文件。要做到这一点，“导出”和“导入”必须正常工作。

朝这个方向迈出的一步是将“manifest.json”中的“service_worker”指定为“"type": "module"”。但是，在使用模块时，TypeScript 和 JavaScript 之间存在一个区别 - 虽然 TypeScript 在导入时不需要文件扩展名，但 JavaScript 需要。因此，例如，此导入：

import { something } from "./fileWithFunctions";

可以在 TS 中使用，但 JS 需要

import { something } from "./fileWithFunctions.js";

还需要理解的是，TS 转译器对导入路径**不做任何事**。它足够“聪明”，能够理解从 `file.js` 导入时还应该查找 `file.ts`。

结合所有这些，TS 也将乐于接受 JS 样式的导入，并在从 `file.js` 导入时使用相应的 TS 文件。需要做的是确保 TS 文件中的所有导入都具有 `.js` 扩展名。要在 VS Code 中自动执行此操作：

按 CTRL + , 打开设置

切换到“工作区”选项卡

搜索 typescript.preferences.importModuleSpecifierEnding

将其设置为“.js / .ts”选项

现在，每当你使用 VS Code 自动导入时，它都会将 `.js` 添加到文件名中 🧠

测试是否正常工作：

创建 ts/hello.ts 文件，内容如下 // ts/hello.ts export function hello() { console.log('Hello'); }

在 ts/background.ts 中删除当前的 console.log 行并开始输入“hello”

在你使用 Tab 接受建议后，VS Code 应该会自动完成并添加正确的导入

最后，该文件应如下所示： // ts/background.ts import { hello } from "./hello.js"; chrome.runtime.onInstalled.addListener(() => { hello(); });

请注意，导入以 `.js` 扩展名结尾。如果您检查 `dist/background.js`，扩展名也在那里，这就是使一切正常工作的原因。

为了确保我们处于同一阶段，您可以比较目录结构：

.
├── .vscode
│   └── settings.json
├── dist
│   ├── background.js
│   └── hello.js
├── icons
│   └── ... icons ...
├── manifest.json
├── node_modules
│   └── chrome-types
│       └── ... some stuff inside ...
├── package-lock.json
├── package.json
├── ts
│   ├── background.ts
│   └── hello.ts
└── tsconfig.json

服务工作者开发工具

好的，我们有了不错的开发体验。我们还添加了一些 `console.log` 调用……但现在在哪里可以找到它们呢？

如果您在内容脚本中添加 `console.log`，则只需打开 Dev Tools 即可看到它们，因为内容脚本的工作环境与它们被注入的页面相同。但是，来自后台脚本的 `console.log` 隐藏得更彻底一些。

打开 edge://extensions/ 并加载你的扩展程序（如果尚未加载）

在列表中找到您的扩展程序

单击“检查视图”行中的“服务工作者”链接：

应该会打开一个新的 Dev Tools 窗口，您将在那里看到来自服务工作者的日志，如果您没有看到日志，请单击“检查视图”下方的“重新加载”

磁贴底部的三个链接也非常重要

“重新加载”-刷新整个扩展，包括对 manifest.json 的更改；查看此表以了解何时可能需要重新加载

“删除”-删除扩展

“详细信息”-显示有关扩展的更多信息，例如其权限

（可选）“错误” - 如果在安装 Service Worker 时出现错误，则会出现此链接并将您带到错误列表

呼。这花了一点时间，但最终我们的环境设置好了。从现在开始，我们只需要

运行 npm run watch (如果你已经停止它了)

在 ts 目录中写入我们的代码

（可选）从扩展选项卡重新加载扩展

我们的扩展程序将自动更新！⚙️

概括

我们已经准备好环境了！

自动完成功能在 manifest.json 中起作用，因此我们不必猜测正确的值是什么

TypeScript 帮助我们正确使用 chrome API

代码可以拆分成更小的逻辑文件

我们在ts文件夹中编写的代码会自动更新

我们知道在哪里可以找到服务工作者和内容脚本的开发工具

在下一部分中，我将描述我的小型“页面音频”扩展的实现细节。

感谢阅读！

CLIS.CC