Userstyles

Userstyles zijn CSS-regels die Scratch-pagina’s beïnvloeden. Ze kunnen stijlen toepassen op bestaande Scratch UI, net zoals elementen die door addons zijn toegevoegd.

Userstyles declareren in de addonmanifest

Sommige veranderingen vereisen dat je de extensie herlaadt van chrome://extensions om effect te hebben, zoals het addonmanifest-bestand updaten.

Het is niet nodig om de extensie te herladen wanneer je de bron van een al bestaand userstyle CSS-bestand verandert. In die gevallen is de pagina herladen genoeg.

Userstyles worden gedeclareerd in een “userstyles”-array, vergelijkbaar met userscripts.

Elk item van de array moet de volgende eigenschappen hebben:

"url": de relatieve URL tot een CSS-bestand.
"matches": de lijst van Scratch-pagina’s waar de userstyle van kracht is. Lees matches voor meer informatie.
if: een lijst van voorwaarden die bepalen of de userstyle op dit moment toegepast moet worden of niet. Lees userstyle.if voor meer informatie.

Voorbeeldmanifest:

{
  "name": "Scratch Berichten",
  "description": "Laat je makkelijker je Scratchberichten lezen en erop antwoorden.",
  "userstyles": [
    {
      "url": "styles.css",
      "matches": ["projects", "https://scratch.mit.edu/", "profiles"]
    },
    {
      "url": "resize.css",
      "matches": ["projects"],
      "if": {
        "settings": {
          "resize": true
        }
      }
    },
  ],
  "settings": [
    {
      "name": "Berichtgrootte aanpassen",
      "id": "resize",
      "type": "boolean",
      "default": false
    }
  ],
  "tags": ["community"],
  "enabledByDefault": false
}

Userstyles dynamisch schakelen nadat pagina is geladen

Het is normaal gesproken onnodig om een JavaScript-userscipt te gebruiken om dynamisch te schakelen of een userstyle actief is op de pagina als reactie op de gebruiker die instellingen verandert.

Includeer dynamicEnable: true in de addonmanifest om de extensie userstyles dynamisch in de pagina te laten zetten als de addon (voor de eerste keer) ingeschakeld wordt nadat de pagina is geladen.
Includeer dynamicDisable: true in de addonmanifest om de extensie userstyles dynamisch weg te laten halen uit de pagina of juist er weer in te zetten als de addon wordt geschakeld, zonder dat de pagina moet herladen.
Includeer updateUserstylesOnSettingsChange: true in de addonmanifest om de “if”-condities die afhangen van gebruikersinstellingen opnieuw te laten evalueren. De extensie zal userstyles overeenkomstig weghalen of erin zetten.

Toegang krijgen tot addoninstellingen van CSS

Userstyles kunnen makkelijk kleur- en numerieke instellingen bekijken door CSS-variabelen. Ze kunnen ook toegang krijgen tot instellingen van andere ingeschakelde addons.

De CSS-variabelen volgen altijd het --addonId-settingId-formaat. Setting ID’s worden altijd omgezet van kebab-case naar camelCase.

Deze CSS-variabelen zijn altijd beschikbaar voor alle ingeschakelde addons en geen manifest-eigenschap is nodig om ze te exposen. Ze zijn ook gesynchroniseerd met gebruikersinstellingen zonder de pagina te moeten herladen.

.sa-progress-bar {
  /* Kleurinstelling */
  background-color: var(--progressBar-bgColor);

  /* Kleurinstelling met terugval */
  border-color: var(--editorDarkMode-border, #fc7c24);
  /* Als editor-dark-mode uitgeschakeld is, wordt de terugvalkleur gebruikt */

  /* Numerieke instelling */
  height: calc(1px * var(--progressBar-height));
}

Aangepaste CSS-variabelen

JavaScript is niet nodig als een userstyle tussen één van twee waarden moet kiezen met een achtergrondkleur (tekstcontrast) of een addoninstelling. Deze condities, inclusief anderen, kunnen worden gedeclareerd in de addonmanifest door customCssVariables, en de userstyle kan simpelweg naar die CSS-variabele verwijzen.

Applying styles based on the editor mode

The extension automatically toggles a class name on the <html> element when the user enters or exits the project editor.

Bijvoorbeeld, de <input>-elementen binnen en buiten de editor een andere stijl geven:

.sa-editor input {
  /* Only applies if `addon.tab.editorMode` is `editor` or `fullscreen` */
}

:root:not(.sa-editor) input {
  /* Only applies if `addon.tab.editorMode` is NOT `editor` nor `fullscreen` */
}

Similarly, the .sa-fullscreen class is added to the <html> element when the project is in full screen mode:

.sa-fullscreen [class*="green-flag_green-flag_"] {
  /* Only applies if `addon.tab.editorMode` is `fullscreen` */
}

:root:not(.sa-fullscreen) [class*="green-flag_green-flag_"] {
  /* Only applies if `addon.tab.editorMode` is NOT `fullscreen` */
}

Sectiepagina's

Debugtips

Tips om userstyles makkelijk te debuggen, en randgevallen om rekening mee te houden.
Optimale Praktijken

Volg deze optimale praktijken wanneer je userstyles aan het schrijven of beoordelen bent.