chrome.tabs

說明

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

總覽

分頁 API 不僅提供分頁操作和管理功能，還能偵測分頁的語言、擷取螢幕截圖，以及與分頁的內容指令碼通訊。

權限

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

使用 Tabs API 時，開發人員應注意三項權限。

「tabs」權限
這項權限不會授予 chrome.tabs 命名空間的存取權。而是授予擴充功能對 tabs.Tab 執行個體上的四個敏感屬性 (url、pendingUrl、title 和 favIconUrl) 呼叫 tabs.query() 的能力。
主機權限
主機權限可讓擴充功能讀取及查詢相符分頁的四項敏感tabs.Tab屬性。開發人員也可以使用 tabs.captureVisibleTab()、tabs.executeScript()、tabs.insertCSS() 和 tabs.removeCSS() 等方法，直接與相符的分頁互動。
「activeTab」權限
activeTab 會在使用者叫用時，授予擴充功能目前分頁的暫時主機權限。與主機權限不同，activeTab 不會觸發任何警告。

資訊清單

以下範例說明如何在資訊清單中宣告各項權限：

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

  {     "name": "My extension",     ...     "host_permissions": [       "http://*/*",       "https://*/*"     ],     ...   } 

  {     "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.");       }     });   }

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

這個範例示範擴充功能的服務工作人員如何使用 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。如果上次變更靜音狀態的原因不是擴充功能，則不會設定這個值。

  • 已設為靜音。

    布林值

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

  • 原因

    MutedInfoReason optional

    分頁靜音或取消靜音的原因。如果分頁的靜音狀態從未變更，則不會設定這個屬性。

MutedInfoReason

Chrome 46 以上版本

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

列舉

「user」
使用者輸入動作設定了靜音狀態。

「capture」
已啟動分頁擷取功能，強制變更為靜音狀態。

「extension」
擴充功能 (由 extensionId 欄位識別) 設定了靜音狀態。

Tab

屬性

  • 已啟用

    布林值

    分頁是否在視窗中處於啟用狀態。不一定代表視窗已聚焦。

  • audible

    布林值 選填

    Chrome 45 以上版本

    分頁是否在過去幾秒內發出聲音 (但如果分頁也設為靜音，可能就聽不到聲音)。相當於是否顯示「音箱音訊」指標。

  • autoDiscardable

    布林值

    Chrome 54 以上版本

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

  • 已捨棄

    布林值

    Chrome 54 以上版本

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

  • favIconUrl

    字串 選填

    分頁的網站小圖示網址。只有在擴充功能具有 "tabs" 權限或網頁的主機權限時，才會顯示這項屬性。如果分頁正在載入，也可能是空字串。

  • 凍結

    布林值

    Chrome 132 以上版本

    分頁是否凍結。凍結的分頁無法執行工作，包括事件處理常式或計時器。分頁會顯示在分頁列中，且內容會載入記憶體。啟用後就會解除凍結。

  • groupId

    數字

    Chrome 88 以上版本

    分頁所屬群組的 ID。

  • 高度

    號碼 選填

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

  • 重要留言

    布林值

    分頁是否醒目顯示。

  • id

    號碼 選填

    分頁的 ID。分頁 ID 在瀏覽器工作階段中不得重複。在某些情況下，系統可能不會為分頁指派 ID，例如使用 sessions API 查詢外部分頁時，這時可能會出現工作階段 ID。應用程式和開發人員工具視窗的索引標籤 ID 也可以設為 chrome.tabs.TAB_ID_NONE。

  • 無痕

    布林值

    分頁是否位於無痕視窗中。

  • 索引

    數字

    分頁在視窗中的索引，從零開始。

  • lastAccessed

    數字

    Chrome 121 以上版本

    分頁在視窗中上次處於使用中狀態的時間，以 Epoch 紀元時間起算的毫秒數表示。

  • mutedInfo

    MutedInfo optional

    Chrome 46 以上版本

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

  • openerTabId

    號碼 選填

    開啟這個分頁的分頁 ID (如有)。只有在開啟器分頁仍存在時，才會顯示這項屬性。

  • pendingUrl

    字串 選填

    Chrome 79 以上版本

    分頁要前往的網址 (尚未提交)。只有在擴充功能具有 "tabs" 權限或網頁主機權限，且有待處理的導覽時，才會顯示這項屬性。

  • 已固定

    布林值

    分頁是否已固定。

  • 已選取

    布林值

    已淘汰

    請使用 tabs.Tab.highlighted。

    分頁是否已選取。

  • sessionId

    字串 選填

    用於準確識別從 sessions API 取得的分頁 ID。

  • 狀態

    TabStatus 選用

    分頁的載入狀態。

  • title

    字串 選填

    分頁標題。只有在擴充功能具有 "tabs" 權限或網頁的主機權限時，才會顯示這項屬性。

  • 網址

    字串 選填

    分頁主要框架上次提交的網址。只有在擴充功能具有 "tabs" 權限或網頁的主機權限時，才會顯示這項屬性。如果分頁尚未提交，則可能為空字串。另請參閱「Tab.pendingUrl」。

  • 寬度

    號碼 選填

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

  • windowId

    數字

    包含分頁的視窗 ID。

TabStatus

Chrome 44 以上版本

分頁的載入狀態。

列舉

「unloaded」

「loading」

「complete」

WindowType

Chrome 44 以上版本

視窗類型。

列舉

「normal」

「popup」

「panel」

「應用程式」

「devtools」

ZoomSettings

定義如何處理分頁中的縮放變更，以及變更的範圍。

屬性

  • defaultZoomFactor

    號碼 選填

    Chrome 43 以上版本

    用於在對 tabs.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 範圍僅適用於automatic 模式。

「每個分頁」
縮放變更只會影響這個分頁，其他分頁的縮放變更不會影響這個分頁。此外，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,
): Promise<string>

擷取指定視窗中目前有效分頁的可見區域。如要呼叫這個方法，擴充功能必須具備 <all_urls> 權限或 activeTab 權限。除了擴充功能通常可存取的網站，這個方法還允許擴充功能擷取受限制的敏感網站，包括 chrome: 配置網頁、其他擴充功能的網頁和資料網址。只有具備 activeTab 權限，才能擷取這些敏感網站。只有在擴充功能獲得檔案存取權時，才能擷取檔案網址。

參數

  • windowId

    號碼 選填

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

  • 選項

    ImageDetails 選填

  • callback

    函式 選用

    callback 參數如下： 

    (dataUrl: string) => void

    • dataUrl

      字串

      資料網址，可編碼擷取的分頁可見區域圖片。可指派給 HTML img 元素的「src」屬性，以供顯示。

傳回

  • Promise<string>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

connect()

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

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

參數

  • tabId

    數字

  • connectInfo

    object 選填

    • documentId

      字串 選填

      Chrome 106 以上版本

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

    • frameId

      號碼 選填

      開啟特定框架的通訊埠 (以 frameId 識別)，而非分頁中的所有框架。

    • 名稱

      字串 選填

      系統會將這個物件傳遞至 onConnect，供監聽連線事件的內容指令碼使用。

傳回

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

create()

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

建立新分頁。

參數

  • createProperties

    物件

    • 已啟用

      布林值 選填

      分頁是否應成為視窗中的使用中分頁。不會影響視窗是否為焦點 (請參閱 windows.update)。預設為 true。

    • 索引

      號碼 選填

      分頁在視窗中的位置。提供的值會限制在零和視窗中的分頁數之間。

    • openerTabId

      號碼 選填

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

    • 已固定

      布林值 選填

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

    • 已選取

      布林值 選填

      已淘汰

      請使用「active」。

      分頁是否應成為視窗中選取的分頁。預設值為 true

    • 網址

      字串 選填

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

    • windowId

      號碼 選填

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

  • callback

    函式 選用

    callback 參數如下： 

    (tab: Tab) => void

    • 分頁

      Tab 鍵

      建立的分頁。

傳回

  • Promise<Tab 鍵>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

detectLanguage()

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

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

參數

  • tabId

    號碼 選填

    預設為目前視窗的有效分頁。

  • callback

    函式 選用

    callback 參數如下： 

    (language: string) => void

    • language

      字串

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

傳回

  • Promise<string>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

discard()

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

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

參數

  • tabId

    號碼 選填

    要捨棄的分頁 ID。如果指定，除非分頁處於啟用狀態或已捨棄，否則會捨棄分頁。如果省略，瀏覽器會捨棄最不重要的分頁。如果沒有可捨棄的分頁，這項作業就會失敗。

  • callback

    函式 選用

    callback 參數如下： 

    (tab?: Tab) => void

    • 分頁

      分頁 選填

      如果成功捨棄分頁，則為捨棄的分頁；否則為未定義。

傳回

  • Promise<Tab | undefined>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

duplicate()

Promise 
chrome.tabs.duplicate(
  tabId: number,
  callback?: function,
): Promise<Tab | undefined>

複製分頁。

參數

  • tabId

    數字

    要複製的分頁 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (tab?: Tab) => void

    • 分頁

      分頁 選填

      重複分頁的詳細資料。只有在擴充功能具備 "tabs" 權限或網頁的主機權限時，tabs.Tab 物件才會包含 url、pendingUrl、title 和 favIconUrl 屬性。

傳回

  • Promise<Tab | undefined>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

executeScript()

Promise &leq; MV2 Chrome 91 版起已淘汰
chrome.tabs.executeScript(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
): Promise<any[] | undefined>

在 Manifest V3 中，此屬性已由 scripting.executeScript 取代。

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

參數

  • tabId

    號碼 選填

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

  • 詳細資料

    InjectDetails

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

  • callback

    函式 選用

    callback 參數如下： 

    (result?: any[]) => void

    • 結果

      any[] 選填

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

傳回

  • Promise<any[] | undefined>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

get()

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

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

參數

  • tabId

    數字

  • callback

    函式 選用

    callback 參數如下： 

    (tab: Tab) => void

    • 分頁

      Tab 鍵

傳回

  • Promise<Tab 鍵>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getAllInWindow()

Promise &leq; MV2 已淘汰
chrome.tabs.getAllInWindow(
  windowId?: number,
  callback?: function,
): Promise<Tab[]>

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

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

參數

  • windowId

    號碼 選填

    預設為目前視窗。

  • callback

    函式 選用

    callback 參數如下： 

    (tabs: Tab[]) => void

傳回

  • Promise<Tab[]>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getCurrent()

Promise 
chrome.tabs.getCurrent(
  callback?: function,
): Promise<Tab | undefined>

取得發出這項指令碼呼叫的分頁。如果從非分頁內容 (例如背景網頁或彈出式視窗) 呼叫，則會傳回 undefined。

參數

  • callback

    函式 選用

    callback 參數如下： 

    (tab?: Tab) => void

傳回

  • Promise<Tab | undefined>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getSelected()

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

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

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

參數

  • windowId

    號碼 選填

    預設為目前視窗。

  • callback

    函式 選用

    callback 參數如下： 

    (tab: Tab) => void

    • 分頁

      Tab 鍵

傳回

  • Promise<Tab 鍵>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getZoom()

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

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

參數

  • tabId

    號碼 選填

    要從中取得目前縮放比例的分頁 ID；預設為目前視窗的現用分頁。

  • callback

    函式 選用

    callback 參數如下： 

    (zoomFactor: number) => void

    • zoomFactor

      數字

      分頁目前的縮放係數。

傳回

  • Promise<number>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getZoomSettings()

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

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

參數

  • tabId

    號碼 選填

    要從中取得目前縮放設定的分頁 ID，預設為目前視窗的有效分頁。

  • callback

    函式 選用

    callback 參數如下： 

    (zoomSettings: ZoomSettings) => void

傳回

  • Promise<ZoomSettings>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

goBack()

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

返回上一頁 (如有)。

參數

  • tabId

    號碼 選填

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

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

goForward()

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

前往下一頁 (如有)。

參數

  • tabId

    號碼 選填

    要向前導覽的分頁 ID；預設為目前視窗所選的分頁。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

group()

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

將一或多個分頁加入指定群組，或在未指定群組的情況下，將指定分頁加入新建立的群組。

參數

  • 選項

    物件

    • createProperties

      object 選填

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

      • windowId

        號碼 選填

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

    • groupId

      號碼 選填

      要將分頁加入的群組 ID。如果未指定，系統會建立新群組。

    • tabIds

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

      要加入指定群組的分頁 ID 或分頁 ID 清單。

  • callback

    函式 選用

    callback 參數如下： 

    (groupId: number) => void

    • groupId

      數字

      分頁所加入的群組 ID。

傳回

  • Promise<number>

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

highlight()

Promise 
chrome.tabs.highlight(
  highlightInfo: object,
  callback?: function,
): Promise<windows.Window>

醒目顯示指定的分頁，並將焦點放在群組的第一個分頁。如果指定的分頁目前處於啟用狀態，系統會顯示沒有任何動作。

參數

  • highlightInfo

    物件

    • 分頁

      數字 | 數字 []

      要醒目顯示的一或多個索引標籤。

    • windowId

      號碼 選填

      包含分頁的視窗。

  • callback

    函式 選用

    callback 參數如下： 

    (window: Window) => void

    • 窗戶

      視窗

      包含醒目顯示分頁的視窗詳細資料。

傳回

  • Promise<windows.Window>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

insertCSS()

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

在 Manifest V3 中，此屬性已由 scripting.insertCSS 取代。

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

參數

  • tabId

    號碼 選填

    要插入 CSS 的分頁 ID，預設為目前視窗的現用分頁。

  • 詳細資料

    InjectDetails

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

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

move()

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

將一或多個分頁移至視窗中的新位置，或移至新視窗。請注意，分頁只能移至一般 (window.type === "normal") 視窗，或從這類視窗移出。

參數

  • tabIds

    數字 | 數字 []

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

  • moveProperties

    物件

    • 索引

      數字

      要將視窗移至的位置。使用 -1 將分頁放在視窗結尾。

    • windowId

      號碼 選填

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

  • callback

    函式 選用

    callback 參數如下： 

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

    • 分頁

      分頁 | 分頁[]

      已移動的分頁詳細資料。

傳回

  • Promise<Tab | Tab[]>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

query()

Promise 
chrome.tabs.query(
  queryInfo: object,
  callback?: function,
): Promise<Tab[]>

取得具有指定屬性的所有分頁，或在未指定屬性時取得所有分頁。

參數

  • queryInfo

    物件

    • 已啟用

      布林值 選填

      分頁是否在視窗中處於啟用狀態。

    • audible

      布林值 選填

      Chrome 45 以上版本

      分頁是否發出聲音。

    • autoDiscardable

      布林值 選填

      Chrome 54 以上版本

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

    • currentWindow

      布林值 選填

      分頁是否位於目前視窗。

    • 已捨棄

      布林值 選填

      Chrome 54 以上版本

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

    • 凍結

      布林值 選填

      Chrome 132 以上版本

      分頁是否已凍結。凍結的分頁無法執行工作，包括事件處理常式或計時器。分頁會顯示在分頁列中，且內容會載入記憶體。啟用後就會解除凍結。

    • groupId

      號碼 選填

      Chrome 88 以上版本

      分頁所屬群組的 ID，或未分組分頁的 tabGroups.TAB_GROUP_ID_NONE。

    • 重要留言

      布林值 選填

      分頁是否醒目顯示。

    • 索引

      號碼 選填

      分頁在視窗中的位置。

    • lastFocusedWindow

      布林值 選填

      分頁是否位於上次聚焦的視窗中。

    • 已設為靜音。

      布林值 選填

      Chrome 45 以上版本

      分頁是否設為靜音。

    • 已固定

      布林值 選填

      分頁是否已固定。

    • splitViewId

      號碼 選填

      待處理

      分頁所在分割檢視畫面的 ID，或不在分割檢視畫面中的分頁的 tabs.SPLIT_VIEW_ID_NONE。

    • 狀態

      TabStatus 選用

      分頁載入狀態。

    • title

      字串 選填

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

    • 網址

      string | string[] optional

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

    • windowId

      號碼 選填

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

    • windowType

      WindowType 選填

      分頁所在的視窗類型。

  • callback

    函式 選用

    callback 參數如下： 

    (result: Tab[]) => void

傳回

  • Promise<Tab[]>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

reload()

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

重新載入分頁。

參數

  • tabId

    號碼 選填

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

  • reloadProperties

    object 選填

    • bypassCache

      布林值 選填

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

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

remove()

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

關閉一或多個分頁。

參數

  • tabIds

    數字 | 數字 []

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

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

removeCSS()

Promise Chrome 87 以上版本 &leq; MV2 Chrome 91 以上版本已淘汰
chrome.tabs.removeCSS(
  tabId?: number,
  details: DeleteInjectionDetails,
  callback?: function,
): Promise<void>

在 Manifest V3 中，此屬性已由 scripting.removeCSS 取代。

從網頁中移除先前透過呼叫 scripting.insertCSS 插入的 CSS。

參數

  • tabId

    號碼 選填

    要移除 CSS 的分頁 ID，預設為目前視窗的有效分頁。

  • 詳細資料

    DeleteInjectionDetails

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

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

sendMessage()

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

將單一訊息傳送至指定分頁中的內容指令碼，並視需要執行回呼，以便在系統傳回回應時執行。系統會在目前擴充功能指定分頁中執行的每個內容指令碼中，觸發 runtime.onMessage 事件。

參數

  • tabId

    數字

  • 訊息

    不限

    要傳送的訊息。這則訊息應為可轉換為 JSON 的物件。

  • 選項

    object 選填

    • documentId

      字串 選填

      Chrome 106 以上版本

      傳送訊息給以 documentId 識別的特定文件，而非分頁中的所有影格。

    • frameId

      號碼 選填

      傳送訊息給以 frameId 識別的特定框架，而非分頁中的所有框架。

  • callback

    函式 選用

    Chrome 99 以上版本

    callback 參數如下： 

    (response: any) => void

    • 回應

      不限

      訊息處理常式傳送的 JSON 回應物件。如果連線至指定分頁時發生錯誤，系統會呼叫回呼，但不含任何引數，且 runtime.lastError 會設為錯誤訊息。

傳回

  • Promise<any>

    Chrome 99 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

sendRequest()

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

請使用 runtime.sendMessage。

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

參數

  • tabId

    數字

  • 申請。

    不限

  • callback

    函式 選用

    Chrome 99 以上版本

    callback 參數如下： 

    (response: any) => void

    • 回應

      不限

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

傳回

  • Promise<any>

    Chrome 99 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setZoom()

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

縮放指定的分頁。

參數

  • tabId

    號碼 選填

    要縮放的分頁 ID，預設為目前視窗的活動分頁。

  • zoomFactor

    數字

    新的縮放係數。如果值為 0，分頁會設為目前的預設縮放比例。如果值大於 0，則表示分頁的縮放比例 (可能不是預設值)。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setZoomSettings()

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

為指定分頁設定縮放設定，定義如何處理縮放變更。瀏覽分頁時，這些設定會重設為預設值。

參數

  • tabId

    號碼 選填

    要變更縮放設定的分頁 ID，預設為目前視窗的有效分頁。

  • zoomSettings

    ZoomSettings

    定義如何處理縮放變更，以及變更的範圍。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

ungroup()

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

從各自的群組中移除一或多個分頁。如果群組變成空白，系統就會刪除。

參數

  • tabIds

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

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

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

update()

Promise 
chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
  callback?: function,
): Promise<Tab | undefined>

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

參數

  • tabId

    號碼 選填

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

  • updateProperties

    物件

    • 已啟用

      布林值 選填

      分頁是否應處於有效狀態。不會影響視窗是否處於焦點狀態 (請參閱 windows.update)。

    • autoDiscardable

      布林值 選填

      Chrome 54 以上版本

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

    • 重要留言

      布林值 選填

      將分頁新增至目前選取範圍，或從中移除分頁。

    • 已設為靜音。

      布林值 選填

      Chrome 45 以上版本

      是否要將分頁設為靜音。

    • openerTabId

      號碼 選填

      開啟這個分頁的分頁 ID。如果指定開啟者分頁，該分頁必須與這個分頁位於相同視窗。

    • 已固定

      布林值 選填

      是否要固定分頁。

    • 已選取

      布林值 選填

      已淘汰

      請使用醒目顯示。

      是否應選取分頁。

    • 網址

      字串 選填

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

  • callback

    函式 選用

    callback 參數如下： 

    (tab?: Tab) => void

    • 分頁

      分頁 選填

      新版分頁的詳細資料。只有在擴充功能具備 "tabs" 權限或網頁的主機權限時，tabs.Tab 物件才會包含 url、pendingUrl、title 和 favIconUrl 屬性。

傳回

  • Promise<Tab | undefined>

    Chrome 88 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onActivated

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

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

參數

  • callback

    函式

    callback 參數如下： 

    (activeInfo: object) => void

    • activeInfo

      物件

      • tabId

        數字

        已啟用的分頁 ID。

      • windowId

        數字

        作用中分頁所在視窗的 ID。

onActiveChanged

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

請使用 tabs.onActivated。

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

參數

  • callback

    函式

    callback 參數如下： 

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

    • tabId

      數字

    • selectInfo

      物件

      • windowId

        數字

        所選分頁所屬視窗的 ID。

onAttached

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

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

參數

  • callback

    函式

    callback 參數如下： 

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

    • tabId

      數字

    • attachInfo

      物件

      • newPosition

        數字

      • newWindowId

        數字

onCreated

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

建立分頁時觸發。請注意，系統觸發這個事件時，可能尚未設定分頁的網址和分頁群組成員資格，但您可以監聽 onUpdated 事件，以便在設定網址或將分頁新增至分頁群組時收到通知。

參數

  • callback

    函式

    callback 參數如下： 

    (tab: Tab) => void

    • 分頁

      Tab 鍵

onDetached

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

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

參數

  • callback

    函式

    callback 參數如下： 

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

    • tabId

      數字

    • detachInfo

      物件

      • oldPosition

        數字

      • oldWindowId

        數字

onHighlightChanged

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

請使用 tabs.onHighlighted。

當視窗中醒目顯示或選取的索引標籤變更時，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    (selectInfo: object) => void

    • selectInfo

      物件

      • tabIds

        number[]

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

      • windowId

        數字

        分頁變更的視窗。

onHighlighted

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

當視窗中醒目顯示或選取的索引標籤變更時，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    (highlightInfo: object) => void

    • highlightInfo

      物件

      • tabIds

        number[]

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

      • windowId

        數字

        分頁變更的視窗。

onMoved

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

當分頁在視窗內移動時觸發。系統只會觸發一個移動事件，代表使用者直接移動的分頁。系統不會針對必須因應手動移動的索引標籤而移動的其他索引標籤，觸發移動事件。在視窗之間移動分頁時，不會觸發這個事件；詳情請參閱 tabs.onDetached。

參數

  • callback

    函式

    callback 參數如下： 

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

    • tabId

      數字

    • moveInfo

      物件

      • fromIndex

        數字

      • toIndex

        數字

      • windowId

        數字

onRemoved

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

分頁關閉時觸發。

參數

  • callback

    函式

    callback 參數如下： 

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

    • tabId

      數字

    • removeInfo

      物件

      • isWindowClosing

        布林值

        如果分頁是因為父項視窗關閉而關閉，則為 True。

      • windowId

        數字

        關閉分頁的視窗。

onReplaced

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

由於預先算繪或即時功能，分頁遭其他分頁取代時觸發。

參數

  • callback

    函式

    callback 參數如下： 

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

    • addedTabId

      數字

    • removedTabId

      數字

onSelectionChanged

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

請使用 tabs.onActivated。

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

參數

  • callback

    函式

    callback 參數如下： 

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

    • tabId

      數字

    • selectInfo

      物件

      • windowId

        數字

        所選分頁所屬視窗的 ID。

onUpdated

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

分頁更新時觸發。

參數

  • callback

    函式

    callback 參數如下： 

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

    • tabId

      數字

    • changeInfo

      物件

      • audible

        布林值 選填

        Chrome 45 以上版本

        分頁的新音訊狀態。

      • autoDiscardable

        布林值 選填

        Chrome 54 以上版本

        分頁的新自動捨棄狀態。

      • 已捨棄

        布林值 選填

        Chrome 54 以上版本

        分頁的新捨棄狀態。

      • favIconUrl

        字串 選填

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

      • 凍結

        布林值 選填

        Chrome 132 以上版本

        分頁的新凍結狀態。

      • groupId

        號碼 選填

        Chrome 88 以上版本

        分頁的新群組。

      • mutedInfo

        MutedInfo optional

        Chrome 46 以上版本

        分頁的新靜音狀態和變更原因。

      • 已固定

        布林值 選填

        分頁的新固定狀態。

      • splitViewId

        號碼 選填

        待處理

        分頁的新分割檢視畫面。

      • 狀態

        TabStatus 選用

        分頁的載入狀態。

      • title

        字串 選填

        Chrome 48 以上版本

        分頁的新標題。

      • 網址

        字串 選填

        分頁的網址 (如有變更)。

    • 分頁

      Tab 鍵

onZoomChange

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

分頁縮放時觸發。

參數

  • callback

    函式

    callback 參數如下： 

    (ZoomChangeInfo: object) => void

    • ZoomChangeInfo

      物件

      • newZoomFactor

        數字

      • oldZoomFactor

        數字

      • tabId

        數字

      • zoomSettings

        ZoomSettings