在使用中分頁中插入指令碼

按一下擴充功能工具列圖示,即可簡化目前頁面的樣式。

總覽

本教學課程會建構一個擴充功能,簡化 Chrome 擴充功能的樣式及 Chrome 線上應用程式商店說明文件頁面,使內容更容易閱讀。

在本指南中,我們會說明如何完成以下作業:

  • 使用擴充功能 Service Worker 做為事件協調者。
  • 透過 "activeTab" 權限保護使用者隱私。
  • 在使用者點選擴充功能工具列圖示時執行程式碼。
  • 使用「Scripting」API 插入及移除樣式表。
  • 使用鍵盤快速鍵執行程式碼。

事前準備

本指南假設您具備基本的網站開發經驗。建議你前往 Hello World:擴充功能開發工作流程簡介。

建立擴充功能

首先,請建立名為 focus-mode 的新目錄,用來存放擴充功能的檔案。如果發生以下情況: 如有需要,您可以前往 GitHub 下載完整的原始碼。

步驟 1:加入擴充功能資料和圖示

建立名為 manifest.json 的檔案,並加入下列程式碼。

{
  "manifest_version": 3,
  "name": "Focus Mode",
  "description": "Enable focus mode on Chrome's official Extensions and Chrome Web Store documentation.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

如要進一步瞭解這些資訊清單鍵,請參閱「在每個分頁中執行指令碼」教學課程,詳細介紹擴充功能的中繼資料圖示

建立 images 資料夾,然後將圖示下載至該資料夾。

步驟 2:初始化擴充功能

擴充功能可以使用擴充功能的服務,在背景監控瀏覽器事件 工作站。Service Worker 是處理程式碼的特殊 JavaScript 環境 並在不需要時終止

首先,請在 manifest.json 檔案中註冊 Service Worker:

{
  ...
  "background": {
    "service_worker": "background.js"
  },
  ...
}

建立名為 background.js 的檔案,並加入下列程式碼:

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setBadgeText({
    text: "OFF",
  });
});

我們的服務工作人員會監聽的第一個事件是 runtime.onInstalled()。這個方法可讓擴充功能設定 或完成安裝時的工作。擴充功能可以使用 Storage API IndexedDB 儲存應用程式狀態。不過在本例中,由於我們只處理兩個狀態,因此會使用動作徽章文字本身追蹤擴充功能是否「開啟」或「關閉」。

步驟 3:啟用擴充功能動作

擴充功能動作可控制擴充功能的工具列圖示。每當使用者按下 擴充功能圖示,可以執行部分程式碼 (如本例) 或顯示彈出式視窗。將 以下程式碼,在 manifest.json 檔案中宣告擴充功能動作:

{
  ...
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  ...
}

使用有效分頁權限保護使用者隱私

activeTab 權限會授予擴充功能「暫時」執行程式碼的能力 。此外,您也可以透過這個 API 存取以下項目的機密屬性: 目前的分頁

這項權限會在使用者叫用擴充功能時啟用。在此情況下,使用者會叫用 方法是按一下擴充功能動作

💡? 哪些使用者互動會在我的擴充功能中啟用有效分頁權限?

  • 按下鍵盤快速鍵組合。
  • 選取內容選單項目。
  • 接受網址列的建議。
  • 正在開啟擴充功能彈出式視窗。

"activeTab" 權限可讓使用者「刻意」選擇在 焦點分頁;確保使用者隱私這麼做的另一個優點是 觸發權限警告

如要使用 "activeTab" 權限,請將權限加入資訊清單的權限陣列:

{
  ...
  "permissions": ["activeTab"],
  ...
}

步驟 4:追蹤目前分頁的狀態

使用者點選擴充功能動作後,擴充功能會檢查網址是否符合 說明文件頁面。接著,它會檢查目前分頁的狀態,並設定下一個狀態。將 將下列程式碼新增至 background.js

const extensions = 'https://developer.chrome.com/docs/extensions';
const webstore = 'https://developer.chrome.com/docs/webstore';

chrome.action.onClicked.addListener(async (tab) => {
  if (tab.url.startsWith(extensions) || tab.url.startsWith(webstore)) {
    // Retrieve the action badge to check if the extension is 'ON' or 'OFF'
    const prevState = await chrome.action.getBadgeText({ tabId: tab.id });
    // Next state will always be the opposite
    const nextState = prevState === 'ON' ? 'OFF' : 'ON';

    // Set the action badge to the next state
    await chrome.action.setBadgeText({
      tabId: tab.id,
      text: nextState,
    });
  }
});

步驟 5:新增或移除樣式表

接下來要變更網頁的版面配置。建立名為 focus-mode.css 的檔案,並加入 下列程式碼:

* {
  display: none !important;
}

html,
body,
*:has(article),
article,
article * {
  display: revert !important;
}

[role='navigation'] {
  display: none !important;
}

article {
  margin: auto;
  max-width: 700px;
}

使用 Scripting API 插入或移除樣式表。開始日期 在資訊清單中宣告 "scripting" 權限:

{
  ...
  "permissions": ["activeTab", "scripting"],
  ...
}
敬上

最後,在 background.js 中加入下列程式碼,變更頁面的版面配置:

  ...
    if (nextState === "ON") {
      // Insert the CSS file when the user turns the extension on
      await chrome.scripting.insertCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    } else if (nextState === "OFF") {
      // Remove the CSS file when the user turns the extension off
      await chrome.scripting.removeCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    }
  }
});

💡? 我可以使用 Scripting API 插入程式碼,而不使用樣式表嗎?

可以。您可以使用 scripting.executeScript() 插入 JavaScript。

選用:指定鍵盤快速鍵

只要新增捷徑,就能輕鬆啟用或停用專注模式。將 "commands" 鍵。

{
  ...
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  }
}

"_execute_action" 鍵會執行與 action.onClicked() 事件相同的程式碼,因此沒有其他 。

測試是否能正常運作

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

焦點模式資料夾的內容:Manifest.json、background.js、focus-mode.css 和 images 資料夾內容。

在本機載入擴充功能

如要在開發人員模式中載入未封裝的擴充功能,請按照 Hello World 的步驟操作。

在說明文件頁面中測試擴充功能

首先,請開啟下列任一頁面:

然後按一下擴充功能動作。如果你已設定鍵盤快速鍵,即可按下 Ctrl + B 鍵或 Cmd + B 鍵進行測試。

其原理如下:

已關閉專注模式擴充功能
已關閉專注模式擴充功能

變更為:

已開啟專注模式擴充功能
已開啟專注模式擴充功能

🎯? 改進空間

請根據您目前學到的內容,嘗試完成下列操作:

  • 改善 CSS 樣式表。
  • 指定其他鍵盤快速鍵。
  • 變更您最愛的網誌或文件網站的版面配置。

繼續建構。

恭喜您完成本教學課程 🎉?。完成其他步驟,繼續提陞技能 本系列的教學課程:

擴充功能 學習目標
閱讀時間 如要在一組特定網頁中自動插入元素,
分頁管理工具 建立用於管理瀏覽器分頁的彈出式視窗。

繼續探索

希望您會喜歡建構這個 Chrome 擴充功能,也期待能夠繼續為您提供擴充功能 開發學習旅程建議您採取下列學習路徑:

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