Stili con CSS

Le applicazioni Blockly sono costituite da elementi HTML e SVG. Questi elementi sono etichettati con classi CSS che identificano ciò che rappresentano (ad es. blocklyBlock, blocklyField) e il loro stato (ad es. blocklyEditing, blocklySelected). Blockly fornisce anche un insieme predefinito di regole CSS.

Puoi utilizzare CSS per definire lo stile della tua applicazione:

  • Esegui l'override delle regole CSS di Blockly con le tue regole.
  • Aggiungi le tue classi CSS ai componenti Blockly per una maggiore specificità.
  • Utilizza classi e regole CSS per applicare uno stile ai componenti personalizzati.

Classi CSS

Le applicazioni Blockly utilizzano le classi CSS per identificare gli elementi a cui applicare uno stile. Ciò fornisce un controllo più granulare rispetto ai selettori di tipo (elemento).

Classi CSS di Blockly

Blockly utilizza le classi CSS per fornire i seguenti tipi di informazioni sugli elementi HTML e SVG che utilizza.

  • Tipo. La maggior parte delle classi CSS di Blockly identifica ciò che rappresenta un elemento. Ad esempio, l'elemento principale di un blocco è etichettato blocklyBlock. Alcuni elementi sono etichettati con più classi, ognuna più specifica della precedente. Ad esempio, l'elemento principale di un campo di input di testo è etichettato blocklyField, blocklyInputField e blocklyTextInputField. I tipi di classi rimangono invariati per tutta la durata di un componente.

  • Stato. Blockly utilizza anche le classi CSS per specificare lo stato di un componente. Ad esempio, quando il cursore si trova su un campo di input di testo, il relativo elemento radice è etichettato con la classe blocklyEditing. Quando il cursore viene spostato, questa classe viene rimossa.

  • Informazioni aggiuntive. Blockly utilizza alcune classi CSS per fornire informazioni aggiuntive. Ad esempio, l'iniezione <div> ha classi che forniscono il nome del renderer e del tema correnti dello spazio di lavoro. Queste classi in genere rimangono invariate per tutta la durata dell'applicazione.

Il modo più semplice per scoprire quali classi CSS utilizza Blockly è aprire gli strumenti per sviluppatori del browser ed esaminare gli elementi utilizzati dall'applicazione.

Classi CSS personalizzate

Puoi utilizzare classi CSS personalizzate per fornire maggiore specificità ai componenti Blockly.

Aree di lavoro

Per aggiungere o rimuovere una classe CSS dall'inserimento <div> di uno spazio di lavoro, chiama WorkspaceSvg.addClass o WorkspaceSvg.removeClass.

Toolboxes

Per aggiungere una classe CSS a un pulsante o a un'etichetta in una casella degli strumenti, utilizza il tasto web-class nella definizione JSON della casella degli strumenti. Per saperne di più, consulta Pulsanti ed etichette.

Per ignorare le classi CSS utilizzate per le varie parti di una categoria, utilizza la chiave cssConfig nella definizione JSON della categoria. In questo modo puoi applicare uno stile alle singole categorie. Per ulteriori informazioni, vedi CSS categoria.

Stoppate

Per aggiungere classi CSS a un blocco personalizzato, passa una stringa o un array di stringhe alla chiave classes.

Blockly.common.defineBlocksWithJsonArray([{
  "type": "string_length",
  "message0": 'length of %1',
  "args0": [
    {
      "type": "input_value",
      "name": "VALUE",
      "check": "String",
    }
  ],
  "classes": "myStringLengthBlock",
  "output": "Number",
  "colour": 160,
}]);

Puoi anche aggiungere o rimuovere una classe CSS dall'elemento <g> di un blocco chiamando BlockSvg.addClass o BlockSvg.removeClass.

Campi delle etichette

Per aggiungere o rimuovere una classe CSS dall'elemento <text> utilizzato da un campo etichetta o da un campo etichetta serializzabile, chiama FieldLabel.setClass. Puoi anche passare un nome di classe al costruttore dell'etichetta.

Classi CSS e componenti personalizzati

Quando crei un componente personalizzato, utilizza uno dei seguenti metodi per aggiungere classi CSS personalizzate:

  • Se il componente è una sottoclasse di Field o Icon, esegui l'override del metodo initView. Ad esempio:

    class MyCustomField extends Blockly.FieldTextInput {
  ...

  initView() {
    super.initView();

    // Add custom CSS class so we can style the field.
    if (this.fieldGroup_) {
      Blockly.utils.dom.addClass(this.fieldGroup_, 'myCustomField');
    }
  }
}

    Per saperne di più, vedi Personalizzare i campi con CSS o Creare la visualizzazione dell'icona.

  • Quando crei un elemento SVG, passa la classe a Blockly.utils.dom.createSvgElement:

    this.svgRoot = Blockly.utils.dom.createSvgElement(Svg.G, {'class': 'myCustomComponent'});

  • Quando crei un elemento HTML, utilizza Blockly.utils.dom.addClass:

    const myDiv = document.createElement('div');
Blockly.utils.dom.addClass(myDiv, 'myInformation');

Per aggiungere o rimuovere classi dopo la costruzione, utilizza Blockly.utils.dom.addClass o Blockly.utils.dom.removeClass.

setMyHighlight(highlight) {
  if (highlight) {
    Blockly.utils.dom.addClass(this.svgRoot, 'myHighlight');
  } else {
    Blockly.utils.dom.removeClass(this.svgRoot, 'myHighlight');
  }
}

Sfondo delle regole CSS

Se conosci le proprietà di stile SVG e la cascata CSS, puoi saltare questa sezione.

Proprietà di stile SVG e proprietà CSS

Gli elementi SVG sono stilizzati con le proprietà di stile SVG. Questi possono essere utilizzati come attributi sugli elementi SVG (ovvero attributi di presentazione) o nelle regole CSS. Pertanto, tutte le seguenti azioni hanno lo stesso effetto.

<!-- SVG file with presentation attributes. -->
<circle fill="red" ... />

<!-- SVG file with <style> tag. -->
<style>
  circle {fill:red;}
</style>
<circle ... />

/* External CSS file.*/
circle {fill:red;}

<!-- SVG file with inline style. -->
<circle style="fill:red;" ... />

L'elenco delle proprietà di stile SVG è correlato all'elenco delle proprietà CSS, ma è diverso:

  • Stesso concetto, stesso nome. Ad esempio, sia SVG che CSS utilizzano direction per specificare se il testo è LTR o RTL.
  • Stesso concetto, nome diverso. Ad esempio, SVG utilizza fill per specificare il colore di riempimento, mentre CSS utilizza background-color.
  • Solo CSS. Il CSS ha molte proprietà che non sono presenti in SVG, ad esempio margin e padding.
  • Solo SVG. SVG ha alcune proprietà che non sono in CSS, come x e y.

Pertanto, se stai applicando uno stile a un elemento SVG, utilizza le proprietà di stile SVG. Se stai applicando uno stile a un elemento HTML, utilizza le proprietà CSS.

CSS a cascata

La cascata CSS determina le priorità delle regole CSS, che determinano quale regola utilizzare se più di una regola si applica a una determinata proprietà ed elemento. La seguente cascata semplificata copre le parti della cascata più comunemente utilizzate da Blockly e può aiutarti a rispondere alla domanda "Perché il mio CSS non funziona?".

Cascata semplificata

Per determinare quale regola si applica a un determinato elemento e a una determinata proprietà, segui questi passaggi e interrompiti quando rimane una sola regola:

  1. Raccogli tutte le regole che si applicano alla proprietà e all'elemento.
  2. Se una regola ha un'annotazione !important, ignora tutte le regole che non hanno un'annotazione !important.

  3. Scegli le regole con la specificità più elevata.

    • Gli attributi di presentazione SVG hanno una specificità pari a zero.
    • Le regole in un tag <style> o in un foglio di stile esterno hanno la loro specificità calcolata normalmente.
    • Gli stili incorporati (stili impostati da un attributo style) hanno una specificità superiore a qualsiasi selettore.

  4. Scegli la regola che appare per ultima nel documento.

  5. Se non viene applicata alcuna regola, eredita il valore della proprietà dall'elemento principale.

Questo algoritmo non prende in considerazione le seguenti parti della cascata:

  • La proprietà transition, che ha la priorità più alta. Blockly ne utilizza alcuni.
  • La regola @media. Blockly ne utilizza uno.
  • Regole specificate dal browser o dall'utente.
  • Le regole @ @scope e @layer e la proprietà animation, che non vengono utilizzate da Blockly.

Regole CSS

Le regole CSS specificano lo stile della tua applicazione. Blockly fornisce un insieme predefinito di regole che puoi sostituire con le tue.

Regole CSS di Blockly

Blockly fornisce un insieme predefinito di regole CSS. Il modo e la posizione in cui vengono aggiunte queste regole influiscono sulla loro priorità.

Tag di stile

La maggior parte delle regole CSS di Blockly sono specificate in due tag <style>. Poiché questi tag si trovano nella parte superiore della pagina, le regole contenute hanno una priorità inferiore rispetto alle regole con la stessa specificità che si trovano più in basso nella pagina.

Regole Blockly.css.register

Quando viene inserito Blockly, viene aggiunto un tag <style> come elemento secondario del tag <head>. Le regole in questo tag provengono da:

  • Lo spazio dei nomi Blockly.css. Per visualizzare queste regole, apri core/css.ts e cerca let content.
  • Componenti individuali, che chiamano Blockly.css.register per aggiungere regole CSS specifiche per i componenti. Poiché css.register aggiunge queste regole alla fine della stringa content, hanno una priorità maggiore rispetto alle regole con la stessa specificità aggiunte in precedenza. Per visualizzare queste regole, consulta la sezione Chiamate a Blockly.css.register.

Se non vuoi utilizzare queste regole, imposta l'opzione di configurazione css su false. In questo caso, è tua responsabilità fornire un insieme alternativo di regole CSS.

Regole del renderer

Quando viene creata un'istanza del renderer, questo aggiunge un tag <style> contenente regole CSS specifiche del renderer come elemento secondario del tag <head>. Tieni presente che queste regole vengono sempre aggiunte e non sono interessate dall'opzione di configurazione css. Per visualizzare queste regole, cerca il metodo getCss_ nel renderer.

Stili in linea

Gli stili in linea vengono specificati con l'attributo style e vengono generalmente creati quando viene creato il DOM per un componente. Per un elenco parziale, consulta questa query di GitHub.

Gli stili in linea vengono applicati direttamente all'elemento in cui si verificano e hanno una specificità superiore a qualsiasi selettore. Per questo motivo, l'override in genere richiede l'utilizzo di un'!important annotazione.

Attributi di presentazione SVG

Gli attributi di presentazione SVG sono proprietà di stile SVG utilizzate come attributi degli elementi SVG. Hanno una specificità pari a zero e non possono contenere un'annotazione !important, pertanto hanno la priorità più bassa di tutte le regole di Blockly. Blockly in genere li crea in chiamate a createSvgElement.

Aggiungere regole CSS personalizzate

Puoi aggiungere le tue regole CSS utilizzando gli stessi metodi di Blockly:

  • Chiama Blockly.css.register prima di inserire Blockly. Le tue regole verranno aggiunte dopo quelle di Blockly e avranno una priorità maggiore rispetto alle regole di Blockly con la stessa specificità.
  • Aggiungi un tag <style> o un link a un foglio di stile esterno come elemento secondario successivo del tag <head>. Poiché Blockly aggiunge le sue regole come primi due elementi secondari del tag <head>, le tue regole avranno una priorità maggiore rispetto alle regole di Blockly con la stessa specificità.
  • Utilizza gli stili in linea per aggiungere stili agli elementi in un componente personalizzato. Queste regole avranno una specificità maggiore rispetto a qualsiasi regola con un selettore.
  • Utilizza gli attributi di presentazione sugli elementi SVG in un componente personalizzato. Queste regole avranno una specificità inferiore rispetto a qualsiasi regola con un selettore.

Risoluzione dei problemi

Se il tuo CSS non funziona, ecco alcune possibili cause:

  • Stai utilizzando proprietà CSS su un elemento SVG o proprietà di stile SVG su un elemento HTML. Consulta Proprietà di stile SVG e proprietà CSS.

  • La tua regola ha una priorità inferiore rispetto a un'altra regola. Di solito, questo problema è dovuto a una specificità inferiore. Ecco alcuni modi per risolvere il problema:

    • Utilizza un selettore di classe anziché un selettore di tipo (elemento).
    • Utilizza più selettori.
    • Se possibile, aggiungi una classe personalizzata all'elemento di destinazione e utilizza questa classe nella regola.
    • Come ultima risorsa, aggiungi un'annotazione !important alla regola. Questa è la tua unica scelta se viene specificata una regola in competizione utilizzando uno stile in linea (attributo style).

  • La tua regola ha la stessa specificità di un'altra regola, ma si verifica prima nella pagina. Se non riesci ad aumentare la specificità della regola, spostala più in basso nella pagina.

Esistono due tipi di regole CSS che non puoi sovrascrivere:

  • Proprietà impostate all'interno di una regola transition.
  • Regole !important specificate dal browser.