chrome.pageAction

refresh date: 2026-09-25 robots: noindex

說明

使用 chrome.pageAction API，在 Google Chrome 主工具列 (網址列右側) 放置圖示。頁面動作代表可在目前頁面執行的動作，但不適用於所有頁面。網頁動作在停用時會顯示為灰色。

可用性

≤ MV2

以下提供一些例子：

  • 訂閱這個頁面的 RSS 動態消息
  • 使用這個頁面的相片製作投影片

下圖中的 RSS 圖示代表網頁動作，可讓您訂閱目前網頁的 RSS 動態消息。

隱藏的頁面動作會顯示為灰色。舉例來說，下方的 RSS 動態消息呈現灰色，因為您無法訂閱目前網頁的動態消息：

建議改用瀏覽器動作，讓使用者隨時都能與擴充功能互動。

資訊清單

在擴充功能資訊清單中註冊頁面動作，如下所示：

{
  "name": "My extension",
  ...
  "page_action": {
    "default_icon": {                    // optional
      "16": "images/icon16.png",           // optional
      "24": "images/icon24.png",           // optional
      "32": "images/icon32.png"            // optional
    },
    "default_title": "Google Mail",      // optional; shown in tooltip
    "default_popup": "popup.html"        // optional
  },
  ...
}

由於縮放比例係數較不常見 (例如 1.5 倍或 1.2 倍) 的裝置越來越普遍，建議您為圖示提供多種大小。Chrome 會選取最接近的大小，並縮放至填滿 16 dip 的空間。這樣一來，即使圖示顯示大小有所變更，您也不必再提供其他圖示！不過，如果大小差異過大，這種縮放可能會導致圖示失去細節或模糊不清。

系統仍支援註冊預設圖示的舊語法：

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

UI 的各個部分

與瀏覽器動作一樣，網頁動作可以有圖示、工具提示和彈出式視窗，但不能有徽章。此外，網頁動作可能會顯示為灰色。如要瞭解圖示、工具提示和彈出式視窗，請參閱瀏覽器動作 UI。

您可以使用 pageAction.show 和 pageAction.hide 方法，分別顯示及停用頁面動作。根據預設，頁面動作會顯示為灰色。顯示時，您需要指定圖示應顯示的分頁。圖示會持續顯示，直到分頁關閉或開始顯示其他網址 (例如使用者點選連結)。

提示

為達到最佳視覺效果，請遵循下列規範：

  • 建議：針對僅適用於少數網頁的功能，使用網頁動作。
  • 請勿將網頁動作套用至適用於大多數網頁的功能。請改用瀏覽器動作。
  • 請勿持續為圖示加上動畫效果。真煩人。

類型

ImageDataType

圖片的像素資料。必須是 ImageData 物件 (例如來自 canvas 元素)。

類型

ImageData

TabDetails

Chrome 88 以上版本

屬性

  • tabId

    數字 選填

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

方法

getPopup()

Promise 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

取得設為這個頁面動作彈出式視窗的 HTML 文件。

參數

  • 詳細資料

    TabDetails

  • callback

    函式 選填

    callback 參數如下： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    Chrome 101 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getTitle()

Promise 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

取得頁面動作的標題。

參數

  • 詳細資料

    TabDetails

  • callback

    函式 選填

    callback 參數如下： 

    (result: string) => void

    • 結果

      字串

傳回

  • Promise<string>

    Chrome 101 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

hide()

Promise 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

隱藏頁面動作。隱藏的網頁動作仍會顯示在 Chrome 工具列中，但會變成灰色。

參數

  • tabId

    數字

    要修改網頁動作的分頁 ID。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 101 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setIcon()

Promise 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

設定網頁動作的圖示。圖示可以指定為圖片檔的路徑、畫布元素的像素資料，或其中一項的字典。必須指定 path 或 imageData 屬性。

參數

  • 詳細資料

    物件

    • iconIndex

      數字 選填

      已淘汰。系統會忽略這個引數。

    • 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

      數字

      要修改網頁動作的分頁 ID。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 101 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setPopup()

Promise 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

設定使用者點選網頁動作圖示時，要以彈出式視窗開啟的 HTML 文件。

參數

  • 詳細資料

    物件

    • 彈出式訊息

      字串

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

    • tabId

      數字

      要修改網頁動作的分頁 ID。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 101 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setTitle()

Promise 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

設定網頁動作的標題。這項資訊會顯示在頁面動作的工具提示中。

參數

  • 詳細資料

    物件

    • tabId

      數字

      要修改網頁動作的分頁 ID。

    • title

      字串

      工具提示字串。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 101 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

show()

Promise 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

顯示頁面動作。只要選取分頁，就會顯示網頁動作。

參數

  • tabId

    數字

    要修改網頁動作的分頁 ID。

  • callback

    函式 選填

    Chrome 67 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 101 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

事件

onClicked

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

在使用者點選網頁動作圖示時觸發。如果網頁動作有彈出式視窗，就不會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    (tab: tabs.Tab) => void