tabs.update()

导航到一个新的 URL 或修改标签页的其他属性。

要使用此函数,传递要更新的标签页的 ID,以及一个包含要更新的属性的 updateProperties 对象。未在 updateProperties 中指定的属性不会被修改。

这是一个返回 Promise 的异步函数。

语法

js
let updating = browser.tabs.update(
  tabId,              // 可选的整数
  updateProperties    // 对象
)

参数

tabId 可选

integer。默认为当前窗口中选定的标签页。

updateProperties

object。标签页中要更新的一组属性。要了解更多有关这些属性的信息,请查看 tabs.Tab 的文档。

active 可选

boolean。标签页是否应该变为活动状态。不影响窗口是否被聚焦(参见 windows.update)。如果设置为 true,非活动的突出显示的标签页将停止被突出显示。如果设置为 false,则不做任何操作。

autoDiscardable 可选

boolean。标签页是否可以被浏览器丢弃。默认值为 true。当设置为 false 时,浏览器无法自动丢弃该标签页。但是,可以通过 tabs.discard 丢弃该标签页。

highlighted 可选

boolean。将标签页添加到当前的选择中,或从中移除。如果设置为 true 并且标签页未被突出显示,则默认情况下它将变为活动状态。

如果只想突出显示标签页而不激活它,在 Firefox 中可以将 highlighted 设置为 true,并将 active 设置为 false。其他浏览器可能即使在这种情况下也会激活标签页。

loadReplace 可选

boolean。新的 URL 是否应该替换标签页导航历史中的旧 URL(可通过“返回”按钮访问)。

例如,用户使用 Ctrl+T 创建一个新的标签页。默认情况下,在 Firefox 中,这会加载“about:newtab”。然后,如果你的扩展使用 tabs.update 更新此页面且没有使用 loadReplace,则“返回”按钮将启用,并且用户可以返回到“about:newtab”。如果扩展设置了 loadReplace,则“返回”按钮将被禁用,并且就像扩展提供的 URL 是该标签页访问的第一个页面一样。

请注意,原始 URL 仍将出现在浏览器的全局历史记录中。

muted 可选

boolean。标签页是否应该静音。

openerTabId 可选

integer。打开该标签页的标签页的 ID。如果指定,则打开者标签页必须与此标签页位于同一窗口。

pinned 可选

boolean。标签页是否应该被固定。

selected 已弃用 可选

boolean。标签页是否应该被选择。此属性已被 activehighlighted 替代。

successorTabId 可选

integer。标签页的后继标签页的 ID。

url 可选

string。要导航标签页到的 URL。

由于安全原因,在 Firefox 中,这不能是特权 URL。因此,传递以下任何 URL 将失败,并设置 runtime.lastError 为错误消息:

  • chrome: 类型的 URL
  • javascript: 类型的 URL
  • data: 类型的 URL
  • file: 类型的 URL(即文件系统上的文件。但是,要使用打包在扩展中的文件,请参见下文)
  • 特权 about: 类型的 URL(例如 about:configabout:addonsabout:debuggingabout:newtab)。非特权的 URL(例如 about:blank)是允许的。

要加载打包在你的扩展中的页面,请指定从扩展的 manifest.json 文件开始的绝对 URL。例如:“/path/to/my-page.html”。如果省略前导的“/”,则 URL 被视为相对 URL,不同的浏览器可能会构造不同的绝对 URL。

返回值

一个 Promise,其会兑现一个包含有关更新的标签页的 tabs.Tab 对象。tabs.Tab 对象不包含 urltitlefavIconUrl,除非匹配的主机权限或已请求 "tabs" 权限。如果找不到标签页或发生其他错误,promise 将以错误消息拒绝。

示例

将当前窗口中的活动标签页导航到 https://developer.mozilla.org

js
function onUpdated(tab) {
  console.log(`更新的标签页:${tab.id}`);
}

function onError(error) {
  console.log(`发生错误:${error}`);
}

let updating = browser.tabs.update({ url: "https://developer.mozilla.org" });
updating.then(onUpdated, onError);

激活当前窗口中的第一个标签页,并将其导航到 https://developer.mozilla.org

js
function onUpdated(tab) {
  console.log(`更新的标签页:${tab.id}`);
}

function onError(error) {
  console.log(`发生错误:${error}`);
}

function updateFirstTab(tabs) {
  let updating = browser.tabs.update(tabs[0].id, {
    active: true,
    url: "https://developer.mozilla.org",
  });
  updating.then(onUpdated, onError);
}

let querying = browser.tabs.query({ currentWindow: true });
querying.then(updateFirstTab, onError);

示例扩展

浏览器兼容性

BCD tables only load in the browser

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