Description
使用
chrome.tabs
API 与浏览器的标签系统交互。您可以使用此 API 在浏览器中创建、修改和重新排列选项卡。
#
Manifest
您可以使用大多数 chrome.tabs 方法和事件，而无需在扩展的清单
manifest
文件中声明任何权限。但是，如果您需要访问
tabs.Tab
的
url
、
pendingUrl
、
title
或
favIconUrl` 属性，则必须在清单中声明“tabs”权限，如下所示：
{
"name": "My extension",
"permissions": [
"tabs"
# Examples
以下部分演示了 chrome.tabs API 的几个常见用例。
# Opening an extension page in a new tab(在新标签页中打开扩展页面)
扩展的常见模式是在安装扩展时在新选项卡中打开入门页面。以下示例显示了如何执行此操作。
内容脚本不能使用 chrome.tabs.create()。
chrome.runtime.onInstalled.addListener((reason) => {
if (reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.tabs.create({
url: 'onboarding.html'
# Get the current tab(获取当前标签)
此示例演示后台脚本如何检索当前聚焦的选项卡。
由于使用了 Promises，此示例需要 Manifest V3。此外，内容脚本不能使用 tabs.query。
async function getCurrentTab() {
let queryOptions = { active: true, currentWindow: true };
let [tab] = await chrome.tabs.query(queryOptions);
return tab;
# Mute the specified tab(静音指定的选项卡)
由于使用了 Promise，需要 Manifest V3。内容脚本不能使用 tabs.get 或 tabs.update。
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' }`);
# Move the current tab to the first position when clicked(单击时将当前选项卡移动到第一个位置)
此示例显示如何在拖动过程中或不进行时移动选项卡。
由于使用了 Promises 和 chrome.tabs.onActivated()，需要 Manifest V3，替换 chrome.tabs.onSelectionChanged()。在 Promise 上下文中使用 catch(error) 是一种确保不会未检查否则会填充 chrome.runtime.lastError 的错误的方法。本示例中使用了 chrome.tabs.move，但相同的等待模式可用于在拖动过程中修改选项卡的其他调用。
chrome.tabs.onActivated.addListener(activeInfo => move(activeInfo));
async function move(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(() => move(activeInfo), 50);
# More samples(更多)
有关演示 Tabs API 的更多示例，请参阅 chrome-extensions-samples 存储库的 mv2-archive/api/tabs 目录。
Summary
Types
MutedInfo
Chrome 46+
选项卡的静音状态以及上次状态更改的原因。
PROPERTIES
extensionId
string optional
更改静音状态的扩展程序的 ID。如果扩展不是静音状态上次更改的原因，则不设置。
muted
boolean
选项卡是否静音（防止播放声音）。即使该选项卡尚未播放或当前未播放声音，它也可能被静音。相当于是否显示“静音”音频指示器。
reason
MutedInfoReason optional
选项卡静音或取消静音的原因。如果选项卡的静音状态从未改变，则不设置。
MutedInfoReason
Chrome 46+
导致静音状态更改的事件。
TYPE
"user", "capture", or "extension"
Tab
PROPERTIES
active
boolean
选项卡在其窗口中是否处于活动状态。不一定意味着窗口已聚焦。
audible
boolean optional
Chrome 45+
该选项卡在过去几秒钟内是否发出声音（但如果也静音，则可能听不到）。相当于是否显示“扬声器音频”指示器。
autoDiscardable
boolean
Chrome 54+
资源不足时浏览器是否可以自动丢弃标签页。
discarded
boolean
Chrome 54+
标签是否被丢弃。丢弃的选项卡是指其内容已从内存中卸载但在选项卡条中仍可见的选项卡。下次激活时会重新加载其内容。
favIconUrl
string optional
选项卡图标的 URL。此属性仅在扩展程序的清单包含“tabs”权限时才存在。如果选项卡正在加载，它也可能是一个空字符串。
groupId
number
Chrome 88+
选项卡所属的组的 ID。
height
number optional
选项卡的高度（以像素为单位）。
highlighted
boolean
该选项卡是否突出显示。
id
number optional
选项卡的 ID。标签 ID 在浏览器会话中是唯一的。在某些情况下，可能不会为选项卡分配 ID；例如，当使用会话 API 查询外部选项卡时，在这种情况下可能会出现会话session ID。对于应用程序和开发工具窗口，标签 ID 也可以设置为 chrome.tabs.TAB_ID_NONE。
incognito
boolean
选项卡是否在隐身窗口中。
index
number
选项卡在其窗口中的从零开始的索引。
mutedInfo
MutedInfo optional
Chrome 46+
选项卡的静音状态以及上次状态更改的原因。
openerTabId
number optional
打开此选项卡的选项卡的 ID（如果有）。此属性仅在 opener 选项卡仍然存在时才存在。
pendingUrl
string optional
Chrome 79+
选项卡在提交之前导航到的 URL。此属性仅在扩展程序的清单包含“选项卡”权限并且存在挂起导航时才存在。
pinned
boolean
选项卡是否固定。
selected
boolean
Deprecated
Please use tabs.Tab.highlighted.
选项卡是否被选中。
sessionId
string optional
用于唯一标识从会话 API 获取的选项卡的会话sessions ID。
status
TabStatus optional
选项卡的加载状态。
title
string optional
选项卡的标题。此属性仅在扩展程序的清单包含“tabs”权限时才存在。
url
string optional
选项卡主框架的最后提交 URL。此属性仅在扩展程序的清单包含“tabs”权限时才存在，如果选项卡尚未提交，则该属性可能为空字符串。另请参阅 Tab.pendingUrl。
width
number optional
选项卡的宽度（以像素为单位）。
windowId
number
包含选项卡的窗口的 ID。
TabStatus
Chrome 44+
选项卡的加载状态。
TYPE
"unloaded", "loading", or "complete"
WindowType
Chrome 44+
窗口的类型。
TYPE
"normal", "popup", "panel", "app", or "devtools"
ZoomSettings
定义如何处理选项卡中的缩放更改以及在什么范围内。
PROPERTIES
defaultZoomFactor
number optional
Chrome 43+
用于在调用 tabs.getZoomSettings 时返回当前选项卡的默认缩放级别。
mode
ZoomSettingsMode optional
定义如何处理缩放更改，即哪个实体负责页面的实际缩放；默认为自动automatic。
scope
ZoomSettingsScope optional
定义缩放更改是保留页面原点，还是仅在此选项卡中生效；在自动automatic模式下默认为 per-origin，否则为 per-tab。
ZoomSettingsMode
Chrome 44+
定义如何处理缩放更改，即哪个实体负责页面的实际缩放；默认为自动automatic。
TYPE
"automatic", "manual", or "disabled"
ZoomSettingsScope
Chrome 44+
定义缩放更改是保留页面原点，还是仅在此选项卡中生效；在自动模式(automatic)下默认为 per-origin，否则为 per-tab。
TYPE
"per-origin", or "per-tab"
Properties
MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND
Chrome 92+
每秒可以调用 captureVisibleTab 的最大次数。captureVisibleTab 很昂贵，不应过于频繁地调用。
VALUE
2
TAB_ID_NONE
Chrome 46+
表示缺少浏览器选项卡的 ID。
VALUE
-1
Methods
captureVisibleTab
chrome.tabs.captureVisibleTab(
windowId?: number,
options?: ImageDetails,
callback?: function,
)
Promise
捕获指定窗口中当前活动选项卡的可见区域。要调用此方法，扩展程序必须具有 权限或 activeTab 权限。除了扩展程序可以正常访问的站点外，此方法还允许扩展程序捕获其他受限制的敏感站点，包括 chrome:-scheme 页面、其他扩展程序的页面和 data: URL。这些敏感站点只能使用 activeTab 权限进行捕获。仅当扩展已被授予文件访问权限时，才可以捕获文件 URL。
PARAMETERS
windowId
number optional
目标窗口。默认为当前窗口current window。
options
ImageDetails optional
callback
function optional
The callback parameter looks like:
(dataUrl: string) => void
RETURNS
connect
chrome.tabs.connect(
tabId: number,
connectInfo?: object,
连接到指定选项卡中的内容脚本。在当前扩展的指定选项卡中运行的每个内容脚本中都会触发 runtime.onConnect 事件。有关更多详细信息，请参阅内容脚本消息传递Content Script Messaging。
PARAMETERS
tabId
number
connectInfo
object optional
RETURNS
create
chrome.tabs.create(
createProperties: object,
callback?: function,
)
Promise
创建一个新选项卡。
PARAMETERS
createProperties
object
active
boolean optional
该选项卡是否应成为窗口中的活动选项卡。不影响窗口是否聚焦（参见 windows.update）。默认为true。
index
number optional
选项卡在窗口中应占据的位置。提供的值被限制在零和窗口中的选项卡数量之间。
openerTabId
number optional
打开此选项卡的选项卡的 ID。如果指定，opener 选项卡必须与新创建的选项卡位于同一窗口中。
pinned
boolean optional
是否应固定选项卡。默认为false。
selected
boolean optional
Deprecated
Please use active.
该选项卡是否应成为窗口中的选定选项卡。默认为true;
url
string optional
最初将选项卡导航到的 URL。完全限定的 URL 必须包含一个方案（即“http://www.google.com”，而不是“www.google.com”）。相对 URL 相对于扩展程序中的当前页面。默认为新标签页。
windowId
number optional
在其中创建新选项卡的窗口。默认为当前窗口current window。
callback
function optional
The callback parameter looks like:
(tab: Tab) => void
RETURNS
detectLanguage
chrome.tabs.detectLanguage(
tabId?: number,
callback?: function,
Promise
检测选项卡中内容的主要语言。
PARAMETERS
tabId
number optional
默认为当前窗口current window的活动选项卡。
callback
function optional
The callback parameter looks like:
(language: string) => void
RETURNS
discard
chrome.tabs.discard(
tabId?: number,
callback?: function,
Promise Chrome 54+
从内存中丢弃一个选项卡。丢弃的标签在标签条上仍然可见，并在激活时重新加载。
PARAMETERS
tabId
number optional
要丢弃的选项卡的 ID。如果指定，选项卡将被丢弃，除非它处于活动状态或已被丢弃。如果省略，浏览器会丢弃最不重要的选项卡。如果不存在可丢弃的选项卡，这可能会失败。
callback
function optional
The callback parameter looks like:
(tab?: Tab) => void
tab
Tab optional
丢弃的选项卡，如果成功丢弃；否则未定义。
RETURNS
duplicate
chrome.tabs.duplicate(
tabId: number,
callback?: function,
Promise
复制选项卡。
PARAMETERS
tabId
number
要复制的选项卡的 ID。
callback
function optional
The callback parameter looks like:
(tab?: Tab) => void
RETURNS
executeScript
chrome.tabs.executeScript(
tabId?: number,
details: InjectDetails,
callback?: function,
)
Promise ≤MV2 Deprecated since Chrome 91
在 Manifest V3 中被 scripting.executeScript 替换。
将 JavaScript 代码注入页面。有关详细信息，请参阅内容脚本文档的程序化注入programmatic injection部分。
PARAMETERS
tabId
number optional
在其中运行脚本的选项卡的 ID；默认为当前窗口的活动选项卡。
details
InjectDetails
要运行的脚本的详细信息。必须设置代码或文件属性，但不能同时设置两者。
callback
function optional
The callback parameter looks like:
(result?: any[]) => void
result
any[] optional
每个注入帧中的脚本结果。
RETURNS
get
chrome.tabs.get(
tabId: number,
callback?: function,
Promise
检索有关指定选项卡的详细信息。
PARAMETERS
tabId
number
callback
function optional
The callback parameter looks like:
(tab: Tab) => void
RETURNS
getAllInWindow
chrome.tabs.getAllInWindow(
windowId?: number,
callback?: function,
Promise ≤MV2 Deprecated
Please use tabs.query {windowId: windowId}.
获取有关指定窗口中所有选项卡的详细信息
PARAMETERS
windowId
number optional
默认为当前窗口current window。
callback
function optional
The callback parameter looks like:
(tabs: Tab[]) => void
RETURNS
getCurrent
chrome.tabs.getCurrent(
callback?: function,
Promise
获取进行此脚本调用的选项卡。如果从非选项卡上下文（例如，背景页面或弹出视图）调用，则可能未定义。
PARAMETERS
callback
function optional
The callback parameter looks like:
(tab?: Tab) => void
RETURNS
getSelected
chrome.tabs.getSelected(
windowId?: number,
callback?: function,
Promise ≤MV2 Deprecated
Please use tabs.query {active: true}.
获取在指定窗口中选择的选项卡。
PARAMETERS
windowId
number optional
默认为当前窗口current window。
callback
function optional
The callback parameter looks like:
(tab: Tab) => void
RETURNS
getZoom
chrome.tabs.getZoom(
tabId?: number,
callback?: function,
Promise
获取指定选项卡的当前缩放系数。
PARAMETERS
tabId
number optional
从中获取当前缩放系数的选项卡的 ID；默认为当前窗口的活动选项卡。
callback
function optional
The callback parameter looks like:
(zoomFactor: number) => void
zoomFactor
number
选项卡的当前缩放系数。
RETURNS
getZoomSettings
chrome.tabs.getZoomSettings(
tabId?: number,
callback?: function,
Promise
获取指定选项卡的当前缩放设置。
PARAMETERS
tabId
number optional
从中获取当前缩放设置的选项卡的 ID；默认为当前窗口的活动选项卡。
callback
function optional
The callback parameter looks like:
(zoomSettings: ZoomSettings) => void
RETURNS
goBack
chrome.tabs.goBack(
tabId?: number,
callback?: function,
Promise Chrome 72+
如果有，请返回上一页。
PARAMETERS
tabId
number optional
要返回的选项卡的 ID；默认为当前窗口的选定选项卡。
callback
function optional
The callback parameter looks like:
() => void
RETURNS
goForward
chrome.tabs.goForward(
tabId?: number,
callback?: function,
Promise Chrome 72+
前进到下一页，如果有的话。
PARAMETERS
tabId
number optional
要向前导航的选项卡的 ID；默认为当前窗口的选定选项卡。
callback
function optional
The callback parameter looks like:
() => void
RETURNS
group
chrome.tabs.group(
options: object,
callback?: function,
Promise Chrome 88+
将一个或多个选项卡添加到指定的组，或者如果未指定组，则将给定的选项卡添加到新创建的组。
PARAMETERS
