说明
使用 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"
});
}
});
获取当前标签页
此示例演示了扩展程序的 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);
}
}
}
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(可选)
标签页被静音或取消静音的原因。如果标签页的静音状态从未更改过,则未设置。
MutedInfoReason
导致静音状态发生变化的事件。
枚举
"user"
用户输入操作用于设置静音状态。
"capture"
标签页捕获已开始,强制设为静音状态。
"extension"
由 extensionId 字段标识的扩展程序,用于设置静音状态。
Tab
属性
-
活跃
boolean
标签页是否在其窗口中处于活动状态。此窗口不一定表示窗口已聚焦。
-
audible
布尔值 选填
Chrome 45 及更高版本标签页在过去几秒内是否发出了声音(但如果静音,则可能听不到声音)。相当于是否显示“扬声器音频”指示符。
-
autoDiscardable
boolean
Chrome 54 及更高版本当资源不足时,浏览器是否会自动舍弃该标签页。
-
已舍弃
boolean
Chrome 54 及更高版本是否舍弃标签页。已舍弃的标签页是指内容已从内存中卸载,但仍显示在标签栏中的标签页。待下次激活时,系统会重新加载该会话的内容。
-
favIconUrl
字符串(可选)
标签页的网站图标的网址。仅当扩展程序的清单包含
"tabs"
权限时,此属性才会显示。如果正在加载标签页,该标识符也可能是空字符串。 -
groupId
number
Chrome 88 及更高版本标签页所属的群组的 ID。
-
高度
数字可选
标签页的高度(以像素为单位)。
-
突出显示
boolean
是否突出显示标签页。
-
id
数字可选
标签页的 ID。标签页 ID 在浏览器会话中是唯一的。在某些情况下,系统可能不会为标签页分配 ID;例如,在使用
sessions
API 查询外部标签页时,在这种情况下,系统可能会显示会话 ID。对于应用和开发者工具窗口,标签页 ID 也可设置为chrome.tabs.TAB_ID_NONE
。 -
无痕模式
boolean
标签页是否位于无痕式窗口中。
-
索引
number
标签页在其窗口中的索引(从零开始)。
-
lastAccessed
数字可选
Chrome 121 及更高版本上次访问标签页的时间,以自纪元以来的毫秒数表示。
-
mutedInfo
MutedInfo 可选
Chrome 46 及更高版本标签页的静音状态以及上次状态发生变化的原因。
-
openerTabId
数字可选
打开此标签页的标签页的 ID(如果有)。仅当“打开者”标签页仍然存在时,此属性才会显示。
-
pendingUrl
字符串(可选)
Chrome 79 及更高版本在标签页提交之前,标签页要导航到的网址。仅当扩展程序的清单包含
"tabs"
权限且存在待处理的导航时,此属性才会显示。 -
已置顶
boolean
是否固定标签页。
-
已选择
boolean
已废弃请使用
tabs.Tab.highlighted
。是否选中标签页。
-
sessionId
字符串(可选)
用于唯一标识从
sessions
API 获取的标签页的会话 ID。 -
status
TabStatus 可选
标签页的加载状态。
-
title
字符串(可选)
标签的标题。仅当扩展程序的清单包含
"tabs"
权限时,此属性才会显示。 -
网址
字符串(可选)
标签页主框架的最后提交网址。仅当扩展程序的清单包含
"tabs"
权限时,此属性才会显示;如果标签页尚未提交,此属性可能为空字符串。另请参阅Tab.pendingUrl
。 -
宽度
数字可选
标签页的宽度(以像素为单位)。
-
windowId
number
包含标签页的窗口的 ID。
TabStatus
标签页的加载状态。
枚举
"loading"
WindowType
窗口类型。
枚举
"normal"
"popup"
"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:-scheme 页面、其他扩展程序的页面,以及 data: 网址。此类敏感网站只能通过 ActiveTab 权限捕获。仅当获得扩展程序文件访问权限时,系统才会捕获文件网址。
参数
-
windowId
数字可选
目标窗口。默认值为当前窗口。
-
选项
ImageDetails 可选
-
callback
函数(可选)
callback
参数如下所示:(dataUrl: string) => void
-
dataUrl
string
对捕获的标签页的可见区域的图片进行编码的数据网址。可以分配给 HTML
img
元素的“src”属性,以供显示。
-
返回
-
Promise<string>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
connect()
chrome.tabs.connect(
tabId: number,
connectInfo?: object,
)
连接到指定标签页中的内容脚本。在当前扩展程序的指定标签页中运行的每个内容脚本中都会触发 runtime.onConnect
事件。如需了解详情,请参阅内容脚本消息传递。
参数
-
tabId
number
-
connectInfo
对象(可选)
返回
-
可用于与指定标签页中运行的内容脚本进行通信的端口。如果标签页关闭或不存在,则会触发相应充电桩的
runtime.Port
事件。
create()
chrome.tabs.create(
createProperties: object,
callback?: function,
)
创建新标签页。
参数
-
createProperties
对象
-
活跃
布尔值 选填
此标签页是否应成为窗口中的活动标签页。不影响窗口是否聚焦(请参阅
windows.update
)。默认值为true
。 -
索引
数字可选
标签页在窗口中应占据的位置。提供的值介于 0 和窗口中的制表符数量之间。
-
openerTabId
数字可选
打开此标签页的标签页的 ID。如果已指定,则打开方式标签页必须与新创建的标签页位于同一窗口中。
-
已置顶
布尔值 选填
是否应固定标签页。默认设置为
false
-
已选择
布尔值 选填
已废弃请使用 active。
相应标签页是否应成为窗口中的选定标签页。默认设置为
true
-
网址
字符串(可选)
标签页最初导航到的网址。完全限定网址必须包含架构(即“http://www.google.com”,而不是“www.google.com”)。相对网址是相对于扩展程序中当前页面的网址。默认为“新标签页”。
-
windowId
数字可选
要在其中创建新标签页的窗口。默认值为当前窗口。
-
-
callback
函数(可选)
callback
参数如下所示:(tab: Tab) => void
-
标签页
已创建的标签页。
-
返回
-
Promise<Tab>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
detectLanguage()
chrome.tabs.detectLanguage(
tabId?: number,
callback?: function,
)
检测标签页中内容的主要语言。
参数
-
tabId
数字可选
默认设置为当前窗口的活动标签页。
-
callback
函数(可选)
callback
参数如下所示:(language: string) => void
-
language
string
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
number
要复制的标签页的 ID。
-
callback
函数(可选)
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
函数(可选)
callback
参数如下所示:(result?: any[]) => void
-
结果
any[] 可选属性
每个注入帧中的脚本结果。
-
返回
-
承诺<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
函数(可选)
callback
参数如下所示:(zoomFactor: number) => void
-
zoomFactor
number
标签页的当前缩放比例。
-
返回
-
Promise<数字>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getZoomSettings()
chrome.tabs.getZoomSettings(
tabId?: number,
callback?: function,
)
获取指定标签页的当前缩放设置。
参数
-
tabId
数字可选
要获取当前缩放设置的标签页 ID;默认为当前窗口的活动标签页。
-
callback
函数(可选)
callback
参数如下所示:(zoomSettings: ZoomSettings) => void
-
zoomSettings
标签页的当前缩放设置。
-
返回
-
Promise<ZoomSettings>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
goBack()
chrome.tabs.goBack(
tabId?: number,
callback?: function,
)
返回到上一页(如果有)。
参数
-
tabId
数字可选
要返回查看的标签页的 ID;默认为当前窗口的所选标签页。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
goForward()
chrome.tabs.goForward(
tabId?: number,
callback?: function,
)
跳转到下一页(如果有)。
参数
-
tabId
数字可选
要向前导航的标签页的 ID;默认为当前窗口的所选标签页。
-
callback
函数(可选)
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
函数(可选)
callback
参数如下所示:(groupId: number) => void
-
groupId
number
添加了标签页的群组的 ID。
-
返回
-
Promise<数字>
只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
highlight()
chrome.tabs.highlight(
highlightInfo: object,
callback?: function,
)
突出显示给定标签页,并将焦点置于组的第一个标签页上。如果指定的标签页当前处于活动状态,这个选项看起来不会执行任何操作。
参数
-
highlightInfo
对象
-
标签页
数字 | 数字 []
要突出显示的一个或多个标签页索引。
-
windowId
数字可选
包含标签页的窗口。
-
-
callback
函数(可选)
callback
参数如下所示:(window: Window) => void
-
窗口
包含突出显示标签页的窗口的相关详细信息。
-
返回
-
Promise<windows.Window>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
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
move()
chrome.tabs.move(
tabIds: number | number[],
moveProperties: object,
callback?: function,
)
将一个或多个标签页移至其窗口中的新位置,或移至新窗口。请注意,只能将标签页移入或移出普通 (window.type === "normal") 窗口。
参数
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[] 可选
将标签页与一个或多个网址格式进行匹配。fragment 标识符不匹配。如果扩展程序没有
"tabs"
权限,系统会忽略此属性。 -
windowId
数字可选
父窗口的 ID,或
windows.WINDOW_ID_CURRENT
(对应于当前窗口)。 -
windowType
WindowType(可选)
标签页所在的窗口类型。
-
-
callback
函数(可选)
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
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
remove()
chrome.tabs.remove(
tabIds: number | number[],
callback?: function,
)
关闭一个或多个标签页。
参数
-
tabIds
数字 | 数字 []
要关闭的标签页 ID 或标签页 ID 列表。
-
callback
函数(可选)
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 中移除。
参数
-
tabId
数字可选
要从中移除 CSS 的标签页的 ID;默认为当前窗口的活动标签页。
-
要移除的 CSS 文本的详细信息。必须设置代码或文件属性,但不能同时设置这两者。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
sendMessage()
chrome.tabs.sendMessage(
tabId: number,
message: any,
options?: object,
callback?: function,
)
向指定标签页中的内容脚本发送一条消息,其中包含在发回响应时运行的可选回调函数。在当前扩展程序的指定标签页中运行的每个内容脚本中都会触发 runtime.onMessage
事件。
参数
-
tabId
number
-
消息
任意
要发送的消息。此消息应为 JSON 可映射的对象。
-
选项
对象(可选)
-
callback
函数(可选)
Chrome 99 及更高版本callback
参数如下所示:(response: any) => void
-
条回复
任意
消息的处理程序发送的 JSON 响应对象。如果在连接到指定标签页时出错,系统将在不使用任何参数的情况下调用该回调函数,并将
runtime.lastError
设置为错误消息。
-
返回
-
承诺<any>
Chrome 99 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
sendRequest()
chrome.tabs.sendRequest(
tabId: number,
request: any,
callback?: function,
)
请使用 runtime.sendMessage
。
向指定标签页中的内容脚本发送单个请求,并在发回响应时运行可选的回调。在当前扩展程序的指定标签页中运行的每个内容脚本中都会触发 extension.onRequest
事件。
参数
-
tabId
number
-
request
任意
-
callback
函数(可选)
Chrome 99 及更高版本callback
参数如下所示:(response: any) => void
-
条回复
任意
请求的处理程序发送的 JSON 响应对象。如果在连接到指定标签页时出错,系统将在不使用任何参数的情况下调用该回调函数,并将
runtime.lastError
设置为错误消息。
-
返回
-
承诺<any>
Chrome 99 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setZoom()
chrome.tabs.setZoom(
tabId?: number,
zoomFactor: number,
callback?: function,
)
缩放指定的标签页。
参数
-
tabId
数字可选
要缩放的标签页的 ID;默认为当前窗口的活动标签页。
-
zoomFactor
number
新的缩放比例。值为
0
可将标签页设置为其当前的默认缩放比例。大于0
的值会为标签页指定(可能是非默认)缩放比例。 -
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setZoomSettings()
chrome.tabs.setZoomSettings(
tabId?: number,
zoomSettings: ZoomSettings,
callback?: function,
)
用于设定指定标签的缩放设置,从而指定处理缩放更改的方式。在浏览该标签页时,这些设置会重置为默认值。
参数
-
tabId
数字可选
要更改缩放设置的标签页 ID,默认为当前窗口的活动标签页。
-
zoomSettings
定义如何处理缩放更改以及在何种范围内处理缩放更改。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
ungroup()
chrome.tabs.ungroup(
tabIds: number | [number, ...number[]],
callback?: function,
)
从对应的分组中移除一个或多个标签页。如果有任何群组变为空白,系统会将其删除。
参数
-
tabIds
数字 | [数字, ...数字 []]
要从相应分组中移除的标签页 ID 或标签页 ID 列表。
-
callback
函数(可选)
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
函数(可选)
callback
参数如下所示:(tab?: Tab) => void
返回
-
Promise<Tab | undefined>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onActivated
chrome.tabs.onActivated.addListener(
callback: function,
)
在窗口中的活动标签页发生变化时触发。请注意,在此事件触发时可能未设置标签页的网址,但您可以监听 onUpdated 事件,以便在设置网址时收到通知。
参数
-
callback
功能
callback
参数如下所示:(activeInfo: object) => void
-
activeInfo
对象
-
tabId
number
已激活的标签页的 ID。
-
windowId
number
在其中更改活动标签页的窗口的 ID。
-
-
onActiveChanged
chrome.tabs.onActiveChanged.addListener(
callback: function,
)
请使用 tabs.onActivated
。
在窗口中的所选标签页发生变化时触发。请注意,在此事件触发时可能未设置标签页的网址,但您可以监听 tabs.onUpdated
事件,以便在设置网址时收到通知。
参数
-
callback
功能
callback
参数如下所示:(tabId: number, selectInfo: object) => void
-
tabId
number
-
selectInfo
对象
-
windowId
number
所选标签页在其中发生更改的窗口的 ID。
-
-
onAttached
chrome.tabs.onAttached.addListener(
callback: function,
)
当标签页附加到窗口时触发;例如,由于标签页在窗口之间移动。
参数
-
callback
功能
callback
参数如下所示:(tabId: number, attachInfo: object) => void
-
tabId
number
-
attachInfo
对象
-
newPosition
number
-
newWindowId
number
-
-
onCreated
chrome.tabs.onCreated.addListener(
callback: function,
)
创建标签页时触发。请注意,在触发此事件时,可能尚未设置标签页的网址和标签页分组成员资格,但您可以监听 onUpdated 事件,以便在设置网址或标签页被添加到标签页分组时收到通知。
onDetached
chrome.tabs.onDetached.addListener(
callback: function,
)
当标签页与窗口分离时触发;例如,由于标签页在窗口之间移动。
参数
-
callback
功能
callback
参数如下所示:(tabId: number, detachInfo: object) => void
-
tabId
number
-
detachInfo
对象
-
oldPosition
number
-
oldWindowId
number
-
-
onHighlightChanged
chrome.tabs.onHighlightChanged.addListener(
callback: function,
)
请使用 tabs.onHighlighted
。
在窗口中突出显示或选中的标签页发生变化时触发。
参数
-
callback
功能
callback
参数如下所示:(selectInfo: object) => void
-
selectInfo
对象
-
tabIds
数值 []
窗口中所有突出显示的标签页。
-
windowId
number
标签页发生更改的窗口。
-
-
onHighlighted
chrome.tabs.onHighlighted.addListener(
callback: function,
)
在窗口中突出显示或选中的标签页发生变化时触发。
参数
-
callback
功能
callback
参数如下所示:(highlightInfo: object) => void
-
highlightInfo
对象
-
tabIds
数值 []
窗口中所有突出显示的标签页。
-
windowId
number
标签页发生更改的窗口。
-
-
onMoved
chrome.tabs.onMoved.addListener(
callback: function,
)
在窗口中移动标签页时触发。仅触发一个移动事件,表示用户直接移动的标签页。对于因响应手动移动的标签页而必须移动的其他标签页,系统不会触发移动事件。在窗口之间移动标签页时,不会触发此事件;如需了解详情,请参阅 tabs.onDetached
。
参数
-
callback
功能
callback
参数如下所示:(tabId: number, moveInfo: object) => void
-
tabId
number
-
moveInfo
对象
-
fromIndex
number
-
toIndex
number
-
windowId
number
-
-
onRemoved
chrome.tabs.onRemoved.addListener(
callback: function,
)
在标签页关闭时触发。
参数
-
callback
功能
callback
参数如下所示:(tabId: number, removeInfo: object) => void
-
tabId
number
-
removeInfo
对象
-
isWindowClosing
boolean
当标签页因其父窗口关闭而关闭时为 true。
-
windowId
number
标签页已关闭的窗口。
-
-
onReplaced
chrome.tabs.onReplaced.addListener(
callback: function,
)
在一个标签页因预渲染或即时渲染而被其他标签页替换时触发。
参数
-
callback
功能
callback
参数如下所示:(addedTabId: number, removedTabId: number) => void
-
addedTabId
number
-
removedTabId
number
-
onSelectionChanged
chrome.tabs.onSelectionChanged.addListener(
callback: function,
)
请使用 tabs.onActivated
。
在窗口中的所选标签页发生变化时触发。
参数
-
callback
功能
callback
参数如下所示:(tabId: number, selectInfo: object) => void
-
tabId
number
-
selectInfo
对象
-
windowId
number
所选标签页在其中发生更改的窗口的 ID。
-
-
onUpdated
chrome.tabs.onUpdated.addListener(
callback: function,
)
在标签页更新时触发。
参数
-
callback
功能
callback
参数如下所示:(tabId: number, changeInfo: object, tab: Tab) => void
-
tabId
number
-
changeInfo
对象
-
audible
布尔值 选填
Chrome 45 及更高版本标签页的新可听状态。
-
autoDiscardable
布尔值 选填
Chrome 54 及更高版本标签页的新可自动舍弃状态。
-
已舍弃
布尔值 选填
Chrome 54 及更高版本标签页的新舍弃状态。
-
favIconUrl
字符串(可选)
标签页的新网站图标网址。
-
groupId
数字可选
Chrome 88 及更高版本为标签页新建分组。
-
mutedInfo
MutedInfo 可选
Chrome 46 及更高版本标签页的新静音状态以及更改原因。
-
已置顶
布尔值 选填
标签页的新固定状态。
-
status
TabStatus 可选
标签页的加载状态。
-
title
字符串(可选)
Chrome 48 及更高版本标签的新标题。
-
网址
字符串(可选)
标签页的网址(如果该网址已发生更改)。
-
-
标签页
-
onZoomChange
chrome.tabs.onZoomChange.addListener(
callback: function,
)
在标签页缩放时触发。
参数
-
callback
功能
callback
参数如下所示:(ZoomChangeInfo: object) => void
-
ZoomChangeInfo
对象
-
newZoomFactor
number
-
oldZoomFactor
number
-
tabId
number
-
zoomSettings
-
-