Chrome 现在支持标准化的 browser.* 命名空间（自 Chrome 148 起提供）。我们正在逐步更新文档。如需了解详情，请参阅我们的过渡指南。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

browser.tabs

说明

使用 chrome.tabs API 与浏览器的标签页系统进行交互。您可以使用此 API 在浏览器中创建、修改和重新排列标签页。

Tabs API 不仅提供用于操作和管理标签页的功能，还可以检测标签页的语言、截取屏幕截图，以及与标签页的内容脚本通信。

权限

大多数功能无需任何权限即可使用。例如：创建新标签页、重新加载标签页、导航到其他网址等。

开发者在使用 Tabs API 时应注意以下三项权限。

“tabs”权限

此权限不授予对 browser.tabs 命名空间的访问权限。而是授予扩展程序针对 tabs.Tab 实例上的四个敏感属性调用 tabs.query() 的能力：url、pendingUrl、title 和 favIconUrl。

{
  "name": "My extension",
  ...
  "permissions": [
    "tabs"
  ],
  ...
}

主持人权限

主机权限允许扩展程序读取和查询匹配标签页的四个敏感 tabs.Tab 属性。它们还可以使用 tabs.captureVisibleTab()、scripting.executeScript()、scripting.insertCSS() 和 scripting.removeCSS() 等方法直接与匹配的标签页互动。

{
  "name": "My extension",
  ...
  "host_permissions": [
    "http://*/*",
    "https://*/*"
  ],
  ...
}

“activeTab”权限

activeTab 会在用户调用时向扩展程序授予当前标签页的临时主机权限。与主机权限不同，activeTab 不会触发任何警告。

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab"
  ],
  ...
}

使用场景

以下部分演示了一些常见用例。

在新标签页中打开扩展程序页面

扩展程序的常见模式是在安装扩展程序后，在新标签页中打开新手入门页面。以下示例展示了如何执行此操作。

background.js:

browser.runtime.onInstalled.addListener(({reason}) => {
  if (reason === 'install') {
    browser.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 browser.tabs.query(queryOptions);
    return tab;
  }

  function getCurrentTab(callback) {
    let queryOptions = { active: true, lastFocusedWindow: true };
    browser.tabs.query(queryOptions, ([tab]) => {
      if (browser.runtime.lastError)
      console.error(browser.runtime.lastError);
      // `tab` will either be a `tabs.Tab` instance or `undefined`.
      callback(tab);
    });
  }

将指定标签页静音

此示例展示了扩展程序如何切换给定标签页的静音状态。

  async function toggleMuteState(tabId) {
    const tab = await browser.tabs.get(tabId);
    const muted = !tab.mutedInfo.muted;
    await browser.tabs.update(tabId, {muted});
    console.log(`Tab ${tab.id} is ${muted ? "muted" : "unmuted"}`);
  }

  function toggleMuteState(tabId) {
    browser.tabs.get(tabId, async (tab) => {
      let muted = !tab.mutedInfo.muted;
      await browser.tabs.update(tabId, { muted });
      console.log(`Tab ${tab.id} is ${ muted ? "muted" : "unmuted" }`);
    });
  }

点击后将当前标签页移至第一个位置

此示例展示了如何在拖动可能正在进行或可能未在进行时移动标签页。虽然此示例使用的是 browser.tabs.move，但对于在拖动过程中修改标签页的其他调用，您也可以使用相同的等待模式。

  browser.tabs.onActivated.addListener(moveToFirstPosition);

  async function moveToFirstPosition(activeInfo) {
    try {
      await browser.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);
      }
    }
  }

  browser.tabs.onActivated.addListener(moveToFirstPositionMV2);

  function moveToFirstPositionMV2(activeInfo) {
    browser.tabs.move(activeInfo.tabId, { index: 0 }, () => {
      if (browser.runtime.lastError) {
        const error = browser.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 browser.tabs.query({ active: true, lastFocusedWindow: true });
  const response = await browser.tabs.sendMessage(tab.id, message);
  // TODO: Do something with the response.
}

扩展程序示例

如需查看更多 Tabs API 扩展程序演示，请探索以下任一内容：

类型

MutedInfo

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

标签页的静音状态以及上次状态更改的原因。

属性

extensionId

字符串可选

更改了静音状态的扩展程序的 ID。如果上次静音状态发生变化的原因不是扩展程序，则不设置此属性。
已设为静音

布尔值

标签页是否已静音（无法播放声音）。即使标签页尚未播放或当前未播放声音，也可能会被静音。相当于是否显示“已静音”音频指示器。
reason

MutedInfoReason 可选

标签页静音或取消静音的原因。如果标签页的静音状态从未更改，则不设置。

MutedInfoReason

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

导致静音状态发生变化的事件。

枚举

"user"
用户输入操作设置了静音状态。

“capture”
标签页捕获已启动，强制更改为静音状态。

"extension"
由 extensionId 字段标识的扩展程序设置了静音状态。

Tab

属性

活跃

布尔值

标签页在其窗口中是否处于活动状态。不一定表示窗口处于聚焦状态。
audible

布尔值（可选）

Chrome 45 及更高版本 browser.*（自 Chrome 148 起）

该标签页在过去几秒内是否发出过声音（但如果同时处于静音状态，则可能听不到）。等同于是否显示“扬声器音频”指示器。
autoDiscardable

布尔值

Chrome 54 及更高版本 browser.*（自 Chrome 148 起）

当资源不足时，浏览器是否可以自动舍弃该标签页。
已舍弃

布尔值

Chrome 54 及更高版本 browser.*（自 Chrome 148 起）

标签页是否已被舍弃。舍弃的标签页是指其内容已从内存中卸载，但仍显示在标签栏中的标签页。其内容会在下次激活时重新加载。
favIconUrl

字符串可选

标签页网站图标的网址。仅当扩展程序具有 "tabs" 权限或具有页面的主机权限时，此属性才会存在。如果标签页正在加载，则该值也可能为空字符串。
冻结

布尔值

Chrome 132+ browser.*（自 Chrome 148 起）

标签页是否已冻结。冻结的标签页无法执行任务，包括事件处理脚本或计时器。它会显示在标签栏中，并且其内容会加载到内存中。激活后，该账号会解冻。
groupId

数值

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

标签页所属分组的 ID。
高度

number 可选

标签页的高度（以像素为单位）。
突出显示

布尔值

标签页是否突出显示。
id

number 可选

标签页的 ID。标签页 ID 在浏览器会话中是唯一的。在某些情况下，标签页可能未分配 ID；例如，使用 sessions API 查询外部标签页时，在这种情况下，可能会存在会话 ID。对于应用和开发者工具窗口，标签页 ID 也可以设置为 chrome.tabs.TAB_ID_NONE。
无痕模式

布尔值

标签页是否位于无痕式窗口中。
索引

数值

标签页在其窗口中的索引（从零开始）。
lastAccessed

数值

Chrome 121 及更高版本 browser.*（自 Chrome 148 起）

该标签页上次在其窗口中变为活动状态的时间（以自公元纪年开始计算的毫秒数表示）。
mutedInfo

MutedInfo 可选

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

标签页的静音状态以及上次状态更改的原因。
openerTabId

number 可选

打开此标签页的标签页的 ID（如果有）。仅当打开标签页仍然存在时，此属性才会存在。
pendingUrl

字符串可选

Chrome 79 及更高版本 browser.*（自 Chrome 148 起）

标签页在提交之前要导航到的网址。仅当扩展程序具有 "tabs" 权限或具有页面的主机权限，并且存在待处理的导航时，此属性才会存在。
已固定

布尔值

标签页是否已固定。
已选择

布尔值

已弃用

请使用 tabs.Tab.highlighted。
指示标签页是否处于选中状态。
sessionId

字符串可选

用于唯一标识从 sessions API 获取的标签页的会话 ID。
splitViewId

number 可选

Chrome 140 及更高版本 browser.*（自 Chrome 148 起）

标签页所属的拆分视图的 ID。
状态

TabStatus 可选

标签页的加载状态。
title

字符串可选

标签页的标题。仅当扩展程序具有 "tabs" 权限或具有页面的主机权限时，此属性才会存在。
网址

字符串可选

标签页主框架的上次提交网址。仅当扩展程序具有 "tabs" 权限或具有页面的主机权限时，此属性才会存在。如果标签页尚未提交，则可能为空字符串。另请参阅 Tab.pendingUrl。
width

number 可选

标签页的宽度（以像素为单位）。
windowId

数值

包含该标签页的窗口的 ID。

TabStatus

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

标签页的加载状态。

枚举

"unloaded"

"loading"

"complete"

WindowType

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

窗口类型。

枚举

"normal"

"popup"

"panel"

"app"

"devtools"

ZoomSettings

定义如何处理标签页中的缩放更改以及在何种范围内处理。

属性

defaultZoomFactor

number 可选

Chrome 43 及更高版本 Chrome 148 及更高版本中的 browser.*

用于在调用 tabs.getZoomSettings 时返回当前标签页的默认缩放级别。
模式

ZoomSettingsMode 可选

定义如何处理缩放更改，即哪个实体负责页面的实际缩放；默认值为 automatic。
范围

ZoomSettingsScope 可选

定义缩放更改是针对网页来源永久生效，还是仅在此标签页中生效；在 automatic 模式下，默认值为 per-origin，否则默认值为 per-tab。

ZoomSettingsMode

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

定义如何处理缩放更改，即哪个实体负责页面的实际缩放；默认值为 automatic。

枚举

"automatic"
缩放更改由浏览器自动处理。

“manual”
替换对缩放更改的自动处理。onZoomChange 事件仍会分派，扩展程序负责监听此事件并手动缩放页面。此模式不支持 per-origin 缩放，因此会忽略 scope 缩放设置并假定为 per-tab。

"disabled"
停用标签页中的所有缩放功能。标签页会还原为默认缩放级别，并且所有尝试的缩放更改都会被忽略。

ZoomSettingsScope

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

定义缩放更改是针对网页来源持久生效，还是仅在此标签页中生效；在 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

Chrome 92 及更高版本 browser.*（自 Chrome 148 起）

每秒可调用 captureVisibleTab 的次数上限。captureVisibleTab 的开销很大，不应过于频繁地调用。

值

SPLIT_VIEW_ID_NONE

Chrome 140 及更高版本 browser.*（自 Chrome 148 起）

表示没有拆分标签页的 ID。

值

-1

TAB_ID_NONE

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

表示不存在浏览器标签页的 ID。

值

-1

TAB_INDEX_NONE

Chrome 123 及更高版本 browser.*（自 Chrome 148 起）

表示标签栏中没有标签页索引的索引。

值

-1

方法

captureVisibleTab()

browser.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
): Promise<string>

截取指定窗口中当前活动标签页的可见区域。为了调用此方法，扩展程序必须具有 <all_urls> 权限或 activeTab 权限。除了扩展程序通常可以访问的网站之外，此方法还允许扩展程序捕获原本受限的敏感网站，包括 chrome:-scheme 页面、其他扩展程序的页面和 data: 网址。这些敏感网站只能通过 activeTab 权限捕获。只有在扩展程序已被授予文件访问权限的情况下，系统才会捕获文件网址。

参数

windowId

number 可选

目标窗口。默认为当前窗口。
选项

ImageDetails 可选

Promise<string>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

connect()

browser.tabs.connect(
  tabId: number,
  connectInfo?: object,
): runtime.Port

连接到指定标签页中的内容脚本。runtime.onConnect 事件会在当前扩展程序的指定标签页中运行的每个内容脚本中触发。如需了解详情，请参阅内容脚本消息传递。

参数

tabId

数值
connectInfo

对象（可选）
- documentId
  
  字符串可选
  
  Chrome 106+ browser.*（自 Chrome 148 起）
  
  打开一个端口，连接到由 documentId 标识的特定文档，而不是标签页中的所有框架。
- frameId
  
  number 可选
  
  打开一个端口，连接到由 frameId 标识的特定框架，而不是标签页中的所有框架。
- name
  
  字符串可选
  
  对于监听连接事件的内容脚本，此参数会传递到 onConnect。

runtime.Port

可用于与在指定标签页中运行的内容脚本进行通信的端口。如果标签页关闭或不存在，则会触发端口的 runtime.Port 事件。

create()

browser.tabs.create(
  createProperties: object,
): Promise<Tab>

创建新标签页。

参数

createProperties

对象
- 活跃
  
  布尔值（可选）
  
  该标签页是否应成为窗口中的活动标签页。不会影响窗口是否获得焦点（请参阅 windows.update）。默认值为 true。
- 索引
  
  number 可选
  
  标签页在窗口中的位置。提供的值会被限制在 0 到窗口中的标签页数量之间。
- openerTabId
  
  number 可选
  
  打开此标签页的标签页的 ID。如果指定了此属性，则打开者标签页必须与新创建的标签页位于同一窗口中。
- 已固定
  
  布尔值（可选）
  
  是否应固定标签页。默认设置为 false
- 已选择
  
  布尔值（可选）
  
  已弃用
  
  请使用有效。
  该标签页是否应成为窗口中的所选标签页。默认设置为 true
- splitWithTabId
  
  number 可选
  
  Chrome 155 及更高版本
  
  要用于创建拆分视图的现有标签页的 ID。如果指定了“split-with”标签页，则该标签页必须满足以下条件：
  - 该标签页不得是已拆分的标签页。
  - 它必须与新创建的标签页位于同一窗口中。
  - 如果指定了 windowId，则它必须与分屏标签页的窗口 ID 相同。
  - 如果指定了 index，则它必须是与拆分标签页相邻的索引，并且会影响新创建的标签页的相对位置。
- 网址
  
  字符串可选
  
  标签页最初导航到的网址。完全限定网址必须包含架构（即 'http://www.google.com'，而不是 'www.google.com'）。相对网址是相对于扩展程序中的当前网页而言的。默认为“新标签页”页面。
- windowId
  
  number 可选
  
  要在其中创建新标签页的窗口。默认为当前窗口。

Promise<Tab>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

createSplit()

Chrome 155 及更高版本

browser.tabs.createSplit(
  tabIds: [number, number],
): Promise<number>

将两个现有标签页拆分为拆分视图。

参数

tabIds

[number, number]

一个数组，其中包含正好两个要配对到拆分视图中的标签页 ID。所有标签页都必须满足以下条件：

它们必须相邻。这些窗口不得已处于拆分视图中。它们必须具有匹配的 windowId、pinned 和 groupId 状态。

<number>

detectLanguage()

browser.tabs.detectLanguage(
  tabId?: number,
): Promise<string>

检测标签页中内容的主要语言。

参数

tabId

number 可选

默认为当前窗口的活动标签页。

Promise<string>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

discard()

Chrome 54 及更高版本 browser.*（自 Chrome 148 起）

browser.tabs.discard(
  tabId?: number,
): Promise<Tab | undefined>

从内存中舍弃标签页。舍弃的标签页仍会显示在标签栏中，并在激活时重新加载。

参数

tabId

number 可选

要舍弃的标签页的 ID。如果指定了此参数，系统会舍弃该标签页，除非该标签页处于活动状态或已被舍弃。如果省略，浏览器会舍弃最不重要的标签页。如果没有可舍弃的标签页，此操作可能会失败。

Promise<Tab | undefined>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

在操作完成后解析。

duplicate()

browser.tabs.duplicate(
  tabId: number,
): Promise<Tab | undefined>

复制标签页。

参数

tabId

数值

要复制的标签页的 ID。

Promise<Tab | undefined>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

get()

browser.tabs.get(
  tabId: number,
): Promise<Tab>

检索指定标签页的详细信息。

参数

tabId

数值

Promise<Tab>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

getCurrent()

browser.tabs.getCurrent(): Promise<Tab | undefined>

获取发出此脚本调用的标签页。如果从非标签页上下文（例如后台页面或弹出式视图）调用，则返回 undefined。

Promise<Tab | undefined>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

getZoom()

browser.tabs.getZoom(
  tabId?: number,
): Promise<number>

获取指定标签页的当前缩放比例。

参数

tabId

number 可选

要从中获取当前缩放比例的标签页的 ID；默认为当前窗口的活动标签页。

<number>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

在获取标签页的当前缩放比例后，使用该缩放比例进行解析。

getZoomSettings()

browser.tabs.getZoomSettings(
  tabId?: number,
): Promise<ZoomSettings>

获取指定标签页的当前缩放设置。

参数

tabId

number 可选

要从中获取当前缩放设置的标签页的 ID；默认为当前窗口的活动标签页。

Promise<ZoomSettings>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

使用标签页的当前缩放设置进行解析。

goBack()

Chrome 72 及更高版本 browser.*（自 Chrome 148 起）

browser.tabs.goBack(
  tabId?: number,
): Promise<void>

返回上一页（如果有）。

参数

tabId

number 可选

要返回的标签页的 ID；默认为当前窗口中所选的标签页。

承诺<void>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

goForward()

Chrome 72 及更高版本 browser.*（自 Chrome 148 起）

browser.tabs.goForward(
  tabId?: number,
): Promise<void>

前往下一页（如果有）。

参数

tabId

number 可选

要向前导航的标签页的 ID；默认为当前窗口中所选的标签页。

承诺<void>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

group()

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

browser.tabs.group(
  options: object,
): Promise<number>

向指定分组添加一个或多个标签页；如果未指定分组，则将给定标签页添加到新创建的分组。

参数

选项

对象
- createProperties
  
  对象（可选）
  
  用于创建群组的配置。如果已指定 groupId，则无法使用。
  - windowId
    
    number 可选
    
    新群组的窗口。默认为当前窗口。
- groupId
  
  number 可选
  
  要将标签页添加到的分组的 ID。如果未指定，系统将创建一个新群组。
- tabIds
  
  number | [number, …number[]]
  
  要添加到指定分组的标签页 ID 或标签页 ID 列表。

<number>

highlight()

browser.tabs.highlight(
  highlightInfo: object,
): Promise<windows.Window>

突出显示给定标签页，并聚焦于该组中的第一个标签页。如果指定的标签页当前处于活动状态，则此操作似乎不会执行任何操作。

参数

highlightInfo

对象
- tabs
  
  number | number[]
  
  要突出显示的一个或多个标签页索引。
- windowId
  
  number 可选
  
  包含标签页的窗口。

Promise<windows.Window>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

move()

browser.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
): Promise<Tab | Tab[]>

将一个或多个标签页移至其窗口中的新位置或新窗口。请注意，标签页只能在普通窗口 (window.type === "normal") 之间移动。

参数

tabIds

number | number[]

要移动的标签页 ID 或标签页 ID 列表。
moveProperties

对象
- 索引
  
  数值
  
  窗口要移动到的位置。使用 -1 可将标签页放置在窗口末尾。
- windowId
  
  number 可选
  
  默认值为标签页当前所在的窗口。

Promise<Tab | Tab[]>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

query()

browser.tabs.query(
  queryInfo: object,
): Promise<Tab[]>

获取具有指定属性的所有标签页，如果未指定任何属性，则获取所有标签页。

参数

queryInfo

对象
- 活跃
  
  布尔值（可选）
  
  标签页是否在其窗口中处于活动状态。
- audible
  
  布尔值（可选）
  
  Chrome 45 及更高版本 browser.*（自 Chrome 148 起）
  
  标签页是否可听。
- autoDiscardable
  
  布尔值（可选）
  
  Chrome 54 及更高版本 browser.*（自 Chrome 148 起）
  
  指定在资源不足时，浏览器是否可以自动舍弃标签页。
- currentWindow
  
  布尔值（可选）
  
  标签页是否位于当前窗口中。
- 已舍弃
  
  布尔值（可选）
  
  Chrome 54 及更高版本 browser.*（自 Chrome 148 起）
  
  是否舍弃标签页。舍弃的标签页是指其内容已从内存中卸载，但仍显示在标签栏中的标签页。下次激活时，其内容会重新加载。
- 冻结
  
  布尔值（可选）
  
  Chrome 132+ browser.*（自 Chrome 148 起）
  
  标签页是否已冻结。冻结的标签页无法执行任务，包括事件处理脚本或计时器。它会显示在标签栏中，并且其内容会加载到内存中。激活后，该账号会解冻。
- groupId
  
  number 可选
  
  Chrome 88 及更高版本 browser.*（自 Chrome 148 起）
  
  标签页所在分组的 ID，对于未分组的标签页，则为 tabGroups.TAB_GROUP_ID_NONE。
- 突出显示
  
  布尔值（可选）
  
  标签页是否突出显示。
- 索引
  
  number 可选
  
  标签页在其窗口中的位置。
- lastFocusedWindow
  
  布尔值（可选）
  
  标签页是否位于最后聚焦的窗口中。
- 已设为静音
  
  布尔值（可选）
  
  Chrome 45 及更高版本 browser.*（自 Chrome 148 起）
  
  标签页是否已静音。
- 已固定
  
  布尔值（可选）
  
  标签页是否已固定。
- splitViewId
  
  number 可选
  
  Chrome 140 及更高版本 browser.*（自 Chrome 148 起）
  
  标签页所在的拆分视图的 ID，如果标签页不在拆分视图中，则为 tabs.SPLIT_VIEW_ID_NONE。
- 状态
  
  TabStatus 可选
  
  标签页加载状态。
- title
  
  字符串可选
  
  将网页标题与模式进行匹配。如果扩展程序没有该网页的 "tabs" 权限或主机权限，系统会忽略此属性。
- 网址
  
  字符串 | 字符串 [] 可选
  
  将标签页与一个或多个网址格式进行匹配。片段标识符不匹配。如果扩展程序没有该网页的 "tabs" 权限或主机权限，系统会忽略此属性。
- windowId
  
  number 可选
  
  父窗口的 ID，或windows.WINDOW_ID_CURRENT（表示当前窗口）。
- windowType
  
  WindowType 可选
  
  标签页所在的窗口类型。

Promise<Tab[]>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

reload()

browser.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
): Promise<void>

重新加载标签页。

参数

tabId

number 可选

要重新加载的标签页的 ID；默认为当前窗口中所选的标签页。
reloadProperties

对象（可选）
- bypassCache
  
  布尔值（可选）
  
  是否绕过本地缓存。默认为 false。

承诺<void>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

remove()

browser.tabs.remove(
  tabIds: number | number[],
): Promise<void>

关闭一个或多个标签页。

参数

tabIds

number | number[]

要关闭的标签页 ID 或标签页 ID 列表。

承诺<void>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

sendMessage()

browser.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
): Promise<any>

向指定标签页中的内容脚本发送一条消息。系统会在当前扩展程序的指定标签页中运行的每个内容脚本中触发 runtime.onMessage 事件。

参数

tabId

数值
私信

任意

要发送的消息。此消息应为可 JSON 化的对象。
选项

对象（可选）
- documentId
  
  字符串可选
  
  Chrome 106+ browser.*（自 Chrome 148 起）
  
  向由 documentId 标识的特定文档发送消息，而不是向标签页中的所有框架发送消息。
- frameId
  
  number 可选
  
  向由 frameId 标识的特定框架发送消息，而不是向标签页中的所有框架发送消息。

承诺<任何>

Chrome 99 及更高版本 browser.*（自 Chrome 148 起）

Promise，其解析结果为内容脚本的响应。如果连接到指定标签页时出错，promise 将被拒绝。

setZoom()

browser.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
): Promise<void>

缩放指定标签页。

参数

tabId

number 可选

要缩放的标签页的 ID；默认为当前窗口的活动标签页。
zoomFactor

数值

新的缩放比例。如果值为 0，则会将标签页设置为其当前的默认缩放比例。大于 0 的值表示标签页的缩放比例（可能不是默认值）。

承诺<void>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

在缩放比例更改后解析。

setZoomSettings()

browser.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
): Promise<void>

为指定标签页设置缩放设置，这些设置定义了如何处理缩放更改。在标签页中导航时，这些设置会重置为默认值。

参数

tabId

number 可选

要更改缩放设置的标签页的 ID；默认为当前窗口的活动标签页。
zoomSettings

ZoomSettings

定义如何处理缩放更改以及在什么范围内处理。

承诺<void>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

在缩放设置更改后解析。

ungroup()

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

browser.tabs.ungroup(
  tabIds: number | [number, ...number[]],
): Promise<void>

从各自的分组中移除一个或多个标签页。如果任何群组变为空，则会被删除。

参数

tabIds

number | [number, …number[]]

要从各自标签页分组中移除的标签页 ID 或标签页 ID 列表。

承诺<void>

unsplit()

Chrome 155 及更高版本

browser.tabs.unsplit(
  splitViewId: number,
): Promise<void>

将拆分视图中的标签页分离为独立标签页。

参数

splitViewId

数值

要分离的拆分视图的 ID。

承诺<void>

update()

browser.tabs.update(
  tabId?: number,
  updateProperties: object,
): Promise<Tab | undefined>

修改标签页的属性。未在 updateProperties 中指定的属性不会被修改。

参数

tabId

number 可选

默认为当前窗口的所选标签页。
updateProperties

对象
- 活跃
  
  布尔值（可选）
  
  标签页是否应处于活动状态。不会影响窗口是否获得焦点（请参阅 windows.update）。
- autoDiscardable
  
  布尔值（可选）
  
  Chrome 54 及更高版本 browser.*（自 Chrome 148 起）
  
  当资源不足时，浏览器是否应自动舍弃该标签页。
- 突出显示
  
  布尔值（可选）
  
  在当前所选标签页中添加或移除标签页。
- 已设为静音
  
  布尔值（可选）
  
  Chrome 45 及更高版本 browser.*（自 Chrome 148 起）
  
  是否应将标签页静音。
- openerTabId
  
  number 可选
  
  打开此标签页的标签页的 ID。如果指定了此属性，则打开者标签页必须与此标签页位于同一窗口中。
- 已固定
  
  布尔值（可选）
  
  是否应固定标签页。
- 已选择
  
  布尔值（可选）
  
  已弃用
  
  请使用突出显示。
  是否应选择该标签页。
- 网址
  
  字符串可选
  
  标签页要导航到的网址。不支持 JavaScript 网址；请改用 scripting.executeScript。

Promise<Tab | undefined>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

事件

onActivated

browser.tabs.onActivated.addListener(
  callback: function,
)

在窗口中的活动标签页发生变化时触发。请注意，触发此事件时，标签页的网址可能尚未设置，但您可以监听 onUpdated 事件，以便在设置网址时收到通知。

参数

callback

函数

callback 参数如下所示：
```
(activeInfo: object) => void
```
- activeInfo
  
  对象
  - tabId
    
    数值
    
    已变为活动状态的标签页的 ID。
  - windowId
    
    数值
    
    活动标签页发生更改的窗口的 ID。

onAttached

browser.tabs.onAttached.addListener(
  callback: function,
)

当标签页附加到窗口时（例如，在窗口之间移动时）触发。

参数

callback

函数

callback 参数如下所示：
```
(tabId: number, attachInfo: object) => void
```
- tabId
  
  数值
- attachInfo
  
  对象
  - newPosition
    
    数值
  - newWindowId
    
    数值

onCreated

browser.tabs.onCreated.addListener(
  callback: function,
)

在创建标签页时触发。请注意，触发此事件时，可能尚未设置标签页的网址和标签页组归属，但您可以监听 onUpdated 事件，以便在设置网址或将标签页添加到标签页组时收到通知。

参数

callback

函数

callback 参数如下所示：
```
(tab: Tab) => void
```
- Tab
  
  制表符

onDetached

browser.tabs.onDetached.addListener(
  callback: function,
)

当标签页与窗口分离时（例如，在窗口之间移动时）触发。

参数

callback

函数

callback 参数如下所示：
```
(tabId: number, detachInfo: object) => void
```
- tabId
  
  数值
- detachInfo
  
  对象
  - oldPosition
    
    数值
  - oldWindowId
    
    数值

onHighlighted

browser.tabs.onHighlighted.addListener(
  callback: function,
)

当窗口中突出显示或选中的标签页发生变化时触发。

参数

callback

函数

callback 参数如下所示：
```
(highlightInfo: object) => void
```
- highlightInfo
  
  对象
  - tabIds
    
    number[]
    
    窗口中所有突出显示的标签页。
  - windowId
    
    数值
    
    标签页发生更改的窗口。

onMoved

browser.tabs.onMoved.addListener(
  callback: function,
)

在标签页在窗口内移动时触发。系统只会触发一个移动事件，表示用户直接移动的标签页。对于因手动移动标签页而必须移动的其他标签页，系统不会触发移动事件。在窗口之间移动标签页时，不会触发此事件；如需了解详情，请参阅 tabs.onDetached。

参数

callback

函数

callback 参数如下所示：
```
(tabId: number, moveInfo: object) => void
```
- tabId
  
  数值
- moveInfo
  
  对象
  - fromIndex
    
    数值
  - toIndex
    
    数值
  - windowId
    
    数值

onRemoved

browser.tabs.onRemoved.addListener(
  callback: function,
)

在标签页关闭时触发。

参数

callback

函数

callback 参数如下所示：
```
(tabId: number, removeInfo: object) => void
```
- tabId
  
  数值
- removeInfo
  
  对象
  - isWindowClosing
    
    布尔值
    
    如果标签页因其父窗口关闭而关闭，则为 true。
  - windowId
    
    数值
    
    标签页已关闭的窗口。

onReplaced

browser.tabs.onReplaced.addListener(
  callback: function,
)

当标签页因预渲染或即时加载而被另一个标签页替换时触发。

参数

callback

函数

callback 参数如下所示：
```
(addedTabId: number, removedTabId: number) => void
```
- addedTabId
  
  数值
- removedTabId
  
  数值

onUpdated

browser.tabs.onUpdated.addListener(
  callback: function,
)

在标签页更新时触发。

参数

callback

函数

callback 参数如下所示：
```
(tabId: number, changeInfo: object, tab: Tab) => void
```
- tabId
  
  数值
- changeInfo
  
  对象
  - audible
    
    布尔值（可选）
    
    Chrome 45 及更高版本 browser.*（自 Chrome 148 起）
    
    标签页的新有声状态。
  - autoDiscardable
    
    布尔值（可选）
    
    Chrome 54 及更高版本 browser.*（自 Chrome 148 起）
    
    标签页的新自动舍弃状态。
  - 已舍弃
    
    布尔值（可选）
    
    Chrome 54 及更高版本 browser.*（自 Chrome 148 起）
    
    标签页的新舍弃状态。
  - favIconUrl
    
    字符串可选
    
    标签页的新网站图标网址。
  - 冻结
    
    布尔值（可选）
    
    Chrome 132+ browser.*（自 Chrome 148 起）
    
    标签页的新冻结状态。
  - groupId
    
    number 可选
    
    Chrome 88 及更高版本 browser.*（自 Chrome 148 起）
    
    标签页的新分组。
  - mutedInfo
    
    MutedInfo 可选
    
    Chrome 46 及更高版本 browser.*（自 Chrome 148 起）
    
    标签页的新静音状态以及更改原因。
  - 已固定
    
    布尔值（可选）
    
    标签页的新固定状态。
  - splitViewId
    
    number 可选
    
    Chrome 140 及更高版本 browser.*（自 Chrome 148 起）
    
    标签页的新拆分视图。
  - 状态
    
    TabStatus 可选
    
    标签页的加载状态。
  - title
    
    字符串可选
    
    Chrome 48+ browser.*（自 Chrome 148 起）
    
    标签页的新标题。
  - 网址
    
    字符串可选
    
    标签页的网址（如果已更改）。
- Tab
  
  制表符

onZoomChange

browser.tabs.onZoomChange.addListener(
  callback: function,
)

在标签页缩放时触发。

参数

callback

函数

callback 参数如下所示：
```
(ZoomChangeInfo: object) => void
```
- ZoomChangeInfo
  
  对象
  - newZoomFactor
    
    数值
  - oldZoomFactor
    
    数值
  - tabId
    
    数值
  - zoomSettings
    
    ZoomSettings

browser.tabs 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

说明

权限

使用场景

在新标签页中打开扩展程序页面

获取当前标签页

将指定标签页静音

点击后将当前标签页移至第一个位置

向所选标签页的内容脚本传递消息

扩展程序示例

类型

MutedInfo

属性

MutedInfoReason

枚举

Tab

属性

TabStatus

枚举

WindowType

枚举

ZoomSettings

属性

ZoomSettingsMode

枚举

ZoomSettingsScope

枚举

属性

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

值

SPLIT_VIEW_ID_NONE

值

TAB_ID_NONE

值

TAB_INDEX_NONE

值

方法

captureVisibleTab()

参数

返回

connect()

参数

返回

create()

参数

返回

createSplit()

参数

返回

detectLanguage()

参数

返回

discard()

参数

返回

duplicate()

参数

返回

get()

参数

返回

getCurrent()

返回

getZoom()

参数

返回

getZoomSettings()

参数

返回

goBack()

参数

返回

goForward()

参数

返回

group()

参数

返回

highlight()

参数

browser.tabs