Scripts utilisateurs

De quoi s’agit-il ?

Les scripts utilisateur vous permettent d’exécuter du code sur les pages de Scratch - vous pouvez y faire des choses comme ajouter des boutons, améliorer l’éditeur Scratch ou tout ce que vous pouvez imaginer.

Comment puis-je ajouter un script utilisateur ?

Assurez-vous d’actualiser Scratch Addons à partir de chrome://extensions après avoir apporté des modifications à votre addon. Accédez au manifeste de votre addon (addon.json) et ajoutez une propriété appelée userscripts". Cette propriété doit être un tableau. Chaque élément du tableau doit avoir les propriétés suivantes : "url" et "matches". "url" doit être une URL relative vers un fichier JavaScript. "matches" doit être un tableau d’URL sur lesquelles vous souhaitez exécuter le script utilisateur. Vous pouvez utiliser des astérisques. Exemple de manifeste :

{
"name": "Messages Scratch",
"description": "Facilite la possibilité de lire et répondre aux messages Scratch",
"userscripts": [
{
"url": "userscript.js",
"matches": ["https://scratch.mit.edu/*"]
},
{
"url": "second_userscript.js",
"matches": ["https://scratch.mit.edu/projects/*", "https://scratch.mit.edu/users/*"]
}
],
"tags": ["community"],
"enabled_by_default": false
}

À quoi un fichier JavaScript ressemble?

Les scripts utilisateur ont besoin d’une structure spéciale pour fonctionner. Vous devez absolument implanter votre code dans une fonction comme ceci :

export default async function ({ addon, global, console }) {
console.log("Hello, " + addon.auth.username);
}

Si souhaitez écrire vos propres fonction pour avoir un code plus aéré, vous devez les inclure dans la fonction principale: Comme ceci:

export default async function ({ addon, global, console }) {
// Ça marche!
sayHello();
function sayHello() {
console.log("Hello, " + addon.auth.username);
}
}

Ça Ne marchera PAS:

export default async function ({ addon, global, console }) {
// This WON'T work!
sayHello();
}
function sayHello() {
console.log("Hello, " + addon.auth.username);
// Error: addon is not defined!
}

addon.* APIs

Vous pouvez accéder à certaines API addon.* à partir de scripts utilisateur. Pour plus d’informations, consultez la documentation.

Aspects techniques des scripts utilisateur

Userscripts run after the Scratch page has fully loaded - in other words, they run in defer mode. Technically speaking, each userscript is a JavaScript module that exports a function. JavaScript modules always run on “strict mode”.
This means that userscripts of the same addon DO NOT share variables and functions! If you want to do that, you should use the global object (more info below). Scratch Addons then calls that function modules exported, giving it access to the addon.* APIs, as well as special wrappers:

  • addon: donne aux scripts utilisateurs l’accès à addon.* APIs.
  • global: this is a shared object between all userscripts of the same addon. Example usage:
// userscript-1.js
export default async function ({ addon, global, console }) {
  global.sayHello = () => console.log("Hello, " + addon.auth.username);
}

// userscript-2.js
export default async function ({ addon, global, console }) {
  global.sayHello();
  // This works, as long as in the addon manifest, userscript-1.js is before userscript-2.js in the userscripts array.
}
  • console: this is a wrapper that allows you to see what addon triggered the log you’re seeing easily.

Débogage des scripts utilisateur

Make sure to refresh Scratch Addons from chrome://extensions after doing any changes to your addon.
To debug userscripts, first of all make sure your addon is enabled.
Then, go to a URL where you specified your userscript should run.
Open the console by pressing Ctrl+Shift+J.
You should see console logs by addons, including yours. If you’re a devtools pro, you won’t have any trouble setting breakpoints in your code.
Protip: if you want to test the addon.* API without changing your file every time, make your addon window.addon = addon; (inside the main function), and you’ll be able to access your addon’s addon object from the console. Make sure to remove that line before contributing to this repo! Userscripts must not pollute the global object.


Améliorer cette page

Commentaires

Assurez-vous de suivre le code de conduite. Vous pouvez voir cette section de commentaires sur les discussions GitHub, ainsi que modifier et supprimer votre commentaire.