說明
使用 chrome.tabs API 與瀏覽器的分頁系統互動。您可以使用這個 API 在瀏覽器中建立、修改及重新排列分頁。
總覽
Tabs API 不僅提供操作和管理分頁的功能，還可偵測分頁的語言、拍攝螢幕截圖，以及與分頁的內容指令碼通訊。
權限
大多數功能都不需要任何權限。例如：建立新分頁、重新載入分頁、前往其他網址等。
開發人員在使用 Tabs API 時，應注意三項權限。
- 「分頁」權限
- 這項權限不會授予
chrome.tabs命名空間的存取權。相反地，它會授予擴充功能在tabs.Tab例項上針對四個敏感性屬性呼叫tabs.query()的功能：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"
});
}
});
取得目前的分頁
本範例說明擴充功能的服務工作者如何從目前聚焦的視窗 (如果沒有 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
分頁的靜音狀態，以及上次狀態變更的原因。
屬性
-
extensionId
string 選填
變更靜音狀態的額外資訊 ID。如果上次變更靜音狀態的原因並非擴充功能，則不會設定。
-
已設為靜音。
布林值
分頁是否設為靜音 (無法播放音訊)。即使分頁尚未播放或目前未播放音訊，也可能會靜音。等同於是否顯示「靜音」音訊指標。
-
reason
分頁靜音或取消靜音的原因。如果分頁的靜音狀態從未變更，則不會設定。
MutedInfoReason
導致靜音狀態變更的事件。
列舉
"user"
使用者輸入動作設定靜音狀態。
"capture"
開始擷取分頁，強制變更靜音狀態。
"extension"
使用 extensionId 欄位識別的擴充功能，可設定靜音狀態。
Tab
屬性
-
已啟用
布林值
分頁在其視窗中是否處於活動狀態。不一定代表視窗已聚焦。
-
audible
boolean 選填
Chrome 45 以上版本分頁在過去幾秒內是否發出聲響 (但如果已設為靜音，可能就不會聽到聲響)。等同於是否顯示「喇叭音訊」指標。
-
autoDiscardable
布林值
Chrome 54 以上版本在資源不足時，瀏覽器是否可以自動捨棄分頁。
-
已捨棄
布林值
Chrome 54 以上版本是否要捨棄分頁。已捨棄的分頁內容已從記憶體中卸載，但仍會顯示在分頁列中。下次啟用時，系統會重新載入內容。
-
favIconUrl
string 選填
分頁網站小圖示的網址。只有在擴充功能的資訊清單包含
"tabs"權限時，才會出現這項屬性。如果分頁正在載入，這可能也是空字串。 -
已凍結
布林值
待處理分頁是否已凍結。凍結的分頁無法執行任務，包括事件處理常式或計時器。它會顯示在分頁列中，內容會載入至記憶體。啟用後會解凍。
-
groupId
數字
Chrome 88 以上版本分頁所屬群組的 ID。
-
高度
號碼 選填
分頁的高度 (以像素為單位)。
-
重要留言
布林值
分頁是否醒目顯示。
-
id
號碼 選填
分頁的 ID。分頁 ID 在瀏覽器工作階段中是唯一的。在某些情況下，分頁可能不會指派 ID，例如使用
sessionsAPI 查詢外部分頁時，可能會出現工作階段 ID。您也可以將應用程式和 devtools 視窗的分頁 ID 設為chrome.tabs.TAB_ID_NONE。 -
無痕模式
布林值
分頁是否位於無痕式視窗中。
-
索引
數字
分頁在視窗中的索引，從零開始。
-
lastAccessed
數字
Chrome 121 以上版本上次存取分頁的時間，以 Epoch 紀元時間起算的毫秒數表示。
-
mutedInfo
MutedInfo 選填
Chrome 46 以上版本分頁的靜音狀態，以及上次狀態變更的原因。
-
openerTabId
號碼 選填
開啟這個分頁的分頁 ID (如果有的話)。只有在開啟者分頁仍存在時，系統才會提供這項屬性。
-
pendingUrl
string 選填
Chrome 79 以上版本分頁尚未提交前，要前往的網址。只有在擴充功能的資訊清單包含
"tabs"權限，且有待處理的導覽時，才會出現這項屬性。 -
已固定
布林值
分頁是否已固定。
-
已選取
布林值
已淘汰請使用
tabs.Tab.highlighted。是否已選取分頁標籤。
-
sessionId
string 選填
工作階段 ID，用於從
sessionsAPI 取得的唯一分頁識別資訊。 -
狀態
TabStatus 選填
分頁的載入狀態。
-
title
string 選填
分頁標題。只有在擴充功能的資訊清單包含
"tabs"權限時，才會出現這項屬性。 -
網址
string 選填
分頁主畫面的上次提交網址。只有在擴充功能的資訊清單包含
"tabs"權限時，才會出現這項屬性，如果分頁尚未提交，則可能會是空白字串。另請參閱Tab.pendingUrl。 -
寬度
號碼 選填
分頁的寬度，以像素為單位。
-
windowId
數字
包含分頁的視窗 ID。
TabStatus
分頁的載入狀態。
列舉
"unloaded"
「loading」
"complete"
WindowType
視窗類型。
列舉
"normal"
"popup"
"panel"
"app"
"devtools"
ZoomSettings
定義如何處理分頁中的縮放變更，以及在哪個範圍內處理。
屬性
-
defaultZoomFactor
號碼 選填
Chrome 43 以上版本在呼叫 tabs.getZoomSettings 時，用於傳回目前分頁的預設縮放等級。
-
模式
定義如何處理縮放變更，也就是哪個實體負責處理頁面的實際縮放作業；預設為
automatic。 -
範圍
定義是否要讓變焦變更持續存在於網頁原始位置，或是只在這個分頁中生效；在
automatic模式下，預設為per-origin，否則為per-tab。
ZoomSettingsMode
定義如何處理縮放變更，也就是哪個實體負責處理頁面的實際縮放作業；預設為 automatic。
列舉
「自動」
瀏覽器會自動處理 Zoom 變更。
「手動」
會覆寫自動處理縮放變更的功能。onZoomChange 事件仍會調度，而擴充功能必須負責監聽此事件，並手動調整頁面大小。這個模式不支援 per-origin 縮放功能，因此會忽略 scope 縮放設定，並假設為 per-tab。
「disabled」
停用分頁中的所有縮放功能。分頁會還原為預設的縮放等級，並忽略所有嘗試的縮放變更。
ZoomSettingsScope
定義是否要讓變焦變更持續存在於網頁原始位置，或是只在這個分頁中生效；在 automatic 模式下，預設為 per-origin，否則為 per-tab。
列舉
「per-origin」
縮放變更會保留在縮放頁面的來源，也就是說，導向至該來源的所有其他分頁也會縮放。此外，per-origin 縮放變更會隨來源儲存，也就是說，當您前往同一來源的其他頁面時，這些頁面都會縮放至相同的縮放係數。per-origin 範圍僅適用於 automatic 模式。
「每個分頁」
縮放變更只會套用至這個分頁，其他分頁的縮放變更不會影響這個分頁的縮放設定。此外，瀏覽時會重設 per-tab 縮放變更；瀏覽分頁時，系統一律會載入含有 per-origin 縮放係數的網頁。
屬性
MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND
每秒可呼叫 captureVisibleTab 的次數上限。captureVisibleTab 的成本高昂，因此不應過度呼叫。
值
2
TAB_ID_NONE
代表瀏覽器分頁不存在的 ID。
值
-1
TAB_INDEX_NONE
代表 tab_strip 中沒有分頁索引的索引。
值
-1
方法
captureVisibleTab()
chrome.tabs.captureVisibleTab(
windowId?: number,
options?: ImageDetails,
callback?: function,
)
擷取指定視窗中目前有效分頁的可視區域。如要呼叫這個方法，擴充功能必須具備 <all_urls> 權限或 activeTab 權限。除了擴充功能可正常存取的網站之外，這個方法還可讓擴充功能擷取原本受限制的私密網站，包括 chrome:-scheme 頁面、其他擴充功能的頁面，以及 data: 網址。這些私密網站只能透過 activeTab 權限擷取。只有在擴充功能獲得檔案存取權時，才能擷取檔案網址。
參數
-
windowId
號碼 選填
目標視窗。預設為目前視窗。
-
選項
ImageDetails 選填
-
回呼
函式 選填
callback參數如下所示：(dataUrl: string) => void
-
dataUrl
字串
資料網址，可對擷取的分頁可見區域編碼成圖片。可指派至 HTML
img元素的 'src' 屬性，用於顯示。
-
傳回
-
Promise<string>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
connect()
chrome.tabs.connect(
tabId: number,
connectInfo?: object,
)
連結至指定分頁中的內容腳本。在目前擴充功能的指定分頁中執行的每個內容指令碼中，都會觸發 runtime.onConnect 事件。詳情請參閱「內容指令碼訊息」。
參數
-
tabId
數字
-
connectInfo
物件 選填
傳回
-
可用於與在指定分頁中執行的內容指令碼通訊的通訊埠。如果分頁關閉或不存在，就會觸發端口的
runtime.Port事件。
create()
chrome.tabs.create(
createProperties: object,
callback?: function,
)
建立新分頁。
參數
-
createProperties
物件
-
已啟用
boolean 選填
分頁是否應成為視窗中的使用中分頁。不會影響視窗是否聚焦 (請參閱
windows.update)。預設為true。 -
索引
號碼 選填
分頁在視窗中應有的顯示位置。提供的值會限制在零和視窗中分頁數之間。
-
openerTabId
號碼 選填
開啟這個分頁的分頁 ID。如果指定了，開啟者分頁必須與新建立的分頁位於同一個視窗中。
-
已固定
boolean 選填
是否要固定分頁。預設值為
false -
已選取
boolean 選填
已淘汰請使用「主動語態」。
分頁是否應成為視窗中的選取分頁。預設值為
true -
網址
string 選填
初始導向分頁的網址。完整網址必須包含配置 (即'http://www.google.com'，而非 'www.google.com')。相對網址是相對於擴充功能內的目前網頁。預設為新分頁。
-
windowId
號碼 選填
建立新分頁的視窗。預設為目前視窗。
-
-
回呼
函式 選填
callback參數如下所示：(tab: Tab) => void
-
分頁
已建立的分頁。
-
傳回
-
Promise<Tab>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
detectLanguage()
chrome.tabs.detectLanguage(
tabId?: number,
callback?: function,
)
偵測分頁中內容的主要語言。
參數
-
tabId
號碼 選填
預設為目前視窗的有效分頁。
-
回呼
函式 選填
callback參數如下所示：(language: string) => void
-
language
字串
ISO 語言代碼，例如
en或fr。如需此方法支援的完整語言清單，請參閱 kLanguageInfoTable。系統會檢查第二到第四欄，並傳回第一個非空值，但簡體中文會傳回zh-CN。如果是不明/未定義的語言，系統會傳回und。
-
傳回
-
Promise<string>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
discard()
chrome.tabs.discard(
tabId?: number,
callback?: function,
)
從記憶體中捨棄分頁。已捨棄的分頁仍會顯示在分頁列中，並會在啟用時重新載入。
參數
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
duplicate()
chrome.tabs.duplicate(
tabId: number,
callback?: function,
)
複製分頁。
參數
-
tabId
數字
要複製的分頁 ID。
-
回呼
函式 選填
callback參數如下所示：(tab?: Tab) => void
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
executeScript()
chrome.tabs.executeScript(
tabId?: number,
details: InjectDetails,
callback?: function,
)
已在 Manifest V3 中由 scripting.executeScript 取代。
將 JavaScript 程式碼插入網頁。詳情請參閱內容指令碼文件中的「程式輔助插入」一節。
參數
-
tabId
號碼 選填
要執行指令碼的分頁 ID；預設為目前視窗的使用中分頁。
-
詳細資料
要執行的指令碼詳細資料。必須設定程式碼或檔案資源，但兩者不得同時設定。
-
回呼
函式 選填
callback參數如下所示：(result?: any[]) => void
-
結果
any[] 選填
每個插入影格中的指令碼結果。
-
傳回
-
Promise<any[] | undefined>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
get()
chrome.tabs.get(
tabId: number,
callback?: function,
)
擷取指定分頁的詳細資料。
傳回
-
Promise<Tab>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
getAllInWindow()
chrome.tabs.getAllInWindow(
windowId?: number,
callback?: function,
)
請使用 tabs.query {windowId: windowId}。
取得指定視窗中所有分頁的詳細資料。
傳回
-
Promise<Tab[]>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
getCurrent()
chrome.tabs.getCurrent(
callback?: function,
)
取得這個指令碼呼叫的來源分頁。如果從非分頁內容 (例如背景頁面或彈出式檢視畫面) 呼叫，則會傳回 undefined。
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
getSelected()
chrome.tabs.getSelected(
windowId?: number,
callback?: function,
)
請使用 tabs.query {active: true}。
取得指定視窗中所選的分頁。
傳回
-
Promise<Tab>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
getZoom()
chrome.tabs.getZoom(
tabId?: number,
callback?: function,
)
取得指定分頁目前的縮放比例。
參數
-
tabId
號碼 選填
要取得目前縮放係數的分頁 ID；預設為目前視窗的有效分頁。
-
回呼
函式 選填
callback參數如下所示：(zoomFactor: number) => void
-
zoomFactor
數字
分頁目前的縮放係數。
-
傳回
-
Promise<number>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
getZoomSettings()
chrome.tabs.getZoomSettings(
tabId?: number,
callback?: function,
)
取得指定分頁目前的縮放設定。
參數
-
tabId
號碼 選填
要取得目前縮放設定的分頁 ID；預設為目前視窗的有效分頁。
-
回呼
函式 選填
callback參數如下所示：(zoomSettings: ZoomSettings) => void
-
zoomSettings
分頁目前的縮放設定。
-
傳回
-
Promise<ZoomSettings>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
goBack()
chrome.tabs.goBack(
tabId?: number,
callback?: function,
)
返回上一頁 (如有)。
參數
-
tabId
號碼 選填
要返回的分頁 ID，預設為目前視窗中選取的分頁。
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
goForward()
chrome.tabs.goForward(
tabId?: number,
callback?: function,
)
前往下一頁 (如有)。
參數
-
tabId
號碼 選填
要前往的分頁 ID，預設為目前視窗中所選的分頁。
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
group()
chrome.tabs.group(
options: object,
callback?: function,
)
將一或多個分頁新增至指定群組，如果未指定群組，則將指定的分頁新增至新建立的群組。
參數
-
選項
物件
-
createProperties
物件 選填
建立群組的設定。如果已指定 groupId，則無法使用。
-
windowId
號碼 選填
新群組的視窗。預設為目前的視窗。
-
-
groupId
號碼 選填
要加入分頁的群組 ID。如果未指定，系統會建立新群組。
-
tabIds
數字 | [數字, ...數字 []]
要加入至指定群組的分頁 ID 或分頁 ID 清單。
-
-
回呼
函式 選填
callback參數如下所示：(groupId: number) => void
-
groupId
數字
分頁加入的群組 ID。
-
傳回
-
Promise<number>
承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
highlight()
chrome.tabs.highlight(
highlightInfo: object,
callback?: function,
)
醒目顯示指定的分頁，並將焦點放在群組的第一個分頁。如果指定的分頁目前處於活動狀態，則不會顯示任何動作。
參數
-
highlightInfo
物件
-
分頁
數字 | 數字陣列
要醒目顯示的一或多個分頁索引。
-
windowId
號碼 選填
包含分頁的視窗。
-
-
回呼
函式 選填
callback參數如下所示：(window: Window) => void
-
窗戶
包含醒目顯示分頁的視窗詳細資料。
-
傳回
-
Promise<windows.Window>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
insertCSS()
chrome.tabs.insertCSS(
tabId?: number,
details: InjectDetails,
callback?: function,
)
已在 Manifest V3 中由 scripting.insertCSS 取代。
將 CSS 插入頁面。您可以使用 scripting.removeCSS 移除透過這個方法插入的樣式。詳情請參閱內容指令碼文件中的「程式輔助插入」一節。
參數
-
tabId
號碼 選填
要插入 CSS 的分頁 ID；預設為目前視窗的有效分頁。
-
詳細資料
要插入的 CSS 文字詳細資料。必須設定程式碼或檔案資源，但兩者不得同時設定。
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
move()
chrome.tabs.move(
tabIds: number | number[],
moveProperties: object,
callback?: function,
)
將一個或多個分頁移至視窗中的新位置，或移至新視窗。請注意，分頁只能在一般 (window.type === "normal") 視窗之間移動。
參數
query()
chrome.tabs.query(
queryInfo: object,
callback?: function,
)
取得具有指定屬性的所有分頁，如果未指定屬性，則取得所有分頁。
參數
-
queryInfo
物件
-
已啟用
boolean 選填
分頁在其視窗中是否處於活動狀態。
-
audible
boolean 選填
Chrome 45 以上版本分頁是否可聽見。
-
autoDiscardable
boolean 選填
Chrome 54 以上版本在資源不足時，瀏覽器是否可以自動捨棄分頁。
-
currentWindow
boolean 選填
分頁是否位於目前視窗中。
-
已捨棄
boolean 選填
Chrome 54 以上版本是否要捨棄分頁。已捨棄的分頁內容已從記憶體中卸載，但仍會顯示在分頁列中。下次啟用時，系統會重新載入內容。
-
已凍結
boolean 選填
待處理分頁是否已凍結。凍結的分頁無法執行任務，包括事件處理常式或計時器。它會顯示在分頁列中，內容會載入至記憶體。啟用後會解凍。
-
groupId
號碼 選填
Chrome 88 以上版本分頁所在群組的 ID，或未分組分頁的
tabGroups.TAB_GROUP_ID_NONE。 -
重要留言
boolean 選填
分頁是否醒目顯示。
-
索引
號碼 選填
分頁在視窗中的位置。
-
lastFocusedWindow
boolean 選填
分頁是否位於最後一個焦點視窗中。
-
已設為靜音。
boolean 選填
Chrome 45 以上版本分頁是否靜音。
-
已固定
boolean 選填
分頁是否已固定。
-
狀態
TabStatus 選填
分頁載入狀態。
-
title
string 選填
將網頁標題與模式比對。如果擴充功能沒有
"tabs"權限，系統會忽略這項屬性。 -
網址
string | string[] 選填
將分頁與一或多個網址模式比對。片段 ID 不相符。如果擴充功能沒有
"tabs"權限，系統會忽略這項屬性。 -
windowId
號碼 選填
父項視窗的 ID，或目前視窗的
windows.WINDOW_ID_CURRENT。 -
windowType
WindowType 選填
分頁所在的視窗類型。
-
-
回呼
函式 選填
callback參數如下所示：(result: Tab[]) => void
-
結果
分頁[]
-
傳回
-
Promise<Tab[]>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
reload()
chrome.tabs.reload(
tabId?: number,
reloadProperties?: object,
callback?: function,
)
重新載入分頁。
參數
-
tabId
號碼 選填
要重新載入的分頁 ID；預設為目前視窗中所選的分頁。
-
reloadProperties
物件 選填
-
bypassCache
boolean 選填
是否略過本機快取。預設值為
false。
-
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
remove()
chrome.tabs.remove(
tabIds: number | number[],
callback?: function,
)
關閉一或多個分頁。
參數
-
tabIds
數字 | 數字陣列
要關閉的分頁 ID 或分頁 ID 清單。
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
removeCSS()
chrome.tabs.removeCSS(
tabId?: number,
details: DeleteInjectionDetails,
callback?: function,
)
已在 Manifest V3 中由 scripting.removeCSS 取代。
從網頁 CSS 中移除先前透過呼叫 scripting.insertCSS 注入的內容。
參數
-
tabId
號碼 選填
要移除 CSS 的分頁 ID；預設為目前視窗的有效分頁。
-
要移除的 CSS 文字詳細資料。必須設定程式碼或檔案資源，但兩者不得同時設定。
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
sendMessage()
chrome.tabs.sendMessage(
tabId: number,
message: any,
options?: object,
callback?: function,
)
將單一訊息傳送至指定分頁中的內容指令碼，並在傳回回應時執行選用的回呼。在目前擴充功能的指定分頁中執行的每個內容指令碼中，會觸發 runtime.onMessage 事件。
參數
-
tabId
數字
-
訊息
不限
要傳送的訊息。此訊息應為可 JSON 化物件。
-
選項
物件 選填
-
回呼
函式 選填
Chrome 99 以上版本callback參數如下所示：(response: any) => void
-
回應
不限
訊息處理常式傳送的 JSON 回應物件。如果在連線至指定分頁時發生錯誤，系統會呼叫回呼，但不帶引數，並將
runtime.lastError設為錯誤訊息。
-
傳回
-
Promise<any>
Chrome 99 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
sendRequest()
chrome.tabs.sendRequest(
tabId: number,
request: any,
callback?: function,
)
請使用 runtime.sendMessage。
將單一要求傳送至指定分頁中的內容指令碼，並在傳回回應時執行選用的回呼。在目前擴充功能的指定分頁中執行的每個內容指令碼中，會觸發 extension.onRequest 事件。
參數
-
tabId
數字
-
申請。
不限
-
回呼
函式 選填
Chrome 99 以上版本callback參數如下所示：(response: any) => void
-
回應
不限
要求的處理常式傳送的 JSON 回應物件。如果在連線至指定分頁時發生錯誤，系統會呼叫回呼，但不帶引數，並將
runtime.lastError設為錯誤訊息。
-
傳回
-
Promise<any>
Chrome 99 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
setZoom()
chrome.tabs.setZoom(
tabId?: number,
zoomFactor: number,
callback?: function,
)
縮放指定分頁。
參數
-
tabId
號碼 選填
要縮放的分頁 ID，預設為目前視窗的有效分頁。
-
zoomFactor
數字
新的縮放比例。值為
0會將分頁設為目前的預設縮放比例。值大於0時，會指定分頁的縮放比例 (可能不是預設值)。 -
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
setZoomSettings()
chrome.tabs.setZoomSettings(
tabId?: number,
zoomSettings: ZoomSettings,
callback?: function,
)
為指定分頁設定縮放設定，定義如何處理縮放變更。在瀏覽分頁時，這些設定會重設為預設值。
參數
-
tabId
號碼 選填
要變更縮放設定的分頁 ID；預設為目前視窗的有效分頁。
-
zoomSettings
定義如何處理縮放變更，以及縮放變更的範圍。
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
ungroup()
chrome.tabs.ungroup(
tabIds: number | [number, ...number[]],
callback?: function,
)
從各自的群組中移除一或多個分頁。如果任何群組變成空白，系統就會刪除該群組。
參數
-
tabIds
數字 | [數字, ...數字 []]
要從各自群組中移除的分頁 ID 或分頁 ID 清單。
-
回呼
函式 選填
callback參數如下所示：() => void
傳回
-
Promise<void>
承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
update()
chrome.tabs.update(
tabId?: number,
updateProperties: object,
callback?: function,
)
修改分頁的屬性。系統不會修改 updateProperties 中未指定的屬性。
參數
-
tabId
號碼 選填
預設為目前視窗中選取的分頁。
-
updateProperties
物件
-
已啟用
boolean 選填
分頁是否應處於啟用狀態。不會影響視窗是否聚焦 (請參閱
windows.update)。 -
autoDiscardable
boolean 選填
Chrome 54 以上版本在資源不足時，瀏覽器是否應自動捨棄分頁。
-
重要留言
boolean 選填
在目前的選取範圍中新增或移除分頁。
-
已設為靜音。
boolean 選填
Chrome 45 以上版本是否要將分頁設為靜音。
-
openerTabId
號碼 選填
開啟這個分頁的分頁 ID。如果指定了開啟分頁，則開啟分頁必須與這個分頁位於同一個視窗中。
-
已固定
boolean 選填
是否應將分頁釘選。
-
已選取
boolean 選填
已淘汰請使用醒目顯示。
是否應選取分頁。
-
網址
string 選填
要導向至分頁的網址。系統不支援 JavaScript 網址，請改用
scripting.executeScript。
-
-
回呼
函式 選填
callback參數如下所示：(tab?: Tab) => void
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
活動
onActivated
chrome.tabs.onActivated.addListener(
callback: function,
)
當視窗中的使用中分頁變更時觸發。請注意，在這個事件觸發時，分頁的網址可能尚未設定，但您可以監聽 onUpdated 事件，以便在設定網址時收到通知。
參數
-
回呼
函式
callback參數如下所示：(activeInfo: object) => void
-
activeInfo
物件
-
tabId
數字
已啟用的分頁 ID。
-
windowId
數字
已變更的活動分頁所在視窗 ID。
-
-
onActiveChanged
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 事件，以便在設定網址或將分頁加入分頁群組時收到通知。
onDetached
chrome.tabs.onDetached.addListener(
callback: function,
)
當分頁從視窗中卸離時觸發，例如在不同視窗之間移動分頁。
參數
-
回呼
函式
callback參數如下所示：(tabId: number, detachInfo: object) => void
-
tabId
數字
-
detachInfo
物件
-
oldPosition
數字
-
oldWindowId
數字
-
-
onHighlightChanged
chrome.tabs.onHighlightChanged.addListener(
callback: function,
)
請使用 tabs.onHighlighted。
當視窗中醒目顯示或選取的分頁變更時觸發。
參數
-
回呼
函式
callback參數如下所示：(selectInfo: object) => void
-
selectInfo
物件
-
tabIds
number[]
視窗中所有醒目顯示的分頁。
-
windowId
數字
分頁變更的視窗。
-
-
onHighlighted
chrome.tabs.onHighlighted.addListener(
callback: function,
)
當視窗中醒目顯示或選取的分頁變更時觸發。
參數
-
回呼
函式
callback參數如下所示：(highlightInfo: object) => void
-
highlightInfo
物件
-
tabIds
number[]
視窗中所有醒目顯示的分頁。
-
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
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
boolean 選填
Chrome 45 以上版本分頁的新可聽狀態。
-
autoDiscardable
boolean 選填
Chrome 54 以上版本分頁的新自動棄用狀態。
-
已捨棄
boolean 選填
Chrome 54 以上版本分頁的新捨棄狀態。
-
favIconUrl
string 選填
分頁的新網站小圖示網址。
-
已凍結
boolean 選填
待處理分頁的新凍結狀態。
-
groupId
號碼 選填
Chrome 88 以上版本分頁的新群組。
-
mutedInfo
MutedInfo 選填
Chrome 46 以上版本分頁的新靜音狀態和變更原因。
-
已固定
boolean 選填
分頁的新固定狀態。
-
狀態
TabStatus 選填
分頁的載入狀態。
-
title
string 選填
Chrome 48 以上版本分頁的新標題。
-
網址
string 選填
分頁的網址 (如果已變更)。
-
-
分頁
-
onZoomChange
chrome.tabs.onZoomChange.addListener(
callback: function,
)
在放大分頁時觸發。
參數
-
回呼
函式
callback參數如下所示：(ZoomChangeInfo: object) => void
-
ZoomChangeInfo
物件
-
newZoomFactor
數字
-
oldZoomFactor
數字
-
tabId
數字
-
zoomSettings
-
-