web_accessible_resources

Typ Array
Pflicht Nein
Manifest-Version 2 oder höher
Beispiel
json
"web_accessible_resources": [
  "images/my-image.png"
]

Beschreibung

Manchmal möchten Sie Ressourcen wie Bilder, HTML, CSS oder JavaScript mit Ihrer Erweiterung verpacken und sie für Webseiten und andere Erweiterungen zugänglich machen.

Hinweis: Bis Firefox 105 konnten Erweiterungen standardmäßig auf Ressourcen zugreifen, die in anderen Erweiterungen verpackt waren. Ab Firefox 105 müssen, um anderen Erweiterungen den Zugriff auf die Ressourcen einer Erweiterung zu ermöglichen, diese in diesem Schlüssel eingeschlossen sein.

Zum Beispiel ersetzt die Beastify-Beispielerweiterung eine Webseite mit einem Bild eines vom Benutzer ausgewählten Tieres. Die Tierbilder sind in der Erweiterung enthalten. Um das ausgewählte Bild sichtbar zu machen, fügt die Erweiterung <img>-Elemente hinzu, deren src-Attribut auf das Bild des Tieres verweist. Damit die Webseite die Bilder laden kann, müssen sie webzugänglich gemacht werden.

Mit dem Schlüssel web_accessible_resources listen Sie alle verpackten Ressourcen auf, die Sie für Webseiten zugänglich machen möchten. Sie geben sie als Pfade relativ zur Datei manifest.json an.

Beachten Sie, dass Inhaltsskripte nicht als webzugängliche Ressourcen aufgelistet werden müssen.

Wenn eine Erweiterung webRequest oder declarativeNetRequest verwenden möchte, um eine öffentliche URL (z.B. HTTPS) auf eine Seite umzuleiten, die in der Erweiterung verpackt ist, dann muss die Erweiterung die Seite im Schlüssel web_accessible_resources auflisten.

Manifest V2-Syntax

In Manifest V2 werden webzugängliche Ressourcen als Array unter dem Schlüssel hinzugefügt, wie folgt:

json
"web_accessible_resources": [
  "images/my-image.png"
]

Manifest V3-Syntax

In Manifest V3 ist der Schlüssel web_accessible_resources ein Array von Objekten wie folgt:

json
{
  // …
  "web_accessible_resources": [
    {
      "resources": ["test1.png", "test2.png"],
      "matches": ["https://web-accessible-resources-1.glitch.me/*"]
    },
    {
      "resources": ["test3.png", "test4.png"],
      "matches": ["https://web-accessible-resources-2.glitch.me/*"],
      "use_dynamic_url": true
    }
  ]
  // …
}

Jedes Objekt muss eine "resources"-Eigenschaft und entweder eine "matches"- oder "extension_ids"-Eigenschaft aus den folgenden Eigenschaften enthalten:

Name Typ Beschreibung
extension_ids Array von String Optional. Standardmäßig [], was bedeutet, dass andere Erweiterungen nicht auf die Ressource zugreifen können.

Eine Liste von Erweiterungs-IDs, die die Erweiterungen angeben, die auf die Ressourcen zugreifen können. "*" steht für alle Erweiterungen.

matches Array von String Optional. Standardmäßig [], was bedeutet, dass andere Webseiten nicht auf die Ressource zugreifen können.

Eine Liste von URL-Übereinstimmungsmustern, die die Seiten angeben, die auf die Ressourcen zugreifen können. Nur der Ursprung wird verwendet, um URLs zu matchen. Allerdings:

  • In Firefox und Safari kann jeder Pfad eingeschlossen werden.
  • In Chrome muss der Pfad auf /* gesetzt werden.
Ursprünge schließen die Übereinstimmung von Subdomains ein.
resources Array von String Ein Array von Ressourcen, die offengelegt werden sollen. Ressourcen werden als Zeichenketten angegeben und können * für Platzhalter-Matches enthalten. Zum Beispiel, "/images/*" gibt alles im Verzeichnis /images der Erweiterung rekursiv frei, während "*.png" alle PNG-Dateien freigibt.
use_dynamic_url Boolean Optional. Standardmäßig false.

Ob Ressourcen über die dynamische ID zugänglich sein sollen. Die dynamische ID wird pro Sitzung generiert und bei jedem Neustart des Browsers oder beim Neuladen der Erweiterung neu erstellt.

Verwendung von web_accessible_resources

Angenommen, Ihre Erweiterung enthält eine Bilddatei unter images/my-image.png, wie folgt:

my-extension-files/
    manifest.json
    my-background-script.js
    images/
        my-image.png

Um einer Webseite die Nutzung eines <img>-Elements zu ermöglichen, dessen src-Attribut auf dieses Bild verweist, würden Sie web_accessible_resources wie folgt angeben:

json
"web_accessible_resources": ["images/my-image.png"]

Die Datei ist dann über eine URL wie diese verfügbar:

moz-extension://<extension-UUID>/images/my-image.png"

<extension-UUID> ist nicht die ID Ihrer Erweiterung. Diese ID wird für jede Browser-Instanz zufällig generiert. Dies verhindert, dass Webseiten einen Browser über die installierten Erweiterungen erkennen.

Hinweis: In Chrome in Manifest V2 ist die ID einer Erweiterung fest. Wenn eine Ressource in web_accessible_resources aufgelistet ist, ist sie als chrome-extension://<your-extension-id>/<path/to/resource> zugänglich. In Manifest V3 kann Chrome eine dynamische URL verwenden, indem use_dynamic_url auf true gesetzt wird.

Der empfohlene Ansatz, um die URL der Ressource zu erhalten, ist die Verwendung von runtime.getURL mit dem Pfad relativ zu manifest.json, zum Beispiel:

js
browser.runtime.getURL("images/my-image.png");
// something like:
// moz-extension://944cfddf-7a95-3c47-bd9a-663b3ce8d699/images/my-image.png

Dieser Ansatz gibt Ihnen die korrekte URL unabhängig vom Browser, auf dem Ihre Erweiterung läuft.

Platzhalter

web_accessible_resources-Einträge können Platzhalter enthalten. Zum Beispiel würde der folgende Eintrag auch funktionieren, um die Ressource unter "images/my-image.png" einzuschließen:

json
  "web_accessible_resources": ["images/*.png"]

Sicherheit

Wenn Sie eine Seite webzugänglich machen, kann jede Webseite diese Seite verlinken oder zu dieser umleiten. Die Seite sollte dann jede Eingabe (beispielsweise POST-Daten) behandeln, als würde sie von einer nicht vertrauenswürdigen Quelle stammen, genau wie eine normale Webseite.

Webzugängliche Erweiterungsressourcen werden nicht von CORS oder CSP blockiert. Aufgrund dieser Fähigkeit, Sicherheitsüberprüfungen zu umgehen, sollten Erweiterungen es vermeiden, webzugängliche Skripte zu verwenden, wann immer möglich. Ein webzugängliches Skript einer Erweiterung kann unerwartet von bösartigen Webseiten missbraucht werden, um die Sicherheit anderer Webseiten zu schwächen. Befolgen Sie die Sicherheitsbest-Praktiken durch Vermeidung der Injektion von moz-extension:-URLs in Webseiten und die Sicherstellung, dass Drittanbieter-Bibliotheken aktuell sind.

Beispiel

Manifest V2-Beispiel

json
"web_accessible_resources": ["images/my-image.png"]

Machen Sie die Datei unter "images/my-image.png" für jede Webseite und Erweiterung webzugänglich.

Manifest V3-Beispiel

json
"web_accessible_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "extension_ids": ["*"],
    "matches": [ "*://*/*" ]
  }
]

Machen Sie die Datei unter "images/my-image.png" für jede Webseite und Erweiterung webzugänglich.

Es wird empfohlen, extension_ids oder matches nur anzugeben, wenn nötig. Zum Beispiel, wenn die Ressource nur für Webseiten bei example.com zugänglich sein muss:

json
"web_accessible_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "matches": [ "https://example.com/*" ]
  }
]

Beispielerweiterungen

Browser-Kompatibilität