chrome.tabs

说明

使用 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()、scripting.executeScript()、scripting.insertCSS() 和 scripting.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() 与特定浏览器标签页中的内容脚本进行通信。

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

Chrome 46 及更高版本

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

属性

  • extensionId

    字符串（选填）

    更改静音状态的扩展服务的 ID。如果扩展程序不是静音状态上次更改的原因，则不设置。

  • 已设为静音

    布尔值

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

  • reason

    MutedInfoReason 可选

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

MutedInfoReason

Chrome 46 及更高版本

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

枚举

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

“捕获”
标签页捕获已开始，强制更改为静音状态。

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

Tab

属性

  • 活跃

    布尔值

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

  • audible

    布尔值（可选）

    Chrome 45 及更高版本

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

  • autoDiscardable

    布尔值

    Chrome 54 及更高版本

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

  • 已舍弃

    布尔值

    Chrome 54 及更高版本

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

  • favIconUrl

    字符串（选填）

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

  • 已冻结

    布尔值

    Chrome 132 及更高版本

    标签页是否处于冻结状态。冻结的标签页无法执行任务，包括事件处理脚本��计时器。它会显示在标签页栏中，并且其内容会加载到内存中。激活后，会员资格将恢复正常。

  • 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。

  • status

    TabStatus 可选

    标签页的加载状态。

  • title

    字符串（选填）

    标签页的标题。仅当扩展程序具有 "tabs" 权限或具有网页的宿主权限时，才会显示此属性。

  • 网址

    字符串（选填）

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

  • width

    number 可选

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

  • windowId

    数值

    包含相应标签页的窗口的 ID。

TabStatus

Chrome 44 及更高版本

标签页的加载状态。

枚举

“unloaded”

“正在加载”

“complete”

WindowType

Chrome 44 及更高版本

窗口类型。

枚举

“normal”

“弹出式”

“面板”

“应用”

"devtools"

ZoomSettings

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

属性

  • defaultZoomFactor

    number 可选

    Chrome 43 及更高版本

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

  • 模式

    ZoomSettingsMode 可选

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

  • 范围

    ZoomSettingsScope 可选

    定义缩放更改是否会保留到相应网页的来源，���是仅在此标签页中生效；在 automatic 模式下默认为 per-origin，否则为 per-tab。

ZoomSettingsMode

Chrome 44 及更高版本

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

枚举

“自动”
缩放更改由浏览器自动处理。

“手动”
替换自动处理缩放更改。系统仍会调度 onZoomChange 事件，扩展程序有责任监听此事件并手动缩放网页。此模式不支持 per-origin 缩放，因此会忽略 scope 缩放设置并假定为 per-tab。

“已停用”
停用标签页中的所有缩放功能。相应标签页会恢复为默认缩放级别，并且系统会忽略所有尝试进行的缩放更改。

ZoomSettingsScope

Chrome 44 及更高版本

定义缩放更改是否会保留到相应网页的来源，还是仅在此标签页中生效；在 automatic 模式下默认为 per-origin，否则为 per-tab。

枚举

“按来源”
缩放更改会保留在缩放网页的来源中，也就是说，导航到同一来源的所有其他标签页也会缩放。此外，per-origin 缩放更改会与来源一起保存，这意味着当导航到同一来源中的其他网页时，所有网页都会缩放到相同的缩放系数。per-origin 作用域仅在 automatic 模式下可用。

“按标签页”
缩放更改仅在此标签页中生效，其他标签页中的缩放更改不会影响此标签页的缩放。此外，per-tab 缩放比例会在导航时重置；导航标签页始终会加载具有 per-origin 缩放因子的网页。

属性

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Chrome 92 及更高版本

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

值

2

TAB_ID_NONE

Chrome 46 及更高版本

表示没有浏览器标签页的 ID。

值

-1

TAB_INDEX_NONE

Chrome 123 及更高版本

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

值

-1

方法

captureVisibleTab()

Promise 
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

    对象（可选）

    • documentId

      字符串（选填）

      Chrome 106 及更高版本

      打开由 documentId 标识的特定文档的端口，而不是标签页中的所有框架。

    • frameId

      number 可选

      打开由 frameId 标识的特定框架的端口，而不是标签页中的所有框架。

    • name

      字符串（选填）

      传递给正在监听连接事件的内容脚本的 onConnect。

返回

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

create()

Promise 
chrome.tabs.create(
  createProperties: object,
  callback?: function,
)

创建新标签页。

参数

  • createProperties

    对象

    • 活跃

      布尔值（可选）

      相应标签页是否应成为窗口中的活动标签页。不影响窗口是否获得焦点（请参阅 windows.update）。默认值为 true。

    • 索引

      number 可选

      标签页在窗口中应占据的位置。提供的值会被限制在 0 到窗口中的标签页数量之间。

    • openerTabId

      number 可选

      打开此标签页的标签页的 ID。如果指定，打开程序标签页必须与新创建的标签页位于同一窗口中。

    • 已固定

      布尔值（可选）

      相应标签页是否应固定。默认设置为 false

    • 已选择

      布尔值（可选）

      已弃用

      请使用 active。

      相应标签页是否应成为窗口中的所选标签页。默认设置为 true

    • 网址

      字符串（选填）

      标签页最初导航到的网址。完全限定网址必须包含方案（即 “http://www.google.com”，而不是“www.google.com”）。相对网址相对于扩展程序中的当前网页。默认为“新标签页”。

    • windowId

      number 可选

      用于创建新标签页的窗口。默认为当前窗口。

  • callback

    函数 可选

    callback 参数如下所示： 

    (tab: Tab) => void

返回

  • Promise<Tab>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

detectLanguage()

Promise 
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()

Promise Chrome 54 及更高版本 
chrome.tabs.discard(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    number 可选

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

  • callback

    函数 可选

    callback 参数如下所示： 

    (tab?: Tab) => void

    • Tab

      标签页 可选

      如果成功舍弃，则为舍弃的标签页；否则为 undefined。

返回

  • Promise<Tab | undefined>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

duplicate()

Promise 
chrome.tabs.duplicate(
  tabId: number,
  callback?: function,
)

复制标签页。

参数

  • tabId

    数值

    要复制的标签页的 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (tab?: Tab) => void

    • Tab

      标签页 可选

      有关复制标签页的详细信息。只有当扩展程序具有 "tabs" 权限或具有网页的宿主权限时，tabs.Tab 对象中才会包含 url、pendingUrl、title 和 favIconUrl 属性。

返回

  • Promise<Tab | undefined>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

get()

Promise 
chrome.tabs.get(
  tabId: number,
  callback?: function,
)

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

参数

  • tabId

    数值

  • callback

    函数 可选

    callback 参数如下所示： 

    (tab: Tab) => void

返回

  • Promise<Tab>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

getCurrent()

Promise 
chrome.tabs.getCurrent(
  callback?: function,
)

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

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    (tab?: Tab) => void

返回

  • Promise<Tab | undefined>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

getZoom()

Promise 
chrome.tabs.getZoom(
  tabId?: number,
  callback?: function,
)

获取指定标签页的当前缩放系数。

参数

  • tabId

    number 可选

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

  • callback

    函数 可选

    callback 参数如下所示： 

    (zoomFactor: number) => void

    • zoomFactor

      数值

      标签页的当前缩放比例。

返回

  • Promise<number>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

getZoomSettings()

Promise 
chrome.tabs.getZoomSettings(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    number 可选

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

  • callback

    函数 可选

    callback 参数如下所示： 

    (zoomSettings: ZoomSettings) => void

    • zoomSettings

      ZoomSettings

      标签页的当前缩放设置。

返回

  • Promise<ZoomSettings>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

goBack()

Promise Chrome 72 及更高版本 
chrome.tabs.goBack(
  tabId?: number,
  callback?: function,
)

返回上一页（如果有）。

参数

  • tabId

    number 可选

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

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

goForward()

Promise Chrome 72 及更高版本 
chrome.tabs.goForward(
  tabId?: number,
  callback?: function,
)

前往下一页（如果有）。

参数

  • tabId

    number 可选

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

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

group()

Promise Chrome 88 及更高版本 
chrome.tabs.group(
  options: object,
  callback?: function,
)

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

参数

  • 选项

    对象

    • createProperties

      对象（可选）

      用于创建群组的配置。如果已指定 groupId，则无法使用此属性。

      • windowId

        number 可选

        新群组的窗口。默认为当前窗口。

    • groupId

      number 可选

      要将标签页添加到的群组的 ID。如果未指定，系统会创建一个新组。

    • tabIds

      number | [number, ...number[]]

      要添加到指定群组的标签页 ID 或标签页 ID 列表。

  • callback

    函数 可选

    callback 参数如下所示： 

    (groupId: number) => void

    • groupId

      数值

      标签页所添加到的群组的 ID。

返回

  • Promise<number>

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

highlight()

Promise 
chrome.tabs.highlight(
  highlightInfo: object,
  callback?: function,
)

突出显示指定标签页，并将焦点移到第一个标签页。如果指定标签页当前处于活动状态，则看起来不会执行任何操作。

参数

  • highlightInfo

    对象

    • 标签页

      number | number[]

      要突出显示的一个或多个标签页的索引。

    • windowId

      number 可选

      包含标签页的窗口。

  • callback

    函数 可选

    callback 参数如下所示： 

    (window: Window) => void

    • 窗口

      窗口

      包含有关标签页突出显示的窗口的详细信息。

返回

  • Promise<windows.Window>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

move()

Promise 
chrome.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
  callback?: function,
)

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

参数

  • tabIds

    number | number[]

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

  • moveProperties

    对象

    • 索引

      数值

      要将窗口移至的位置。使用 -1 将标签页放置在窗口末尾。

    • windowId

      number 可选

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

  • callback

    函数 可选

    callback 参数如下所示： 

    (tabs: Tab | Tab[]) => void

返回

  • Promise<Tab | Tab[]>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

query()

Promise 
chrome.tabs.query(
  queryInfo: object,
  callback?: function,
)

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

参数

  • queryInfo

    对象

    • 活跃

      布尔值（可选）

      标签页是否在其窗口中处于活动状态。

    • audible

      布尔值（可选）

      Chrome 45 及更高版本

      标签页是否可听。

    • autoDiscardable

      布尔值（可选）

      Chrome 54 及更高版本

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

    • currentWindow

      布尔值（可选）

      标签页是否位于当前窗口中。

    • 已舍弃

      布尔值（可选）

      Chrome 54 及更高版本

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

    • 已冻结

      布尔值（可选）

      Chrome 132 及更高版本

      标签页是否处于冻结状态。冻结的标签页无法执行任务，包括事件处理脚本或计时器。它会显示在标签页栏中，并且其内容会加载到内存中。激活后，会员资格将恢复正常。

    • groupId

      number 可选

      Chrome 88 及更高版本

      标签页所在群组的 ID，或 tabGroups.TAB_GROUP_ID_NONE（对于未分组的标签页）。

    • 突出显示

      布尔值（可选）

      标签页是否突出显示。

    • 索引

      number 可选

      标签页在其窗口中的位置。

    • lastFocusedWindow

      布尔值（可选）

      相应标签页是否位于上次聚焦的窗口中。

    • 已设为静音

      布尔值（可选）

      Chrome 45 及更高版本

      标签页是否处于静音状态。

    • 已固定

      布尔值（可选）

      标签页是否已固定。

    • splitViewId

      number 可选

      待处理

      标签页所在的拆分视图的 ID，如果标签页不在拆分视图中，则为 tabs.SPLIT_VIEW_ID_NONE。

    • status

      TabStatus 可选

      标签页加载状态。

    • title

      字符串（选填）

      根据某种模式匹配网页标题。如果扩展程序没有 "tabs" 权限或网页的宿主权限，则系统会忽略此属性。

    • 网址

      字符串 | 字符串数组 可选

      根据一个或多个 网址 格式匹配标签页。片段标识符不匹配。如果扩展程序没有 "tabs" 权限或网页的宿主权限，则系统会忽略此属性。

    • windowId

      number 可选

      父窗口的 ID，或windows.WINDOW_ID_CURRENT（表示当前窗口）。

    • windowType

      WindowType 可选

      标签页所在的窗口类型。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: Tab[]) => void

返回

  • Promise<Tab[]>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

reload()

Promise 
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()

Promise 
chrome.tabs.remove(
  tabIds: number | number[],
  callback?: function,
)

关闭一个或多个标签页。

参数

  • tabIds

    number | number[]

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

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

sendMessage()

Promise 
chrome.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
  callback?: function,
)

向指定标签页中的内容脚本发送一条消息，并提供一个可选的回调函数，用于在收到响应时运行。runtime.onMessage 事件会在当前扩展程序中指定标签页内运行的每个内容脚本中触发。

参数

  • tabId

    数值

  • 私信

    任意

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

  • 选项

    对象（可选）

    • documentId

      字符串（选填）

      Chrome 106 及更高版本

      向由 documentId 标识的特定文档发送消息，而不是向标签页中的所有框架发送消息。

    • frameId

      number 可选

      向由 frameId 标识的特定帧发送消息，而不是向标签页中的所有帧发送消息。

  • callback

    函数 可选

    Chrome 99 及更高版本

    callback 参数如下所示： 

    (response: any) => void

    • Response

      任意

      消息处理程序发送的 JSON 响应对象。如果在连接到指定标签页时发生错误，系统会调用回调函数，但不带任何实参，并将 runtime.lastError 设置为错误消息。

返回

  • Promise<any>

    Chrome 99 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

setZoom()

Promise 
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()

Promise 
chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
  callback?: function,
)

为指定标签页设置缩放设置，以定义如何处理缩放更改。在标签页之间切换时，这些设置会重置为默认值。

参数

  • tabId

    number 可选

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

  • zoomSettings

    ZoomSettings

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

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

ungroup()

Promise Chrome 88 及更高版本 
chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
  callback?: function,
)

从相应群组中移除一个或多个标签页。如果任何组变为空组，系统会将其删除。

参数

  • tabIds

    number | [number, ...number[]]

    要从相应群组中移除的标签页 ID 或标签页 ID 列表。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，也提供了回调。您无法在同一函数调用中同时使用这两个参数。 相应 promise 会解析为传递给回调的相同类型。

update()

Promise 
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

    • Tab

      标签页 可选

      有关更新后标签页的详细信息。只有当扩展程序具有 "tabs" 权限或具有网页的宿主权限时，tabs.Tab 对象中才会包含 url、pendingUrl、title 和 favIconUrl 属性。

返回

  • 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。

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 事件，以便在设置网址或将标签页添加到标签页分组时收到通知。

参数

  • callback

    函数

    callback 参数如下所示： 

    (tab: Tab) => void

onDetached

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (tabId: number, detachInfo: object) => void

    • tabId

      数值

    • detachInfo

      对象

      • oldPosition

        数值

      • oldWindowId

        数值

onHighlighted

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (highlightInfo: object) => void

    • highlightInfo

      对象

      • tabIds

        number[]

        窗口中所有突出显示的标签页。

      • 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

      数值

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

        字符串（选填）

        标签页的新网站图标网址。

      • 已冻结

        布尔值（可选）

        Chrome 132 及更高版本

        标签页的新冻结状态。

      • groupId

        number 可选

        Chrome 88 及更高版本

        相应标签页的新分组。

      • mutedInfo

        MutedInfo 可选

        Chrome 46 及更高版本

        相应标签页的新静音状态以及更改原因。

      • 已固定

        布尔值（可选）

        相应标签页的新固定状态。

      • splitViewId

        number 可选

        待处理

        标签页的新拆分视图。

      • status

        TabStatus 可选

        标签页的加载状态。

      • title

        字符串（选填）

        Chrome 48 及更高版本

        标签页的新标题。

      • 网址

        字符串（选填）

        标签页的网址（如果已更改）。

    • Tab

      制表符

onZoomChange

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

在标签页缩放时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (ZoomChangeInfo: object) => void

    • ZoomChangeInfo

      对象

      • newZoomFactor

        数值

      • oldZoomFactor

        数值

      • tabId

        数值

      • zoomSettings

        ZoomSettings