说明
使用 chrome.tabs
API 与浏览器的标签页系统进行交互。您可以使用此 API 在浏览器中创建、修改和重新排列标签页。
Tabs API 不仅提供用于操作和管理标签页的功能,还可以检测标签页的语言、截取屏幕截图,以及与标签页的内容脚本进行通信。
权限
大多数功能无需任何权限即可使用。例如:创建新标签页、重新加载标签页、导航到另一个网址等。
开发者在使用 Tabs API 时应注意以下三项权限。
- “标签页”权限
此权限不会授予对
chrome.tabs
命名空间的访问权限。相反,它会授予扩展程序对tabs.Tab
实例上的四个敏感属性(url
、pendingUrl
、title
和favIconUrl
)调用tabs.query()
的权限。{ "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.");
}
});
}
将消息传递给所选标签页的内容脚本
此示例演示了扩展程序的服务工件如何使用 tabs.sendMessage()
与特定浏览器标签页中的 content 脚本进行通信。
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。如果上次静音状态发生变化的原因不是扩展程序,则不设置此属性。
-
已设为静音
布尔值
标签页是否处于静音状态(无法播放声音)。即使该标签页尚未播放或当前未播放声音,也可能会被静音。相当于是否显示“静音”音频指示器。
-
reason
MutedInfoReason(可选)
标签页被静音或取消静音的原因。如果标签页的静音状态从未更改,则不设置此属性。
MutedInfoReason
导致静音状态更改的事件。
枚举
“user”
用户输入操作设置了静音状态。
“capture”
已开始标签页截图,强制更改了静音状态。
“extension”
由 extensionId 字段标识的扩展程序设置了静音状态。
Tab
属性
-
活跃
布尔值
标签页在其窗口中是否处于活动状态。并不一定表示窗口处于聚焦状态。
-
audible
布尔值(可选)
Chrome 45 及更高版本标签页在过去几秒内是否发出了声音(但如果同时静音,则可能听不到声音)。相当于是否显示“扬声器音频”指示符。
-
autoDiscardable
布尔值
Chrome 54 及更高版本浏览器在资源不足时是否可以自动舍弃标签页。
-
已舍弃
布尔值
Chrome 54 及更高版本标签页是否被舍弃。已舍弃的标签页是指其内容已从内存中卸载,但仍显示在标签栏中。系统会在下次激活该实例时重新加载其内容。
-
favIconUrl
字符串(选填)
标签页的网站图标的网址。只有在扩展程序的清单包含
"tabs"
权限时,此属性才会存在。如果标签页正在加载,此值也可能是空字符串。 -
已冻结
布尔值
待处理标签页是否已冻结。已冻结的标签页无法执行任务,包括事件处理脚本或计时器。它显示在标签栏中,其内容会加载到内存中。激活后,此状态会解冻。
-
groupId
数值
Chrome 88 及更高版本标签页所属的群组的 ID。
-
高度
number 可选
标签页的高度(以像素为单位)。
-
突出显示
布尔值
标签页是否突出显示。
-
id
number 可选
标签页的 ID。标签页 ID 在浏览器会话中是唯一的。在某些情况下,系统可能不会为标签页分配 ID;例如,使用
sessions
API 查询外部标签页时,此时可能存在会话 ID。对于应用和开发者工具窗口,标签页 ID 也可以设置为chrome.tabs.TAB_ID_NONE
。 -
无痕
布尔值
标签页是否位于无痕式窗口中。
-
索引
数值
标签页在其窗口中的索引(从零开始)。
-
lastAccessed
数值
Chrome 121 及更高版本上次访问该标签页的时间(以从纪元开始计算的毫秒数表示)。
-
mutedInfo
MutedInfo 可选
Chrome 46 及更高版本标签页的静音状态和上次状态更改的原因。
-
openerTabId
number 可选
打开此标签页的标签页的 ID(如果有)。只有在打开器标签页仍然存在时,此属性才会存在。
-
pendingUrl
字符串(选填)
Chrome 79 及更高版本标签页要导航到的网址(在提交之前)。只有在扩展程序的清单包含
"tabs"
权限且存在待处理的导航时,此属性才会存在。 -
已固定
布尔值
标签页是否已固定。
-
已选择
布尔值
已废弃请使用
tabs.Tab.highlighted
。标签页是否处于选中状态。
-
sessionId
字符串(选填)
用于唯一标识从
sessions
API 获取的标签页的会话 ID。 -
状态
TabStatus(可选)
标签页的加载状态。
-
title
字符串(选填)
标签页的标题。仅当扩展程序的清单包含
"tabs"
权限时,此属性才会显示。 -
网址
字符串(选填)
标签页主框架上次提交的网址。只有在扩展程序的清单包含
"tabs"
权限时,此属性才会存在;如果标签页尚未提交,此属性可能为空字符串。另请参阅Tab.pendingUrl
。 -
width
number 可选
标签页的宽度(以像素为单位)。
-
windowId
数值
包含该标签页的窗口的 ID。
TabStatus
标签页的加载状态。
枚举
"unloaded"
“loading”
"complete"
WindowType
窗口的类型。
枚举
“normal”
"popup"
"panel"
"app"
"devtools"
ZoomSettings
定义如何处理标签页中的缩放更改以及在哪个范围内处理。
属性
-
defaultZoomFactor
编号(选填)
Chrome 43 及更高版本用于在调用 tab.getZoomSettings 时返回当前标签页的默认缩放级别。
-
模式
ZoomSettingsMode(可选)
定义如何处理缩放更改,即哪个实体负责页面的实际缩放;默认为
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
作用域仅在 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
number 可选
目标窗口。默认为当前窗口。
-
选项
ImageDetails 可选
-
callback
函数(可选)
callback
参数如下所示:(dataUrl: string) => void
-
dataUrl
字符串
用于编码所截取标签页可见区域的图片的数据网址。可分配给 HTML
img
元素的“src”属性以进行显示。
-
返回
-
Promise<string>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一函数调用中同时使用这两种方法。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
。 -
索引
编号(选填)
标签页应在窗口中占据的位置。所提供的值会被限制在 0 到窗口中标签页数量之间。
-
openerTabId
number 可选
打开此标签页的标签页的 ID。如果指定了打开器标签页,则打开器标签页必须与新创建的标签页位于同一窗口中。
-
已固定
布尔值(可选)
是否应固定该标签页。默认设置为
false
-
已选择
布尔值(可选)
已废弃请使用有效。
该标签页是否应成为窗口中的选定标签页。默认设置为
true
-
网址
字符串(选填)
标签页的初始导航网址。完全限定网址必须包含 scheme(即'http://www.google.com',而不是 'www.google.com')。相对网址相对于扩展程序中的当前网页。默认为“新标签页”页面。
-
windowId
number 可选
用于创建新标签页的窗口。默认为当前窗口。
-
-
callback
函数(可选)
callback
参数如下所示:(tab: Tab) => void
-
Tab
创建的标签页。
-
返回
-
Promise<标签页>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
detectLanguage()
chrome.tabs.detectLanguage(
tabId?: number,
callback?: function,
)
检测标签页中内容的主要语言。
参数
-
tabId
number 可选
默认为当前窗口的活动标签页。
-
callback
函数(可选)
callback
参数如下所示:(language: string) => void
-
language
字符串
ISO 语言代码,例如
en
或fr
。如需查看此方法支持的语言的完整列表,请参阅 kLanguageInfoTable。系统会检查第二列到第四列,并返回第一个非 NULL 值(简体中文除外,其返回的是zh-CN
)。对于未知/未定义的语言,系统会返回und
。
-
返回
-
Promise<string>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
discard()
chrome.tabs.discard(
tabId?: number,
callback?: function,
)
从内存中舍弃标签页。舍弃的标签页仍会显示在标签栏中,并且会在激活后重新加载。
参数
返回
-
Promise<Tab | undefined>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
duplicate()
chrome.tabs.duplicate(
tabId: number,
callback?: function,
)
复制标签页。
参数
-
tabId
数值
要复制的标签页的 ID。
-
callback
函数(可选)
callback
参数如下所示:(tab?: Tab) => void
返回
-
Chrome 88 及更高版本
清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
executeScript()
chrome.tabs.executeScript(
tabId?: number,
details: InjectDetails,
callback?: function,
)
在 Manifest V3 中,已替换为 scripting.executeScript
。
将 JavaScript 代码注入页面。如需了解详情,请参阅内容脚本文档的程序化注入部分。
参数
-
tabId
number 可选
用于运行脚本的标签页的 ID;默认为当前窗口的活动标签页。
-
详细信息
要运行的脚本的详细信息。必须设置代码或文件属性,但不能同时设置这两者。
-
callback
函数(可选)
callback
参数如下所示:(result?: any[]) => void
-
结果
any[] 可选
每个注入帧中的脚本结果。
-
返回
-
Promise<any[] | undefined>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
get()
chrome.tabs.get(
tabId: number,
callback?: function,
)
检索指定标签页的详细信息。
返回
-
Chrome 88 及更高版本
清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
getAllInWindow()
chrome.tabs.getAllInWindow(
windowId?: number,
callback?: function,
)
请使用 tabs.query
{windowId: windowId}
。
获取指定窗口中所有标签页的详细信息。
返回
-
Promise<Tab[]>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
getCurrent()
chrome.tabs.getCurrent(
callback?: function,
)
获取要执行此脚本调用的标签。如果从非标签页上下文(例如背景页面或弹出式窗口视图)调用,则返回 undefined
。
返回
-
Promise<Tab | undefined>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
getSelected()
chrome.tabs.getSelected(
windowId?: number,
callback?: function,
)
请使用 tabs.query
{active: true}
。
获取指定窗口中选定的标签页。
返回
-
Chrome 88 及更高版本
清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
getZoom()
chrome.tabs.getZoom(
tabId?: number,
callback?: function,
)
获取指定标签页的当前缩放比例。
参数
-
tabId
number 可选
要从中获取当前缩放比例的标签页的 ID;默认为当前窗口的活动标签页。
-
callback
函数(可选)
callback
参数的格式为:(zoomFactor: number) => void
-
zoomFactor
数值
标签页的当前缩放比例。
-
返回
-
Promise<number>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
getZoomSettings()
chrome.tabs.getZoomSettings(
tabId?: number,
callback?: function,
)
获取指定标签页的当前缩放设置。
参数
-
tabId
number 可选
要从中获取当前缩放设置的标签页的 ID;默认为当前窗口的活动标签页。
-
callback
函数(可选)
callback
参数如下所示:(zoomSettings: ZoomSettings) => void
-
zoomSettings
标签页的当前缩放设置。
-
返回
-
Promise<ZoomSettings>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
goBack()
chrome.tabs.goBack(
tabId?: number,
callback?: function,
)
返回上一页(如果有)。
参数
-
tabId
number 可选
要返回到的标签页的 ID;默认为当前窗口的选定标签页。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
goForward()
chrome.tabs.goForward(
tabId?: number,
callback?: function,
)
前往下一页(如果有)。
参数
-
tabId
number 可选
要向前导航的标签页的 ID;默认为当前窗口的选定标签页。
-
callback
函数(可选)
callback
参数的格式为:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
group()
chrome.tabs.group(
options: object,
callback?: function,
)
将一个或多个标签页添加到指定的组;如果未指定组,则将给定标签页添加到新创建的组。
参数
-
选项
对象
-
createProperties
对象(可选)
用于创建群组的配置。如果已指定 groupId,则无法使用此参数。
-
windowId
编号(选填)
新建组的窗口。默认为当前窗口。
-
-
groupId
number 可选
要将标签页添加到的群组的 ID。如果未指定,系统会创建一个新组。
-
tabIds
数字 | [数字, ...数字 []]
要添加到指定组的标签页 ID 或标签页 ID 列表。
-
-
callback
函数(可选)
callback
参数如下所示:(groupId: number) => void
-
groupId
数值
标签页所属群组的 ID。
-
返回
-
我保证<数字>
清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
highlight()
chrome.tabs.highlight(
highlightInfo: object,
callback?: function,
)
突出显示指定的标签页,并将焦点移至该组中的第一个标签页。如果指定的标签页当前处于活动状态,则似乎不会执行任何操作。
参数
-
highlightInfo
对象
-
标签页
数字 | 数字 []
要突出显示的一个或多个标签页编号。
-
windowId
number 可选
包含标签页的窗口。
-
-
callback
函数(可选)
callback
参数如下所示:(window: Window) => void
-
窗口
包含有关突出显示标签页的窗口的详细信息。
-
返回
-
Promise<windows.Window>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
insertCSS()
chrome.tabs.insertCSS(
tabId?: number,
details: InjectDetails,
callback?: function,
)
在 Manifest V3 中已替换为 scripting.insertCSS
。
将 CSS 注入到网页中。您可以使用 scripting.removeCSS
移除通过此方法插入的样式。如需了解详情,请参阅内容脚本文档的程序化注入部分。
参数
-
tabId
number 可选
要插入 CSS 的标签页的 ID;默认为当前窗口的活动标签页。
-
详细信息
要插入的 CSS 文本的详细信息。必须设置代码或文件属性,但不能同时设置这两者。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
move()
chrome.tabs.move(
tabIds: number | number[],
moveProperties: object,
callback?: function,
)
将一个或多个标签页移至窗口内的新位置,或移至新窗口。请注意,标签页只能在普通窗口(window.type === "normal")之间移动。
参数
返回
-
Chrome 88 及更高版本
清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
query()
chrome.tabs.query(
queryInfo: object,
callback?: function,
)
获取具有指定属性的所有标签页,如果未指定任何属性,则获取所有标签页。
参数
-
queryInfo
对象
-
活跃
布尔值(可选)
标签页在其窗口中是否处于活动状态。
-
audible
布尔值(可选)
Chrome 45 及更高版本标签页是否可听。
-
autoDiscardable
布尔值(可选)
Chrome 54 及更高版本浏览器在资源不足时是否可以自动舍弃标签页。
-
currentWindow
布尔值(可选)
标签页是否位于当前窗口中。
-
已舍弃
布尔值(可选)
Chrome 54 及更高版本是否舍弃标签页。已舍弃的标签页是指其内容已从内存中卸载,但仍显示在标签栏中。其内容会在下次激活时重新加载。
-
已冻结
布尔值(可选)
待处理标签页是否冻结。冻结的标签页无法执行任务,包括事件处理程序或计时器。它会显示在标签页栏中,其内容会加载到内存中。激活后,此状态会解冻。
-
groupId
number 可选
Chrome 88 及更高版本标签页所属分组的 ID,或
tabGroups.TAB_GROUP_ID_NONE
(如果标签页未分组)。 -
突出显示
布尔值(可选)
是否突出显示标签页。
-
索引
编号(选填)
标签页在其窗口中的位置。
-
lastFocusedWindow
布尔值(可选)
标签页是否位于上次聚焦的窗口中。
-
已设为静音
布尔值(可选)
Chrome 45 及更高版本指示标签页是否处于静音状态。
-
已固定
布尔值(可选)
标签页是否已固定。
-
状态
TabStatus(可选)
标签页加载状态。
-
title
字符串(选填)
将网页标题与模式进行匹配。如果扩展程序没有
"tabs"
权限,系统会忽略此属性。 -
网址
字符串 | 字符串数组 可选
将标签页与一个或多个网址格式相匹配。fragment 标识符不匹配。如果扩展程序没有
"tabs"
权限,系统会忽略此属性。 -
windowId
number 可选
父窗口的 ID,对于当前窗口,则为
windows.WINDOW_ID_CURRENT
。 -
windowType
WindowType(可选)
标签页所在的窗口类型。
-
-
callback
函数(可选)
callback
参数如下所示:(result: Tab[]) => void
-
结果
Tab[]
-
返回
-
Chrome 88 及更高版本
清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
reload()
chrome.tabs.reload(
tabId?: number,
reloadProperties?: object,
callback?: function,
)
重新加载标签页。
参数
-
tabId
number 可选
要重新加载的标签页的 ID;默认为当前窗口的所选标签页。
-
reloadProperties
对象(可选)
-
bypassCache
布尔值(可选)
是否要绕过本地缓存。默认为
false
。
-
-
callback
函数(可选)
callback
参数的格式为:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
remove()
chrome.tabs.remove(
tabIds: number | number[],
callback?: function,
)
关闭一个或多个标签页。
参数
-
tabIds
number | number[]
要关闭的标签页 ID 或标签页 ID 列表。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
removeCSS()
chrome.tabs.removeCSS(
tabId?: number,
details: DeleteInjectionDetails,
callback?: function,
)
在 Manifest V3 中已替换为 scripting.removeCSS
。
从页面中移除之前通过调用 scripting.insertCSS
注入的 CSS。
参数
-
tabId
number 可选
要从中移除 CSS 的标签页的 ID;默认为当前窗口的活动标签页。
-
要移除的 CSS 文本的详细信息。必须设置代码或文件属性,但不能同时设置这两者。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
sendMessage()
chrome.tabs.sendMessage(
tabId: number,
message: any,
options?: object,
callback?: function,
)
向指定标签页中的内容脚本发送一条消息,其中包含在发回响应时运行的可选回调函数。在当前扩展程序的指定标签页中运行的每个内容脚本都会触发 runtime.onMessage
事件。
参数
-
tabId
数值
-
消息
任意
要发送的消息。此消息应为可 JSON 化对象。
-
选项
对象(可选)
-
callback
函数(可选)
Chrome 99 及更高版本callback
参数如下所示:(response: any) => void
-
Response
任意
消息处理脚本发送的 JSON 响应对象。如果在连接到指定标签页时发生错误,系统会调用不带参数的回调,并将
runtime.lastError
设置为错误消息。
-
返回
-
Promise<any>
Chrome 99 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
sendRequest()
chrome.tabs.sendRequest(
tabId: number,
request: any,
callback?: function,
)
请使用 runtime.sendMessage
。
向指定标签页中的内容脚本发送单个请求,其中包含在发回响应时运行的可选回调函数。在当前扩展程序的指定标签页中运行的每个内容脚本都会触发 extension.onRequest
事件。
参数
-
tabId
数值
-
request
任意
-
callback
函数(可选)
Chrome 99 及更高版本callback
参数的格式为:(response: any) => void
-
Response
任意
请求处理脚本发送的 JSON 响应对象。如果在连接到指定标签页时发生错误,系统会调用不带参数的回调,并将
runtime.lastError
设置为错误消息。
-
返回
-
Promise<any>
Chrome 99 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
setZoom()
chrome.tabs.setZoom(
tabId?: number,
zoomFactor: number,
callback?: function,
)
缩放指定标签页。
参数
-
tabId
number 可选
要缩放的标签页的 ID;默认为当前窗口的活动标签页。
-
zoomFactor
数值
新的缩放比例。值为
0
会将标签页设为其当前的默认缩放比例。大于0
的值用于为标签页指定(可能非默认的)缩放比例。 -
callback
函数(可选)
callback
参数的格式为:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
setZoomSettings()
chrome.tabs.setZoomSettings(
tabId?: number,
zoomSettings: ZoomSettings,
callback?: function,
)
为指定标签页设置缩放设置,这些设置用于定义如何处理缩放更改。在浏览标签页时,这些设置会重置为默认设置。
参数
-
tabId
number 可选
要更改其缩放设置的标签页的 ID;默认为当前窗口的活动标签页。
-
zoomSettings
定义如何处理缩放更改以及在哪个范围内处理。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
ungroup()
chrome.tabs.ungroup(
tabIds: number | [number, ...number[]],
callback?: function,
)
从相应分组中移除一个或多个标签页。如果任何组变为空组,系统会将其删除。
参数
-
tabIds
数字 | [数字, ...数字 []]
要从相应组中移除的标签页 ID 或标签页 ID 列表。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
update()
chrome.tabs.update(
tabId?: number,
updateProperties: object,
callback?: function,
)
修改标签页的属性。系统不会修改未在 updateProperties
中指定的属性。
参数
-
tabId
number 可选
默认为当前窗口的选定标签页。
-
updateProperties
对象
-
活跃
布尔值(可选)
标签页是否应处于活跃状态。不会影响窗口是否聚焦(请参阅
windows.update
)。 -
autoDiscardable
布尔值(可选)
Chrome 54 及更高版本在资源不足时,浏览器是否应自动舍弃标签页。
-
突出显示
布尔值(可选)
在当前所选内容中添加或移除标签页。
-
已设为静音
布尔值(可选)
Chrome 45 及更高版本是否应将标签页静音。
-
openerTabId
number 可选
打开此标签页的标签页的 ID。如果指定了此属性,则打开标签页必须与此标签页位于同一窗口中。
-
已固定
布尔值(可选)
是否应固定该标签页。
-
已选择
布尔值(可选)
已废弃请使用突出显示。
是否应选择该标签页。
-
网址
字符串(选填)
要将标签页导航到的网址。不支持 JavaScript 网址;请改用
scripting.executeScript
。
-
-
callback
函数(可选)
callback
参数的格式为:(tab?: Tab) => void
返回
-
Promise<Tab | undefined>
Chrome 88 及更高版本清单 V3 及更高版本支持 Promise,但为了实现向后兼容性,我们提供了回调。您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。
事件
onActivated
chrome.tabs.onActivated.addListener(
callback: function,
)
当窗口中的活动标签页发生变化时触发。请注意,此事件触发时,标签页的网址可能尚未设置,但您可以监听 onUpdated 事件,以便在设置网址时收到通知。
参数
-
callback
函数
callback
参数如下所示:(activeInfo: object) => void
-
activeInfo
对象
-
tabId
数值
已变为活动状态的标签页的 ID。
-
windowId
数值
发生活动标签页更改的窗口的 ID。
-
-
onActiveChanged
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 事件,以便在设置了网址或标签页添加到标签页组时收到通知。
onDetached
chrome.tabs.onDetached.addListener(
callback: function,
)
当标签页与窗口分离(例如在窗口之间移动)时触发。
参数
-
callback
函数
callback
参数如下所示:(tabId: number, detachInfo: object) => void
-
tabId
数值
-
detachInfo
对象
-
oldPosition
数值
-
oldWindowId
数值
-
-
onHighlightChanged
chrome.tabs.onHighlightChanged.addListener(
callback: function,
)
请使用 tabs.onHighlighted
。
当窗口中的突出显示或选定的标签页发生变化时触发。
参数
-
callback
函数
callback
参数如下所示:(selectInfo: object) => void
-
selectInfo
对象
-
tabIds
数字 []
窗口中所有突出显示的标签页。
-
windowId
数值
标签页发生更改的窗口。
-
-
onHighlighted
chrome.tabs.onHighlighted.addListener(
callback: function,
)
在窗口中突出显示或选中的标签页发生变化时触发。
参数
-
callback
函数
callback
参数的格式为:(highlightInfo: object) => void
-
highlightInfo
对象
-
tabIds
数字 []
窗口中所有突出显示的标签页。
-
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
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
字符串(可选)
标签页的新网站图标网址。
-
已冻结
布尔值(可选)
待处理标签页的新冻结状态。
-
groupId
number 可选
Chrome 88 及更高版本标签页的新分组。
-
mutedInfo
MutedInfo(可选)
Chrome 46 及更高版本标签页的新静音状态和更改原因。
-
已固定
布尔值(可选)
标签页的新固定状态。
-
状态
TabStatus(可选)
标签页的加载状态。
-
title
字符串(可选)
Chrome 48 及更高版本标签页的新标题。
-
网址
字符串(可选)
标签页的网址(如果网址已更改)。
-
-
Tab
-
onZoomChange
chrome.tabs.onZoomChange.addListener(
callback: function,
)
在缩放标签页时触发。
参数
-
callback
函数
callback
参数的格式为:(ZoomChangeInfo: object) => void
-
ZoomChangeInfo
对象
-
newZoomFactor
数值
-
oldZoomFactor
数值
-
tabId
数值
-
zoomSettings
-
-