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

Chrome 46 及更高版本

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

属性

  • extensionId

    字符串（选填）

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

  • 已设为静音

    布尔值

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

  • reason

    MutedInfoReason（可选）

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

MutedInfoReason

Chrome 46 及更高版本

导致静音状态更改的事件。

枚举

“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

Chrome 44 及更高版本

标签页的加载状态。

枚举

"unloaded"

"loading"

"complete"

WindowType

Chrome 44 及更高版本

窗口的类型。

枚举

“normal”

"popup"

"panel"

"app"

"devtools"

ZoomSettings

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

属性

  • defaultZoomFactor

    number 可选

    Chrome 43 及更高版本

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

  • 模式

    ZoomSettingsMode（可选）

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

  • 范围

    ZoomSettingsScope（可选）

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

ZoomSettingsMode

Chrome 44 及更高版本

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

枚举

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

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

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

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

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

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

创建新标签页。

参数

  • createProperties

    对象

    • 活跃

      布尔值（可选）

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

    • 索引

      number 可选

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

    • openerTabId

      number 可选

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

    • 已固定

      布尔值（可选）

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

    • 已选择

      布尔值（可选）

      已废弃

      请使用有效。

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

    • 网址

      字符串（选填）

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

    • windowId

      number 可选

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab: Tab) => void

返回

  • Promise<标签页>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

detectLanguage()

prometido 
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

      标签页（可选）

      已舍弃的标签页（如果已成功舍弃）；否则为未定义。

返回

  • Promise<Tab | undefined>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

duplicate()

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

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

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

参数

  • tabId

    数值

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab: Tab) => void

返回

  • Promise<标签页>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getCurrent()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab?: Tab) => void

返回

  • Promise<Tab | undefined>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getZoom()

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

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

参数

  • tabId

    number 可选

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (zoomFactor: number) => void

    • zoomFactor

      数值

      标签页的当前缩放比例。

返回

  • Promise<number>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getZoomSettings()

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

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

prometido 
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

    • 标签页

      Tab | Tab[]

      有关已移动标签页的详细信息。

返回

  • Promise<Tab | Tab[]>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

query()

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

    • 突出显示

      布尔值（可选）

      标签页是否突出显示。

    • 索引

      number 可选

      标签页在窗口中的位置。

    • lastFocusedWindow

      布尔值（可选）

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

    • 已设为静音

      布尔值（可选）

      Chrome 45 及更高版本

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

    • 已固定

      布尔值（可选）

      标签页是否已固定。

    • 状态

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

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

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

关闭一个或多个标签页。

参数

  • tabIds

    number | number[]

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 88 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

sendMessage()

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

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

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

prometido 
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

        字符串（选填）

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

      • 已冻结

        布尔值（可选）

        待处理

        标签页的新冻结状态。

      • 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

        ZoomSettings