Style avec CSS

Les applications Blockly sont constituées d'éléments HTML et SVG. Ces éléments sont associés à des classes CSS qui identifient ce qu'ils représentent (par exemple, blocklyBlock, blocklyField) ainsi que leur état (par exemple, blocklyEditing, blocklySelected). Blockly fournit également un ensemble de règles CSS par défaut.

Vous pouvez utiliser le CSS pour styliser votre application :

• Remplacez les règles CSS de Blockly par les vôtres.
• Ajoutez vos propres classes CSS aux composants Blockly pour plus de spécificité.
• Utilisez des classes et des règles CSS pour styliser les composants personnalisés.

Remarque : Bien que Blockly soit toujours compatible avec les thèmes, la méthode privilégiée pour styliser les applications Blockly est d'utiliser CSS.

Classes CSS

Les applications Blockly utilisent des classes CSS pour identifier les éléments à styliser. Cela permet un contrôle plus précis que les sélecteurs de type (élément).

Classes CSS Blockly

Blockly utilise des classes CSS pour fournir les types d'informations suivants sur les éléments HTML et SVG qu'il utilise.

• Type La plupart des classes CSS Blockly identifient ce qu'un élément représente. Par exemple, l'élément racine d'un bloc est libellé blocklyBlock. Certains éléments sont associés à plusieurs classes, chacune étant plus spécifique que la précédente. Par exemple, l'élément racine d'un champ de saisie de texte est libellé blocklyField, blocklyInputField et blocklyTextInputField. Les classes de type restent les mêmes pendant toute la durée de vie d'un composant.

• État Blockly utilise également des classes CSS pour spécifier l'état d'un composant. Par exemple, lorsque le curseur se trouve sur un champ de saisie de texte, son élément racine est associé à la classe blocklyEditing. Lorsque le curseur est déplacé, cette classe est supprimée.

• Informations supplémentaires Blockly utilise quelques classes CSS pour fournir des informations supplémentaires. Par exemple, l'injection <div> comporte des classes qui fournissent le nom du rendu et du thème actuels de l'espace de travail. Ces classes restent généralement les mêmes pendant toute la durée de vie de l'application.

Le moyen le plus simple de découvrir les classes CSS utilisées par Blockly consiste à ouvrir les outils pour les développeurs de votre navigateur et à inspecter les éléments utilisés par votre application.

Classes CSS personnalisées

Vous pouvez utiliser des classes CSS personnalisées pour spécifier plus précisément les composants Blockly.

Espaces de travail

Pour ajouter ou supprimer une classe CSS de l'injection <div> d'un espace de travail, appelez WorkspaceSvg.addClass ou WorkspaceSvg.removeClass.

Boîtes à outils

Pour ajouter une classe CSS à un bouton ou à un libellé dans une boîte à outils, utilisez la clé web-class dans votre définition JSON de la boîte à outils. Pour en savoir plus, consultez Boutons et libellés.

Pour remplacer les classes CSS utilisées pour les différentes parties d'une catégorie, utilisez la clé cssConfig dans la définition JSON de la catégorie. Cela vous permet de styliser des catégories individuelles. Pour en savoir plus, consultez CSS des catégories.

Blocs

Pour ajouter des classes CSS à un bloc personnalisé, transmettez une chaîne ou un tableau de chaînes à la clé 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,
}]);

Vous pouvez également ajouter ou supprimer une classe CSS de l'élément <g> d'un bloc en appelant BlockSvg.addClass ou BlockSvg.removeClass.

Champs de libellé

Pour ajouter ou supprimer une classe CSS de l'élément <text> utilisé par un champ de libellé ou un champ de libellé sérialisable, appelez FieldLabel.setClass. Vous pouvez également transmettre un nom de classe au constructeur du libellé.

Classes CSS et composants personnalisés

Lorsque vous créez un composant personnalisé, utilisez l'une des méthodes suivantes pour ajouter des classes CSS personnalisées :

• Si votre composant est une sous-classe de Field ou Icon, remplacez la méthode initView. Exemple :

  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');
      }
    }
  }
  

  Pour en savoir plus, consultez Personnaliser les champs avec CSS ou Créer la vue de l'icône.

• Lorsque vous construisez un élément SVG, transmettez votre classe à Blockly.utils.dom.createSvgElement :

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

• Lorsque vous créez un élément HTML, utilisez Blockly.utils.dom.addClass :

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

Pour ajouter ou supprimer des classes après la construction, utilisez Blockly.utils.dom.addClass ou Blockly.utils.dom.removeClass.

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

Avertissement : N'utilisez pas dom.addClass ni dom.removeClass pour ajouter ou supprimer des classes dans des composants écrits par d'autres personnes, y compris Blockly. Cela peut entraîner des résultats imprévisibles.

Contexte des règles CSS

Si vous comprenez les propriétés de style SVG et la cascade CSS, vous pouvez ignorer cette section.

Propriétés de style SVG et propriétés CSS

Les éléments SVG sont stylisés avec des propriétés de style SVG. Ils peuvent être utilisés comme attributs sur les éléments SVG (également appelés attributs de présentation) ou dans les règles CSS. Ainsi, toutes les commandes suivantes font la même chose.

<!-- 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;" ... />

La liste des propriétés de style SVG est liée à la liste des propriétés CSS, mais elle en diffère :

• Même concept, même nom. Par exemple, SVG et CSS utilisent tous deux direction pour spécifier si le texte est de gauche à droite ou de droite à gauche.
• Même concept, nom différent. Par exemple, SVG utilise fill pour spécifier la couleur de remplissage, tandis que CSS utilise background-color.
• CSS uniquement : Le CSS comporte de nombreuses propriétés qui ne sont pas dans le SVG, comme margin et padding.
• SVG uniquement. SVG comporte quelques propriétés qui ne sont pas dans CSS, telles que x et y.

Par conséquent, si vous stylisez un élément SVG, utilisez les propriétés de style SVG. Si vous mettez en forme un élément HTML, utilisez les propriétés CSS.

Cascade CSS

La cascade CSS détermine les priorités des règles CSS, qui déterminent la règle à utiliser si plusieurs règles s'appliquent à une propriété et à un élément donnés. La cascade simplifiée suivante couvre les parties de la cascade les plus couramment utilisées par Blockly et peut vous aider à répondre à la question "Pourquoi mon CSS ne fonctionne-t-il pas ?".

Cascade simplifiée

Pour déterminer la règle qui s'applique à un élément et à une propriété spécifiques, suivez ces étapes et arrêtez-vous lorsqu'il ne reste plus qu'une seule règle :

1. Rassemblez toutes les règles qui s'appliquent à la propriété et à l'élément.
2. Si des règles comportent une annotation !important, ignorez toutes les règles qui n'en comportent pas.!important

3. Choisissez les règles les plus spécifiques.

   • La spécificité des attributs de présentation SVG est nulle.
   • La spécificité des règles dans une balise <style> ou une feuille de style externe est calculée normalement.
   • Les styles intégrés (styles définis par un attribut style) ont une spécificité supérieure à celle de n'importe quel sélecteur.

4. Choisissez la règle qui apparaît en dernier dans le document.

5. Si aucune règle ne s'applique, héritez de la valeur de la propriété à partir de l'élément parent.

Cet algorithme ne tient pas compte des éléments suivants de la cascade :

• La propriété transition, qui a la priorité la plus élevée. Blockly en utilise quelques-uns.
• La règle at @media. Blockly en utilise un.
• Règles spécifiées par le navigateur ou l'utilisateur.
• Les règles @ @scope et @layer, ainsi que la propriété animation, qui ne sont pas utilisées par Blockly.

Règles CSS

Les règles CSS spécifient le style de votre application. Blockly fournit un ensemble de règles par défaut que vous pouvez remplacer par les vôtres.

Règles CSS Blockly

Blockly fournit un ensemble de règles CSS par défaut. La façon dont ces règles sont ajoutées et l'endroit où elles le sont ont une incidence sur leur priorité.

Balises de style

La majorité des règles CSS de Blockly sont spécifiées dans deux balises <style>. Étant donné que ces balises se trouvent en haut de la page, les règles qu'elles contiennent ont une priorité inférieure à celle des règles ayant la même spécificité qui se trouvent plus bas sur la page.

Règles Blockly.css.register

Lorsque Blockly est injecté, il ajoute une balise <style> en tant qu'enfant de la balise <head>. Les règles de ce tag proviennent des éléments suivants :

• Espace de noms Blockly.css. Pour consulter ces règles, ouvrez core/css.ts et recherchez let content.
• Composants individuels qui appellent Blockly.css.register pour ajouter des règles CSS spécifiques aux composants. Comme css.register ajoute ces règles à la fin de la chaîne content, elles ont une priorité plus élevée que les règles ayant la même spécificité qui ont été ajoutées précédemment. Pour consulter ces règles, consultez les appels vers Blockly.css.register.

Si vous ne souhaitez pas utiliser ces règles, définissez l'option de configuration css sur false. Dans ce cas, vous devez fournir un autre ensemble de règles CSS.

Règles du moteur de rendu

Lorsque le moteur de rendu est instancié, il ajoute une balise <style> contenant des règles CSS spécifiques au moteur de rendu en tant qu'enfant de la balise <head>. Notez que ces règles sont toujours ajoutées. Elles ne sont pas concernées par l'option de configuration css. Pour afficher ces règles, recherchez la méthode getCss_ dans votre moteur de rendu.

Styles intégrés

Les styles intégrés sont spécifiés avec l'attribut style et sont généralement créés lorsque le DOM d'un composant est créé. Pour obtenir une liste partielle, consultez cette requête GitHub.

Les styles intégrés s'appliquent directement à l'élément sur lequel ils se trouvent et ont une spécificité supérieure à celle de n'importe quel sélecteur. Pour cette raison, les remplacer nécessite généralement l'utilisation d'une annotation !important.

Attributs de présentation SVG

Les attributs de présentation SVG sont des propriétés de style SVG utilisées comme attributs d'éléments SVG. Elles ont une spécificité de zéro et ne peuvent pas contenir d'annotation !important. Elles ont donc la priorité la plus basse de toutes les règles Blockly. Blockly les crée généralement dans les appels à createSvgElement.

Ajouter vos propres règles CSS

Vous pouvez ajouter vos propres règles CSS en utilisant les mêmes méthodes que Blockly :

• Appelez Blockly.css.register avant d'injecter Blockly. Vos règles seront ajoutées après celles de Blockly et auront une priorité plus élevée que les règles Blockly ayant la même spécificité.
• Ajoutez une balise <style> ou un lien vers une feuille de style externe en tant qu'enfant ultérieur de la balise <head>. Comme Blockly ajoute ses règles en tant que deux premiers enfants de la balise <head>, vos règles auront une priorité plus élevée que les règles Blockly ayant la même spécificité.
• Utilisez des styles intégrés pour ajouter des styles aux éléments d'un composant personnalisé. Ces règles auront une spécificité plus élevée que toutes les règles comportant un sélecteur.
• Utilisez des attributs de présentation sur les éléments SVG d'un composant personnalisé. Ces règles seront moins spécifiques que celles comportant un sélecteur.

Dépannage

Si votre CSS ne fonctionne pas, voici quelques causes possibles :

• Vous utilisez des propriétés CSS sur un élément SVG ou des propriétés de style SVG sur un élément HTML. Consultez Propriétés de style SVG par rapport aux propriétés CSS.

• Votre règle a une priorité inférieure à celle d'une autre règle. Cela est généralement dû à une spécificité plus faible. Voici quelques solutions possibles :

  • Utilisez un sélecteur de classe plutôt qu'un sélecteur de type (élément).
  • Utilisez plusieurs sélecteurs.
  • Si possible, ajoutez une classe personnalisée à votre élément cible et utilisez cette classe dans votre règle.
  • En dernier recours, ajoutez une annotation !important à votre règle. Il s'agit de votre seule option si une règle concurrente est spécifiée à l'aide d'un style intégré (attribut style).

• Votre règle a le même niveau de spécificité qu'une autre règle, mais elle apparaît plus tôt sur la page. Si vous ne pouvez pas augmenter la spécificité de votre règle, déplacez-la plus bas sur la page.

Il existe deux types de règles CSS que vous ne pouvez pas remplacer :

• Propriétés définies dans une règle transition.
• Règles !important spécifiées par le navigateur.