创建您的首个用于在网页上插入新元素的扩展程序。
概览
本教程将构建一个扩展程序,用于将预期阅读时间添加到任何 Chrome 扩展程序和 Chrome 应用商店文档页面。
![在该扩展程序的欢迎页面中读出延长时间](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-on-every-tab/image/reading-extension-the-e-0070620f12665.png?authuser=8&hl=hu)
在本指南中,我们将介绍以下概念:
- 扩展程序清单。
- 扩展程序使用的图标尺寸。
- 如何使用内容脚本将代码注入网页。
- 如何使用匹配模式。
- 扩展程序权限。
前期准备
本指南假定您具备基本的 Web 开发经验。建议您查看 Hello world 教程,了解扩展程序开发工作流。
构建扩展程序
首先,创建一个名为 reading-time
的新目录来存放扩展程序的文件。如果您愿意,可以从 GitHub 下载完整的源代码。
第 1 步:添加扩展程序的相关信息
清单 JSON 文件是唯一的必需文件。其中包含有关扩展程序的重要信息。在项目的根目录中创建 manifest.json
文件,并添加以下代码:
{
"manifest_version": 3,
"name": "Reading time",
"version": "1.0",
"description": "Add the reading time to Chrome Extension documentation articles"
}
这些键包含扩展程序的基本元数据。它们可以控制扩展程序在扩展程序页面上的显示方式,以及扩展程序在 Chrome 应用商店中的发布方式。如需深入了解,请查看清单概览页面上的 "name"
、"version"
和 "description"
键。
💡? 关于扩展程序清单的其他事实
- 它必须位于项目的根目录下。
- 唯一的必需键为
"manifest_version"
、"name"
和"version"
。 - 它支持在开发过程中使用注释 (
//
),但在将代码上传到 Chrome 应用商店之前必须先移除这些注释。
第 2 步:提供图标
那么,为什么需要图标呢?虽然图标在开发过程中是可选的,但如果您计划在 Chrome 应用商店中分发扩展程序,则必须提供图标。它们还会出现在“扩展程序管理”页面等其他位置。
创建一个 images
文件夹并将图标放在其中。您可以在 GitHub 上下载这些图标。接下来,将突出显示的代码添加到清单中以声明图标:
{
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}
我们建议使用 PNG 文件,但允许使用其他文件格式(SVG 文件除外)。
💡? 这些大小不同的图标会显示在什么位置?
图标大小 | 图标的使用 |
---|---|
16x16 | 扩展程序页面和上下文菜单上的网站图标。 |
32x32 | Windows 计算机通常需要此大小。 |
48x48 | 显示在“扩展程序”页面上。 |
128x128 | 安装时会显示在 Chrome 应用商店中。 |
第 3 步:声明内容脚本
扩展程序可以运行用于读取和修改网页内容的脚本。这些脚本称为内容脚本。它们生活在一个独立的世界,这意味着它们可以对其 JavaScript 环境进行更改,而不会影响其托管网页或其他扩展程序的内容脚本。
将以下代码添加到 manifest.json
以注册一个名为 content.js
的内容脚本。
{
"content_scripts": [
{
"js": ["scripts/content.js"],
"matches": [
"https://developer.chrome.com/docs/extensions/*",
"https://developer.chrome.com/docs/webstore/*"
]
}
]
}
"matches"
字段可以有一种或多种匹配模式。这些变量可让浏览器识别要将内容脚本注入到哪些网站。匹配模式由三部分组成:<scheme>://<host><path>
。它们可以包含“*
”字符。
💡? 此扩展程序会显示权限警告吗?
用户安装某个扩展程序后,浏览器会告知他们该扩展程序的用途。内容脚本会请求在符合匹配模式条件的网站上运行该扩展程序。
在此示例中,用户将看到以下权限警告:
![用户在安装“阅读时间”扩展程序时会看到的权限警告](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-on-every-tab/image/permission-warning-user-af0cb023a0128.png?authuser=8&hl=hu)
如需深入了解扩展程序权限,请参阅声明权限并警告用户。
第 4 步:计算并插入阅读时间
内容脚本可以使用标准文档对象模型 (DOM) 读取和更改网页内容。该扩展程序会首先检查该网页是否包含 <article>
元素。
然后,它会统计此元素中的所有字词,并创建一个显示总阅读时间的段落。
在名为 scripts
的文件夹内创建一个名为 content.js
的文件,并添加以下代码:
const article = document.querySelector("article");
// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
const text = article.textContent;
const wordMatchRegExp = /[^\s]+/g; // Regular expression
const words = text.matchAll(wordMatchRegExp);
// matchAll returns an iterator, convert to array to get word count
const wordCount = [...words].length;
const readingTime = Math.round(wordCount / 200);
const badge = document.createElement("p");
// Use the same styling as the publish information in an article's header
badge.classList.add("color-secondary-text", "type--caption");
badge.textContent = `⏱️ ${readingTime} min read`;
// Support for API reference docs
const heading = article.querySelector("h1");
// Support for article docs with date
const date = article.querySelector("time")?.parentNode;
(date ?? heading).insertAdjacentElement("afterend", badge);
}
💡? 这段代码中使用了有趣的 JavaScript
- 用于仅统计
<article>
元素中的字词的正则表达式。 insertAdjacentElement()
,用于在元素后面插入朗读时间节点。- 用于向元素类属性添加 CSS 类名称的 classList 属性。
- 可选链,用于访问可能未定义或为 null 的对象属性。
- 如果
<date>
为 null 或未定义,Null 合并会返回<heading>
。
测试它是否正常运行
验证项目的文件结构是否如下所示:
在本地加载扩展程序
如需在开发者模式下加载已解压的扩展程序,请按照开发基础知识中的步骤操作。
打开扩展程序或 Chrome 应用商店文档
您可以打开以下页面,了解阅读每篇文章所需的时间。
显示的内容应如下所示:
![欢迎页面上运行的阅读时间](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-on-every-tab/image/reading-running-the-wel-1d750346edcea.png?authuser=8&hl=hu)
🎯? 有望改进的方面
根据今天学到的知识,尝试实现以下任何操作:
- 在 manifest.json 中添加另一个匹配模式,以支持其他 Chrome 开发者页面,例如 Chrome 开发者工具或 Workbox。
- 添加新的内容脚本,以计算您喜爱的任意博客或文档网站的阅读时间。
继续构建
恭喜您学完了本教程 🎉?。请继续学习本系列中的其他教程,进一步提升您的技能:
扩展程序 | 学习内容 |
---|---|
专注模式 | 点击扩展程序操作后在当前页面上运行代码。 |
标签页管理器 | 创建一个用于管理浏览器标签页的弹出式窗口。 |
继续探索
我们希望您喜欢这个 Chrome 扩展程序的构建过程,并且很高兴能够继续您的 Chrome 开发学习之旅。我们建议您学习以下学习路线:
- 开发者指南还有数十个额外链接,这些链接指向与创建高级扩展程序相关的文档片段。
- 扩展程序可以访问除开放 Web 上提供的 API 之外的强大 API。 Chrome API 文档详细介绍了各个 API。