chrome.tabs

說明

使用 chrome.tabs API 與瀏覽器的分頁系統互動。您可以使用這個 API 在瀏覽器中建立、修改及重新排列分頁。

Tabs API 不僅提供操控及管理分頁的功能，也可以偵測分頁的語言、擷取螢幕截圖，以及利用分頁的內容指令碼通訊。

權限

大部分的功能不需具備任何權限即可使用。例如：建立新分頁、重新載入分頁、前往其他網址等。

使用 Tabs API 時，應瞭解以下三種權限。

「分頁」權限

這項權限不會授予 chrome.tabs 命名空間的存取權。而是允許擴充功能針對 tabs.Tab 執行個體，針對下列四種敏感屬性呼叫 tabs.query()：url、pendingUrl、title 和 favIconUrl。

{
  "name": "My extension",
  ...
  "permissions": [
    "tabs"
  ],
  ...
}
主機權限

主機權限可讓擴充功能讀取及查詢相符分頁的四個敏感 tabs.Tab 屬性。也可以使用 tabs.captureVisibleTab()、tabs.executeScript()、tabs.insertCSS() 和 tabs.removeCSS() 等方法，直接與相符的分頁互動。

{
  "name": "My extension",
  ...
  "host_permissions": [
    "http://*/*",
    "https://*/*"
  ],
  ...
}
「activeTab」權限

activeTab 會根據使用者叫用，授予擴充功能目前分頁的臨時主機權限。與主機權限不同，activeTab 不會觸發任何警告。

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab"
  ],
  ...
}

用途

以下各節將說明一些常見的用途。

在新分頁中開啟擴充功能頁面

常見的擴充功能模式是在安裝擴充功能時，在新分頁中開啟新手上路頁面。以下範例說明如何執行這項操作。

background.js:

chrome.runtime.onInstalled.addListener(({reason}) => {
  if (reason === 'install') {
    chrome.tabs.create({
      url: "onboarding.html"
    });
  }
});

取得目前的分頁

這個範例說明擴充功能的服務工作站如何從目前聚焦的視窗 (如果未聚焦 Chrome 視窗，則最近聚焦的視窗) 擷取使用中的分頁。這通常可以視為使用者目前的分頁。

  async function getCurrentTab() {
    let queryOptions = { active: true, lastFocusedWindow: true };
    // `tab` will either be a `tabs.Tab` instance or `undefined`.
    let [tab] = await chrome.tabs.query(queryOptions);
    return tab;
  }


  function getCurrentTab(callback) {
    let queryOptions = { active: true, lastFocusedWindow: true };
    chrome.tabs.query(queryOptions, ([tab]) => {
      if (chrome.runtime.lastError)
      console.error(chrome.runtime.lastError);
      // `tab` will either be a `tabs.Tab` instance or `undefined`.
      callback(tab);
    });
  }

關閉指定的分頁

這個範例說明擴充功能如何切換特定分頁的靜音狀態。

  async function toggleMuteState(tabId) {
    const tab = await chrome.tabs.get(tabId);
    const muted = !tab.mutedInfo.muted;
    await chrome.tabs.update(tabId, {muted});
    console.log(`Tab ${tab.id} is ${muted ? "muted" : "unmuted"}`);
  }


  function toggleMuteState(tabId) {
    chrome.tabs.get(tabId, async (tab) => {
      let muted = !tab.mutedInfo.muted;
      await chrome.tabs.update(tabId, { muted });
      console.log(`Tab ${tab.id} is ${ muted ? "muted" : "unmuted" }`);
    });
  }

按下後將目前的分頁移至第一位置

這個範例說明在拖曳時移動分頁的方式，不一定正在進行。本範例使用 chrome.tabs.move，但您也可以針對其他會在拖曳過程中修改分頁的呼叫使用相同的等候模式。

  chrome.tabs.onActivated.addListener(moveToFirstPosition);

  async function moveToFirstPosition(activeInfo) {
    try {
      await chrome.tabs.move(activeInfo.tabId, {index: 0});
      console.log("Success.");
    } catch (error) {
      if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
        setTimeout(() => moveToFirstPosition(activeInfo), 50);
      } else {
        console.error(error);
      }
    }
  }


  chrome.tabs.onActivated.addListener(moveToFirstPositionMV2);

  function moveToFirstPositionMV2(activeInfo) {
    chrome.tabs.move(activeInfo.tabId, { index: 0 }, () => {
      if (chrome.runtime.lastError) {
        const error = chrome.runtime.lastError;
        if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
          setTimeout(() => moveToFirstPositionMV2(activeInfo), 50);
        } else {
          console.error(error);
        }
      } else {
        console.log("Success.");
      }
    });
  }

將訊息傳遞至所選分頁的內容指令碼

這個範例說明擴充功能的 Service Worker 如何使用 tabs.sendMessage() 與特定瀏覽器分頁中的內容指令碼通訊。

function sendMessageToActiveTab(message) {
  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
  const response = await chrome.tabs.sendMessage(tab.id, message);
  // TODO: Do something with the response.
}

擴充功能範例

如要查看更多 Tabs API 擴充功能示範，請參考下列任何主題：

類型

MutedInfo

Chrome 46 以上版本

該分頁標籤的已靜音狀態，以及上次狀態變更的原因。

屬性

  • extensionId

    字串 選用

    變更靜音狀態的擴充功能 ID。如果擴充功能並非上次變更靜音狀態的原因，則未設定。

  • 已設為靜音。

    boolean

    分頁是否設為靜音 (禁止播放音效)。分頁即使未播放或目前未播放音效，也可能會設為靜音。等同於是否顯示「靜音」音訊指標。

  • 原因

    MutedInfoReason 選用

    分頁設為靜音或取消靜音的原因。如果分頁的靜音狀態尚未變更，則未設定。

MutedInfoReason

Chrome 46 以上版本

導致靜音狀態變更的事件。

列舉

"user"
使用者輸入動作設為靜音狀態。

"擷取"
已啟動分頁擷取作業，強制靜音狀態變更。

"extension"
由 ExtensionsId 欄位識別的擴充功能，可設定靜音狀態。

Tab

屬性

  • 已啟用

    boolean

    指出分頁是否在視窗中處於有效狀態。並不一定代表該視窗處於聚焦狀態。

  • audible

    布林值 (選用)

    Chrome 45 以上版本

    分頁是否在過去幾秒內產生音效 (但如果你同時設為靜音)，可能會無法聽到音效。這相當於是否顯示「揚聲器音訊」指標。

  • autoDiscardable

    boolean

    Chrome 54 以上版本

    是否要在資源不足時，讓瀏覽器自動捨棄分頁。

  • 已捨棄

    boolean

    Chrome 54 以上版本

    是否捨棄這個分頁。捨棄的分頁是其內容已從記憶體中卸載，但仍顯示在分頁列上。系統會在下次啟動時重新載入內容。

  • favIconUrl

    字串 選用

    分頁網站小圖示的網址。只有在擴充功能的資訊清單包含 "tabs" 權限時，才會顯示這個屬性。如果分頁正在載入，這個字串也可能會是空白字串。

  • groupId

    號碼

    Chrome 88 以上版本

    分頁所屬群組的 ID。

  • 高度

    數字 選填

    分頁的高度 (以像素為單位)。

  • 重要留言

    boolean

    是否醒目顯示分頁。

  • id

    數字 選填

    分頁的 ID。分頁 ID 是瀏覽器工作階段內唯一的。在某些情況下，系統可能不會為分頁指派 ID，例如使用 sessions API 查詢外分頁時，就可能會顯示工作階段 ID。您也可以將應用程式和開發人員工具視窗的分頁 ID 設為 chrome.tabs.TAB_ID_NONE。

  • 無痕模式

    boolean

    這個分頁是否使用無痕視窗。

  • 索引

    號碼

    分頁視窗中分頁標籤的從零開始索引。

  • lastAccessed

    數字 選填

    Chrome 121 以上版本

    上次存取分頁的時間，以 Epoch 紀元時間起算的毫秒數表示。

  • mutedInfo

    MutedInfo 選用

    Chrome 46 以上版本

    該分頁標籤的已靜音狀態，以及上次狀態變更的原因。

  • openerTabId

    數字 選填

    開啟此分頁的分頁 ID (如果有的話)。只有在開啟工具分頁仍然存在時，才會顯示這個屬性。

  • pendingUrl

    字串 選用

    Chrome 79 以上版本

    分頁提交前，分頁所要前往的網址。只有在擴充功能的資訊清單包含 "tabs" 權限，且有待處理的導覽時，這個屬性才會顯示。

  • 已固定

    boolean

    分頁是否固定。

  • 已選取

    boolean

    已淘汰

    請使用 tabs.Tab.highlighted。

    指出是否已選取分頁標籤。

  • sessionId

    字串 選用

    工作階段 ID 用於識別從 sessions API 取得的分頁。

  • status

    TabStatus 選用

    分頁的載入狀態。

  • title

    字串 選用

    分頁標題。只有在擴充功能的資訊清單包含 "tabs" 權限時，才會顯示這個屬性。

  • 網址

    字串 選用

    分頁主頁框的最後一個提交網址。只有在擴充功能的資訊清單包含 "tabs" 權限時，這個屬性才會顯示；如果分頁尚未修訂，這個屬性可能是空白字串。另請參閱 Tab.pendingUrl。

  • 寬度

    數字 選填

    分頁的寬度 (以像素為單位)。

  • windowId

    號碼

    包含分頁的視窗 ID。

TabStatus

Chrome 44 以上版本

分頁的載入狀態。

列舉

WindowType

Chrome 44 以上版本

視窗類型。

列舉

"devtools"

ZoomSettings

定義標籤中縮放變更的方式和範圍。

屬性

  • defaultZoomFactor

    數字 選填

    Chrome 43 以上版本

    用於在呼叫 tab.getZoomSettings 時，傳回目前分頁的預設縮放等級。

  • 模式

    ZoomSettingsMode 選用

    定義縮放變更的方式，也就是由哪個實體負責網頁實際縮放比例；預設為 automatic。

  • 範圍

    ZoomSettingsScope 選用

    定義縮放比例變更是否要保留網頁來源，或只在這個分頁中生效；在 automatic 模式中預設為 per-origin，其他情況則預設為 per-tab。

ZoomSettingsMode

Chrome 44 以上版本

定義縮放變更的方式，也就是由哪個實體負責網頁實際縮放比例；預設為 automatic。

列舉

「自動」
瀏覽器會自動處理縮放變更。

"manual"
覆寫縮放變更的自動處理方式。系統仍會分派 onZoomChange 事件，擴充功能有責任監聽這個事件，並手動縮放網頁。這個模式不支援 per-origin 縮放功能，因此會忽略 scope 縮放設定，並假設為 per-tab。

"disabled"
停用分頁中的所有縮放功能。分頁會還原為預設的縮放等級，並忽略所有嘗試變更的縮放比例。

ZoomSettingsScope

Chrome 44 以上版本

定義縮放比例變更是否要保留網頁來源，或只在這個分頁中生效；在 automatic 模式中預設為 per-origin，其他情況則預設為 per-tab。

列舉

"per-origin"
縮放頁面來源的縮放變更仍會保持不變，也就是說，瀏覽同一個來源的所有其他分頁也會一併縮放。此外，per-origin 縮放變更會以原點儲存，也就是說，導覽至相同來源的其他頁面時，所有頁面都會放大為相同的縮放比例係數。per-origin 範圍僅適用於 automatic 模式。

"per-tab"
縮放變更只會在這個分頁中生效，而在其他分頁中進行縮放變更並不會影響這個分頁的縮放。此外，瀏覽分頁時系統會重設 per-tab 縮放設定；瀏覽分頁一律會使用 per-origin 縮放係數來載入網頁。

屬性

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Chrome 92 以上版本

每秒可呼叫 captureVisibleTab 的次數上限。captureVisibleTab 耗用過多資源，且呼叫頻率不高。

值

2

TAB_ID_NONE

Chrome 46 以上版本

此 ID 代表沒有瀏覽器分頁。

值

-1

TAB_INDEX_NONE

Chrome 123 以上版本

這個索引代表 tab_strip 缺少分頁索引。

值

-1

方法

captureVisibleTab()

Promise 
chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
  callback?: function,
)

擷取目前使用中分頁在指定視窗中的顯示區域。如要呼叫這個方法，擴充功能必須具備 <all_urls> 權限或 activeTab 權限。除了擴充功能通常會存取的網站之外，如果使用這個方法，擴充功能也能擷取原本受到限制的敏感網站，包括 chrome: 配置網頁、其他擴充功能的網頁和資料：網址。如要擷取這些敏感網站，必須使用 ActiveTab 權限。只有在擴充功能授予檔案存取權的情況下，系統才能擷取檔案網址。

參數

  • windowId

    數字 選填

    目標視窗。預設值為目前的視窗。

  • 選項

    ImageDetails 選用

  • 回呼

    函式選用

    callback 參數如下所示： 

    (dataUrl: string)=>void

    • dataUrl

      字串

      對所擷取分頁可見區域的圖片進行編碼的資料網址。可指派給 HTML img 元素的「src」屬性。

傳回

  • Promise<string>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

connect()

chrome.tabs.connect(
  tabId: number,
  connectInfo?: object,
)

連結至指定分頁中的內容指令碼。針對目前擴充功能，在指定分頁中執行的每個內容指令碼都會觸發 runtime.onConnect 事件。詳情請參閱「內容指令碼訊息」。

參數

  • tabId

    號碼

  • connectInfo

    物件選用

    • documentId

      字串 選用

      Chrome 106 以上版本

      開啟通訊埠指向由 documentId 識別的特定文件，而非分頁中的所有頁框。

    • frameId

      數字 選填

      開啟連接埠，指向由 frameId 識別的特定影格，而非分頁中所有影格。

    • 名稱

      字串 選用

      會傳入 onConnect，以取得監聽連線事件的內容指令碼。

傳回

  • 這個通訊埠可用來與指定分頁中執行的內容指令碼通訊。如果分頁關閉或不存在，系統會觸發通訊埠的 runtime.Port 事件。

create()

Promise 
chrome.tabs.create(
  createProperties: object,
  callback?: function,
)

開啟新分頁。

參數

  • createProperties

    物件

    • 已啟用

      布林值 (選用)

      是否要在視窗中將分頁設為使用中的分頁。這不會影響視窗是否聚焦 (請參閱 windows.update)。預設為 true。

    • 索引

      數字 選填

      分頁在視窗中的位置。系統會將提供的值調整到零和視窗中的定位點數量之間。

    • openerTabId

      數字 選填

      開啟這個分頁的分頁 ID。如有指定，開啟的分頁必須與新建立的分頁位於相同的視窗。

    • 已固定

      布林值 (選用)

      是否要固定分頁。預設值為 false

    • 已選取

      布林值 (選用)

      已淘汰

      請使用 active。

      是否要在視窗中將分頁設為所選分頁。預設值為 true

    • 網址

      字串 選用

      初始瀏覽分頁的網址。完整網址必須包含架構 (即「http://www.google.com」，而非「www.google.com」)。相對網址與擴充功能中目前的網頁相關。預設為新分頁。

    • windowId

      數字 選填

      用於建立新分頁的視窗。預設值為目前的視窗。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tab: Tab)=>void

    • 分頁

      Tab 鍵

      已建立的分頁。

傳回

  • Promise<Tab>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

detectLanguage()

Promise 
chrome.tabs.detectLanguage(
  tabId?: number,
  callback?: function,
)

偵測分頁中內容的主要語言。

參數

  • tabId

    數字 選填

    預設為目前視窗的使用中分頁。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (language: string)=>void

    • language

      字串

      ISO 語言代碼，例如 en 或 fr。如需此方法支援的完整語言清單，請參閱 kLanguageInfoTable。系統會檢查第二欄到第四欄，並傳回第一個非 NULL 值，但傳回 zh-CN 的簡體中文除外。如為不明/未定義的語言，系統會傳回 und。

傳回

  • Promise<string>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

discard()

Promise Chrome 54 以上版本 
chrome.tabs.discard(
  tabId?: number,
  callback?: function,
)

捨棄記憶體中的分頁。捨棄的分頁仍會顯示在分頁列，並在啟用後重新載入。

參數

  • tabId

    數字 選填

    要捨棄的分頁 ID，如有指定，系統就會捨棄該分頁，除非該分頁處於有效狀態或已捨棄。如果省略，瀏覽器會捨棄最不重要的分頁。如果沒有可捨棄的分頁，就可能會失敗。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tab?: Tab)=>void

    • 分頁

      Tab 選用

      捨棄的分頁 (如果成功捨棄)，否則不會定義。

傳回

  • Promise<Tab|未定義>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

duplicate()

Promise 
chrome.tabs.duplicate(
  tabId: number,
  callback?: function,
)

複製分頁。

參數

  • tabId

    號碼

    要複製的分頁 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tab?: Tab)=>void

    • 分頁

      Tab 選用

      複製分頁的詳細資料。如果未要求 "tabs" 權限，tabs.Tab 物件不會包含 url、pendingUrl、title 和 favIconUrl。

傳回

  • Promise<Tab|未定義>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

executeScript()

Promise &leq; MV2 自 Chrome 91 起已淘汰
chrome.tabs.executeScript(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

Manifest V3 已替換為 scripting.executeScript。

將 JavaScript 程式碼插入網頁中。詳情請參閱內容指令碼文件的「程式輔助插入」一節。

參數

  • tabId

    數字 選填

    執行指令碼的分頁 ID；預設為目前視窗的使用中分頁。

  • 詳細資料

    InjectDetails

    要執行的指令碼詳細資料。程式碼或檔案屬性必須設定，但兩者不能同時設定。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (result?: any[])=>void

    • 結果

      any[] 選填

      每個插入的影格中指令碼的結果。

傳回

  • 承諾<任何 []|未定義>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

get()

Promise 
chrome.tabs.get(
  tabId: number,
  callback?: function,
)

擷取指定分頁的詳細資料。

參數

  • tabId

    號碼

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tab: Tab)=>void

    • 分頁

      Tab 鍵

傳回

  • Promise<Tab>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getAllInWindow()

Promise &leq；MV2 已淘汰
chrome.tabs.getAllInWindow(
  windowId?: number,
  callback?: function,
)

請使用 tabs.query {windowId: windowId}。

取得指定視窗中所有分頁的詳細資料。

參數

  • windowId

    數字 選填

    預設值為目前的視窗。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tabs: Tab[])=>void

傳回

  • Promise<Tab[]>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getCurrent()

Promise 
chrome.tabs.getCurrent(
  callback?: function,
)

取得這個指令碼呼叫的來源分頁。如果從非分頁結構定義 (例如背景頁面或彈出式檢視畫面) 呼叫，則傳回 undefined。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tab?: Tab)=>void

    • 分頁

      Tab 選用

傳回

  • Promise<Tab|未定義>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getSelected()

Promise &leq；MV2 已淘汰
chrome.tabs.getSelected(
  windowId?: number,
  callback?: function,
)

請使用 tabs.query {active: true}。

取得在指定視窗中選取的分頁。

參數

  • windowId

    數字 選填

    預設值為目前的視窗。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tab: Tab)=>void

    • 分頁

      Tab 鍵

傳回

  • Promise<Tab>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getZoom()

Promise 
chrome.tabs.getZoom(
  tabId?: number,
  callback?: function,
)

取得指定分頁目前的縮放係數。

參數

  • tabId

    數字 選填

    用於取得目前縮放係數的分頁 ID；預設為目前視窗的使用中分頁。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (zoomFactor: number)=>void

    • zoomFactor

      號碼

      分頁目前的縮放比例係數。

傳回

  • Promise<number>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getZoomSettings()

Promise 
chrome.tabs.getZoomSettings(
  tabId?: number,
  callback?: function,
)

取得指定分頁目前的縮放設定。

參數

  • tabId

    數字 選填

    用於取得目前縮放設定的標籤 ID；預設為目前視窗使用中的分頁。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (zoomSettings: ZoomSettings)=>void

傳回

  • Promise<ZoomSettings>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

goBack()

Promise Chrome 72 以上版本 
chrome.tabs.goBack(
  tabId?: number,
  callback?: function,
)

返回上一頁 (如果有的話)。

參數

  • tabId

    數字 選填

    分頁 ID 即可返回；預設為目前視窗選取的分頁。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

goForward()

Promise Chrome 72 以上版本 
chrome.tabs.goForward(
  tabId?: number,
  callback?: function,
)

返回下一頁 (如果有的話)。

參數

  • tabId

    數字 選填

    分頁 ID 即可繼續瀏覽；預設為目前視窗選取的分頁。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

group()

Promise Chrome 88 以上版本 
chrome.tabs.group(
  options: object,
  callback?: function,
)

將一或多個分頁新增至指定群組。如未指定群組，系統會將這些分頁新增至新建立的群組。

參數

  • 選項

    物件

    • createProperties

      物件選用

      建立群組的設定。如果已指定 groupId，則無法使用。

      • windowId

        數字 選填

        新群組的視窗。預設為目前的視窗。

    • groupId

      數字 選填

      要新增分頁的群組 ID。如未指定，系統會建立新群組。

    • tabIds

      數字|[數字,...數字 []]

      要新增至指定群組的分頁 ID 或分頁 ID 清單。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (groupId: number)=>void

    • groupId

      號碼

      要新增分頁的群組 ID。

傳回

  • Promise<number>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

highlight()

Promise 
chrome.tabs.highlight(
  highlightInfo: object,
  callback?: function,
)

醒目顯示指定的分頁，並將焦點移至第一個群組。如果指定的分頁目前處於啟用狀態，就不會顯示任何動作。

參數

  • highlightInfo

    物件

    • 分頁

      數字|數字 []

      要醒目顯示的一或多個分頁索引。

    • windowId

      數字 選填

      包含分頁的視窗。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (window: Window)=>void

    • 窗戶

      視窗

      包含醒目顯示的視窗相關詳細資料。

傳回

  • Promise<windows.Window>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

insertCSS()

Promise &leq; MV2 自 Chrome 91 起已淘汰
chrome.tabs.insertCSS(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

Manifest V3 已替換為 scripting.insertCSS。

將 CSS 插入網頁。您可以使用 scripting.removeCSS 移除使用這個方法插入的樣式。詳情請參閱內容指令碼文件的「程式輔助插入」一節。

參數

  • tabId

    數字 選填

    用於插入 CSS 的分頁 ID；預設為目前視窗的使用中分頁。

  • 詳細資料

    InjectDetails

    要插入的 CSS 文字詳細資料。程式碼或檔案屬性必須設定，但兩者不能同時設定。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

move()

Promise 
chrome.tabs.move(
  tabIds: number|number[],
  moveProperties: object,
  callback?: function,
)

將一或多個分頁移至視窗內的新位置，或移到新視窗。請注意，您只能在一般視窗 (window.type === "normal") 視窗之間來回移動分頁。

參數

  • tabIds

    數字|數字 []

    要移動的分頁 ID 或分頁 ID 清單。

  • moveProperties

    物件

    • 索引

      號碼

      將視窗移至的位置。使用 -1 將分頁置於視窗末端。

    • windowId

      數字 選填

      預設為分頁目前所在的視窗。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tabs: Tab|Tab[])=>void

    • 分頁

      Tab|Tab[] 鍵

      已移動分頁的詳細資料。

傳回

  • Promise<Tab|Tab[]>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

query()

Promise 
chrome.tabs.query(
  queryInfo: object,
  callback?: function,
)

取得具有指定屬性的所有分頁，或是如未指定任何屬性，則會取得所有分頁。

參數

  • queryInfo

    物件

    • 已啟用

      布林值 (選用)

      指出分頁是否在視窗中處於使用中狀態。

    • audible

      布林值 (選用)

      Chrome 45 以上版本

      分頁是否可聽到聲音。

    • autoDiscardable

      布林值 (選用)

      Chrome 54 以上版本

      是否要在資源不足時，瀏覽器自動捨棄分頁。

    • currentWindow

      布林值 (選用)

      這些分頁是否在目前視窗內。

    • 已捨棄

      布林值 (選用)

      Chrome 54 以上版本

      是否捨棄分頁。捨棄的分頁是其內容已從記憶體中卸載，但仍顯示在分頁列上。系統會在下次啟動時重新載入內容。

    • groupId

      數字 選填

      Chrome 88 以上版本

      所在分頁所屬的群組 ID；如果分頁未分組，則使用 tabGroups.TAB_GROUP_ID_NONE。

    • 重要留言

      布林值 (選用)

      分頁是否醒目顯示。

    • 索引

      數字 選填

      分頁中分頁在視窗中的位置。

    • lastFocusedWindow

      布林值 (選用)

      是否在最後一個聚焦視窗中開啟分頁。

    • 已設為靜音。

      布林值 (選用)

      Chrome 45 以上版本

      分頁是否設為靜音。

    • 已固定

      布林值 (選用)

      是否固定分頁。

    • status

      TabStatus 選用

      分頁載入狀態。

    • title

      字串 選用

      比對網頁標題與模式。如果擴充功能沒有 "tabs" 權限，系統會忽略這個屬性。

    • 網址

      string|string[] optional

      比對分頁與一或多個網址模式。片段 ID 不相符。如果擴充功能沒有 "tabs" 權限，系統會忽略這個屬性。

    • windowId

      數字 選填

      父項視窗的 ID，或目前視窗的 windows.WINDOW_ID_CURRENT。

    • windowType

      WindowType 選用

      分頁所在的視窗類型。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (result: Tab[])=>void

傳回

  • Promise<Tab[]>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

reload()

Promise 
chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
  callback?: function,
)

重新載入分頁。

參數

  • tabId

    數字 選填

    要重新載入的分頁 ID；預設為目前視窗選取的分頁。

  • reloadProperties

    物件選用

    • bypassCache

      布林值 (選用)

      是否略過本機快取。預設值為 false。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

remove()

Promise 
chrome.tabs.remove(
  tabIds: number|number[],
  callback?: function,
)

關閉一或多個分頁。

參數

  • tabIds

    數字|數字 []

    要關閉的分頁 ID 或分頁 ID 清單。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeCSS()

Promise Chrome 87 以上版本 &leq; MV2 自 Chrome 91 版起已淘汰的項目
chrome.tabs.removeCSS(
  tabId?: number,
  details: DeleteInjectionDetails,
  callback?: function,
)

Manifest V3 已替換為 scripting.removeCSS。

從先前透過呼叫 scripting.insertCSS 插入的頁面 CSS 移除這個 CSS。

參數

  • tabId

    數字 選填

    要移除 CSS 的分頁 ID；預設為目前視窗的使用中分頁。

  • 詳細資料

    DeleteInjectionDetails

    要移除的 CSS 文字詳細資料。程式碼或檔案屬性必須設定，但兩者不能同時設定。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

sendMessage()

Promise 
chrome.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
  callback?: function,
)

將單一訊息傳送至指定分頁的內容指令碼，並加入選用的回呼，在系統傳回回應時執行。針對目前擴充功能，在指定分頁中執行的每個內容指令碼都會觸發 runtime.onMessage 事件。

參數

  • tabId

    號碼

  • 訊息

    不限

    要傳送的訊息。這則訊息應為 JSON 可匯入的物件。

  • 選項

    物件選用

    • documentId

      字串 選用

      Chrome 106 以上版本

      將郵件傳送給 documentId 辨識的特定文件，而非分頁中的所有頁框。

    • frameId

      數字 選填

      將郵件傳送至 frameId 識別的特定「影格」，而非分頁標籤中的所有頁框。

  • 回呼

    函式選用

    Chrome 99 以上版本

    callback 參數如下所示： 

    (response: any)=>void

    • 則回應

      不限

      由訊息處理常式傳送的 JSON 回應物件。如果連線至指定分頁時發生錯誤，系統會在呼叫回呼時不使用引數，並將 runtime.lastError 設為錯誤訊息。

傳回

  • 承諾<任何>

    Chrome 99 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

sendRequest()

Promise &leq；MV2 已淘汰
chrome.tabs.sendRequest(
  tabId: number,
  request: any,
  callback?: function,
)

請使用 runtime.sendMessage。

將單一要求傳送至指定分頁的內容指令碼，並加入選用的回呼，在系統傳回回應時執行。針對目前擴充功能，在指定分頁中執行的每個內容指令碼都會觸發 extension.onRequest 事件。

參數

  • tabId

    號碼

  • 申請。

    不限

  • 回呼

    函式選用

    Chrome 99 以上版本

    callback 參數如下所示： 

    (response: any)=>void

    • 則回應

      不限

      要求處理常式傳送的 JSON 回應物件。如果連線至指定分頁時發生錯誤，系統會在呼叫回呼時不使用引數，並將 runtime.lastError 設為錯誤訊息。

傳回

  • 承諾<任何>

    Chrome 99 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setZoom()

Promise 
chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
  callback?: function,
)

縮放特定分頁。

參數

  • tabId

    數字 選填

    要縮放的分頁 ID；預設為目前視窗使用中的分頁。

  • zoomFactor

    號碼

    新的縮放係數。0 值可將分頁設為目前的預設縮放係數。大於 0 的值會指定分頁標籤的縮放係數 (可能是非預設值)。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setZoomSettings()

Promise 
chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
  callback?: function,
)

設定特定分頁的縮放設定，該標籤會定義縮放變更的處理方式。瀏覽分頁時，這些設定會重設為預設值。

參數

  • tabId

    數字 選填

    用於變更縮放設定的標籤 ID；預設為目前視窗的使用中分頁。

  • zoomSettings

    ZoomSettings

    定義縮放變更的方式和範圍。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

ungroup()

Promise Chrome 88 以上版本 
chrome.tabs.ungroup(
  tabIds: number|[number,...number[]],
  callback?: function,
)

從各自群組中移除一或多個分頁。如有任何群組變成空白，就會刪除。

參數

  • tabIds

    數字|[數字,...數字 []]

    要從各群組中移除的分頁 ID 或分頁 ID 清單。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

update()

Promise 
chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
  callback?: function,
)

修改分頁的屬性。未在 updateProperties 中指定的屬性不會修改。

參數

  • tabId

    數字 選填

    預設為目前視窗中選取的分頁。

  • updateProperties

    物件

    • 已啟用

      布林值 (選用)

      是否啟用分頁。這不會影響視窗是否聚焦 (請參閱 windows.update)。

    • autoDiscardable

      布林值 (選用)

      Chrome 54 以上版本

      是否要在資源不足時，讓瀏覽器自動捨棄分頁。

    • 重要留言

      布林值 (選用)

      從目前選項中新增或移除分頁。

    • 已設為靜音。

      布林值 (選用)

      Chrome 45 以上版本

      是否要將分頁設為靜音。

    • openerTabId

      數字 選填

      開啟這個分頁的分頁 ID。如有指定，開啟的分頁必須與此分頁位於相同的視窗中。

    • 已固定

      布林值 (選用)

      是否要固定分頁。

    • 已選取

      布林值 (選用)

      已淘汰

      請使用醒目顯示。

      是否應選取分頁標籤。

    • 網址

      字串 選用

      要瀏覽分頁的網址。系統不支援 JavaScript 網址，請改用 scripting.executeScript。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (tab?: Tab)=>void

    • 分頁

      Tab 選用

      已更新分頁的詳細資料。如果未要求 "tabs" 權限，tabs.Tab 物件不會包含 url、pendingUrl、title 和 favIconUrl。

傳回

  • Promise<Tab|未定義>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onActivated

chrome.tabs.onActivated.addListener(
  callback: function,
)

在視窗中使用中的分頁變更時觸發。請注意，當這個事件觸發時，標籤網址可能不會設定，但您可以監聽 onUpdated 事件，以便在設定網址時收到通知。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (activeInfo: object)=>void

    • activeInfo

      物件

      • tabId

        號碼

        啟用後分頁的 ID。

      • windowId

        號碼

        使用中的分頁變更過的視窗 ID。

onActiveChanged

&leq; MV2 已淘汰
chrome.tabs.onActiveChanged.addListener(
  callback: function,
)

請使用 tabs.onActivated。

在視窗中選取的分頁變更時觸發。請注意，當事件觸發時，這個分頁可能不會設定分頁網址，但您可以監聽 tabs.onUpdated 事件，這樣就能在設定網址時收到通知。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tabId: number,selectInfo: object)=>void

    • tabId

      號碼

    • selectInfo

      物件

      • windowId

        號碼

        所選分頁的內部 ID 已變更。

onAttached

chrome.tabs.onAttached.addListener(
  callback: function,
)

當分頁附加至視窗時觸發，例如因為分頁在視窗之間移動。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tabId: number,attachInfo: object)=>void

    • tabId

      號碼

    • attachInfo

      物件

      • newPosition

        號碼

      • newWindowId

        號碼

onCreated

chrome.tabs.onCreated.addListener(
  callback: function,
)

在建立分頁時觸發。請注意，當觸發這個事件時，您無法設定分頁的網址和分頁群組成員，但您可以監聽 onUpdated 事件，以便接收已設定網址或分頁加入分頁群組的通知。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tab: Tab)=>void

    • 分頁

      Tab 鍵

onDetached

chrome.tabs.onDetached.addListener(
  callback: function,
)

當分頁從視窗卸離時觸發，例如因為分頁在視窗之間移動。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tabId: number,detachInfo: object)=>void

    • tabId

      號碼

    • detachInfo

      物件

      • oldPosition

        號碼

      • oldWindowId

        號碼

onHighlightChanged

&leq; MV2 已淘汰
chrome.tabs.onHighlightChanged.addListener(
  callback: function,
)

請使用 tabs.onHighlighted。

視窗中醒目顯示或選取的分頁有所變更時觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (selectInfo: object)=>void

    • selectInfo

      物件

      • tabIds

        數字 []

        視窗中所有醒目顯示的分頁。

      • windowId

        號碼

        其中分頁已變更的視窗。

onHighlighted

chrome.tabs.onHighlighted.addListener(
  callback: function,
)

視窗中醒目顯示或選取的分頁有所變更時觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (highlightInfo: object)=>void

    • highlightInfo

      物件

      • tabIds

        數字 []

        視窗中所有醒目顯示的分頁。

      • windowId

        號碼

        其中分頁已變更的視窗。

onMoved

chrome.tabs.onMoved.addListener(
  callback: function,
)

當分頁在視窗內移動時觸發。系統只會觸發一個移動事件，代表使用者直接移動的分頁。對於其他必須回應手動移動的分頁，系統不會觸發移動事件。如果分頁在不同視窗之間移動，則不會觸發此事件；詳情請參閱 tabs.onDetached。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tabId: number,moveInfo: object)=>void

    • tabId

      號碼

    • moveInfo

      物件

      • fromIndex

        號碼

      • toIndex

        號碼

      • windowId

        號碼

onRemoved

chrome.tabs.onRemoved.addListener(
  callback: function,
)

關閉分頁時觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tabId: number,removeInfo: object)=>void

    • tabId

      號碼

    • removeInfo

      物件

      • isWindowClosing

        boolean

        如果分頁因上層視窗關閉而關閉，則為 True。

      • windowId

        號碼

        分頁關閉的視窗。

onReplaced

chrome.tabs.onReplaced.addListener(
  callback: function,
)

如果分頁因預先算繪或免安裝而替換為其他分頁，就會觸發這個事件。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (addedTabId: number,removedTabId: number)=>void

    • addedTabId

      號碼

    • removedTabId

      號碼

onSelectionChanged

&leq; MV2 已淘汰
chrome.tabs.onSelectionChanged.addListener(
  callback: function,
)

請使用 tabs.onActivated。

在視窗中選取的分頁變更時觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tabId: number,selectInfo: object)=>void

    • tabId

      號碼

    • selectInfo

      物件

      • windowId

        號碼

        所選分頁的內部 ID 已變更。

onUpdated

chrome.tabs.onUpdated.addListener(
  callback: function,
)

更新分頁時觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tabId: number,changeInfo: object,tab: Tab)=>void

    • tabId

      號碼

    • changeInfo

      物件

      • audible

        布林值 (選用)

        Chrome 45 以上版本

        分頁最新的可聽狀態。

      • autoDiscardable

        布林值 (選用)

        Chrome 54 以上版本

        分頁的全新可自動捨棄狀態。

      • 已捨棄

        布林值 (選用)

        Chrome 54 以上版本

        該分頁的新捨棄狀態。

      • favIconUrl

        字串 選用

        分頁的新網站小圖示網址。

      • groupId

        數字 選填

        Chrome 88 以上版本

        分頁的新群組。

      • mutedInfo

        MutedInfo 選用

        Chrome 46 以上版本

        標籤新的靜音狀態以及變更的原因。

      • 已固定

        布林值 (選用)

        分頁的新的固定狀態。

      • status

        TabStatus 選用

        分頁的載入狀態。

      • title

        字串 選用

        Chrome 48 以上版本

        分頁的新標題。

      • 網址

        字串 選用

        如果分頁的網址已變更，請加以顯示。

    • 分頁

      Tab 鍵

onZoomChange

chrome.tabs.onZoomChange.addListener(
  callback: function,
)

縮放分頁時觸發。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (ZoomChangeInfo: object)=>void

    • ZoomChangeInfo

      物件

      • newZoomFactor

        號碼

      • oldZoomFactor

        號碼

      • tabId

        號碼

      • zoomSettings

        ZoomSettings