Пользовательские скрипты

Пользовательские сценарии — это файлы JavaScript, которые воспроизводятся каждый раз при загрузке страницы Scratch. Они могут изменять HTML документа, добавлять новые кнопки, персонализировать поведение редактора Scratch и многое другое.

Также как и в пользовательских сценариях, которые Вы можете скачивать для таких менеджеров пользовательских сценариев, как Tampermonkey или Greasemonkey, пользовательские сценарии Scratch Addons составлены из кусочков JavaScript, исполняемых в том же контексте, что и код JavaScript из самого Scratch. В словаре браузерных расширений, этот контекст воспроизведения называют “основной мир”.

Несмотря на то, что пользовательские сценарии Scratch Addons являются частью браузерного расширения, они не имеют доступ к интерфейсам chrome.* или browser.*. Вместо этого, Scratch Addons предоставляет интерфейс addon.*.

Объявление пользовательских сценариев в манифесте дополнения

Пользовательские сценарии объявляются в массиве “userscripts”

Каждый предмет массива должен иметь следующие свойства:

• "url": относительная гиперссылка к файлу JavaScript.
• "matches": список страниц Scratch, где пользовательский сценарий будет воспроизводиться. Смотрите совпадения для исчерпывающей информации.

Примерный манифест:

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

Создание Вашего первого пользовательского сценария

В отличии от расширений сценариев контента и пользовательских сценариев Tampermonkey, Вы должны упаковать весь Ваш код внутри основного экспорта модуля:

// Примерный пользовательский сценарий
export default async function ({ addon, console }) {
  console.log("Hello, " + await addon.auth.fetchUsername());
  console.log("How are you today?");
}

Запомните, что JavaScript позволяет функциям объявляться внутри других функций, как здесь:

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

  await sayHelloToUser();
  console.log("How are you today?");
}

Изменение HTML документа

Используйте интерфейсы DOM браузера для изменения HTML страницы.

Вот пример:

const myButton = document.createElement("button");
myButton.textContent = "Click me!";
myButton.classList.add("button");
myButton.setAttribute("title", "You're hovering a button");

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

Локализация пользовательских сценариев

Пользовательским сценариям дополнениц иногда надо ссылаться на английские слова или предложения. Пожалуйста, не привязывайте из напрямую, чтобы они могли участвовать в процессе перевода.

// Не делайте так:
document.querySelector(".sa-find-bar").placeholder = "Find blocks";

Чтобы создать переводимую строку, следуйте этим инструкциям:

1. Создайте файл под названием addon-id.json внутри папки /addon-l10n/en.
2. Дайте каждой строке идентификатор:

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

3. Не забудьте импортировать функцию msg() в Вашем пользовательском сценарии. Первая строка вашего кода должна выглядеть примерно вот так:

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

4. Используйте функцию msg() в Вашем коде, вместо прямой строки:

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

Технические детали

Каждый файл пользовательского сценария — это модуль JavaScript, который экспортирует функцию. Scratch Addons импортирует модуль лишь при надобности и исполняет его код после полной загрузки страницы.

Пользовательские сценарии — это модули JavaScript, поэтому они всегда воспроизводятся на “строгом режиме”. Это также означает, что пользовательские сценарии могут использовать высшие импортирования других файлов JavaScript.

Порядок, в котором пользовательские сценарии исполняются может изменяться на каждой загрузке страницы. После загрузки страницы, пользователь может динамически включать некоторые дополнения вперемешку, поэтому порядок поспроизведения никогда не гарантирован. Такие интерфейсы, как addon.tab.appendToSharedSpace пытаются решить возможные крайние случаи обгона и неожиданное поведение при динамическом включении дополнений.

runAtComplete

Пользовательские сценарии также могут попросить исполняться до полной загрузки страницы с помощью опции "runAtComplete": false в манифесте дополнения, раз для каждого пользовательского сценария.

Пока что только присутствие document.head гарантировано при воспроизведении пользовательского сценария раньше времени. В будущем, существование document.body тоже будет гарантироваться, чтобы никакие пользовательские сценарии не воспроизводились до того, как документ HTML загрузился до точки </head> <body>.

Содержание

• Лучшие Практики

  Следуйте эти лучшие практики при написании или подтверждении кода пользовательских сценариев.

• Советы для Отладки

  Советы для легкой отладки пользовательских сценариев, а также частые крайние случаи для учитывания.