Userscript

Gli userscript sono file JavaScript che vengono eseguiti ogni volta che l’utente carica una pagina di Scratch. Possono modificare il codice HTML del documento, aggiungere nuovi pulsanti, personalizzare il comportamento dell’editor di Scratch e molto altro ancora.

In modo simile agli userscript che potresti scaricare per gestori di userscript come Tampermonkey o Greasemonkey, gli userscript di Scratch Addons consistono di porzioni di codice JavaScript che vengono eseguite nello stesso contesto di esecuzione del codice JavaScript di Scratch. Nelle terminologia delle estensioni del browser, questo contesto di esecuzione è spesso chiamato il “main world”.

Anche se gli userscript di Scratch Addons fanno parte di un’estensione del browser, non possono accedere a nessuna API chrome.* or browser.*. Al contrario, Scratch Addons offre una API addon.*.

Dichiarazione di userscript nel file manifest dell’addon

Gli userscript sono dichiarati nell’array “userscripts”.

Ogni elemento dell’array deve avere le seguenti proprietà:

• "url": l’URL relativo di un file Javascript.
• "matches": la lista di pagine Scratch a cui lo userscript verrà eseguito. Per ulteriori informazioni vai a matches.

Esempio di manifest:

{
  "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
}

Creazione del tuo primo userscript

A differenza degli script di contenuto delle estensioni e degli userscript di Tampermonkey, è necessario inserire tutto il codice all’interno di default export di un modulo:  

// Userscript di esempio
export default async function ({ addon, console }) {
  console.log("Ciao, " + await addon.auth.fetchUsername());
  console.log("Come va oggi?");
}

Ricorda che JavaScript permette di dichiarare funzioni all’interno di altre funzioni, ad esempio:

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

  await sayHelloToUser();
  console.log("Come va oggi?");
}

Modificare il codice HTML del documento

Per personalizzare il codice HTML della pagina usa le API del DOM del browser.

Ecco un esempio:

const myButton = document.createElement("button");
myButton.textContent = "Cliccami!";
myButton.classList.add("button");
myButton.setAttribute("title", "Stai passando con il mouse sopra ad un pulsante");

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

Localizzazione degli userscript

Gli userscript degli addon a volte devono mostrare parole o frasi in inglese. Assicurati di non inserirle direttamente nel codice in modo che possano entrare a far parte integrante del processo di traduzione di Scratch Addons.

// NON scrivere il codice il questo modo:
document.querySelector(".sa-find-bar").placeholder = "Find blocks";

Per creare una scritta che possa essere tradotta, segui questi passi:

1. Crea un file chiamato addon-id.json dentro la cartella /addon-l10n/en.
2. Crea un ID per ogni stringa:

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

3. Assicurati di importare la funzione msg() nel tuo userscript. La prima linea del tuo userscript dovrebbe essere questa:

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

4. Nel tuo codice usa la funzione msg() invece di una stringa cablata:

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

Dettagli tecnici

Il file di ogni userscript è un modulo JavaScript che esporta una funzione. Scratch Addons importa il modulo solo se è necessario e lo esegue dopo che la pagina è stata completamente caricata.

Gli userscript sono moduli JavaScript, quindi vengono sempre eseguiti in “strict mode”. Questo significa che gli userscript possono usare importazioni top-level per importare altri file JavaScript.

L’ordine in cui gli userscript vengono eseguiti varia ad ogni caricamento della pagina. Dopo che la pagina è stata caricata l’utente può abilitare dinamicamente alcuni addon nell’ordine che preferisce, quindi l’ordine di esecuzione non è mai garantitoa. Alcune API, come ad esempio addon.tab.appendToSharedSpace, tentano di risolvere ogni race condition e ogni comportamento inatteso quando si caricano dinamicamente gli addon.

runAtComplete

Gli userscript possono scegliere di essere eseguiti prima che la pagina sia completamente caricata specificando "runAtComplete": false nel file manifest dell’addon. Va fatto per ogni userscript.

Al momento, solo l’esistenza di document.head è garantita se si esegue uno userscript in anticipo. In futuro sarà garantita anche l’esistenza di document.body, quindi nessuno userscript verrà eseguito prima che il documento HTML sia stato caricato abbastanza da raggiungere </head> <body>.

Pagine della sezione

• Migliori Pratiche

  Segui queste migliori pratiche quando scrivi o rivedi gli userstyle.

• Suggerimenti per il debug

  Suggerimenti per debuggare facilmente gli userstyle e casi limite di cui tener conto.