Arbeiten mit documentId

Tabs, Frames und Dokumente

Ein Browser-Tab, identifiziert durch eine tabId, ist der oberste Container für Webinhalte. Innerhalb eines Tabs können Inhalte in mehrere Frames strukturiert werden: der Hauptframe (äußerster), der eine frameId von 0 hat, und alle verschachtelten <iframe>-Elemente, die jeweils eine frameId haben. Da die oberste frameId 0 ist, kann frameId nicht verwendet werden, um alle Frames über alle Tabs hinweg eindeutig zu identifizieren.

Jeder Frame enthält ein Dokument, die HTML-Seite, die unter einer URL geladen wird. Die Beziehung zwischen diesen drei Konzepten ist:

• Ein Tab enthält ein oder mehrere Frames.
• Ein Frame enthält ein Dokument.
• Wenn ein Frame zu einer neuen URL navigiert, wird sein Dokument ersetzt, aber der gleiche Frame und somit die gleiche frameId bleibt bestehen.

Das bedeutet, dass die Kombination aus tabId und frameId einen Frame (einen stabilen Browsing-Kontext) identifiziert, aber nicht das darin geladene Dokument.

Dokumente und Frames sind auch in Nicht-Tab-Kontexten vorhanden, einschließlich, aber nicht beschränkt auf:

• Sidebars
• Popups, die an Erweiterungsschaltflächen angehängt sind
• Devtools-Panels
• Hintergrundseiten

Operationen mit Tab- und Frame-IDs

Viele WebExtension-APIs verwenden tabId und frameId, um zu identifizieren, wo eine Operation ausgeführt werden soll:

• Skript- und CSS-Injektion: scripting.executeScript(), scripting.insertCSS(), und scripting.removeCSS() akzeptieren eine tabId und optionale frameIds in ihrem scripting.InjectionTarget, um anzugeben, wo injiziert werden soll.
• Benutzerskript-Injektion: userScripts.execute() nimmt tabId und frameIds in seinem target.
• Messaging: tabs.sendMessage() und tabs.connect() akzeptieren eine tabId und eine optionale frameId, um eine Nachricht an ihren Empfänger zu senden.
• Frame-Informationen: webNavigation.getFrame() und webNavigation.getAllFrames() verwenden tabId und frameId, um Frame-Details zu suchen oder aufzulisten.
• Ereignisse: Navigationsevents (webNavigation.onCommitted, webNavigation.onCompleted und andere), Anfrageereignisse (webRequest.onBeforeRequest und andere), und proxy.onRequest beinhalten alle tabId und frameId, um zu identifizieren, wo ein Event aufgetreten ist.

Da frameId den Frame anstelle seines Inhalts identifiziert, besteht ein potenzielles Race-Condition-Risiko. Nachdem Ihre Erweiterung die tabId und frameId erhalten hat, kann sich das geladene Dokument ändern, sodass die nachfolgende Operation der Erweiterung nicht mehr das beabsichtigte Dokument anvisiert. documentId wurde eingeführt, um dieses Problem zu lösen.

Was ist eine documentId?

Eine documentId wird jedem Dokument zugewiesen, wenn es geladen wird, und bleibt über die gesamte Lebensdauer des Dokuments konstant. Wenn ein Frame zu einer neuen URL navigiert, behält er seine frameId, erhält aber eine neue documentId. Dies unterscheidet documentId von frameId: Eine frameId identifiziert den Browsing-Kontext (das Frame-Element selbst), während eine documentId das geladene Dokument innerhalb dieses Kontexts identifiziert.

Die documentId behandelt korrekt Sonderfälle, die frameId nicht unterscheiden kann:

• Navigationen: Jeder neue Dokumenten-Ladevorgang, einschließlich Cross-Origin-Navigationen, erhält eine neue documentId, obwohl die frameId unverändert bleibt.
• Reloads: Ein Neuladen der Seite erzeugt eine neue documentId, was auf ein frisches Dokument hinweist.
• history.pushState() und Fragment-Updates: Diese erzeugen kein neues Dokument, sodass die documentId unverändert bleibt.

Da sich die ID bei jedem Dokumenten-Ladevorgang ändert, bleibt die von Ihrer Erweiterung für ein Dokument erhaltene ID nur für dieses Dokument gültig. Wenn der Frame navigiert ist, passt die documentId nicht mehr. Wenn Ihre Erweiterung ein Skript injiziert oder eine Nachricht mit der dokumentierten ID nach der Navigation sendet, schlägt die Operation fehl, anstatt stillschweigend das falsche Dokument zu adressieren.

Wenn ein Dokument aus dem Vorwärts-/Rückwärtscache (bfcache) wiederhergestellt wird, wird auch seine ursprüngliche documentId wiederhergestellt.

Wie erhält man eine documentId?

Es gibt mehrere Möglichkeiten, eine documentId zu erhalten:

• Rufen Sie runtime.getDocumentId() mit einem window oder Frame-Element innerhalb eines Inhaltsskripts auf.
• Lesen Sie die documentId oder parentDocumentId-Eigenschaft in den Ergebnissen von webNavigation.getFrame() oder webNavigation.getAllFrames().
• Lesen Sie die documentId oder parentDocumentId von Ereignisdetails in webNavigation-Ereignissen (für Ereignisse, bei denen das Dokument des Navigationziels bekannt ist, wenn das Ereignis ausgelöst wird).
• Lesen Sie die documentId aus Ereignisdetails von webRequest-Ereignissen.
• Lesen Sie die documentId aus runtime.MessageSender, wenn Sie Nachrichten mit runtime.onMessage, runtime.onConnect und verwandten Listenern empfangen.
• Lesen Sie die documentId aus den Ergebnissen von runtime.getContexts().

Verwendung von documentId zur Zieladresse von Dokumenten

Wenn Sie eine documentId haben, können Sie diese verwenden, um dieses Dokument anzusteuern:

• Skript- und CSS-Injektion: Verwenden Sie documentIds in scripting.InjectionTarget mit scripting.executeScript(), scripting.insertCSS() und scripting.removeCSS(), um in spezifische Dokumente zu injizieren.
• Benutzerskript-Injektion: Setzen Sie documentIds im target-Parameter von userScripts.execute().
• Messaging: Übergeben Sie documentId im options-Parameter von tabs.connect() oder tabs.sendMessage(), um an ein Dokument in einem Tab zu senden.
• Frame-Suche: Übergeben Sie documentId an webNavigation.getFrame() als Alternative zu tabId und frameId. Wenn Sie auch tabId und frameId angeben, wird der Frame nur zurückgegeben, wenn alle drei übereinstimmen.

APIs, die documentId unterstützen

Diese APIs unterstützen documentId.

Abrufen einer documentId

• runtime.getDocumentId() gibt die Dokument-UUID eines Zielsfensters oder Frame-Elements zurück.

documentId in Rückgabewerten und Ereignisdetails

• runtime.getContexts() gibt eine documentId für jeden Erweiterungskontext zurück und unterstützt eine documentIds-Filtereigenschaft.
• runtime.MessageSender enthält documentId, verfügbar in runtime.onConnect, runtime.onMessage, runtime.onMessageExternal, runtime.onConnectExternal, runtime.onUserScriptMessage und runtime.onUserScriptConnect-Listenern.
• scripting.executeScript() gibt documentId in jedem InjectionResult zurück.
• userScripts.execute()-Ergebnisse enthalten documentId.
• webNavigation.getAllFrames() gibt documentId und parentDocumentId für jeden Frame zurück.
• webNavigation.getFrame() gibt documentId und parentDocumentId zurück.
• webNavigation.onCommitted, webNavigation.onDOMContentLoaded, webNavigation.onCompleted, webNavigation.onErrorOccurred, webNavigation.onReferenceFragmentUpdated und webNavigation.onHistoryStateUpdated beinhalten documentId und parentDocumentId in den Ereignisdetails. webNavigation.onBeforeNavigate kann eine parentDocumentId haben, wenn ein Frame navigiert, aber keine documentId, da das Ereignis ausgelöst wird, bevor ein Dokument geladen wird.
• Alle webRequest-Ereignisse — webRequest.onBeforeRequest, webRequest.onBeforeSendHeaders, webRequest.onSendHeaders, webRequest.onHeadersReceived, webRequest.onAuthRequired, webRequest.onBeforeRedirect, webRequest.onResponseStarted, webRequest.onCompleted und webRequest.onErrorOccurred — beinhalten documentId und parentDocumentId, wenn zutreffend.
• proxy.RequestDetails beinhaltet documentId und parentDocumentId, wenn zutreffend.
• declarativeNetRequest.onRuleMatchedDebug beinhaltet documentId, wenn zutreffend.

documentId für Zielanwendungen

• scripting.InjectionTarget unterstützt documentIds, um spezifische Dokumente in scripting.executeScript(), scripting.insertCSS() und scripting.removeCSS() anzusteuern.
• userScripts.execute() target unterstützt documentIds.
• tabs.connect() options unterstützt documentId, um ein spezifisches Dokument anzusteuern.
• tabs.sendMessage() options unterstützt documentId, um ein spezifisches Dokument anzusteuern.
• webNavigation.getFrame() akzeptiert documentId als Alternative zu tabId und frameId.

Zukünftige Entwicklungen

Die WebExtensions Community Group (WECG) diskutiert die Möglichkeit, die Anforderung zu lockern, tabId zusammen mit documentId beim Ansteuern von Dokumenten bereitzustellen. Siehe WECG issue #91 für die Diskussion.