chrome.action

說明

使用 chrome.action API 控制 Google Chrome 工具列中的擴充功能圖示。

動作圖示會顯示在瀏覽器工具列的 萬用搜尋方塊旁邊。安裝完成後，這些擴充功能就會顯示在擴充功能選單 (拼圖圖示) 中。使用者可以將擴充功能圖示固定在工具列上。

可用性

Chrome 88 以上版本 MV3 以上版本

資訊清單

如要使用這個 API，您必須在資訊清單中宣告下列鍵。

"action"

如要使用 chrome.action API，請指定 "manifest_version" 為 3，並在資訊清單檔案中加入 "action" 鍵。

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

"action" 鍵 (以及子鍵) 為選用項目。如果未納入，工具列仍會顯示擴充功能，以便使用者存取擴充功能的選單。因此，建議您一律納入至少 "action" 和 "default_icon" 鍵。

概念和用法

UI 的部分

圖示

這個圖示是擴充功能工具列的主要圖片，由資訊清單的 "action" 鍵中的 "default_icon" 鍵設定。圖示的寬度和高度必須為 16 個裝置無關像素 (DIP)。

"default_icon" 鍵是大小與圖片路徑的字典。Chrome 會使用這些圖示選擇要使用的圖片縮放比例。如果找不到完全相符的結果，Chrome 會選取最接近的結果，並將其縮放至適合圖片的大小，這可能會影響圖片品質。

由於使用較不常見的縮放比例 (例如 1.5x 或 1.2x) 的裝置越來越多，建議您為圖示提供多種尺寸。這也能讓你的擴充功能在未來因應圖示顯示大小的變更。不過，如果只提供單一大小，"default_icon" 鍵也可以設為字串，其中包含單一圖示的路徑，而非字典。

您也可以呼叫 action.setIcon()，透過程式設計方式設定擴充功能圖示，方法是指定不同的圖片路徑，或是使用 HTML 畫布元素提供動態產生的圖示，如果是從擴充功能服務工作站設定，則可以使用 離螢幕畫布 API。

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

對於已封裝的擴充功能 (從 .crx 檔案安裝)，圖片可以採用 Blink 算繪引擎可顯示的大部分格式，包括 PNG、JPEG、BMP、ICO 和其他格式。不支援 SVG。未封裝的擴充功能必須使用 PNG 圖片。

工具提示 (標題)

當使用者將滑鼠游標懸停在工具列中擴充功能的圖示上時，系統就會顯示工具提示或標題。當按鈕獲得焦點時，螢幕閱讀器也會朗讀這段文字。

預設工具提示會使用 manifest.json 中 "action" 鍵的 "default_title" 欄位設定。您也可以呼叫 action.setTitle() 以程式輔助方式設定。

徽章

動作可選擇顯示「徽章」(圖示上方會顯示一小段文字)。這樣一來，您就能更新動作，顯示擴充功能狀態的少量資訊，例如計數器。徽章包含文字元件和背景顏色。由於空間有限，建議徽章文字使用四個半形字元或更少。

如要建立徽章，請呼叫 action.setBadgeBackgroundColor() 和 action.setBadgeText()，以程式輔助方式設定徽章。資訊清單中沒有預設徽章設定。徽章顏色值可以是 0 到 255 之間四個整數的陣列，用於組成徽章的 RGBA 顏色，也可以是包含 CSS 顏色值的字串。

chrome.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

當使用者在工具列中按一下擴充功能的動作按鈕時，系統就會顯示動作的彈出式視窗。彈出式視窗可包含任何 HTML 內容，且會自動調整大小以配合內容。彈出式視窗的大小必須介於 25x25 和 800x600 像素之間。

彈出式視窗最初是由 manifest.json 檔案中 "action" 鍵的 "default_popup" 屬性設定。如果有此屬性，則應指向擴充功能目錄中的相對路徑。您也可以使用 action.setPopup() 方法，動態更新路徑，讓路徑指向其他相對路徑。

用途

每個分頁狀態

擴充功能動作可為每個分頁設定不同的狀態。如要為個別分頁設定值，請在 action API 的設定方法中使用 tabId 屬性。舉例來說，如要設定特定分頁的徽章文字，請執行以下操作：

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

如果省略 tabId 屬性，系統會將設定視為全域設定。分頁專屬設定優先於全域設定。

已啟用狀態

根據預設，每個分頁都會啟用 (可點選) 工具列動作。您可以變更這個預設值，方法是在資訊清單的 action 鍵中設定 default_state 屬性。如果 default_state 設為 "disabled"，則該動作預設為停用，必須透過程式設計啟用才能點選。如果 default_state 設為 "enabled" (預設值)，系統會啟用該動作，並預設為可點選。

您可以使用 action.enable() 和 action.disable() 方法，透過程式輔助方式控制狀態。這只會影響是否將彈出式視窗 (如有) 或 action.onClicked 事件傳送至擴充功能；不會影響動作在工具列中的顯示情形。

範例

以下範例說明在擴充功能中使用動作的常見方式。如要試用這個 API，請從 chrome-extension-samples 存放區安裝 Action API 範例。

顯示彈出式視窗

當使用者點選擴充功能的動作時，擴充功能通常會顯示彈出式視窗。如要在自己的擴充功能中實作這項功能，請在 manifest.json 中宣告彈出式視窗，並指定 Chrome 應在彈出式視窗中顯示的內容。

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

在點擊時插入內容指令碼

擴充功能的常見模式是使用擴充功能的動作公開主要功能。以下範例說明此模式。使用者點選動作時，擴充功能會將內容指令碼插入目前的網頁。接著，內容指令碼會顯示快訊，確認所有內容都運作正常。

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

使用 declarativeContent 模擬動作

本例說明擴充功能的背景邏輯如何 (a) 預設停用動作，以及 (b) 使用 declarativeContent 在特定網站上啟用動作。

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

  // Clear all rules to ensure only our expected rules are set
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});

類型

OpenPopupOptions

Chrome 99 以上版本

屬性

  • windowId

    號碼 選填

    要開啟動作彈出式視窗的視窗 ID。如未指定，預設為目前的活動視窗。

TabDetails

屬性

  • tabId

    號碼 選填

    要查詢狀態的分頁 ID。如果未指定分頁，系統會傳回非分頁專屬的狀態。

UserSettings

Chrome 91 以上版本

使用者指定的擴充功能動作相關設定集合。

屬性

  • isOnToolbar

    布林值

    擴充功能的動作圖示是否顯示在瀏覽器視窗的頂層工具列上 (也就是使用者是否已「固定」擴充功能)。

UserSettingsChange

Chrome 130 以上版本

屬性

  • isOnToolbar

    boolean 選填

    擴充功能的動作圖示是否顯示在瀏覽器視窗的頂層工具列上 (也就是使用者是否已「固定」擴充功能)。

方法

disable()

Promise 
chrome.action.disable(
  tabId?: number,
  callback?: function,
)

停用分頁的動作。

參數

  • tabId

    號碼 選填

    您要修改動作的分頁 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

enable()

Promise 
chrome.action.enable(
  tabId?: number,
  callback?: function,
)

啟用分頁的動作。根據預設，系統會啟用動作。

參數

  • tabId

    號碼 選填

    您要修改動作的分頁 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getBadgeBackgroundColor()

Promise 
chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

取得動作的背景顏色。

參數

傳回

  • 承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getBadgeText()

Promise 
chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

取得動作的徽章文字。如果未指定分頁，系統會傳回非分頁專屬的徽章文字。如果啟用 displayActionCountAsBadgeText，系統會傳回預留位置文字，除非有 declarativeNetRequestFeedback 權限或提供分頁專屬徽章文字。

參數

  • 詳細資料

    TabDetails

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getBadgeTextColor()

Promise Chrome 110 以上版本 
chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

取得動作的文字顏色。

參數

傳回

  • 承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getPopup()

Promise 
chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

取得設為此動作的彈出式視窗的 HTML 文件。

參數

  • 詳細資料

    TabDetails

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getTitle()

Promise 
chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

取得動作的標題。

參數

  • 詳細資料

    TabDetails

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getUserSettings()

Promise Chrome 91 以上版本 
chrome.action.getUserSettings(
  callback?: function,
)

傳回使用者指定的擴充功能動作相關設定。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (userSettings: UserSettings) => void

傳回

  • Promise<UserSettings>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

isEnabled()

Promise Chrome 110 以上版本 
chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

指出是否已為分頁啟用擴充功能動作 (如果未提供 tabId，則為全域啟用)。僅使用 declarativeContent 啟用的動作一律會傳回 false。

參數

  • tabId

    號碼 選填

    要查看啟用狀態的分頁 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (isEnabled: boolean) => void

    • isEnabled

      布林值

      如果已啟用擴充功能動作，則傳回 true。

傳回

  • Promise<布林值>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

openPopup()

Promise Chrome 127 以上版本 
chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

開啟擴充功能的彈出式視窗。在 Chrome 118 和 Chrome 126 之間，這項功能僅適用於政策安裝的擴充功能。

參數

  • 選項

    OpenPopupOptions 選填

    指定開啟彈出式視窗的選項。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setBadgeBackgroundColor()

Promise 
chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

設定徽章的背景顏色。

參數

  • 詳細資料

    物件

    • 顏色

      string | ColorArray

      陣列包含四個介於 [0,255] 範圍內的整數，用於組成徽章的 RGBA 顏色。例如不透明紅色是 [255, 0, 0, 255]。也可以是含有 CSS 值的字串，不透明的紅色為 #FF0000 或 #F00。

    • tabId

      號碼 選填

      限制變更時機，僅在選取特定分頁時才會變更。關閉分頁時會自動重設。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setBadgeText()

Promise 
chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

設定動作的徽章文字。徽章會顯示在圖示上方。

參數

  • 詳細資料

    物件

    • tabId

      號碼 選填

      限制變更時機，僅在選取特定分頁時才會變更。關閉分頁時會自動重設。

    • 文字

      string 選填

      您可以傳遞任意數量的字元，但空間只能容納約四個字元。如果傳遞空白字串 ('')，系統會清除徽章文字。如果指定 tabId 且 text 為空值，系統會清除指定分頁的文字，並預設為全域徽章文字。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setBadgeTextColor()

Promise Chrome 110 以上版本 
chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

設定徽章的文字顏色。

參數

  • 詳細資料

    物件

    • 顏色

      string | ColorArray

      陣列包含四個介於 [0,255] 範圍內的整數，用於組成徽章的 RGBA 顏色。例如不透明紅色是 [255, 0, 0, 255]。也可以是含有 CSS 值的字串，其中不透明的紅色為 #FF0000 或 #F00。如果未設定這個值，系統會自動選擇與徽章背景顏色形成對比的顏色，讓文字清楚顯示。系統不會設定 Alpha 值等於 0 的顏色，並會傳回錯誤。

    • tabId

      號碼 選填

      限制變更時機，僅在選取特定分頁時才會變更。關閉分頁時會自動重設。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setIcon()

Promise 
chrome.action.setIcon(
  details: object,
  callback?: function,
)

設定動作的圖示。您可以指定圖示的圖片檔案路徑、畫布元素的像素資料，或上述任一項目的字典。必須指定 path 或 imageData 屬性。

參數

  • 詳細資料

    物件

    • imageData

      ImageData | 物件 選用

      ImageData 物件或字典 {size -> ImageData}，代表要設定的圖示。如果圖示是使用字典指定，系統會根據螢幕的像素密度選擇要使用的實際圖片。如果圖片像素數量可容納在一個螢幕空間單位中，且等於 scale，系統就會選取大小為 scale * n 的圖片，其中 n 是 UI 中圖示的大小。至少須指定一張圖片。請注意，'details.imageData = foo' 等同於 'details.imageData = {'16': foo}'

    • 路徑

      字串 | 物件 選填

      相對圖片路徑或字典 {size -> relative image path}，指向要設定的圖示。如果圖示是使用字典指定，系統會根據螢幕的像素密度選擇要使用的實際圖片。如果圖片像素數量可容納在一個螢幕空間單位中，且等於 scale，系統就會選取大小為 scale * n 的圖片，其中 n 是 UI 中圖示的大小。至少須指定一張圖片。請注意，'details.path = foo' 等同於 'details.path = {'16': foo}'

    • tabId

      號碼 選填

      限制變更時機，僅在選取特定分頁時才會變更。關閉分頁時會自動重設。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setPopup()

Promise 
chrome.action.setPopup(
  details: object,
  callback?: function,
)

設定使用者按一下動作圖示時，要以彈出式開啟的 HTML 文件。

參數

  • 詳細資料

    物件

    • 彈出式訊息

      字串

      要顯示在彈出式視窗中的 HTML 檔案相對路徑。如果設為空字串 ('')，系統就不會顯示彈出式視窗。

    • tabId

      號碼 選填

      限制變更時機，僅在選取特定分頁時才會變更。關閉分頁時會自動重設。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setTitle()

Promise 
chrome.action.setTitle(
  details: object,
  callback?: function,
)

設定動作的標題。這會顯示在工具提示中。

參數

  • 詳細資料

    物件

    • tabId

      號碼 選填

      限制變更時機，僅在選取特定分頁時才會變更。關閉分頁時會自動重設。

    • title

      字串

      滑鼠游標經過時，動作應顯示的字串。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onClicked

chrome.action.onClicked.addListener(
  callback: function,
)

在點選動作圖示時觸發。如果動作含有彈出式視窗，系統就不會觸發這個事件。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (tab: tabs.Tab) => void

onUserSettingsChanged

Chrome 130 以上版本 
chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

當使用者指定的擴充功能動作相關設定變更時觸發。

參數