【譯】Chrome 擴展 : 入門

時間 2021-05-01

標籤 css html git github web chrome 編程 json api 架構欄目 Chrome 简体版

原文原文鏈接

引子

按照 Chrome 擴展 : 擴展是什麼?中引導，接着就是入門教程。css

原文：Getting started
版本：Updated on Wednesday, November 18, 2020
源庫：developer.chrome.com GitHub
Origin
My GitHub

入門

擴展由不一樣但內聚的組件組成。組件能夠包括後臺腳本、內容腳本、選項頁、UI 元素和各類邏輯文件。擴展組件是使用 web 開發技術建立的：HTML、CSS 和 JavaScript 。擴展的組件將取決於其功能，可能不須要全部選項。html

剛開始，建立一個新文件夾用來存放擴展的文件。git

完整的擴展能夠在這裏下載。github

建立 manifest

擴展從 manifest 開始。建立一個名爲 manifest.json 文件幷包含如下代碼。web

{
  "name": "Getting Started Example",
  "description": "Build an Extension!",
  "version": "1.0",
  "manifest_version": 3
}

在當前狀態下，能夠在開發人員模式下將包含 manifest 文件的目錄添加爲擴展。chrome

導航到 chrome://extensions 打開擴展管理頁面。編程
- 或者點擊擴展菜單按鈕，選擇菜單底部的 Manage Extensions 打開這個頁面。
- 或者點擊 Chrome 菜單，懸浮在 More Tools 以後選擇 Extensions 。
點擊 Developer mode 旁邊的開關，開啓開發者模式。
點擊 Load unpacked 按鈕，並選擇擴展文件夾。

嗒嗒！已成功安裝擴展。由於在 manifest 中沒有包含圖標，因此將爲擴展建立一個通用圖標。json

添加功能

如今已經安裝了擴展，可是它如今什麼作不了，由於咱們尚未告訴它作什麼或者何時作。咱們經過添加一些代碼來存儲背景色值來解決這個問題。api

爲此，咱們須要建立一個後臺腳本並將其添加到擴展的 manifest 中。首先在擴展的目錄中建立一個名爲 background.js 的文件。架構

{
  "name": "Getting Started Example",
  "description": "Build an Extension!",
  "version": "1.0",
  "manifest_version": 3,
+ "background": {
+   "service_worker": "background.js"
+ }
}

與許多其它重要組件同樣，後臺腳本必須在 manifest 中註冊。在 manifest 中註冊一個後臺腳本會告訴擴展要引用哪一個文件，以及該文件的行爲。

Chrome 如今意識到擴展包含一個服務。當你從新加載擴展時，Chrome 將掃描指定的文件以獲取附加指令，例如須要偵聽的重要事件。

這個擴展一旦安裝，就須要來自持久變量的信息。首先在後臺腳本中包含一個對 runtime.onInstalled 的監聽。在 onInstalled 偵聽器中，擴展將使用 storage API 設置一個值。這將容許多個擴展組件訪問該值並更新它。

let color = '#3aa757';

chrome.runtime.onInstalled.addListener(() => {
  chrome.storage.sync.set({ color });
  console.log('Default background color set to %cgreen', `color: ${color}`);
});

大多數的 API ，包括 storage API ，必須在 manifest 中的 permissions 字段下注冊，擴展才能使用它們。

{
  "name": "Getting Started Example",
  "description": "Build an Extension!",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  },
+ "permissions": ["storage"]
}

返回到擴展管理頁面，點擊 Reload 連接。一個新的字段 Inspect views 可用，它有一個藍色的連接：background page 。

點擊連接查看後臺腳本輸出的日誌："Default background color set to green"

譯者備註

在 Chrome 版本 90.0.4430.85（正式版本） (x86_64) 中試了一下，發現有些出入的地方：

可點擊的連接是 Service Worker ，並且在必定的時間後會變成無效，因此須要點擊 Reload 連接。

引入用戶界面

擴展能夠有多種形式的用戶界面；這一種將使用 popup 。建立並添加名爲 popup.html 的文件到擴展的目錄。此擴展使用按鈕更改背景色。

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="button.css">
  </head>
  <body>
    <button id="changeColor"></button>
  </body>
</html>

與後臺腳本同樣，這個文件必須在 manifest 中聲明，以便 Chrome 在擴展彈出窗口中顯示它。爲此，向 manifest 添加一個 action 對象並設置 popup.html 做爲 action 的 default_popup 屬性值。

{
  "name": "Getting Started Example",
  "description": "Build an Extension!",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["storage"],
+ "action": {
+   "default_popup": "popup.html"
+ }
}

這個彈出窗口的 HTML 引用了一個名爲 button.css 的 CSS 文件。將另外一個文件添加到擴展的目錄中，適當地命名它，並添加如下代碼。

button {
  height: 30px;
  width: 30px;
  outline: none;
  margin: 10px;
  border: none;
  border-radius: 2px;
}

button.current {
  box-shadow: 0 0 0 2px white,
              0 0 0 4px black;
}

工具欄圖標的指定也包含在 action 的 default_icons 字段下。在這裏下載圖片文件，解壓它，並將它放在擴展的目錄中。更新 manifest ，使擴展知道如何使用圖片。

{
  "name": "Getting Started Example",
  "description": "Build an Extension!",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["storage"],
  "action": {
    "default_popup": "popup.html",
+   "default_icon": {
+     "16": "/images/get_started16.png",
+     "32": "/images/get_started32.png",
+     "48": "/images/get_started48.png",
+     "128": "/images/get_started128.png"
+   }
  }
}

擴展還能夠在擴展管理頁、權限警告和 favicon 上顯示圖像。這些圖像在 manifest 的 icons 字段下指定。

{
  "name": "Getting Started Example",
  "description": "Build an Extension!",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["storage"],
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "/images/get_started16.png",
      "32": "/images/get_started32.png",
      "48": "/images/get_started48.png",
      "128": "/images/get_started128.png"
    }
  },
+ "icons": {
+   "16": "/images/get_started16.png",
+   "32": "/images/get_started32.png",
+   "48": "/images/get_started48.png",
+   "128": "/images/get_started128.png"
+ }
}

若是在此階段從新加載擴展，它將包含提供的圖標而不是默認佔位符，單擊該操做將打開一個帶有默認顏色按鈕的彈出窗口。

彈出 UI 的最後一步是向按鈕添加顏色。在擴展目錄中建立名 popup.js 的文件，並添加如下代碼。

// Initialize button with user's preferred color
let changeColor = document.getElementById("changeColor");

chrome.storage.sync.get("color", ({ color }) => {
  changeColor.style.backgroundColor = color;
});

這個代碼從 popup.html 中抓取按鈕，並從存儲中請求顏色值。而後將顏色做爲按鈕的背景。在 popup.html 中添加一個指向 popup.js 腳本標籤。

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="button.css">
  </head>
  <body>
    <button id="changeColor"></button>
+   <script src="popup.js"></script>
  </body>
</html>

從新加載擴展查看綠色按鈕。

邏輯層

擴展示在有一個自定義圖標和一個彈出窗口，它根據保存到擴展存儲中的值爲彈出窗口按鈕着色。接下來，它須要進一步的用戶交互邏輯。在 popup.js 文件末尾添加如下內容。

// When the button is clicked, inject setPageBackgroundColor into current page
changeColor.addEventListener("click", async () => {
  let [tab] = await chrome.tabs.query({ active: true, currentWindow: true });

  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    function: setPageBackgroundColor,
  });
});

// The body of this function will be executed as a content script inside the
// current page
function setPageBackgroundColor() {
  chrome.storage.sync.get("color", ({ color }) => {
    document.body.style.backgroundColor = color;
  });
}

更新後的代碼向按鈕添加了一個 click 事件監聽器，該監聽器觸發一個以編程方式注入的內容腳本。這將使頁面的背景色與按鈕的顏色相同。使用編程注入容許用戶調用內容腳本，而不是將不須要的代碼自動插入網頁。

manifest 將須要 activeTab 權限來容許擴展臨時訪問當前頁，而且須要 scripting 權限來使用腳本 API 的 executeScript 方法。

{
  "name": "Getting Started Example",
  ...
+ "permissions": ["storage", "activeTab", "scripting"],
  ...
}

擴展示在功能完成了！從新加載擴展，刷新此頁面，打開彈出窗口並單擊按鈕將其變爲綠色！可是，有些用戶可能但願將背景更改成不一樣的顏色。

爲用戶提供選項

該擴展目前只容許用戶將背景更改成綠色。包含一個選項頁面可讓用戶更好地控制擴展的功能，進一步定製他們的瀏覽體驗。

首先在目錄建立一個名 options.html 的文件幷包含如下代碼。

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="button.css">
  </head>
  <body>
    <div id="buttonDiv">
    </div>
    <div>
      <p>Choose a different background color!</p>
    </div>
  </body>
  <script src="options.js"></script>
</html>

在 manifest 中登記選項頁面。

{
  "name": "Getting Started Example",
  ...
+ "options_page": "options.html"
}

從新加載並點擊 DETAILS 。

向下滾動詳情頁面並選擇 Extension options 以查看選項頁面。

最後一步是添加選項邏輯。在擴展的目錄中建立一個名爲 options.js 的文件並添加如下代碼。

let page = document.getElementById("buttonDiv");
let selectedClassName = "current";
const presetButtonColors = ["#3aa757", "#e8453c", "#f9bb2d", "#4688f1"];

// Reacts to a button click by marking the selected button and saving
// the selection
function handleButtonClick(event) {
  // Remove styling from the previously selected color
  let current = event.target.parentElement.querySelector(
    `.${selectedClassName}`
  );
  if (current && current !== event.target) {
    current.classList.remove(selectedClassName);
  }

  // Mark the button as selected
  let color = event.target.dataset.color;
  event.target.classList.add(selectedClassName);
  chrome.storage.sync.set({ color });
}

// Add a button to the page for each supplied color
function constructOptions(buttonColors) {
  chrome.storage.sync.get("color", (data) => {
    let currentColor = data.color;
    // For each color we were provided…
    for (let buttonColor of buttonColors) {
      // …create a button with that color…
      let button = document.createElement("button");
      button.dataset.color = buttonColor;
      button.style.backgroundColor = buttonColor;

      // …mark the currently selected color…
      if (buttonColor === currentColor) {
        button.classList.add(selectedClassName);
      }

      // …and register a listener for when that button is clicked
      button.addEventListener("click", handleButtonClick);
      page.appendChild(button);
    }
  });
}

// Initialize the page by constructing the color options
constructOptions(presetButtonColors);

提供四種顏色選項，而後在選項頁上生成帶有 onclick 事件偵聽器的按鈕。當用戶單擊按鈕時，它會更新擴展存儲中的顏色值。因爲擴展的全部文件都從該存儲中提取顏色信息，所以不須要更新其它值。