chrome.tabs

说明

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

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

权限

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

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

“标签页”权限

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

{
  "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"
    });
  }
});

获取当前标签页

此示例演示了扩展程序的 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 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.");
      }
    });
  }

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

此示例演示了扩展程序的 Service Worker 如何使用 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。如果扩展程序不是上次更改静音状态的原因，则未设置。

  • 已设为静音

    boolean

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

  • 原因

    MutedInfoReason（可选）

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

MutedInfoReason

Chrome 46 及更高版本

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

枚举

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

"capture"
标签页捕获已开始，强制设为静音状态。

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

Tab

属性

  • 活跃

    boolean

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

  • audible

    布尔值 选填

    Chrome 45 及更高版本

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

  • autoDiscardable

    boolean

    Chrome 54 及更高版本

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

  • 已舍弃

    boolean

    Chrome 54 及更高版本

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

  • favIconUrl

    字符串（可选）

    标签页的网站图标的网址。仅当扩展程序的清单包含 "tabs" 权限时，此属性才会显示。如果正在加载标签页，该标识符也可能是空字符串。

  • groupId

    number

    Chrome 88 及更高版本

    标签页所属的群组的 ID。

  • 高度

    数字可选

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

  • 突出显示

    boolean

    是否突出显示标签页。

  • id

    数字可选

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

  • 无痕模式

    boolean

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

  • 索引

    number

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

  • lastAccessed

    数字可选

    Chrome 121 及更高版本

    上次访问标签页的时间，以自纪元以来的毫秒数表示。

  • mutedInfo

    MutedInfo 可选

    Chrome 46 及更高版本

    标签页的静音状态以及上次状态发生变化的原因。

  • openerTabId

    数字可选

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

  • pendingUrl

    字符串（可选）

    Chrome 79 及更高版本

    在标签页提交之前，标签页要导航到的网址。仅当扩展程序的清单包含 "tabs" 权限且存在待处理的导航时，此属性才会显示。

  • 已置顶

    boolean

    是否固定标签页。

  • 已选择

    boolean

    已废弃

    请使用 tabs.Tab.highlighted。

    是否选中标签页。

  • sessionId

    字符串（可选）

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

  • status

    TabStatus 可选

    标签页的加载状态。

  • title

    字符串（可选）

    标签的标题。仅当扩展程序的清单包含 "tabs" 权限时，此属性才会显示。

  • 网址

    字符串（可选）

    标签页主框架的最后提交网址。仅当扩展程序的清单包含 "tabs" 权限时，此属性才会显示；如果标签页尚未提交，此属性可能为空字符串。另请参阅 Tab.pendingUrl。

  • 宽度

    数字可选

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

  • windowId

    number

    包含标签页的窗口的 ID。

TabStatus

Chrome 44 及更高版本

标签页的加载状态。

枚举

"loading"

WindowType

Chrome 44 及更高版本

窗口类型。

枚举

"normal"

"popup"

"devtools"

ZoomSettings

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

属性

  • defaultZoomFactor

    数字可选

    Chrome 43 及更高版本

    用于在调用 tab.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的缩放更改会与原点一同保存，这意味着当用户导航到同一来源的其他网页时，这些网页都将会缩放至相同的缩放比例。per-origin 范围仅在 automatic 模式下可用。

"per-tab"
缩放更改仅会在此标签页中生效，在其他标签页中进行缩放更改不会影响此标签页的缩放设置。此外，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

    数字可选

    目标窗口。默认值为当前窗口。

  • 选项

    ImageDetails 可选

  • callback

    函数（可选）

    callback 参数如下所示：

    (dataUrl: string)=>void

    • dataUrl

      string

      对捕获的标签页的可见区域的图片进行编码的数据网址。可以分配给 HTML img 元素的“src”属性，以供显示。

返回

  • Promise<string>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

connect()

chrome.tabs.connect(
  tabId: number,
  connectInfo?: object,
)

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

参数

  • tabId

    number

  • connectInfo

    对象（可选）

    • documentId

      字符串（可选）

      Chrome 106 及更高版本

      打开一个指向由 documentId 标识的特定文档（而不是标签页中的所有框架）的端口。

    • frameId

      数字可选

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

    • name

      字符串（可选）

      对于正在监听连接事件的内容脚本，系统会将此参数传入 onConnect。

返回

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

create()

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

创建新标签页。

参数

  • createProperties

    对象

    • 活跃

      布尔值 选填

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

    • 索引

      数字可选

      标签页在窗口中应占据的位置。提供的值介于 0 和窗口中的制表符数量之间。

    • openerTabId

      数字可选

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

    • 已置顶

      布尔值 选填

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

    • 已选择

      布尔值 选填

      已废弃

      请使用 active。

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

    • 网址

      字符串（可选）

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

    • windowId

      数字可选

      要在其中创建新标签页的窗口。默认值为当前窗口。

  • callback

    函数（可选）

    callback 参数如下所示：

    (tab: Tab)=>void

    • 标签页

      制表符

      已创建的标签页。

返回

  • Promise<Tab>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

detectLanguage()

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

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

参数

  • tabId

    数字可选

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (language: string)=>void

    • language

      string

      ISO 语言代码，例如 en 或 fr。如需查看此方法支持的语言的完整列表，请参阅 kLanguageInfoTable。系统会检查第二至第四列，并返回第一个非 NULL 值，但会返回 zh-CN 的简体中文。对于未知/未定义的语言，会返回 und。

返回

  • Promise<string>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

discard()

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

从内存中舍弃标签页。已舍弃的标签页仍会在标签页栏中显示，并会在启用后重新加载。

参数

  • tabId

    数字可选

    要舍弃的标签页的 ID。如果指定，则该标签页会被舍弃，除非它处于有效状态或已被舍弃。如果省略，浏览器会舍弃最不重要的标签页。如果不存在可舍弃的标签页，则可能会失败。

  • callback

    函数（可选）

    callback 参数如下所示：

    (tab?: Tab)=>void

    • 标签页

      Tab 可选

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

返回

  • Promise<制表符|未定义>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

duplicate()

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

复制标签页。

参数

  • tabId

    number

    要复制的标签页的 ID。

  • callback

    函数（可选）

    callback 参数如下所示：

    (tab?: Tab)=>void

    • 标签页

      Tab 可选

      有关所复制标签页的详细信息。如果未请求 "tabs" 权限，则 tabs.Tab 对象不包含 url、pendingUrl、title 和 favIconUrl。

返回

  • Promise<制表符|未定义>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

executeScript()

Promise &leq; MV2 从 Chrome 91 开始已废弃
chrome.tabs.executeScript(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

在 Manifest V3 中已替换为 scripting.executeScript。

将 JavaScript 代码注入网页。如需了解详情，请参阅内容脚本文档的程序化注入部分。

参数

  • tabId

    数字可选

    要在其中运行脚本的标签页的 ID；默认为当前窗口的活动标签页。

  • 明细

    InjectDetails

    要运行的脚本的详细信息。必须设置代码或文件属性，但不能同时设置这两者。

  • callback

    函数（可选）

    callback 参数如下所示：

    (result?: any[])=>void

    • 结果

      any[] 可选属性

      每个注入帧中的脚本结果。

返回

  • 承诺<any[]|undefined>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

get()

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

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

参数

  • tabId

    number

  • callback

    函数（可选）

    callback 参数如下所示：

    (tab: Tab)=>void

返回

  • Promise<Tab>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getAllInWindow()

Promise &leq; MV2 已废弃
chrome.tabs.getAllInWindow(
  windowId?: number,
  callback?: function,
)

请使用 tabs.query {windowId: windowId}。

获取指定窗口中所有标签页的详细信息。

参数

  • windowId

    数字可选

    默认值为当前窗口。

  • callback

    函数（可选）

    callback 参数如下所示：

    (tabs: Tab[])=>void

    • 标签页

      Tab[]

返回

  • Promise<Tab[]>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getCurrent()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (tab?: Tab)=>void

    • 标签页

      Tab 可选

返回

  • Promise<制表符|未定义>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getSelected()

Promise &leq; MV2 已废弃
chrome.tabs.getSelected(
  windowId?: number,
  callback?: function,
)

请使用 tabs.query {active: true}。

获取在指定窗口中选择的标签页。

参数

  • windowId

    数字可选

    默认值为当前窗口。

  • callback

    函数（可选）

    callback 参数如下所示：

    (tab: Tab)=>void

返回

  • Promise<Tab>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getZoom()

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

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

参数

  • tabId

    数字可选

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (zoomFactor: number)=>void

    • zoomFactor

      number

      标签页的当前缩放比例。

返回

  • Promise<数字>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getZoomSettings()

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

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

参数

  • tabId

    数字可选

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (zoomSettings: ZoomSettings)=>void

    • zoomSettings

      ZoomSettings

      标签页的当前缩放设置。

返回

  • Promise<ZoomSettings>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

goBack()

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

返回到上一页（如果有）。

参数

  • tabId

    数字可选

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

goForward()

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

跳转到下一页（如果有）。

参数

  • tabId

    数字可选

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

group()

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

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

参数

  • 选项

    对象

    • createProperties

      对象（可选）

      用于创建群组的配置。如果已指定 groupId，则不能使用。

      • windowId

        数字可选

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

    • groupId

      数字可选

      要向其中添加标签页的组的 ID。如果未指定，则会创建一个新组。

    • tabIds

      数字|[数字,...数字 []]

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (groupId: number)=>void

    • groupId

      number

      添加了标签页的群组的 ID。

返回

  • Promise<数字>

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

highlight()

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

突出显示给定标签页，并将焦点置于组的第一个标签页上。如果指定的标签页当前处于活动状态，这个选项看起来不会执行任何操作。

参数

  • highlightInfo

    对象

    • 标签页

      数字|数字 []

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

    • windowId

      数字可选

      包含标签页的窗口。

  • callback

    函数（可选）

    callback 参数如下所示：

    (window: Window)=>void

    • 窗口

      窗户

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

返回

  • Promise<windows.Window>windows.Window

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

insertCSS()

Promise &leq; MV2 从 Chrome 91 开始已废弃
chrome.tabs.insertCSS(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

在 Manifest V3 中已替换为 scripting.insertCSS。

将 CSS 注入网页中。可以使用 scripting.removeCSS 移除通过此方法插入的样式。如需了解详情，请参阅内容脚本文档的程序化注入部分。

参数

  • tabId

    数字可选

    要在其中插入 CSS 的标签页的 ID；默认为当前窗口的活动标签页。

  • 明细

    InjectDetails

    要插入的 CSS 文本的详细信息。必须设置代码或文件属性，但不能同时设置这两者。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

move()

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

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

参数

  • tabIds

    数字|数字 []

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

  • moveProperties

    对象

    • 索引

      number

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

    • windowId

      数字可选

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

  • callback

    函数（可选）

    callback 参数如下所示：

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

    • 标签页

      Tab|Tab[]

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

返回

  • Promise<Tab|Tab[]>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

query()

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

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

参数

  • queryInfo

    对象

    • 活跃

      布尔值 选填

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

    • audible

      布尔值 选填

      Chrome 45 及更高版本

      标签页是否可听。

    • autoDiscardable

      布尔值 选填

      Chrome 54 及更高版本

      当资源不足时，浏览器是否会自动舍弃这些标签页。

    • currentWindow

      布尔值 选填

      标签页是否在当前窗口中。

    • 已舍弃

      布尔值 选填

      Chrome 54 及更高版本

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

    • groupId

      数字可选

      Chrome 88 及更高版本

      标签页所属的群组的 ID，如果标签页未分组，则为 tabGroups.TAB_GROUP_ID_NONE。

    • 突出显示

      布尔值 选填

      是否突出显示标签页。

    • 索引

      数字可选

      标签页在窗口中的位置。

    • lastFocusedWindow

      布尔值 选填

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

    • 已设为静音

      布尔值 选填

      Chrome 45 及更高版本

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

    • 已置顶

      布尔值 选填

      是否固定标签页。

    • status

      TabStatus 可选

      标签页加载状态。

    • title

      字符串（可选）

      将网页标题与格式进行匹配。如果扩展程序没有 "tabs" 权限，系统会忽略此属性。

    • 网址

      string|string[] optional

      将标签页与一个或多个网址格式进行匹配。fragment 标识符不匹配。如果扩展程序没有 "tabs" 权限，系统会忽略此属性。

    • windowId

      数字可选

      父窗口的 ID，或 windows.WINDOW_ID_CURRENT（对应于当前窗口）。

    • windowType

      WindowType（可选）

      标签页所在的窗口类型。

  • callback

    函数（可选）

    callback 参数如下所示：

    (result: Tab[])=>void

返回

  • Promise<Tab[]>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

reload()

Promise 
chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
  callback?: function,
)

重新加载标签页。

参数

  • tabId

    数字可选

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

  • reloadProperties

    对象（可选）

    • bypassCache

      布尔值 选填

      是否绕过本地缓存。默认为 false。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

remove()

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

关闭一个或多个标签页。

参数

  • tabIds

    数字|数字 []

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeCSS()

Promise Chrome 87 及更高版本 &leq; MV2 从 Chrome 91 开始弃用
chrome.tabs.removeCSS(
  tabId?: number,
  details: DeleteInjectionDetails,
  callback?: function,
)

在 Manifest V3 中已替换为 scripting.removeCSS。

从之前通过调用 scripting.insertCSS 注入的网页 CSS 中移除。

参数

  • tabId

    数字可选

    要从中移除 CSS 的标签页的 ID；默认为当前窗口的活动标签页。

  • 要移除的 CSS 文本的详细信息。必须设置代码或文件属性，但不能同时设置这两者。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

sendMessage()

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

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

参数

  • tabId

    number

  • 信息

    任意

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

  • 选项

    对象（可选）

    • documentId

      字符串（可选）

      Chrome 106 及更高版本

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

    • frameId

      数字可选

      向由 frameId 标识的特定框架（而不是标签页中的所有框架）发送消息。

  • callback

    函数（可选）

    Chrome 99 及更高版本

    callback 参数如下所示：

    (response: any)=>void

    • 条回复

      任意

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

返回

  • 承诺<any>

    Chrome 99 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

sendRequest()

Promise &leq; MV2 已废弃
chrome.tabs.sendRequest(
  tabId: number,
  request: any,
  callback?: function,
)

请使用 runtime.sendMessage。

向指定标签页中的内容脚本发送单个请求，并在发回响应时运行可选的回调。在当前扩展程序的指定标签页中运行的每个内容脚本中都会触发 extension.onRequest 事件。

参数

  • tabId

    number

  • request

    任意

  • callback

    函数（可选）

    Chrome 99 及更高版本

    callback 参数如下所示：

    (response: any)=>void

    • 条回复

      任意

      请求的处理程序发送的 JSON 响应对象。如果在连接到指定标签页时出错，系统将在不使用任何参数的情况下调用该回调函数，并将 runtime.lastError 设置为错误消息。

返回

  • 承诺<any>

    Chrome 99 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setZoom()

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

缩放指定的标签页。

参数

  • tabId

    数字可选

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

  • zoomFactor

    number

    新的缩放比例。值为 0 可将标签页设置为其当前的默认缩放比例。大于 0 的值会为标签页指定（可能是非默认）缩放比例。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setZoomSettings()

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

用于设定指定标签的缩放设置，从而指定处理缩放更改的方式。在浏览该标签页时，这些设置会重置为默认值。

参数

  • tabId

    数字可选

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

  • zoomSettings

    ZoomSettings

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

ungroup()

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

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

参数

  • tabIds

    数字|[数字,...数字 []]

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

update()

Promise 
chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
  callback?: function,
)

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

参数

  • tabId

    数字可选

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

  • updateProperties

    对象

    • 活跃

      布尔值 选填

      标签页是否应处于活动状态。不影响窗口是否已聚焦（请参阅 windows.update）。

    • autoDiscardable

      布尔值 选填

      Chrome 54 及更高版本

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

    • 突出显示

      布尔值 选填

      在当前所选内容中添加或移除标签页。

    • 已设为静音

      布尔值 选填

      Chrome 45 及更高版本

      是否应将标签页静音。

    • openerTabId

      数字可选

      打开此标签页的标签页的 ID。如果指定，则打开方式标签页必须与此标签页位于同一窗口中。

    • 已置顶

      布尔值 选填

      是否应固定标签页。

    • 已选择

      布尔值 选填

      已废弃

      请使用突出显示的内容。

      是否应选择标签页。

    • 网址

      字符串（可选）

      标签页导航到的网址。不支持 JavaScript 网址；请改用 scripting.executeScript。

  • callback

    函数（可选）

    callback 参数如下所示：

    (tab?: Tab)=>void

    • 标签页

      Tab 可选

      关于更新后的标签页的详细信息。如果未请求 "tabs" 权限，则 tabs.Tab 对象不包含 url、pendingUrl、title 和 favIconUrl。

返回

  • Promise<制表符|未定义>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onActivated

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    (activeInfo: object)=>void

    • activeInfo

      对象

      • tabId

        number

        已激活的标签页的 ID。

      • windowId

        number

        在其中更改活动标签页的窗口的 ID。

onActiveChanged

&leq; MV2 已废弃
chrome.tabs.onActiveChanged.addListener(
  callback: function,
)

请使用 tabs.onActivated。

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

参数

  • callback

    功能

    callback 参数如下所示：

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

    • tabId

      number

    • selectInfo

      对象

      • windowId

        number

        所选标签页在其中发生更改的窗口的 ID。

onAttached

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

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

参数

  • callback

    功能

    callback 参数如下所示：

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

    • tabId

      number

    • attachInfo

      对象

      • newPosition

        number

      • newWindowId

        number

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

      number

    • detachInfo

      对象

      • oldPosition

        number

      • oldWindowId

        number

onHighlightChanged

&leq; MV2 已废弃
chrome.tabs.onHighlightChanged.addListener(
  callback: function,
)

请使用 tabs.onHighlighted。

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

参数

  • callback

    功能

    callback 参数如下所示：

    (selectInfo: object)=>void

    • selectInfo

      对象

      • tabIds

        数值 []

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

      • windowId

        number

        标签页发生更改的窗口。

onHighlighted

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    (highlightInfo: object)=>void

    • highlightInfo

      对象

      • tabIds

        数值 []

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

      • windowId

        number

        标签页发生更改的窗口。

onMoved

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

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

参数

  • callback

    功能

    callback 参数如下所示：

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

    • tabId

      number

    • moveInfo

      对象

      • fromIndex

        number

      • toIndex

        number

      • windowId

        number

onRemoved

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

在标签页关闭时触发。

参数

  • callback

    功能

    callback 参数如下所示：

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

    • tabId

      number

    • removeInfo

      对象

      • isWindowClosing

        boolean

        当标签页因其父窗口关闭而关闭时为 true。

      • windowId

        number

        标签页已关闭的窗口。

onReplaced

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

在一个标签页因预渲染或即时渲染而被其他标签页替换时触发。

参数

  • callback

    功能

    callback 参数如下所示：

    (addedTabId: number,removedTabId: number)=>void

    • addedTabId

      number

    • removedTabId

      number

onSelectionChanged

&leq; MV2 已废弃
chrome.tabs.onSelectionChanged.addListener(
  callback: function,
)

请使用 tabs.onActivated。

在窗口中的所选标签页发生变化时触发。

参数

  • callback

    功能

    callback 参数如下所示：

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

    • tabId

      number

    • selectInfo

      对象

      • windowId

        number

        所选标签页在其中发生更改的窗口的 ID。

onUpdated

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

在标签页更新时触发。

参数

  • callback

    功能

    callback 参数如下所示：

    (tabId: number,changeInfo: object,tab: Tab)=>void

    • tabId

      number

    • changeInfo

      对象

      • audible

        布尔值 选填

        Chrome 45 及更高版本

        标签页的新可听状态。

      • autoDiscardable

        布尔值 选填

        Chrome 54 及更高版本

        标签页的新可自动舍弃状态。

      • 已舍弃

        布尔值 选填

        Chrome 54 及更高版本

        标签页的新舍弃状态。

      • favIconUrl

        字符串（可选）

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

      • groupId

        数字可选

        Chrome 88 及更高版本

        为标签页新建分组。

      • mutedInfo

        MutedInfo 可选

        Chrome 46 及更高版本

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

      • 已置顶

        布尔值 选填

        标签页的新固定状态。

      • status

        TabStatus 可选

        标签页的加载状态。

      • title

        字符串（可选）

        Chrome 48 及更高版本

        标签的新标题。

      • 网址

        字符串（可选）

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

    • 标签页

      制表符

onZoomChange

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

在标签页缩放时触发。

参数

  • callback

    功能

    callback 参数如下所示：

    (ZoomChangeInfo: object)=>void

    • ZoomChangeInfo

      对象

      • newZoomFactor

        number

      • oldZoomFactor

        number

      • tabId

        number

      • zoomSettings

        ZoomSettings