tabs.update()

Navigieren Sie den Tab zu einer neuen URL oder ändern Sie andere Eigenschaften des Tabs.

Um diese Funktion zu verwenden, übergeben Sie die ID des zu aktualisierenden Tabs und ein updateProperties-Objekt, das die Eigenschaften enthält, die Sie aktualisieren möchten. Eigenschaften, die im updateProperties-Objekt nicht angegeben sind, werden nicht geändert.

Dies ist eine asynchrone Funktion, die ein Promise zurückgibt.

Syntax

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

Parameter

tabId Optional

integer. Standardmäßig der ausgewählte Tab des aktuellen Fensters.

updateProperties

object. Das Set der Eigenschaften, die für diesen Tab aktualisiert werden sollen. Um mehr über diese Eigenschaften zu erfahren, lesen Sie die tabs.Tab Dokumentation.

active Optional

boolean. Ob der Tab aktiv werden soll. Beeinflusst nicht, ob das Fenster im Fokus steht (siehe windows.update). Wenn true, werden nicht-aktive, hervorgehobene Tabs nicht mehr hervorgehoben. Bei false passiert nichts.

autoDiscardable Optional

boolean. Ob der Tab vom Browser verworfen werden kann. Der Standardwert ist true. Wird er auf false gesetzt, kann der Browser den Tab nicht automatisch verwerfen. Der Tab kann jedoch durch tabs.discard verworfen werden.

highlighted Optional

boolean. Fügt den Tab der aktuellen Auswahl hinzu oder entfernt ihn daraus. Wenn true und der Tab nicht hervorgehoben ist, wird er standardmäßig aktiv.

Wenn Sie den Tab nur hervorheben möchten, ohne ihn zu aktivieren, akzeptiert Firefox das Setzen von highlighted auf true und active auf false. Andere Browser könnten den Tab in diesem Fall trotzdem aktivieren.

loadReplace Optional

boolean. Ob die neue URL die alte URL in der Navigationshistorie des Tabs ersetzen soll, wie sie über die Schaltfläche "Zurück" zugänglich ist.

Beispielsweise, wenn der Benutzer einen neuen Tab mit Strg+T erstellt. Standardmäßig würde in Firefox "about:newtab" geladen werden. Wenn Ihre Erweiterung diese Seite dann mit tabs.update aktualisiert, ohne loadReplace, wird die Schaltfläche "Zurück" aktiviert und führt den Benutzer zurück zu "about:newtab". Wenn die Erweiterung loadReplace setzt, wird die Schaltfläche "Zurück" deaktiviert, und es ist so, als ob die von der Erweiterung bereitgestellte URL die erste besuchte Seite in diesem Tab wäre.

Beachten Sie jedoch, dass die ursprüngliche URL immer noch in der globalen Historie des Browsers erscheint.

muted Optional

boolean. Ob der Tab stummgeschaltet werden soll.

openerTabId Optional

integer. Die ID des Tabs, der diesen Tab geöffnet hat. Wenn angegeben, muss der öffnende Tab im selben Fenster wie dieser Tab sein. Setzen Sie -1, um die gesetzte openerTabId zu löschen.

pinned Optional

boolean. Ob der Tab angepinnt werden soll.

selected Optional

boolean. Ob der Tab ausgewählt werden soll. Diese Eigenschaft wurde durch active und highlighted ersetzt.

successorTabId Optional

integer. Die ID des Nachfolgers des Tabs.

url Optional

string. Eine URL, zu der der Tab navigiert werden soll.

Aus Sicherheitsgründen darf es in Firefox keine privilegierte URL sein. Daher wird das Übergeben einer der folgenden URLs fehlschlagen, wobei runtime.lastError auf eine Fehlermeldung gesetzt wird:

  • chrome: URLs
  • javascript: URLs
  • data: URLs
  • file: URLs (d.h. Dateien im Dateisystem. Um jedoch eine im Add-on verpackte Datei zu verwenden, siehe unten)
  • privilegierte about: URLs (z. B. about:config, about:addons, about:debugging, about:newtab). Nicht-privilegierte URLs (z. B. about:blank) sind erlaubt.

Um eine Seite zu laden, die mit Ihrem Add-on verpackt ist, geben Sie eine absolute URL, beginnend bei der manifest.json-Datei des Add-ons, an. Zum Beispiel: '/path/to/my-page.html'. Wenn Sie das führende '/' weglassen, wird die URL als relative URL behandelt, und unterschiedliche Browser können unterschiedliche absolute URLs konstruieren.

Rückgabewert

Ein Promise, das mit einem tabs.Tab Objekt erfüllt wird, das Details über den aktualisierten Tab enthält. Das tabs.Tab Objekt enthält keine url, title und favIconUrl, es sei denn, passende Host-Berechtigungen oder die "tabs" Berechtigung wurde angefordert. Wenn der Tab nicht gefunden werden konnte oder ein anderer Fehler auftritt, wird das Promise mit einer Fehlermeldung abgelehnt.

Beispiele

Navigieren Sie den aktiven Tab im aktuellen Fenster zu https://developer.mozilla.org:

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

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

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

Aktivieren Sie den ersten Tab im aktuellen Fenster und navigieren Sie ihn zu https://developer.mozilla.org:

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://developer.mozilla.org",
  });
  updating.then(onUpdated, onError);
}

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

Beispielerweiterungen

Browser-Kompatibilität

Hinweis: Diese API basiert auf der chrome.tabs API von Chromium. Diese Dokumentation ist abgeleitet von tabs.json im Chromium-Quellcode.