You may be using a browser extension. Some extensions are very popular and useful, such as ad blockers, password managers, and PDF viewers. These extensions (or "add-ons") aren't limited to this - you can do more with them! This article will explain how to create an extension. Eventually, we will make it run in multiple browsers.
We will make an extension called "Reddit Transcription" that will improve Reddit accessibility by moving specific comments to the top of the comment section and adding aria- attribute to the screen reader. We will also take our extension a step further by adding options to add borders and backgrounds to comments for better text contrast.
The whole idea is to give you a good idea of how to develop browser extensions. We will first create extensions for Chromium-based browsers such as Google Chrome, Microsoft Edge, Brave, etc. In future articles, we will port the extension to make it compatible with Firefox, and recently added Safari for Web Extensions support in its MacOS and iOS versions of browsers.
Is the GitHub codebase ready? Let's do it step by step.
First, we need a project workspace. All we really need is to create a folder and name it (I named it transistors-of-reddit). Then, create a folder called src in it for our source code.
An entry point is a file that contains general information about the extension (i.e., extension name, description, etc.) and defines the permissions or scripts to be executed.
Our entry point can be the manifest.json file located in the src folder we just created. In it, let's add the following three properties:
<code>{ "manifest_version": 3, "name": "Reddit 转录器", "version": "1.0" }</code>manifest_version is similar to the version in npm or Node. It defines which APIs are available (or not available). We will be using the latest version 3 (also known as mv3) for cutting-edge work.
The second property is name, which specifies our extension name. This name is the name that our extension appears when it appears everywhere, such as the Chrome Web Store and the Chrome://extensions page in the Chrome browser.
Then there is version. It marks the extension with a version number. Remember that this property (as opposed to manifest_version) is a string that can only contain numbers and dots (e.g. 1.3.5).
In fact, we can add more to help add the context of the extension. For example, we can provide a description that explains the functionality of an extension. It is best to provide this information as it gives users a better understanding of what they will encounter when using the extension.
In this example, we not only add a description, but also provide the icons and URLs that the Chrome Web Store points to on its extension page.
<code>{ "description": "使Reddit 对残疾用户更易于访问。", "icons": { "16": "images/logo/16.png", "48": "images/logo/48.png", "128": "images/logo/128.png" }, "homepage_url": "https://www.php.cn/link/530ebdeb0491c0459e00298fcdb3a2bd/extensions/tor/" }</code>One of the great advantages of extensions is that their API allows you to interact directly with your browser. But we must explicitly grant these permissions to the extension, which is also included in the manifest.json file.
<code>{ "manifest_version": 3, "name": "Reddit 转录器", "version": "1.0", "description": "使Reddit 对残疾用户更易于访问。", "icons": { "16": "images/logo/16.png", "48": "images/logo/48.png", "128": "images/logo/128.png" }, "homepage_url": "https://www.php.cn/link/530ebdeb0491c0459e00298fcdb3a2bd/extensions/tor/", "permissions": [ "storage", "webNavigation" ] }</code>What permissions do we just granted this extension? First of all, storage. We want this extension to save the user's settings, so we need to access the browser's web storage to save them. For example, if the user wants the comment to show a red border, we will save the setting for the next time instead of having them set it again.
We also grant the extension permission to see how users navigate to the current screen. Reddit is a single page application (SPA), which means it does not trigger page refresh. We need to "capture" this interaction because Reddit will only load comments for posts when we click on them. So, that's why we take advantage of webNavigation.
We'll cover executing code on the page later, as it requires adding a brand new entry in manifest.json.
/Explanation Depending on the permissions allowed, the browser may display a warning to the user to accept permissions. However, only certain permissions are like this, and Chrome has a good overview of these permissions.
The browser extension has a built-in internationalized (i18n) API. It allows you to manage translations in multiple languages (full list). To use the API, we must define our translation and default language in the manifest.json file:
<code>"default_locale": "en"</code>
This sets English as language. If the browser is set to any other language that is not supported, the extension falls back to the default locale (en in this example).
Our translation is defined in the _locales directory. Let's create a folder in it for each language to support. Each subdirectory has its own messages.json file.
<code>src └─ _locales └─ en └─ messages.json └─ fr └─ messages.json</code>
A translation file contains multiple parts:
Here is an example that brings all of this together:
<code>{ "userGreeting": { // 翻译键(“id”) "message": "Good $daytime$, $user$!" // 翻译"description": "用户问候", // 翻译人员的可选描述"placeholders": { // 可选占位符"daytime": { // 如消息中所引用"content": "$1", "example": "morning" // 我们内容的示例值}, "user": { "content": "$1", "example": "Lars" } } } }</code>Using placeholders is a bit difficult. First, we need to define placeholders in the message. Placeholders need to be enclosed in $ characters. After that, we have to add the placeholder to the "placeholder list". This is a bit unintuitive, but Chrome wants to know what value should be inserted for our placeholders. We (apparently) want to use dynamic values here, so we use a special content value $1 to reference the value we inserted.
The example property is optional. It can be used to prompt the translator what the placeholder might be (but it doesn't actually show).
We need to define the following translation for our extension. Copy and paste them into the messages.json file. Feel free to add more languages (for example, if you speak German, add a de folder in _locales, and so on).
<code>{ "name": { "message": "Reddit 转录器" }, "description": { "message": "子reddits 的辅助图像描述。" }, "popupManageSettings": { "message": "管理设置" }, "optionsPageTitle": { "message": "设置" }, "sectionGeneral": { "message": "常规设置" }, "settingBorder": { "message": "显示评论边框" }, "settingBackground": { "message": "显示评论背景" } }</code>You might be wondering why we registered without the i18n permissions, right? Chrome is a little weird in this regard, because you don't need to register every permission. Some (such as chrome.i18n) do not require registration in manifest. Other permissions require an entry, but are not displayed to the user when the extension is installed. Some other permissions are "mixed" (such as chrome.runtime), which means some of their features can be used without declaring permissions - but other features of the same API require an entry registered in the manifest. You need to look at the documentation to fully understand these differences.
The first thing end users see is an entry or extension overview page in the Chrome Web Store. We need to adjust the manifest file to make sure everything is translated.
<code>{ // 更新这些条目"name": "__MSG_name__", "description": "__MSG_description__" }</code>Applying this syntax will use the corresponding translation in the messages.json file (for example, _MSG name is translated using name).
Applying translation in HTML files requires some JavaScript.
<code>chrome.i18n.getMessage('name');</code>This code returns the translation we defined (i.e., Reddit transcript). Placeholders can be done in a similar way.
<code>chrome.i18n.getMessage('userGreeting', { daytime: 'morning', user: 'Lars' });</code>Applying translation to all elements this way can be cumbersome. But we can write a small script that performs translation according to the data- attribute. So let's create a new js folder in the src directory and then add a new util.js file in it.
<code>src └─ js └─ util.js</code>
This can accomplish the task:
<code>const i18n = document.querySelectorAll("[data-intl]"); i18n.forEach(msg => { msg.innerHTML = chrome.i18n.getMessage(msg.dataset.intl); }); chrome.i18n.getAcceptLanguages(languages => { document.documentElement.lang = languages[0]; });</code>After adding this script to the HTML page, we can add a data-intl attribute to the element to set its contents. The document language will also be set according to the user's language.
<code> </code>
<code>管理设置</code>
Before we dive into actual programming, we need to create two pages:
Here is an overview of the folders and files we need to create the page:
<code>src ├─ css | └─ paintBucket.css ├─ popup | ├─ popup.html | ├─ popup.css | └─ popup.js └─ options ├─ options.html ├─ options.css └─ options.js</code>
The .css file contains pure CSS, that's it. I won't go into details, because I know that most of you readers already have a complete understanding of how CSS works. You can copy and paste styles from the project's GitHub repository.
Note that the popup is not a tab, its size depends on what it is inside. If you want to use a fixed-size popup, you can set the width and height properties on the html element.
This is an HTML skeleton that links CSS and JavaScript files and in
Add title and buttons to it. ```
<code><meta charset="UTF-8"> <meta content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0" name="viewport"> <meta content="ie=edge" http-equiv="X-UA-Compatible"></code> <title data-intl="name"></title><link href="../css/paintBucket.css" rel="stylesheet"><link href="popup.css" rel="stylesheet"><h1></h1>
<code>h1 包含扩展程序名称和版本；按钮用于打开选项页面。标题将不会填充翻译（因为它缺少data-intl 属性），并且按钮还没有任何点击处理程序，因此我们需要填充popup.js 文件：</code>
const title = document.getElementById('title'); const settingsBtn = document.querySelector('button'); const manifest = chrome.runtime.getManifest();
title.textContent = ${manifest.name} (${manifest.version}) ;
settingsBtn.addEventListener('click', () => { chrome.runtime.openOptionsPage(); });
<code>此脚本首先查找manifest 文件。Chrome 提供了包含getManifest 方法的runtime API（此特定方法不需要runtime 权限）。它将我们的manifest.json 返回为JSON 对象。在我们使用扩展程序名称和版本填充标题后，我们可以向设置按钮添加事件侦听器。如果用户与之交互，我们将使用chrome.runtime.openOptionsPage() 打开选项页面（同样不需要权限条目）。弹出窗口页面现在已完成，但扩展程序尚不知道它的存在。我们必须通过将以下属性附加到manifest.json 文件来注册弹出窗口。</code>
"action": { "default_popup": "popup/popup.html", "default_icon": { "16": "images/logo/16.png", "48": "images/logo/48.png", "128": "images/logo/128.png" } },
<code>#### 创建选项页面创建此页面的过程与我们刚刚完成的过程非常相似。首先，我们填充options.html 文件。以下是一些我们可以使用的标记：</code>
<circle cx="12" cy="12" r="3"></circle><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"></path>
<code><div></div></code> <p>Reddit transcriptionist extension provided by <a href="https://www.php.cn/link/530ebdeb0491c0459e00298fcdb3a2bd" target="_blank">lars.koelker.dev</a> .</p>
Reddit is a registered trademark of Reddit, Inc. This extension is not endorsed or associated with Reddit, Inc. in any way.
<code>目前还没有实际的选项（只有它们的包装器）。我们需要编写选项页面的脚本。首先，我们在options.js 中定义变量以访问我们的包装器和默认设置。“冻结”我们的默认设置可以防止我们以后意外修改它们。</code>
const defaultSettings = Object.freeze({ border: false, background: false, }); const generalSection = document.getElementById('generalOptionsWrapper');
<code>接下来，我们需要加载保存的设置。我们可以为此使用（先前注册的）存储API。具体来说，我们需要定义是要在本地存储数据(chrome.storage.local) 还是通过登录的所有设备同步设置(chrome.storage.sync)。让我们在这个项目中使用本地存储。需要使用get 方法检索值。它接受两个参数： 1. 我们要加载的条目2. 包含值的回调我们的条目可以是字符串（例如，下面的settings）或条目数组（如果我们想要加载多个条目，则很有用）。回调函数中的参数包含我们先前在{ settings: ... } 中定义的所有条目的对象：</code>chrome.storage.local.get('settings', ({ settings }) => { const options = settings ?? defaultSettings; // If the settings are not defined, fall back to the default settings if (!settings) { chrome.storage.local.set({ settings: defaultSettings, }); }
// Create and display options const generalOptions = Object.keys(options).filter(x => !x.startsWith('advanced'));
generalOptions.forEach(option => createOption(option, options, generalSection)); });
<code>为了呈现选项，我们还需要创建一个createOption() 函数。</code>
function createOption(setting, settingsObject, wrapper) { const settingWrapper = document.createElement("div"); settingWrapper.classList.add("setting-item"); settingWrapper.innerHTML = <div><label for="${setting}">${chrome.i18n.getMessage(</label></div> setting${setting}`)}
`;
const toggleSwitch = settingWrapper.querySelector("label.is-switch"); const input = settingWrapper.querySelector("input");
input.onchange = () => { toggleSwitch.setAttribute('aria-checked', input.checked); updateSetting(setting, input.checked); };
toggleSwitch.onkeydown = e => { if(e.key === " " || e.key === "Enter") { e.preventDefault(); toggleSwitch.click(); } }
wrapper.appendChild(settingWrapper); }
<code>在我们的开关（又名单选按钮）的onchange 事件侦听器中，我们调用函数updateSetting。此方法将把单选按钮的更新值写入存储中。为此，我们将使用set 函数。它有两个参数：我们要覆盖的条目和（可选）回调（在本例中我们不使用）。由于我们的settings 条目不是布尔值或字符串，而是一个包含不同设置的对象，因此我们使用扩展运算符(...) 并仅覆盖settings 对象中的实际键(setting)。</code>
function updateSetting(key, value) { chrome.storage.local.get('settings', ({ settings }) => { chrome.storage.local.set({ settings: { ...settings,
<code> } })</code>
}); }
<code>同样，我们需要通过将以下条目附加到manifest.json 来“通知”扩展程序我们的选项页面：</code>
"options_ui": { "open_in_tab": true, "page": "options/options.html" },
<code>根据您的用例，您还可以通过将open_in_tab 设置为false 来强制选项对话框作为弹出窗口打开。 ### 安装开发扩展程序现在我们已经成功设置了manifest 文件并将弹出窗口和选项页面都添加到了组合中，我们可以安装扩展程序来检查我们的页面是否正常工作。导航到chrome://extensions 并启用“开发者模式”。将出现三个按钮。单击标记为“加载解压”的按钮，然后选择扩展程序的src 文件夹以加载它。扩展程序现在应该已成功安装，并且我们的“Reddit 转录器”图块应该在页面上。我们现在已经可以与扩展程序交互了。单击地址栏旁边的拼图块(?) 图标，然后单击新添加的“Reddit 转录器”扩展程序。您现在应该会看到一个小的弹出窗口，其中包含一个按钮，用于打开选项页面。不错吧？在我的设备上它可能看起来有点不同，因为我在这些屏幕截图中启用了深色模式。如果您启用“显示评论背景”和“显示评论边框”设置，然后重新加载页面，则状态将保留，因为我们将其保存在浏览器的本地存储中。 ### 添加内容脚本好的，我们现在已经可以触发弹出窗口并与扩展程序设置交互，但是扩展程序本身还没有做任何特别有用的事情。为了让它发挥作用，我们将添加一个内容脚本。在js 目录中添加一个名为comment.js 的文件，并确保在manifest.json 文件中定义它：</code>
"content_scripts": [ { "matches": [ " ://www.reddit.com/ " ], "js": [ "js/comment.js" ] } ],
<code>content_scripts 由两部分组成： - matches：此数组保存URL，这些URL 告诉浏览器我们希望内容脚本在何处运行。作为Reddit 的扩展程序，我们希望它在与://www.redit.com/* 匹配的任何页面上运行，其中星号是通配符，用于匹配顶级域之后的任何内容。 - js：此数组包含实际的内容脚本。内容脚本无法与其他（普通）JavaScript 交互。这意味着如果网站的脚本定义了变量或函数，我们就无法访问它。例如：</code>
// script_on_website.js const username = 'Lars';
// content_script.js console.log(username); // Error: username not defined
<code>现在让我们开始编写内容脚本。首先，我们在comment.js 中添加一些常量。这些常量包含稍后将使用的RegEx 表达式和选择器。CommentUtils 用于确定帖子是否包含“tor 评论”，或者是否存在评论包装器。</code>
const messageTypes = Object.freeze({ COMMENT_PAGE: 'comment_page', SUBREDDIT_PAGE: 'subreddit_page', MAIN_PAGE: 'main_page', OTHER_PAGE: 'other_page', });
const Selectors = Object.freeze({ commentWrapper: 'div[style ="--commentswrapper-gradient-color"] > div, div[style ="max-height: unset"] > div', torComment: 'div[data-tor-comment]', postContent: 'div[data-test-]' });
const UrlRegex = Object.freeze({ commentPage: /\/r\/. \/comments\/. /, subredditPage: /\/r\/.*\// });
const CommentUtils = Object.freeze({ isTorComment: (comment) => comment.querySelector('[data-test-]') ? comment.querySelector('[data-test-]').textContent.includes('ma human volunteer content transmitter for Reddit') : false, torCommentsExist: () => !!document.querySelector(Selectors.torComment), commentWrapperExists: () => !!document.querySelector('[data-reddit-comment-wrapper="true"]') });
<code>接下来，我们检查用户是否直接打开评论页面（“帖子”），然后执行RegEx 检查并更新directPage 变量。当用户直接打开URL（例如，通过将其键入地址栏或单击另一个页面上的<a> 元素（例如Twitter））时，就会发生这种情况。</a></code>
let directPage = false; if (UrlRegex.commentPage.test(window.location.href)) { directPage = true; moveComments(); }
<code>除了直接打开页面外，用户通常还会与SPA 交互。为了捕获这种情况，我们可以通过使用runtime API 向comment.js 文件添加消息侦听器。</code>
chrome.runtime.onMessage.addListener(msg => { if (msg.type === messageTypes.COMMENT_PAGE) { waitForComment(moveComments); } });
<code>我们现在只需要这些函数。让我们创建一个moveComments() 函数。它将特殊的“tor 评论”移动到评论部分的开头。它还会根据设置中是否启用了边框，有条件地将背景颜色和边框应用于评论。为此，我们调用存储API 并加载settings 条目：</code>
function moveComments() { if (CommentUtils.commentWrapperExists()) { return; }
const wrapper = document.querySelector(Selectors.commentWrapper); let comments = wrapper.querySelectorAll( ${Selectors.commentWrapper} > div ); const postContent = document.querySelector(Selectors.postContent);
wrapper.dataset.redditCommentWrapper = 'true'; wrapper.style.flexDirection = 'column'; wrapper.style.display = 'flex';
if (directPage) { comments = document.querySelectorAll("[data-reddit-comment-wrapper='true'] > div"); }
chrome.storage.local.get('settings', ({ settings }) => { // HIGHLIGHT 18 comments.forEach(comment => { if (CommentUtils.isTorComment(comment)) { comment.dataset.torComment = 'true'; if (settings.background) { comment.style.backgroundColor = 'var(--newCommunityTheme-buttonAlpha05)'; } if (settings.border) { comment.style.outline = '2px solid red'; } comment.style.order = "-1"; applyWaiAria(postContent, comment); } }); }) }
<code>applyWaiAria() 函数在moveComments() 函数中调用——它添加aria- 属性。另一个函数创建唯一标识符以与aria- 属性一起使用。</code>
function applyWaiAria(postContent, comment) { const postMedia = postContent.querySelector('img[class*="ImageBox-image"], video'); const commentId = uuidv4();
if (!postMedia) { return; }
comment.setAttribute('id', commentId); postMedia.setAttribute('aria-describedby', commentId); }
function uuidv4() { return 'xxxxxxx-xxxx-4xxx-yxxxx-xxxxxxxxxxxxxxx'.replace(/[xy]/g, function(c) { var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8); return v.toString(16); }); }
<code>以下函数等待评论加载，如果找到评论包装器，则调用回调参数。</code>
function waitForComment(callback) { const config = { childList: true, subtree: true }; const observer = new MutationObserver(mutations => { for (const mutation of mutations) { if (document.querySelector(Selectors.commentWrapper)) { callback(); observer.disconnect(); clearTimeout(timeout); break; } } });
observer.observe(document.documentElement, config); const timeout = startObservingTimeout(observer, 10); }
function startObservingTimeout(observer, seconds) { return setTimeout(() => { observer.disconnect(); }, 1000 * seconds); }
<code>### 添加服务工作者还记得我们在内容脚本中添加了消息侦听器吗？此侦听器当前未接收消息。我们需要自己将其发送到内容脚本。为此，我们需要注册一个服务工作者。我们必须通过将以下代码附加到manifest.json 来注册服务工作者：</code>
"background": { "service_worker": "sw.js" }
<code>不要忘记在src 目录中创建sw.js 文件（服务工作者始终需要在扩展程序的根目录src 中创建）。现在，让我们为消息和页面类型创建一些常量：</code>
const messageTypes = Object.freeze({ COMMENT_PAGE: 'comment_page', SUBREDDIT_PAGE: 'subreddit_page', MAIN_PAGE: 'main_page', OTHER_PAGE: 'other_page', });
const UrlRegex = Object.freeze({ commentPage: /\/r\/. \/comments\/. /, subredditPage: /\/r\/.*\// });
const Utils = Object.freeze({ getPageType: (url) => { if (new URL(url).pathname === '/') { return messageTypes.MAIN_PAGE; } else if (UrlRegex.commentPage.test(url)) { return messageTypes.COMMENT_PAGE; } else if (UrlRegex.subredditPage.test(url)) { return messageTypes.SUBREDDIT_PAGE; }
<code>return messageTypes.OTHER_PAGE;</code>
} });
<code>我们可以添加服务工作者的实际内容。我们使用历史状态上的事件侦听器(onHistoryStateUpdated) 来执行此操作，该侦听器检测何时使用History API 更新页面（通常在SPA 中用于在没有页面刷新情况下导航）。在此侦听器中，我们查询活动选项卡并提取其tabId。然后，我们将包含页面类型和URL 的消息发送到我们的内容脚本。</code>
chrome.webNavigation.onHistoryStateUpdated.addListener(async ({ url }) => { const [{ id: tabId }] = await chrome.tabs.query({ active: true, currentWindow: true });
chrome.tabs.sendMessage(tabId, { type: Utils.getPageType(url), url }); });
<code>### 全部完成！我们完成了！导航到Chrome 的扩展程序管理页面(chrome://extensions)，然后点击解压扩展程序上的重新加载图标。如果您打开包含“Reddit 转录器”评论和图像转录的Reddit 帖子（例如此帖子），只要我们在扩展程序设置中启用了它，它就会被移动到评论部分的开头并突出显示。 ### 结论这是否像您想象的那么难？在我深入研究之前，它肯定比我想象的要简单得多。在设置manifest.json 并创建任何我们需要的文件和资产后，我们真正做的只是像往常一样编写HTML、CSS 和JavaScript。如果您在途中遇到任何问题，Chrome API 文档是一个很好的资源，可以帮助您重回正轨。再次声明，这是包含我们在本文中介绍的所有代码的GitHub 代码库。阅读它，使用它，并让我知道您的想法！</code>
The above is the detailed content of How to Create a Browser Extension. For more information, please follow other related articles on the PHP Chinese website!
![[Web front-end] Node.js quick start](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
