tabs.onUpdated

标签页更新时触发。

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

此事件也会在标签页的属性更改时触发，这些更改不涉及导航，例如固定和取消固定（更新 pinned 属性）以及静音或取消静音（更新 audible 和 mutedInfo 属性）。

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

语法

js
browser.tabs.onUpdated.addListener(
  listener, // 函数
  filter     // 可选的对象
)
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。如果标签页是隐藏的#，则为 true。

isArticle 可选

boolean。如果标签页是文章，因此可以显示在阅读模式#中，则为 true。

mutedInfo 可选

tabs.MutedInfo。标签页的新静音状态及更改原因。

pinned 可选

boolean。标签页的新固定状态。

status 可选

string。标签页的状态。可以是 loading 或 complete。

title 可选

string。标签页的新标题。

url 可选

string。如果标签页的 URL 已更改。

示例

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

js
function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`更新的标签：${tabId}`);
  console.log("改变的属性：", changeInfo);
  console.log("新标签的信息：", tabInfo);
}

browser.tabs.onUpdated.addListener(handleUpdated);

记录 URL 的更改：

js
function handleUpdated(tabId, changeInfo, tabInfo) {
  if (changeInfo.url) {
    console.log(`标签：${tabId} 的 URL 改变为 ${changeInfo.url}`);
  }
}

browser.tabs.onUpdated.addListener(handleUpdated);

过滤示例

仅当标签页的 url 属性匹配 https://developer.mozilla.org/* 或 https://mozilla.social/@mdn 时记录更改：

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

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

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`更新的标签：${tabId}`);
  console.log("改变的属性：", changeInfo);
  console.log("新标签的信息：", tabInfo);
}

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

仅记录标签页的 pinned 属性的更改（即固定和取消固定操作）：

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

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`更新的标签：${tabId}`);
  console.log("改变的属性：", changeInfo);
  console.log("新标签的信息：", tabInfo);
}

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

组合前两个过滤器，仅当标签页的 pinned 属性更改且 url 属性匹配 https://developer.mozilla.org/* 或 https://mozilla.social/@mdn 时记录更改：

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

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

function handleUpdated(tabId, changeInfo, tabInfo) {
  console.log(`更新的标签：${tabId}`);
  console.log("改变的属性：", changeInfo);
  console.log("新标签的信息：", tabInfo);
}

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

仅当标签页的 pinned 属性更改且 url 属性匹配 https://developer.mozilla.org/* 或 https://mozilla.social/@mdn 且在事件触发时标签页属于当前浏览器窗口时记录更改：

js
const pattern1 = "https://developer.mozilla.org/*";
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(`更新的标签：${tabId}`);
  console.log("改变的属性：", changeInfo);
  console.log("新标签的信息：", tabInfo);
}

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

示例扩展

浏览器兼容性

BCD tables only load in the browser

备注： 该 API 基于 Chromium 的 chrome.tabs API。此文档来自 Chromium 代码中的 tabs.json。