chrome.pageAction

說明

使用 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 像素的空間這也可確保如果圖示顯示大小曾經變更，您無須再進行其他操作來提供不同的圖示！但是，如果大小差異太過極端，這種縮放方式可能會導致圖示喪失細節，或看起來模糊不清。

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

{
  "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,
)

取得 HTML 文件集，做為這個網頁動作的彈出式視窗。

參數

  • 詳細資料

    TabDetails

  • 回呼

    函式選用

    callback 參數如下所示： 

    (result: string)=>void

    • 結果

      字串

傳回

  • Promise<string>

    Chrome 101 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getTitle()

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

取得網頁動作的標題。

參數

  • 詳細資料

    TabDetails

  • 回呼

    函式選用

    callback 參數如下所示： 

    (result: string)=>void

    • 結果

      字串

傳回

  • Promise<string>

    Chrome 101 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

hide()

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

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

參數

  • tabId

    號碼

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

  • 回呼

    函式選用

    Chrome 67 以上版本

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 101 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

setIcon()

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

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

參數

  • 詳細資料

    物件

    • iconIndex

      數字 選填

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

    • imageData

      ImageData|object 選用

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

    • path

      string|object 選用

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

    • tabId

      號碼

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 101 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

setPopup()

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

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

參數

  • 詳細資料

    物件

    • 彈出式視窗

      字串

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

    • tabId

      號碼

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

  • 回呼

    函式選用

    Chrome 67 以上版本

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 101 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

setTitle()

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

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

參數

  • 詳細資料

    物件

    • tabId

      號碼

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

    • title

      字串

      工具提示字串。

  • 回呼

    函式選用

    Chrome 67 以上版本

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 101 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

show()

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

顯示網頁動作。每次選取分頁時，畫面上會顯示頁面動作。

參數

  • tabId

    號碼

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

  • 回呼

    函式選用

    Chrome 67 以上版本

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 101 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

活動

onClicked

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

在點選網頁動作圖示時觸發。如果網頁動作會顯示彈出式視窗，則不會觸發這個事件。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tab: tabs.Tab)=>void