tabs.onUpdated

当标签更新时触发。

当用户在标签中导航到新的 URL 时，这通常会生成多个 onUpdated 事件，因为 tabs.Tab 对象的各种属性都已更新。这包括 url，但也可能包括 title 和 favIconUrl 属性。status 属性将循环遍历 "loading" 和 "complete"。

此事件还会针对不涉及导航的标签属性更改而触发，例如固定和取消固定（更新 pinned 属性）以及静音或取消静音（更新 audible 和 mutedInfo 属性）。

您可以过滤此事件，使其仅针对 URL 匹配特定模式、特定属性的更改、标签或窗口的更改，或这些限制的任何组合而触发。

语法

browser.tabs.onUpdated.addListener(
  listener, // function
  filter     // optional object
)
browser.tabs.onUpdated.removeListener(listener)
browser.tabs.onUpdated.hasListener(listener)

事件具有三个函数

addListener(callback, filter): 向此事件添加监听器。
removeListener(listener): 停止监听此事件。listener 参数是要移除的监听器。
hasListener(listener): 检查 listener 是否注册了此事件。如果正在监听，则返回 true，否则返回 false。

addListener 语法

参数

listener

当此事件发生时调用的函数。该函数将传递以下参数

tabId: integer。更新的标签的 ID。
changeInfo: object。已更改的标签的属性。有关更多详细信息，请参阅 changeInfo 部分。
tab: tabs.Tab。标签的新状态。

filter 可选

object。一组限制发送到此监听器的事件的过滤器。此对象可以包含以下一个或多个属性。只有满足所有提供的过滤器的事件才会被发送。

urls

Array。一组匹配模式。仅针对当前 url 属性匹配模式数组中的任何一个的标签触发事件。

properties

Array。一组字符串，包含受支持的 tabs.Tab 对象属性名称。仅针对对数组中命名的属性之一的更改触发事件。可以使用这些属性

"attention"
"autoDiscardable"
"audible"
"discarded"
"favIconUrl"
"hidden"
"isArticle"
"mutedInfo"
"pinned"
"status"
"title"
"url"

注意："url" 值从 Firefox 88 开始受支持。在 Firefox 87 及更早版本中，可以通过过滤 "status" 来观察 "url" 更改。

tabId

Integer。仅针对由此 ID 标识的标签触发此事件。

windowId

Integer。仅针对由此 ID 标识的窗口中的标签触发此事件。

附加对象

changeInfo

列出已更新的标签状态的更改。要了解有关这些属性的更多信息，请参阅 tabs.Tab 文档。请注意，并非所有 tabs.Tab 属性都受支持。

attention 可选: boolean。指示标签是否正在引起注意。例如，当标签显示模态对话框时，attention 为 true。
audible 可选: boolean。标签的新可听状态。
autoDiscardable 可选: boolean。标签是否可以被浏览器丢弃。默认值为 true。当设置为 false 时，浏览器无法自动丢弃标签。但是，可以使用 tabs.discard 丢弃标签。
discarded 可选: boolean。标签是否已丢弃。丢弃的标签是指其内容已从内存中卸载但仍在标签栏中可见的标签。下次激活时，其内容将重新加载。
favIconUrl 可选: string。标签的新收藏夹图标 URL。当标签丢失收藏夹图标时不包括在内（从具有收藏夹图标的页面导航到没有收藏夹图标的页面）。请改用 tab 中的 favIconUrl。
hidden 可选: boolean。如果标签是 hidden，则为 true。
isArticle 可选: boolean。如果标签是文章，并且因此有资格在阅读器模式中显示，则为 true。
mutedInfo 可选: tabs.MutedInfo。标签的新静音状态以及更改的原因。
pinned 可选: boolean。标签的新固定状态。
status 可选: string. 选项卡的状态。可以是 加载中 或 已完成。
title 可选: string. 选项卡的新标题。
url 可选: string. 选项卡的 URL，如果它已更改。

示例

监听并记录所有更改信息和新状态

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`Updated tab: ${tabId}`);
  console.log("Changed attributes: ", changeInfo);
  console.log("New tab Info: ", tabInfo);
}

browser.tabs.onUpdated.addListener(handleUpdated);

记录对 URL 的更改

function handleUpdated(tabId, changeInfo, tabInfo) {
  if (changeInfo.url) {
    console.log(`Tab: ${tabId} URL changed to ${changeInfo.url}`);
  }
}

browser.tabs.onUpdated.addListener(handleUpdated);

过滤示例

仅记录 url 属性与 https://mdn.org.cn/* 或 https://mozilla.social/@mdn 匹配的选项卡的更改

const pattern1 = "https://mdn.org.cn/*";
const pattern2 = "https://mozilla.social/@mdn";

const filter = {
  urls: [pattern1, pattern2],
};

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`Updated tab: ${tabId}`);
  console.log("Changed attributes: ", changeInfo);
  console.log("New tab Info: ", tabInfo);
}

browser.tabs.onUpdated.addListener(handleUpdated, filter);

仅记录选项卡的 pinned 属性的更改（即，固定和取消固定操作）

const filter = {
  properties: ["pinned"],
};

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`Updated tab: ${tabId}`);
  console.log("Changed attributes: ", changeInfo);
  console.log("New tab Info: ", tabInfo);
}

browser.tabs.onUpdated.addListener(handleUpdated, filter);

将前两个过滤器结合起来，仅在 url 属性与 https://mdn.org.cn/* 或 https://mozilla.social/@mdn 匹配的选项卡的 pinned 属性发生更改时记录更改

const pattern1 = "https://mdn.org.cn/*";
const pattern2 = "https://mozilla.social/@mdn";

const filter = {
  urls: [pattern1, pattern2],
  properties: ["pinned"],
};

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`Updated tab: ${tabId}`);
  console.log("Changed attributes: ", changeInfo);
  console.log("New tab Info: ", tabInfo);
}

browser.tabs.onUpdated.addListener(handleUpdated, filter);

仅在更新事件触发时，选项卡的 pinned 属性发生更改，并且该选项卡属于当前浏览器窗口时，记录选项卡的 pinned 属性更改

const pattern1 = "https://mdn.org.cn/*";
const pattern2 = "https://mozilla.social/@mdn";

const filter = {
  urls: [pattern1, pattern2],
  properties: ["pinned"],
  windowId: browser.windows.WINDOW_ID_CURRENT,
};

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`Updated tab: ${tabId}`);
  console.log("Changed attributes: ", changeInfo);
  console.log("New tab Info: ", tabInfo);
}

browser.tabs.onUpdated.addListener(handleUpdated, filter);

扩展示例

浏览器兼容性

BCD 表格仅在浏览器中加载

注意： 此 API 基于 Chromium 的 chrome.tabs API。此文档源于 Chromium 代码中的 tabs.json。