chrome.tabs

說明

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

總覽

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

注意：Tabs API 可供 Service Worker 和擴充功能頁面使用，但不能使用內容指令碼。

權限

大多數功能都不需要任何權限即可使用，例如建立新分頁。 重新載入分頁、導覽至其他網址等。

開發人員使用 Tabs API 時，應留意下列三種權限。

分頁權限

這項權限不會授予 chrome.tabs 命名空間的存取權。相反地 可授予擴充功能對四個 tabs.query() 呼叫的能力 tabs.Tab 例項的機密屬性：url、pendingUrl、title 和 favIconUrl。

主機權限

主機權限可讓擴充功能讀取及查詢相符分頁的四項機密內容 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"
    });
  }
});

敬上

成功：這個範例不需要任何權限。

取得目前的分頁

這個範例說明瞭擴充功能的 Service Worker 如何從 目前聚焦視窗 (如果沒有瀏覽任何 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);
      }
    }
  }

敬上

成功：在 Promise 內容中使用 include(error) 有助於確保錯誤。 會填入 chrome.runtime.lastError。

  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 擴充功能示範，請參閱下列資源：

• Manifest V2 - Tabs API 擴充功能。
• Manifest V3 - 分頁管理工具。

類型

MutedInfo

Chrome 46 以上版本

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

屬性

• extensionId

  string optional

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

• 已設為靜音。

  布林值

  分頁是否設為靜音 (無法播放音效)。即使分頁未播放或目前未播放音效，該分頁仍可能設為靜音。等同於「靜音」音訊指標正在顯示。

• 原因

  MutedInfoReason 選用

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

MutedInfoReason

Chrome 46 以上版本

造成靜音狀態變更的事件。

列舉

"user"
使用者輸入內容動作設定了靜音狀態。

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

"extension"
由 extensionId 欄位識別的擴充功能會設定靜音狀態。

Tab

屬性

• 已啟用

  布林值

  分頁在視窗中是否仍為使用中。但不一定代表視窗已聚焦。

• audible

  布林值 選填

  Chrome 45 以上版本

  這個分頁是否在過去幾秒內發出聲音 (但即使也並未聽到該聲音)。等同於「喇叭音訊」狀態指示燈。

• autoDiscardable

  布林值

  Chrome 54 以上版本

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

• 已捨棄

  布林值

  Chrome 54 以上版本

  是否捨棄該分頁。捨棄的分頁是內容已從記憶體卸載，但依然會顯示在分頁列中。下次啟用時，內容就會重新載入。

• favIconUrl

  string optional

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

• groupId

  數字

  Chrome 88 以上版本

  分頁所屬的群組 ID。

• 高度

  編號 選填

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

• 重要留言

  布林值

  是否醒目顯示該分頁。

• id

  編號 選填

  分頁的 ID。分頁 ID 不得與瀏覽器工作階段重複。在某些情況下，標籤不可指派 ID；例如使用 sessions API 查詢外國分頁時，可能會顯示工作階段 ID。針對應用程式和開發人員工具視窗，您也可以將分頁 ID 設為 chrome.tabs.TAB_ID_NONE。

• 無痕模式

  布林值

  分頁是否在無痕式視窗中。

• 索引

  數字

  分頁視窗內從零開始的索引。

• lastAccessed

  數字

  Chrome 121 以上版本

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

• mutedInfo

  MutedInfo 選用

  Chrome 46 以上版本

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

• openerTabId

  編號 選填

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

• pendingUrl

  string optional

  Chrome 79 以上版本

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

• 已固定

  布林值

  是否固定分頁。

• 已選取

  布林值

  已淘汰

  請使用 tabs.Tab.highlighted。

  是否選取分頁。

• sessionId

  string optional

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

• 狀態

  TabStatus 選用

  分頁的載入狀態。

• title

  string optional

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

• 網址

  string optional

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

• 寬度

  編號 選填

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

• windowId

  數字

  包含分頁的視窗 ID。

TabStatus

Chrome 44 以上版本

分頁的載入狀態。

列舉

「未載入」

"載入中"

"complete"

WindowType

Chrome 44 以上版本

視窗類型。

列舉

"normal"

「彈出式視窗」

「面板」

「應用程式」

"devtools"

ZoomSettings

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

屬性

• defaultZoomFactor

  編號 選填

  Chrome 43 以上版本

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

• 模式

  ZoomSettingsMode optional

  定義縮放變更的處理方式，也就是負責處理網頁實際縮放比例的實體；預設值為 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-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:-scheme 網頁和其他擴充功能包括網頁和資料網址你必須使用 Active Tab 權限才能擷取這些敏感網站。只有在擴充功能獲得檔案存取權時，才能擷取檔案網址。

參數

• windowId

  編號 選填

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

• 選項

  ImageDetails 選用

• 回呼

  函式 選用

  callback 參數如下所示：

  (dataUrl: string) => void

  • dataUrl

    字串

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

傳回

• 承諾<字串>

  Chrome 88 以上版本

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

connect()

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

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

參數

• tabId

  數字

• connectInfo

  物件 optional

  • documentId

    string optional

    Chrome 106 以上版本

    開啟通訊埠，連至 documentId 識別的特定「文件」，而非該分頁中的所有頁框。

  • frameId

    編號 選填

    開啟通訊埠至由 frameId 識別的特定頁框，而非該分頁中的所有影格。

  • 名稱

    string optional

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

傳回

• runtime.Port

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

create()

Promise

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

建立新分頁。

參數

• createProperties

  物件

  • 已啟用

    布林值 選填

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

  • 索引

    編號 選填

    分頁在視窗中應佔的位置。提供的值會介於 0 到視窗中的分頁數量之間。

  • openerTabId

    編號 選填

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

  • 已固定

    布林值 選填

    是否應固定分頁。預設為 false

  • 已選取

    布林值 選填

    已淘汰

    請使用「啟用」。

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

  • 網址

    string optional

    分頁最初前往的網址。完全符合規定的網址必須包含配置 (即「http://www.google.com」，而不是「www.google.com」)。相對網址是指額外資訊中目前網頁的相對網址。預設為新分頁。

  • windowId

    編號 選填

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (tab: Tab) => void

  • 分頁

    Tab 鍵

    已建立的分頁。

傳回

• Promise <Tab>

  Chrome 88 以上版本

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

detectLanguage()

Promise

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

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

參數

• tabId

  編號 選填

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (language: string) => void

  • language

    字串

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

傳回

• 承諾<字串>

  Chrome 88 以上版本

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

discard()

Promise Chrome 54 以上版本

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

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

參數

• tabId

  編號 選填

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (tab?: Tab) => void

  • 分頁

    Tab 鍵 選用

    已捨棄的分頁 (如果已成功捨棄)。未定義。

傳回

• Promise<Tab |未定義>

  Chrome 88 以上版本

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

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 以上版本

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

executeScript()

Promise &amp;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[] 選填

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

傳回

• Promise&lt;any[] |未定義>

  Chrome 88 以上版本

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

get()

Promise

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

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

參數

• tabId

  數字

• 回呼

  函式 選用

  callback 參數如下所示：

  (tab: Tab) => void

  • 分頁

    Tab 鍵

傳回

• Promise <Tab>

  Chrome 88 以上版本

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

getAllInWindow()

Promise &amp;leq;MV2 已淘汰

chrome.tabs.getAllInWindow(
  windowId?: number,
  callback?: function,
)

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

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

參數

• windowId

  編號 選填

  預設為目前的視窗。

• 回呼

  函式 選用

  callback 參數如下所示：

  (tabs: Tab[]) => void

  • 分頁

    Tab 鍵[]

傳回

• 承諾<Tab[]>

  Chrome 88 以上版本

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

getCurrent()

Promise

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

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

參數

• 回呼

  函式 選用

  callback 參數如下所示：

  (tab?: Tab) => void

  • 分頁

    Tab 鍵 選用

傳回

• Promise<Tab |未定義>

  Chrome 88 以上版本

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

getSelected()

Promise &amp;leq;MV2 已淘汰

chrome.tabs.getSelected(
  windowId?: number,
  callback?: function,
)

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

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

參數

• windowId

  編號 選填

  預設為目前的視窗。

• 回呼

  函式 選用

  callback 參數如下所示：

  (tab: Tab) => void

  • 分頁

    Tab 鍵

傳回

• Promise <Tab>

  Chrome 88 以上版本

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

getZoom()

Promise

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

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

參數

• tabId

  編號 選填

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (zoomFactor: number) => void

  • zoomFactor

    數字

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

傳回

• Promise&lt;number&gt;

  Chrome 88 以上版本

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

getZoomSettings()

Promise

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

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

參數

• tabId

  編號 選填

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (zoomSettings: ZoomSettings) => void

  • zoomSettings

    ZoomSettings

    分頁目前的縮放設定。

傳回

• Promise&lt;ZoomSettings&gt;

  Chrome 88 以上版本

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

goBack()

Promise Chrome 72 以上版本

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

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

參數

• tabId

  編號 選填

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

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

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

goForward()

Promise Chrome 72 以上版本

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

移至下一頁 (如果有的話)。

參數

• tabId

  編號 選填

  後續瀏覽的分頁 ID；預設為目前視窗的所選分頁。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

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

group()

Promise Chrome 88 以上版本

chrome.tabs.group(
  options: object,
  callback?: function,
)

將一或多個分頁新增至指定群組。如未指定群組，則會將指定的分頁加入新建的群組。

參數

• 選項

  物件

  • createProperties

    物件 optional

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

    • windowId

      編號 選填

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

  • groupId

    編號 選填

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

  • tabIds

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

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (groupId: number) => void

  • groupId

    數字

    分頁所屬的群組 ID。

傳回

• Promise&lt;number&gt;

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

highlight()

Promise

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

醒目顯示指定的分頁，並聚焦在群組的第一個群組。如果指定的分頁目前為使用中，就不會執行任何動作。

參數

• highlightInfo

  物件

  • 分頁

    數字 |數字 []

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

  • windowId

    編號 選填

    包含分頁的視窗。

• 回呼

  函式 選用

  callback 參數如下所示：

  (window: Window) => void

  • 窗戶

    視窗

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

傳回

• Promise&lt;windows.Window&gt;

  Chrome 88 以上版本

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

insertCSS()

Promise &amp;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

傳回

• 承諾<void>

  Chrome 88 以上版本

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

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 以上版本

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

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 以上版本

    這些分頁是否設為靜音。

  • 已固定

    布林值 選填

    是否要固定分頁。

  • 狀態

    TabStatus 選用

    分頁載入狀態。

  • title

    string optional

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

  • 網址

    string |string[] 選填

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

  • windowId

    編號 選填

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

  • windowType

    WindowType 選用

    分頁所在的視窗類型。

• 回呼

  函式 選用

  callback 參數如下所示：

  (result: Tab[]) => void

  • 結果

    Tab 鍵[]

傳回

• 承諾<Tab[]>

  Chrome 88 以上版本

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

reload()

Promise

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

重新載入分頁。

參數

• tabId

  編號 選填

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

• reloadProperties

  物件 optional

  • bypassCache

    布林值 選填

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

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

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

remove()

Promise

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

關閉一或多個分頁。

參數

• tabIds

  數字 |數字 []

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

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

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

removeCSS()

Promise Chrome 87 以上版本 &amp;leq;MV2 自 Chrome 91 版起已淘汰

chrome.tabs.removeCSS(
  tabId?: number,
  details: DeleteInjectionDetails,
  callback?: function,
)

已在 Manifest V3 中替換為 scripting.removeCSS。

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

參數

• tabId

  編號 選填

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

• 詳細資料

  DeleteInjectionDetails

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

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

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

sendMessage()

Promise

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

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

參數

• tabId

  數字

• 訊息

  不限

  要傳送的訊息。這則訊息應為 JSON 格式的物件。

• 選項

  物件 optional

  • documentId

    string optional

    Chrome 106 以上版本

    傳送訊息至由 documentId 識別的特定「文件」，而非該分頁中的所有影格。

  • frameId

    編號 選填

    傳送訊息至由 frameId 識別的特定頁框，而非該分頁中的所有影格。

• 回呼

  函式 選用

  Chrome 99 以上版本

  callback 參數如下所示：

  (response: any) => void

  • 回應

    不限

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

傳回

• 承諾<任何>

  Chrome 99 以上版本

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

sendRequest()

Promise &amp;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 以上版本

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

setZoom()

Promise

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

縮放指定分頁。

參數

• tabId

  編號 選填

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

• zoomFactor

  數字

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

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

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

setZoomSettings()

Promise

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

設定指定分頁的縮放設定，定義縮放變更的方式。當你瀏覽該分頁時，這些設定會重設為預設值。

參數

• tabId

  編號 選填

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

• zoomSettings

  ZoomSettings

  定義縮放變更的處理方式以及範圍。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

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

ungroup()

Promise Chrome 88 以上版本

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

從所屬的群組中移除一或多個分頁。如果任何群組沒有任何內容，就會刪除這些群組。

參數

• tabIds

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

  要從所屬群組移除的分頁 ID 或分頁 ID 清單。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

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

update()

Promise

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

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

參數

• tabId

  編號 選填

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

• updateProperties

  物件

  • 已啟用

    布林值 選填

    分頁是否應為使用中。不會影響是否聚焦視窗 (請參閱 windows.update)。

  • autoDiscardable

    布林值 選填

    Chrome 54 以上版本

    瀏覽器是否在資源較低時自動捨棄分頁。

  • 重要留言

    布林值 選填

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

  • 已設為靜音。

    布林值 選填

    Chrome 45 以上版本

    是否關閉分頁。

  • openerTabId

    編號 選填

    開啟此分頁的分頁 ID。如有指定，開啟器分頁必須與此分頁在同一個視窗中。

  • 已固定

    布林值 選填

    是否應固定分頁。

  • 已選取

    布林值 選填

    已淘汰

    請使用醒目顯示的部分。

    是否應選取分頁。

  • 網址

    string optional

    要導向分頁的網址。不支援 JavaScript 網址；請改用 scripting.executeScript。

• 回呼

  函式 選用

  callback 參數如下所示：

  (tab?: Tab) => void

  • 分頁

    Tab 鍵 選用

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

傳回

• Promise<Tab |未定義>

  Chrome 88 以上版本

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

活動

onActivated

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

在視窗中使用中的分頁變更時啟動。請注意，分頁的網址可能無法在此事件觸發時設定，但您可以監聽 onUpdated 事件，這樣就能收到設定網址時收到通知。

參數

• 回呼

  函式

  callback 參數如下所示：

  (activeInfo: object) => void

  • activeInfo

    物件

    • tabId

      數字

      生效的分頁 ID。

    • windowId

      數字

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

onActiveChanged

&amp;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

&amp;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

      布林值

      當分頁因上層視窗關閉而關閉時為 True。

    • windowId

      數字

      分頁關閉的視窗。

onReplaced

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

當分頁因預先算繪或即時而遭取代為其他分頁時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • addedTabId

    數字

  • removedTabId

    數字

onSelectionChanged

&amp;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

      string optional

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

    • groupId

      編號 選填

      Chrome 88 以上版本

      分頁的新群組。

    • mutedInfo

      MutedInfo 選用

      Chrome 46 以上版本

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

    • 已固定

      布林值 選填

      分頁的新固定狀態。

    • 狀態

      TabStatus 選用

      分頁的載入狀態。

    • title

      string optional

      Chrome 48 以上版本

      分頁的新標題。

    • 網址

      string optional

      分頁網址 (如有變更)。

  • 分頁

    Tab 鍵

onZoomChange

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

在分頁縮放時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

  (ZoomChangeInfo: object) => void

  • ZoomChangeInfo

    物件

    • newZoomFactor

      數字

    • oldZoomFactor

      數字

    • tabId

      數字

    • zoomSettings

      ZoomSettings