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 语法

参数

监听器

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

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

filter 可选

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

URLs

Array。一组匹配模式。仅当标签页的当前 url 属性与提供的任何模式匹配时，才触发事件。

properties

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

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

注意： "url" 值自 Firefox 88 起受支持。在 Firefox 87 及更早版本中，可以通过过滤 "status" 来观察 "url" 的变化。

tabId

Integer。仅为由此 ID 标识的标签页触发此事件。

windowId

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

cookieStoreId

Integer。仅为由此 ID 标识的 Cookie 存储中的标签页触发此事件。

额外对象

changeInfo

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

attention 可选: boolean。指示标签页是否正在吸引注意。例如，当标签页显示模态对话框时，attention 为 true。
audible 可选: boolean。标签页的新声音状态。
autoDiscardable 可选: boolean。标签页是否可以被浏览器丢弃。默认值为 true。当设置为 false 时，浏览器无法自动丢弃该标签页。但是，该标签页可以通过 tabs.discard 进行丢弃。
discarded 可选: boolean。标签页是否被丢弃。被丢弃的标签页是指其内容已从内存中卸载但仍显示在标签页栏中的标签页。下次激活时，其内容将重新加载。
favIconUrl 可选: string。标签页的新图标 URL。当标签页失去其图标时（从带有图标的页面导航到没有图标的页面），此项不包含在内。请参阅 tab 中的 favIconUrl。
groupId 可选: integer。标签页所属组的 ID，或未分组标签页的 -1 (tabGroups.TAB_GROUP_ID_NONE)。
hidden 可选: boolean。如果标签页被 hidden，则为 true。
isArticle 可选: boolean。如果标签页是文章，则为 true，因此有资格在阅读模式中显示。
mutedInfo 可选: tabs.MutedInfo。标签页的新静音状态和更改原因。
openerTabId 可选: integer。打开此标签页的标签页的 ID（如果存在）。仅当打开标签页存在且位于同一窗口中时，才存在此属性。
pinned 可选: boolean。标签页的新固定状态。
status 可选: string。标签页的状态。可以是 loading 或 complete。
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://mastodon.social/@mdn 匹配的标签页的更改

const pattern1 = "https://mdn.org.cn/*";
const pattern2 = "https://mastodon.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);

结合之前的两个过滤器，仅在标签页的 pinned 属性发生更改时进行记录，且该标签页的 URL 属性与 https://mdn.org.cn/* 或 https://mastodon.social/@mdn 匹配

const pattern1 = "https://mdn.org.cn/*";
const pattern2 = "https://mastodon.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 属性发生更改时的记录，且该标签页的 URL 属性与 https://mdn.org.cn/* 或 https://mastodon.social/@mdn 匹配，并且在更新事件触发时该标签页是当前浏览器窗口的一部分

const pattern1 = "https://mdn.org.cn/*";
const pattern2 = "https://mastodon.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);

扩展程序示例

浏览器兼容性

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

帮助改进 MDN

了解如何贡献

此页面最后修改于 2025 年 9 月 2 日，由 MDN 贡献者进行修改。

在 GitHub 上查看此页面 • 报告此内容的某个问题