Benutzerskripte (Userscripts)

Userscripts sind Javascript-Dateien, die jedes Mal, wenn der Benutzer eine Scratchseite öffnet, ausgeführt werden. Sie können das HTML des Dokumentes verändern, neue Schaltflächen hinzufügen, das Verhalten des Scratcheditors verändern, und so viel mehr.

Userscripts für Scratch Addons sind, ähnlich wie Userscripts die du vielleicht für Userscriptmanager wie Tampermonkey oder Greasemonkey runterlädst, JavaScript-Programme, die in dem selben Kontext wie der Javascript-Code von Scratch ausgeführt werden. In Browsererweiterungsworten wird dieser Kontext oft “Hauptwelt” genannt.

Obwohl Scratch Addons-Userscripts Teil einer Browsererweiterung sind, können sie keine chrome.*- oder browser.*-APIs aufrufen. Stattdessen gibt Scratch Addons eine addon.*-API vor.

Userscripts im Addon-Manifest deklarieren

Einige Änderungen erfordern eine Erweiterungsneuladung von chrome://extensions, um wirksam zu werden, wie z. B. die Aktualisierung der Addon-Manifestdatei.

Es ist nicht nötig, die Erweiterung neu zu laden, wenn man den Code einer schon existierenden Javascriptdatei ändern. In diesem Fall kannst du einfach die Seite neu laden.

Userscripts werden in einem “userscripts”-Array deklariert.

Jedes Element dieses Arrays muss die folgenden Elemente haben:

"url": die relative URL zu einer Javascript-Datei
"matches": Die Liste von Scratchseiten, wo das Userscript ausgeführt wird. Siehe matches für mehr Informationen.

Beispielsmanifest:

{
  "name": "Copy link to comment button",
  "description": "Adds a \"Copy Link\" button to all comments on the website, next to the \"Report\" button.",
  "userscripts": [
    {
      "url": "userscript.js",
      "matches": ["projects", "https://scratch.mit.edu/", "profiles", "studios"]
    }
  ],
  "tags": ["community"],
  "enabledByDefault": false
}

Erstellen deines ersten Benutzerskripts

Im Gegensatz zu Erweiterungsinhaltsskripten und Tampermonkey-Benutzerskripten musst du deinen gesamten Code in einem Standardexportmodul einschließen:

// Beispiel-Benutzerskript
export default async function ({ addon, console }) {
  console.log("Hallo, " + await addon.auth.fetchUsername());
  console.log("Wie geht es dir heute?");
}

Denke daran, dass JavaScript es erlaubt, Funktionen innerhalb anderer Funktionen zu deklarieren, zum Beispiel:

export default async function ({ addon, console }) {
  async function sayHelloToUser() {
    console.log("Hallo, " + await addon.auth.fetchUsername());
  }

  await sayHelloToUser();
  console.log("Wie geht es dir heute?");
}

Du kannst auf viele Addons* zugreifen. API-Dienstprogramme aus Benutzerskripten. Du kannst beispielsweise den aktuellen Benutzernamen abrufen, warten, bis ein Element auf der Seite vorhanden ist, oder einen Verweis auf das Scratch VM-Objekt abrufen.

Weitere Informationen findest du unter der API-Referenz.

Ändern des Dokuments HTML

Verwende Browser-DOM-APIs, um den HTML-Code der Seite anzupassen.

Hier ist ein Beispiel:

const myButton = document.createElement("Button");
myButton.textContent = "Klicke auf mich!";
myButton.classList.add("button");
myButton.setAttribute("title", "Du hoverst über einen Button");

const myContainer = document.querySelector(".container");
myContainer.append(myButton);

Lokalisierung von Benutzerskripten

Addon-Benutzerskripte müssen manchmal auf englische Wörter oder Sätze verweisen. Stelle sicher, dass du sie nicht fest programmieren, damit sie Teil des Übersetzungsprozesses sein können.

// Tu dies nicht:
document.querySelector(".sa-find-bar").placeholder = "Find blocks";

Um eine übersetzbare Zeichenfolge zu erstellen, gehe folgendermaßen vor:

Erstelle eine Datei mit dem Namen addon-id.json im Ordner /addon-l10n/en.
Gebe für jede Zeichenfolge eine ID an:

{
  "addon-id/find": "Find blocks"
}

Stelle sicher, dass die Funktion msg() in dem Benutzerskript importiert wird. Die erste Zeile des Benutzerskripts sollte wie folgt aussehen:

export default async function ({ addon, console, msg  }) {
                                              // ^^^

Verwende die Funktion msg() in Ihrem Code anstelle einer fest codierten Zeichenfolge:

document.querySelector(".sa-find-bar").placeholder = msg("find");

Weitere Informationen zur Lokalisierung von Benutzerskripten findest du unter dieser Seite.

Technische Details

Jede Benutzerskriptdatei ist ein JavaScript-Modul, das eine Funktion exportiert. Scratch Addons importiert das Modul nur bei Bedarf und führt es aus, nachdem die Seite vollständig geladen wurde.

Userscripts sind JavaScript-Module, daher laufen sie immer im “strict mode”. Dies bedeutet auch, dass Benutzerskripte Top-Level-Imports verwenden können, um andere JavaScript-Dateien zu importieren.

Die Reihenfolge, in der Userscripts ausgeführt werden, kann bei jedem Seitenladen variieren. Nach dem Laden der Seite aktiviert der Benutzer möglicherweise einige Add-Ons dynamisch in einer benutzerdefinierten Reihenfolge, sodass die Ausführungsreihenfolge nie garantiert ist. Einige APIs wie addon.tab.appendToSharedSpace versuchen, alle potenziellen Race Conditions und unerwarteten Verhaltensweisen beim dynamischen Aktivieren von Add-ons zu beheben.

runAtComplete

Userscripts können sich dafür entscheiden, ausgeführt zu werden, bevor die Seite vollständig geladen ist, indem Sie im Addon-Manifest einmal für jedes Userscript "runAtComplete": false angeben.

Derzeit ist nur die Existenz von document.head garantiert, wenn ein Benutzerskript frühzeitig ausgeführt wird. In Zukunft wird auch die Existenz von document.body garantiert sein, sodass nie Userscripts ausgeführt werden, bevor das HTML-Dokument ausreichend geladen ist, um </head> <body> zu erreichen.

Sektions-Seiten

Empfohlene Vorgehensweisen

Wenn du Code für Userscripts schreibst oder überprüfst, folge diesen empfohlenen Vorgehensweisen.
Tipps zum Debugging

Tipps zum einfachen Debuggen von Benutzerskripten und zu berücksichtigende Edge-Fälle.