說明
使用 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
該分頁標籤的已靜音狀態,以及上次狀態變更的原因。
屬性
-
extensionId
字串 選用
變更靜音狀態的擴充功能 ID。如果擴充功能並非上次變更靜音狀態的原因,則未設定。
-
已設為靜音。
boolean
分頁是否設為靜音 (禁止播放音效)。分頁即使未播放或目前未播放音效,也可能會設為靜音。等同於是否顯示「靜音」音訊指標。
-
原因
分頁設為靜音或取消靜音的原因。如果分頁的靜音狀態尚未變更,則未設定。
MutedInfoReason
導致靜音狀態變更的事件。
列舉
"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
分頁的載入狀態。
列舉
WindowType
視窗類型。
列舉
"devtools"
ZoomSettings
定義標籤中縮放變更的方式和範圍。
屬性
-
defaultZoomFactor
數字 選填
Chrome 43 以上版本用於在呼叫 tab.getZoomSettings 時,傳回目前分頁的預設縮放等級。
-
模式
定義縮放變更的方式,也就是由哪個實體負責網頁實際縮放比例;預設為
automatic
。 -
範圍
定義縮放比例變更是否要保留網頁來源,或只在這個分頁中生效;在
automatic
模式中預設為per-origin
,其他情況則預設為per-tab
。
ZoomSettingsMode
定義縮放變更的方式,也就是由哪個實體負責網頁實際縮放比例;預設為 automatic
。
列舉
「自動」
瀏覽器會自動處理縮放變更。
"manual"
覆寫縮放變更的自動處理方式。系統仍會分派 onZoomChange
事件,擴充功能有責任監聽這個事件,並手動縮放網頁。這個模式不支援 per-origin
縮放功能,因此會忽略 scope
縮放設定,並假設為 per-tab
。
"disabled"
停用分頁中的所有縮放功能。分頁會還原為預設的縮放等級,並忽略所有嘗試變更的縮放比例。
ZoomSettingsScope
定義縮放比例變更是否要保留網頁來源,或只在這個分頁中生效;在 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
每秒可呼叫 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: 配置網頁、其他擴充功能的網頁和資料:網址。如要擷取這些敏感網站,必須使用 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
物件選用
傳回
-
這個通訊埠可用來與指定分頁中執行的內容指令碼通訊。如果分頁關閉或不存在,系統會觸發通訊埠的
runtime.Port
事件。
create()
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()
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()
chrome.tabs.discard(
tabId?: number,
callback?: function,
)
捨棄記憶體中的分頁。捨棄的分頁仍會顯示在分頁列,並在啟用後重新載入。
參數
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
duplicate()
chrome.tabs.duplicate(
tabId: number,
callback?: function,
)
複製分頁。
參數
-
tabId
號碼
要複製的分頁 ID。
-
回呼
函式選用
callback
參數如下所示:(tab?: Tab) => void
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
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 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
get()
chrome.tabs.get(
tabId: number,
callback?: function,
)
擷取指定分頁的詳細資料。
傳回
-
Promise<Tab>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getAllInWindow()
chrome.tabs.getAllInWindow(
windowId?: number,
callback?: function,
)
請使用 tabs.query
{windowId: windowId}
。
取得指定視窗中所有分頁的詳細資料。
傳回
-
Promise<Tab[]>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getCurrent()
chrome.tabs.getCurrent(
callback?: function,
)
取得這個指令碼呼叫的來源分頁。如果從非分頁結構定義 (例如背景頁面或彈出式檢視畫面) 呼叫,則傳回 undefined
。
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getSelected()
chrome.tabs.getSelected(
windowId?: number,
callback?: function,
)
請使用 tabs.query
{active: true}
。
取得在指定視窗中選取的分頁。
傳回
-
Promise<Tab>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getZoom()
chrome.tabs.getZoom(
tabId?: number,
callback?: function,
)
取得指定分頁目前的縮放係數。
參數
-
tabId
數字 選填
用於取得目前縮放係數的分頁 ID;預設為目前視窗的使用中分頁。
-
回呼
函式選用
callback
參數如下所示:(zoomFactor: number) => void
-
zoomFactor
號碼
分頁目前的縮放比例係數。
-
傳回
-
Promise<number>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getZoomSettings()
chrome.tabs.getZoomSettings(
tabId?: number,
callback?: function,
)
取得指定分頁目前的縮放設定。
參數
-
tabId
數字 選填
用於取得目前縮放設定的標籤 ID;預設為目前視窗使用中的分頁。
-
回呼
函式選用
callback
參數如下所示:(zoomSettings: ZoomSettings) => void
-
zoomSettings
分頁目前的縮放設定。
-
傳回
-
Promise<ZoomSettings>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
goBack()
chrome.tabs.goBack(
tabId?: number,
callback?: function,
)
返回上一頁 (如果有的話)。
參數
-
tabId
數字 選填
分頁 ID 即可返回;預設為目前視窗選取的分頁。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
goForward()
chrome.tabs.goForward(
tabId?: number,
callback?: function,
)
返回下一頁 (如果有的話)。
參數
-
tabId
數字 選填
分頁 ID 即可繼續瀏覽;預設為目前視窗選取的分頁。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
group()
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()
chrome.tabs.highlight(
highlightInfo: object,
callback?: function,
)
醒目顯示指定的分頁,並將焦點移至第一個群組。如果指定的分頁目前處於啟用狀態,就不會顯示任何動作。
參數
-
highlightInfo
物件
-
分頁
數字 | number[]
要醒目顯示的一或多個分頁索引。
-
windowId
數字 選填
包含分頁的視窗。
-
-
回呼
函式選用
callback
參數如下所示:(window: Window) => void
-
窗戶
包含醒目顯示的視窗相關詳細資料。
-
傳回
-
Promise<windows.Window>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
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 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
move()
chrome.tabs.move(
tabIds: number | number[],
moveProperties: object,
callback?: function,
)
將一或多個分頁移至視窗內的新位置,或移到新視窗。請注意,您只能在一般視窗 (window.type === "normal") 視窗之間來回移動分頁。
參數
傳回
-
Chrome 88 以上版本
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
query()
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[] 選填
比對分頁與一或多個網址模式。片段 ID 不相符。如果擴充功能沒有
"tabs"
權限,系統會忽略這個屬性。 -
windowId
數字 選填
父項視窗的 ID,或目前視窗的
windows.WINDOW_ID_CURRENT
。 -
windowType
WindowType 選用
分頁所在的視窗類型。
-
-
回呼
函式選用
callback
參數如下所示:(result: Tab[]) => void
-
結果
Tab[]
-
傳回
-
Promise<Tab[]>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
reload()
chrome.tabs.reload(
tabId?: number,
reloadProperties?: object,
callback?: function,
)
重新載入分頁。
參數
-
tabId
數字 選填
要重新載入的分頁 ID;預設為目前視窗選取的分頁。
-
reloadProperties
物件選用
-
bypassCache
布林值 (選用)
是否略過本機快取。預設值為
false
。
-
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
remove()
chrome.tabs.remove(
tabIds: number | number[],
callback?: function,
)
關閉一或多個分頁。
參數
-
tabIds
數字 | number[]
要關閉的分頁 ID 或分頁 ID 清單。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
removeCSS()
chrome.tabs.removeCSS(
tabId?: number,
details: DeleteInjectionDetails,
callback?: function,
)
Manifest V3 已替換為 scripting.removeCSS
。
從先前透過呼叫 scripting.insertCSS
插入的頁面 CSS 移除這個 CSS。
參數
-
tabId
數字 選填
要移除 CSS 的分頁 ID;預設為目前視窗的使用中分頁。
-
要移除的 CSS 文字詳細資料。程式碼或檔案屬性必須設定,但兩者不能同時設定。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
sendMessage()
chrome.tabs.sendMessage(
tabId: number,
message: any,
options?: object,
callback?: function,
)
將單一訊息傳送至指定分頁的內容指令碼,並加入選用的回呼,在系統傳回回應時執行。針對目前擴充功能,在指定分頁中執行的每個內容指令碼都會觸發 runtime.onMessage
事件。
參數
-
tabId
號碼
-
訊息
不限
要傳送的訊息。這則訊息應為 JSON 可匯入的物件。
-
選項
物件選用
-
documentId
字串 選用
Chrome 106 以上版本將郵件傳送給
documentId
辨識的特定文件,而非分頁中的所有頁框。 -
frameId
數字 選填
-
-
回呼
函式選用
Chrome 99 以上版本callback
參數如下所示:(response: any) => void
-
則回應
不限
由訊息處理常式傳送的 JSON 回應物件。如果連線至指定分頁時發生錯誤,系統會在呼叫回呼時不使用引數,並將
runtime.lastError
設為錯誤訊息。
-
傳回
-
承諾<任何>
Chrome 99 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
sendRequest()
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()
chrome.tabs.setZoom(
tabId?: number,
zoomFactor: number,
callback?: function,
)
縮放特定分頁。
參數
-
tabId
數字 選填
要縮放的分頁 ID;預設為目前視窗使用中的分頁。
-
zoomFactor
號碼
新的縮放係數。
0
值可將分頁設為目前的預設縮放係數。大於0
的值會指定分頁標籤的縮放係數 (可能是非預設值)。 -
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setZoomSettings()
chrome.tabs.setZoomSettings(
tabId?: number,
zoomSettings: ZoomSettings,
callback?: function,
)
設定特定分頁的縮放設定,該標籤會定義縮放變更的處理方式。瀏覽分頁時,這些設定會重設為預設值。
參數
-
tabId
數字 選填
用於變更縮放設定的標籤 ID;預設為目前視窗的使用中分頁。
-
zoomSettings
定義縮放變更的方式和範圍。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
ungroup()
chrome.tabs.ungroup(
tabIds: number | [number, ...number[]],
callback?: function,
)
從各自群組中移除一或多個分頁。如有任何群組變成空白,就會刪除。
參數
-
tabIds
數字 | [數字, ...數字 []]
要從各群組中移除的分頁 ID 或分頁 ID 清單。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
update()
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
傳回
-
Promise<Tab | undefined>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
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
數字 []
視窗中所有醒目顯示的分頁。
-
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
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
-
-