chrome.tabs

说明

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

概览

Tabs API 不仅提供操作和管理标签页的功能， 语言，截取屏幕截图，然后 与标签页的内容脚本通信。

权限

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

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

“标签页”权限
此权限不提供对 chrome.tabs 命名空间的访问权限。相反， 授予扩展程序对 4 个扩展调用 tabs.query() 的权限 tabs.Tab 实例上的敏感属性：url、pendingUrl、title 和 favIconUrl。
主机权限
通过主机权限，扩展程序可以读取和查询匹配标签页的四个敏感项 tabs.Tab 属性。他们还可以使用以下方法直接与匹配的标签页互动： 以tabs.captureVisibleTab()的身份， tabs.executeScript()、tabs.insertCSS()和 tabs.removeCSS()。
“activeTab”权限
activeTab 向某个扩展程序授予对当前标签页的临时托管权限 响应用户调用。与主机权限不同，activeTab 不会触发任何警告。

清单

以下示例说明了如何在清单中声明每项权限：

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


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


  {
    "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。如果某个扩展程序不是静音状态上次更改的原因，则未设置。

  • 已设为静音

    布尔值

    是否将标签页静音（阻止播放声音）。即使该标签页未播放或当前未播放声音，也可能会被静音。相当于“静音”正在显示音频指示灯。

  • reason

    MutedInfoReason 可选

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

MutedInfoReason

Chrome 46 及更高版本

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

枚举

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

"capture"
已启动标签页捕获，并强制更改静音状态。

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

Tab

属性

  • 活跃

    布尔值

    标签页是否在窗口中处于活动状态。并不一定意味着窗口已聚焦。

  • audible

    布尔值（可选）

    Chrome 45 及更高版本

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

  • autoDiscardable

    布尔值

    Chrome 54 及更高版本

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

  • 已舍弃

    布尔值

    Chrome 54 及更高版本

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

  • favIconUrl

    字符串（可选）

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

  • groupId

    number

    Chrome 88 及更高版本

    标签页所属分组的 ID。

  • 高度

    编号（选填）

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

  • 突出显示

    布尔值

    用于指明标签页是否处于突出显示状态。

  • id

    编号（选填）

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

  • 无痕模式

    布尔值

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

  • 索引

    number

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

  • lastAccessed

    number

    Chrome 121 及更高版本

    上次访问该标签页的时间，以从公元纪年开始计算的毫秒数表示。

  • mutedInfo

    MutedInfo（可选）

    Chrome 46 及更高版本

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

  • openerTabId

    编号（选填）

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

  • pendingUrl

    字符串（可选）

    Chrome 79 及更高版本

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

  • 已固定

    布尔值

    是否固定标签页。

  • 已选择

    布尔值

    <ph type="x-smartling-placeholder"></ph> 已弃用

    请使用 tabs.Tab.highlighted。

    标签是否处于选中状态。

  • sessionId

    字符串（可选）

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

  • 状态

    TabStatus（可选）

    标签页的加载状态。

  • 标题

    字符串（可选）

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

  • 网址

    字符串（可选）

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

  • width

    编号（选填）

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

  • windowId

    number

    包含标签页的窗口的 ID。

TabStatus

Chrome 44 及更高版本

标签页的加载状态。

枚举

"已卸载"

"正在加载"

"complete"

WindowType

Chrome 44 及更高版本

窗口的类型。

枚举

“normal”

“popup”

"面板"

“应用”

“devtools”

ZoomSettings

定义标签页中缩放更改的处理方式及范围。

属性

  • defaultZoomFactor

    编号（选填）

    Chrome 43 及更高版本

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

  • 模式

    ZoomSettingsMode optional

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

  • 范围

    ZoomSettingsScope 可选

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

ZoomSettingsMode

Chrome 44 及更高版本

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

枚举

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

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
  callback?: function,
)

捕获指定窗口中当前活动标签页的可见区域。要调用此方法，扩展程序必须具有 &lt;all_urls&gt; 权限或 activeTab 权限。除了扩展程序通常可以访问的网站外，此方法还可让扩展程序捕获原本受限的敏感网站，包括“chrome:-scheme”网页、其他扩展程序的以及数据：网址您只能使用 activeTab 权限来捕获这些敏感网站。只有在获得文件访问权限的情况下，系统才能捕获相应文件网址。

参数

  • windowId

    编号（选填）

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

  • 选项

    ImageDetails 可选

  • callback

    函数（可选）

    callback 参数如下所示： 

    (dataUrl: string) => void

    • dataUrl

      字符串

      一个数据网址，用于对所截取标签页的可见区域的图片进行编码。可能会分配给“src”属性，以用于显示 HTML img 元素。

返回

  • 承诺<字符串>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 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()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.create(
  createProperties: object,
  callback?: function,
)

创建新标签页。

参数

  • createProperties

    对象

    • 活跃

      布尔值（可选）

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

    • 索引

      编号（选填）

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

    • openerTabId

      编号（选填）

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

    • 已固定

      布尔值（可选）

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

    • 已选择

      布尔值（可选）

      <ph type="x-smartling-placeholder"></ph> 已弃用

      请使用有效。

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

    • 网址

      字符串（可选）

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

    • windowId

      编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab: Tab) => void

返回

  • Promise<标签页>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

detectLanguage()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.detectLanguage(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (language: string) => void

    • language

      字符串

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

返回

  • 承诺<字符串>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

discard()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 54 及更高版本 
chrome.tabs.discard(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab?: Tab) => void

    • Tab

      Tab（可选）

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

返回

  • Promise<Tab未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

duplicate()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.duplicate(
  tabId: number,
  callback?: function,
)

复制某个标签页。

参数

  • tabId

    number

    要复制的标签页的 ID。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab?: Tab) => void

    • Tab

      Tab（可选）

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

返回

  • Promise<Tab未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

executeScript()

<ph type="x-smartling-placeholder"></ph> 承诺 &amp;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[] 选填

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

返回

  • Promise&lt;any[] |未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

get()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.get(
  tabId: number,
  callback?: function,
)

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

参数

  • tabId

    number

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab: Tab) => void

返回

  • Promise<标签页>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getAllInWindow()

<ph type="x-smartling-placeholder"></ph> 承诺 &amp;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，其他平台需要使用回调。

getCurrent()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.getCurrent(
  callback?: function,
)

获取要执行此脚本调用的标签。如果是从非标签页上下文（例如，背景页面或弹出式视图）调用，会返回 undefined。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab?: Tab) => void

    • Tab

      Tab（可选）

返回

  • Promise<Tab未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getSelected()

<ph type="x-smartling-placeholder"></ph> 承诺 &amp;leq;MV2 已弃用
chrome.tabs.getSelected(
  windowId?: number,
  callback?: function,
)

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

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

参数

  • windowId

    编号（选填）

    默认为当前窗口。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab: Tab) => void

返回

  • Promise<标签页>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getZoom()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.getZoom(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (zoomFactor: number) => void

    • zoomFactor

      number

      标签页的当前缩放比例。

返回

  • Promise&lt;number&gt;

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getZoomSettings()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.getZoomSettings(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (zoomSettings: ZoomSettings) => void

    • zoomSettings

      ZoomSettings

      标签页的当前缩放设置。

返回

  • Promise&lt;ZoomSettings&gt;

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

goBack()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 72 及更高版本 
chrome.tabs.goBack(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

goForward()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 72 及更高版本 
chrome.tabs.goForward(
  tabId?: number,
  callback?: function,
)

前往下一页（如果有）。

参数

  • tabId

    编号（选填）

    要前进的标签页的 ID；默认为当前窗口的选定标签页。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

group()

<ph type="x-smartling-placeholder"></ph> 承诺 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&lt;number&gt;

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

highlight()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.highlight(
  highlightInfo: object,
  callback?: function,
)

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

参数

  • highlightInfo

    对象

    • 标签页

      数字 |数值 []

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

    • windowId

      编号（选填）

      包含标签页的窗口。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (window: Window) => void

    • 窗口

      窗口

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

返回

  • Promise&lt;windows.Window&gt;

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

insertCSS()

<ph type="x-smartling-placeholder"></ph> 承诺 &amp;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

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

move()

<ph type="x-smartling-placeholder"></ph> 承诺 
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<TabTab[]>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

query()

<ph type="x-smartling-placeholder"></ph> 承诺 
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 及更高版本

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

    • 已固定

      布尔值（可选）

      是否固定标签页。

    • 状态

      TabStatus（可选）

      标签页加载状态。

    • 标题

      字符串（可选）

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

    • 网址

      string |string[] 选填

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

    • windowId

      编号（选填）

      父窗口的 ID，或当前窗口的 windows.WINDOW_ID_CURRENT。

    • windowType

      WindowType 选填

      标签页所在的窗口类型。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: Tab[]) => void

    • 结果

      Tab 键 []

返回

  • Promise<Tab[]>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

reload()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
  callback?: function,
)

重新加载标签页。

参数

  • tabId

    编号（选填）

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

  • reloadProperties

    对象（可选）

    • bypassCache

      布尔值（可选）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

remove()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.remove(
  tabIds: number | number[],
  callback?: function,
)

关闭一个或多个标签页。

参数

  • tabIds

    数字 |数值 []

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

removeCSS()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 87 及更高版本 &amp;leq;MV2 自 Chrome 91 起弃用
chrome.tabs.removeCSS(
  tabId?: number,
  details: DeleteInjectionDetails,
  callback?: function,
)

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

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

参数

  • tabId

    编号（选填）

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

  • 详细信息

    DeleteInjectionDetails

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

sendMessage()

<ph type="x-smartling-placeholder"></ph> 承诺 
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

    • Response

      任意

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

返回

  • 承诺<any>

    Chrome 99 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

sendRequest()

<ph type="x-smartling-placeholder"></ph> 承诺 &amp;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

    • Response

      任意

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

返回

  • 承诺<any>

    Chrome 99 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setZoom()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
  callback?: function,
)

缩放指定的标签页。

参数

  • tabId

    编号（选填）

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

  • zoomFactor

    number

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setZoomSettings()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • zoomSettings

    ZoomSettings

    定义缩放变化的处理方式和范围。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

ungroup()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 88 及更高版本 
chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
  callback?: function,
)

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

参数

  • tabIds

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

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

update()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • updateProperties

    对象

    • 活跃

      布尔值（可选）

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

    • autoDiscardable

      布尔值（可选）

      Chrome 54 及更高版本

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

    • 突出显示

      布尔值（可选）

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

    • 已设为静音

      布尔值（可选）

      Chrome 45 及更高版本

      是否应将标签页静音。

    • openerTabId

      编号（选填）

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

    • 已固定

      布尔值（可选）

      是否应固定标签页。

    • 已选择

      布尔值（可选）

      <ph type="x-smartling-placeholder"></ph> 已弃用

      请使用突出显示的内容。

      是否应选择标签页。

    • 网址

      字符串（可选）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tab?: Tab) => void

    • Tab

      Tab（可选）

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

返回

  • Promise<Tab未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onActivated

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (activeInfo: object) => void

    • activeInfo

      对象

      • tabId

        number

        已处于活动状态的标签页的 ID。

      • windowId

        number

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

onActiveChanged

<ph type="x-smartling-placeholder"></ph> &amp;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

<ph type="x-smartling-placeholder"></ph> &amp;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

        布尔值

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

      • windowId

        number

        标签页已关闭的窗口。

onReplaced

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • addedTabId

      number

    • removedTabId

      number

onSelectionChanged

<ph type="x-smartling-placeholder"></ph> &amp;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 及更高版本

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

      • 已固定

        布尔值（可选）

        标签页的新固定状态。

      • 状态

        TabStatus（可选）

        标签页的加载状态。

      • 标题

        字符串（可选）

        Chrome 48 及更高版本

        标签页的新标题。

      • 网址

        字符串（可选）

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

    • Tab

      制表符

onZoomChange

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

缩放标签页时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (ZoomChangeInfo: object) => void

    • ZoomChangeInfo

      对象

      • newZoomFactor

        number

      • oldZoomFactor

        number

      • tabId

        number

      • zoomSettings

        ZoomSettings