tabs.update()

将选项卡导航到新的 URL，或修改选项卡的其他属性。

要使用此函数，请传递要更新的选项卡的 ID 和一个包含要更新的属性的 updateProperties 对象。updateProperties 中未指定的属性不会被修改。

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

语法

js
let updating = browser.tabs.update(
  tabId,              // optional integer
  updateProperties    // object
)

参数

tabId 可选

整数。默认为当前窗口的选定选项卡。

updateProperties

对象。要更新此选项卡的属性集。要了解有关这些属性的更多信息，请参阅 tabs.Tab 文档。

active 可选

布尔值。选项卡是否应变为活动状态。不影响窗口是否处于焦点状态（请参阅 windows.update）。如果为 true，则非活动突出显示的选项卡将停止突出显示。如果为 false，则不执行任何操作。

autoDiscardable 可选

布尔值。浏览器是否可以丢弃选项卡。默认值为 true。设置为 false 时，浏览器无法自动丢弃选项卡。但是，选项卡可以通过 tabs.discard 丢弃。

highlighted 可选

布尔值。将选项卡添加到当前选择或从中删除。如果为 true 且选项卡未突出显示，则默认情况下它将变为活动状态。

如果你只想突出显示选项卡而不将其激活，Firefox 接受将 highlighted 设置为 true 而将 active 设置为 false。其他浏览器即使在这种情况下也可能会激活选项卡。

loadReplace 可选

布尔值。新的 URL 是否应替换选项卡导航历史记录中的旧 URL，如通过“后退”按钮访问。

例如，假设用户使用 Ctrl+T 创建了一个新选项卡。默认情况下，在 Firefox 中，这将加载“about:newtab”。如果你的扩展随后使用 tabs.update 更新此页面，而没有 loadReplace，则“后退”按钮将被启用，并将用户带回“about:newtab”。如果扩展设置了 loadReplace，则“后退”按钮将被禁用，这就像扩展提供的 URL 是该选项卡中访问的第一个页面一样。

但请注意，原始 URL 仍将显示在浏览器的全局历史记录中。

muted 可选

布尔值。选项卡是否应静音。

openerTabId 可选

整数。打开此选项卡的选项卡的 ID。如果指定，则打开程序选项卡必须与该选项卡位于同一窗口中。

pinned 可选

布尔值。选项卡是否应固定。

selected 可选

布尔值。选项卡是否应选中。此属性已被 active 和 highlighted 替换。

successorTabId 可选

整数。选项卡的后继者的 ID。

url 可选

字符串。要导航到的选项卡的 URL。

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

  • chrome: URL
  • javascript: URL
  • data: URL
  • file: URL（即文件系统上的文件。但是，要使用扩展程序内部打包的文件，请参见下文）
  • 特权 about: URL（例如，about:config、about:addons、about:debugging、about:newtab）。允许使用非特权 URL（例如，about:blank）。

要加载与扩展程序打包在一起的页面，请指定从扩展程序的 manifest.json 文件开始的绝对 URL。例如：'/path/to/my-page.html'。如果你省略了开头的 '/'，则 URL 将被视为相对 URL，并且不同的浏览器可能会构造不同的绝对 URL。

返回值

一个 Promise，它将使用包含有关更新的选项卡详细信息的 tabs.Tab 对象来履行。除非已请求匹配的 主机权限 或 "tabs" 权限，否则 tabs.Tab 对象不包含 url、title 和 favIconUrl。如果找不到选项卡或发生其他错误，则 promise 将被拒绝并显示错误消息。

示例

将当前窗口中的活动选项卡导航到 https://mdn.org.cn

js
function onUpdated(tab) {
  console.log(`Updated tab: ${tab.id}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

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

激活当前窗口中的第一个选项卡，并将其导航到 https://mdn.org.cn

js
function onUpdated(tab) {
  console.log(`Updated tab: ${tab.id}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

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

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

扩展示例

浏览器兼容性

BCD 表格仅在浏览器中加载

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