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.club.tw/* 或 https://mastodon.social/@mdn 匹配的標籤頁的更改

const pattern1 = "https://mdn.club.tw/*";
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.club.tw/* 或 https://mastodon.social/@mdn 匹配

const pattern1 = "https://mdn.club.tw/*";
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.club.tw/* 或 https://mastodon.social/@mdn 匹配，並且在更新事件觸發時該標籤頁是當前瀏覽器視窗的一部分

const pattern1 = "https://mdn.club.tw/*";
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 上檢視此頁面 • 報告此內容的某個問題