在每個網頁上執行指令碼

建立第一個能在網頁上插入新元素的擴充功能。

總覽

本教學課程會建構一個擴充功能，可將預期的閱讀時間新增至任何 Chrome 擴充功能， Chrome 線上應用程式商店說明文件頁面。

在擴充功能的歡迎頁面上閱讀延期時間。

本指南將說明下列概念：

• 擴充功能資訊清單。
• 擴充功能使用的圖示大小。
• 如何使用內容指令碼將程式碼插入網頁。
• 如何使用比對模式。
• 擴充功能權限。

事前準備

本指南假設您具備基本的網站開發經驗。建議您參閱 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：提供圖示

那麼，為什麼需要圖示？雖然圖示在開發期間是選用項目，但 。也會顯示在其他 例如「擴充功能管理」頁面

建立 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：宣告內容指令碼

擴充功能可以執行指令碼，以便讀取及修改網頁內容。這些都稱為內容 指令碼這些 Cookie 生活在獨立的世界，因此能夠變更自己的 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>。可以包含「*」字元。

💡? 這項擴充功能會顯示權限警告嗎？

當使用者安裝擴充功能時，瀏覽器會通知使用者這項擴充功能可執行的操作。內容指令碼會要求在符合比對模式條件的網站上執行。

在此範例中，使用者會看到下列權限警告：

讀取時間權限警告。

如要進一步瞭解擴充功能權限，請參閱「宣告權限及警告使用者」。

步驟 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()，用來在元素後方插入朗讀時間節點。
• classList 屬性可用於將 CSS 類別名稱新增至元素類別屬性。
• 選用的鏈結，用來存取可能未定義或空值的物件屬性。
• 如果 <date> 為空值或未定義，Nullish Coalescing 會傳回 <heading>。

測試是否能正常運作

確認專案的檔案結構如下所示：

在本機載入擴充功能

如要在開發人員模式下載入未封裝的擴充功能，請按照「開發 基本概念。

開啟擴充功能或 Chrome 線上應用程式商店說明文件

您可以開啟下列幾頁，查看每篇文章需要多少時間。

• 在 Chrome 線上應用程式商店中發布
• 瞭解內容指令碼

看起來應該像這樣：

擴充功能歡迎頁面，搭配 Reading Time 擴充功能

🎯? 改進空間

請根據您目前學到的內容，嘗試以下列任何一種方式實作：

• 在 manifest.json 中加入另一個比對模式，以支援其他 Chrome 開發人員 頁面，例如 Chrome 開發人員工具或 Workbox。
• 新增內容指令碼，可計算閱讀時間至任何喜愛網誌，或是 說明文件網站。

，瞭解如何調查及移除這項存取權。

提示：您可以使用開發人員工具檢查 DOM 元素。

繼續建構

恭喜您完成本教學課程 🎉?。完成其他 本系列的教學課程：

擴充功能	學習目標
專注模式	點選擴充功能動作後，在目前頁面執行程式碼。
分頁管理工具	建立用於管理瀏覽器分頁的彈出式視窗。

繼續探索

希望您會喜歡建構這個 Chrome 擴充功能，也非常期待能繼續使用您的 Chrome 開發學習旅程建議您按照下列學習路徑操作：

• 開發人員指南提供了數十種說明文件的連結 與進階額外資訊建立流程相關
• 除了開放網路可用的擴充功能，擴充功能也能存取各種強大的 API。 Chrome API 說明文件會逐一介紹各個 API。