Types de champs
Blockstudio propose plusieurs types de champs pour créer des interfaces de blocs.
Les projets peuvent également enregistrer leurs propres types de champs avec espace de noms à l’aide de blockstudio/field_types. Utilisez cette méthode si vous avez besoin d’un nouveau contrôle d’éditeur ou d’une structure de valeur. Utilisez les champs custom/{name} si vous avez seulement besoin de réutiliser un groupe de champs existants.
Recettes pratiques : groupes conditionnels, listes de sélection intelligentes, répéteurs et stockage interrogeable.
Propriétés générales
Le tableau ci-dessous répertorie les propriétés communes et les options de valeur courantes. default et fallback sont pris en charge lorsqu’ils figurent dans le tableau des propriétés de chaque type de champ.
| Propriété | Type | Description |
|---|---|---|
id |
chaîne | Identifiant unique de l’attribut |
type |
chaîne | Type de champ |
label |
chaîne | Libellé affiché dans l’éditeur |
description |
chaîne | Texte descriptif affiché sous le champ |
default |
mixte | Valeur par défaut du champ |
fallback |
mixte | Valeur de secours lorsque le champ est vide |
help |
chaîne | Texte d’aide affiché sous forme d’infobulle à côté du libellé |
hidden |
booléen | Masquer le champ dans UI |
switch |
booléen | Afficher un bouton bascule permettant de désactiver le champ. La valeur par défaut est false. |
translate |
booléen | Définissez sur false pour exclure le champ de la configuration WPML |
conditions |
tableau | Règles de logique conditionnelle |
Les champs de type fichier avec "returnFormat": "id" préservent les références de chaînes importées, y compris les valeurs uniques dans les répéteurs. Les noms non résolus affichent des cartes de secours sans miniatures ; Blockstudio ne les convertit pas en identifiants de pièces jointes. Consultez les références de médias portables pour plus de détails.
Consultez Chargement des icônes pour les requêtes du sélecteur, les nouvelles tentatives et les sous-ensembles d’icônes.
attributs
Génère des champs de saisie d’attributs de données.
{
"type": "attributes"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
array |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
array |
Valeur de repli affichée lorsque la valeur du champ est vide. |
link |
boolean |
Permet de sélectionner un lien dans une liste déroulante. |
media |
boolean |
Permet de sélectionner un média dans une liste déroulante. |
block
Fait référence à un autre bloc Blockstudio et développe ses champs en ligne. Dans les modèles, la valeur renvoie le contenu rendu du bloc.
{
"type": "block"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
block |
string |
Nom du bloc auquel faire référence (e.g, « mytheme/card »). |
returnFormat |
string |
Définit la manière dont la valeur est renvoyée dans les modèles. |
checkbox
Affiche un ensemble de cases à cocher.
{
"type": "checkbox",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
array | string | number |
Valeur par défaut à appliquer lors de l’ajout initial du bloc. |
fallback |
array | string | number |
Valeur de secours affichée lorsque la valeur du champ est vide. |
options |
array |
Options parmi lesquelles choisir. |
returnFormat |
string |
Spécifie le format de la valeur renvoyée. |
populate |
object |
|
toggle |
boolean | string |
Ajoute au-dessus des options une case à cocher permettant de toutes les sélectionner ou de toutes les désélectionner. Une chaîne sert de libellé ; la valeur true utilise le libellé par défaut. |
classes
Affiche un champ permettant de sélectionner des classes CSS.
{
"type": "classes"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
tailwind |
boolean |
Indique s’il faut activer les classes Tailwind pour ce champ de saisie. |
code
Affiche un éditeur de code.
{
"type": "code"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut appliquée lors de l’ajout initial du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
autoCompletion |
boolean |
Indique s’il faut activer ou non la complétion automatique. |
foldGutter |
boolean |
Indique s’il faut afficher ou non la marge de repli. |
height |
string |
Hauteur de l’éditeur. |
language |
string |
Langage utilisé pour la coloration syntaxique. |
lineNumbers |
boolean |
Indique s’il faut afficher ou non les numéros de ligne. |
maxHeight |
string |
Hauteur maximale de l’éditeur. |
minHeight |
string |
Hauteur minimale de l’éditeur. |
popout |
boolean |
Indique s’il faut afficher ou non un bouton ouvrant l’éditeur dans une fenêtre contextuelle. |
asset |
boolean |
Génère CSS, SCSS ou JavaScript du champ comme ressource du bloc, afin que le modèle n’ait pas à afficher la balise de style ou de script. |
color
Affiche une palette de couleurs et un sélecteur de couleur.
{
"type": "color",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur de l’option sélectionnée lors de l’ajout initial du bloc. |
fallback |
string |
Valeur de l’option affichée lorsque la valeur du champ est vide. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
Indique si la palette doit ou non comporter un bouton d’effacement. |
disableCustomColors |
boolean |
Indique si une couleur personnalisée est autorisée. |
date
Affiche un sélecteur de date.
{
"type": "date"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
startOfWeek |
number |
Jour de début de la semaine : 0 pour dimanche, 1 pour lundi, etc. |
datetime
Affiche un sélecteur de date et d’heure.
{
"type": "datetime"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
is12Hour |
boolean |
Indique si l’horloge utilise le format 12 heures. Ce format affiche un sélecteur AM/PM et suppose le format d’heure MM-DD-YYYY (au lieu du format par défaut DD-MM-YYYY). |
files
Affiche un bouton ouvrant la bibliothèque de médias. Les éléments sélectionnés peuvent être réorganisés directement dans le champ.
{
"type": "files",
"min": 0,
"max": 100,
"multiple": false
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
array | object | number |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
array | object | number |
Valeur de repli affichée lorsque la valeur du champ est vide. |
addToGallery |
boolean |
Si cette valeur est true, la fenêtre modale de la galerie s’ouvre directement dans la bibliothèque de médias, où l’utilisateur peut ajouter des images. Si elle est false, elle s’ouvre en mode modification, où l’utilisateur peut modifier les images existantes, les réorganiser, les supprimer ou changer leurs attributs. S’applique uniquement si gallery === true. |
allowedTypes |
array | string |
Tableau des types de médias à téléverser ou à sélectionner dans la bibliothèque. Chaque type est une chaîne qui peut contenir le type MIME général e.g : ‘image’, ‘audio’, ‘text’, ou le type MIME complet e.g : ‘audio/mpeg’, ‘image/gif’. Si allowedTypes n’est pas défini, tous les types MIME sont autorisés. |
gallery |
boolean |
Si cette valeur est true, le composant initialise tous les états nécessaires à l’affichage d’une galerie. Par défaut, la fenêtre modale des médias s’ouvre dans l’interface de modification de la galerie, mais cela peut être changé à l’aide de addToGalleryflag. |
max |
number |
Nombre maximal de fichiers pouvant être ajoutés. |
min |
number |
Nombre minimal de fichiers pouvant être ajoutés. |
multiple |
boolean |
Indique si plusieurs sélections sont autorisées. |
size |
boolean |
Ajoute une liste déroulante de tailles de média au champ. |
textMediaButton |
string |
Texte du bouton de média. |
title |
string |
Titre affiché dans la fenêtre modale des médias. |
returnFormat |
string |
Définit le format de la valeur renvoyée. |
returnSize |
string |
Taille du média à renvoyer lorsque le format de retour URL est utilisé. |
gradient
Affiche une palette et un sélecteur de dégradé.
{
"type": "gradient",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur de l’option sélectionnée lors de l’ajout initial du bloc. |
fallback |
string |
Valeur de l’option affichée lorsque la valeur du champ est vide. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
Indique si la palette doit ou non comporter un bouton d’effacement. |
disableCustomGradients |
boolean |
Indique si une couleur personnalisée est autorisée. |
group
Affiche plusieurs champs dans un conteneur (éventuellement) repliable.
{
"type": "group"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
title |
string |
Texte du titre. Il reste affiché même lorsque le composant est fermé. |
opened |
boolean |
Si cette valeur est true, le composant reste ouvert, quelle que soit la valeur initiale de initialOpen et la |
initialOpen |
boolean |
Indique si le panneau est ouvert au départ. |
scrollAfterOpen |
boolean |
Fait défiler la page jusqu’au contenu lorsqu’il devient visible. |
class |
string |
Classe CSS personnalisée appliquée au groupe. |
style |
object |
Styles CSS personnalisés appliqués au groupe. |
attributes |
array |
Accepte tous les autres types de champs, à l’exception d’un autre champ tabs. |
html-tag
Affiche un sélecteur de balise HTML. Utile pour choisir des niveaux de titre ou des éléments sémantiques.
{
"type": "html-tag"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
tags |
string | array |
Balises à inclure. Utilisez une chaîne prédéfinie ou un tableau de noms de balises. |
exclude |
array |
Balises à exclure de la sélection prédéfinie. S’applique uniquement si une chaîne prédéfinie est utilisée pour les balises. |
icon
Affiche une icône SVG issue d’un jeu d’icônes.
{
"type": "icon"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
object |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
object |
Valeur de repli affichée lorsque la valeur du champ est vide. |
sets |
array | string |
Jeux d’icônes à inclure. Laissez vide pour tous les inclure. |
subSets |
array | string |
Sous-jeux d’icônes à inclure. Laissez vide pour tous les inclure. |
returnFormat |
string |
Format de l’icône renvoyée. |
link
Affiche un contrôle de lien permettant de choisir des liens internes ou externes.
{
"type": "link"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
object |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
object |
Valeur de repli affichée lorsque la valeur du champ est vide. |
hasRichPreviews |
boolean |
Indique si des aperçus enrichis doivent s’afficher lors de l’ajout d’un URL. |
noDirectEntry |
boolean |
Indique si une requête de recherche de type URL peut être directement convertie en lien. |
noURLSuggestion |
boolean |
Indique si une suggestion de repli doit traiter la requête de recherche comme un URL. |
opensInNewTab |
boolean |
Ajoute un bouton à bascule à la fenêtre modale du lien. |
showSuggestions |
boolean |
Indique si des suggestions doivent s’afficher lors de la saisie du URL. |
textButton |
string |
Texte personnalisé à afficher dans le bouton de lien. |
withCreateSuggestion |
boolean |
Indique si une recherche de lien sans correspondance peut générer une suggestion de nouvelle page en brouillon. |
message
Affiche un message avec un contenu personnalisé.
{
"type": "message"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
value |
string |
Message à afficher. Les données du bloc et des attributs sont disponibles avec la syntaxe entre crochets, e.g : {block.title} ou {attributes.text} |
number
Affiche un champ de saisie numérique.
{
"type": "number",
"min": 0,
"max": 100,
"step": 1
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
number |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
number |
Valeur de repli affichée lorsque la valeur du champ est vide. |
dragDirection |
string |
Détermine l’axe de déplacement pour augmenter ou diminuer la valeur. |
dragThreshold |
number |
Si isDragEnabled vaut true, définit le nombre de px à parcourir avant que la valeur change. |
hideHTMLArrows |
boolean |
Si cette valeur est true, les flèches HTML par défaut du champ sont masquées. |
isShiftStepEnabled |
boolean |
Si cette valeur est true, active le geste de glissement de la souris pour augmenter ou diminuer le nombre. Maintenez MAJ pendant le glissement pour augmenter la valeur de shiftStep. |
max |
number |
Longueur maximale de la valeur. |
min |
number |
Longueur minimale de la valeur. |
required |
boolean |
Si cette valeur est true, impose un nombre valide dans la plage min/max du contrôle. Si elle est false, une chaîne vide est acceptée comme valeur valide. |
shiftStep |
number |
Valeur d’incrément lorsque la touche MAJ est maintenue. Cette valeur est un multiplicateur de la valeur step. Par exemple, si step vaut 5 et shiftStep vaut 10, chaque saut augmente ou diminue la valeur de 50. |
step |
number |
Valeur de modification à chaque incrément ou décrément. Elle intervient aussi dans la validation : la valeur doit être un multiple de step (décalé de min, si spécifié) pour être valide. Accepte la chaîne spéciale any, qui annule la contrainte de validation et fait que les actions d’incrémentation ou de décrémentation modifient la valeur de 1. |
radio
Affiche un ensemble de boutons radio.
{
"type": "radio",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string | number |
Valeur par défaut appliquée lors de l’ajout initial du bloc. |
fallback |
string | number |
Valeur de repli affichée lorsque la valeur du champ est vide. |
options |
array |
Options parmi lesquelles choisir. |
returnFormat |
string |
Définit le format de la valeur renvoyée. |
populate |
object |
|
display |
string |
Définir sur buttonGroup pour afficher les options sous forme de groupe de boutons plutôt que de boutons radio. |
allowNull |
boolean |
Permet à l’utilisateur d’effacer la valeur en cliquant de nouveau sur le bouton radio sélectionné. |
range
Affiche un curseur permettant de définir une valeur numérique entre deux points.
{
"type": "range",
"min": 0,
"max": 100,
"step": 1
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
number |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
number |
Valeur de repli affichée lorsque la valeur du champ est vide. |
allowReset |
boolean |
Si cette propriété vaut true, un bouton permettant de réinitialiser le curseur est affiché. |
initialPosition |
number |
Position initiale du curseur, utilisée lorsqu’aucune valeur n’est transmise. initialPosition est limitée aux valeurs min et max fournies. |
isShiftStepEnabled |
boolean |
Si cette valeur est true, active le geste de glissement de la souris pour augmenter ou diminuer le nombre. Maintenez MAJ pendant le glissement pour augmenter la valeur de shiftStep. |
marks |
array |
Affiche les graduations. Des repères personnalisés peuvent être fournis sous forme de tableau. |
max |
number |
Longueur maximale de la valeur. |
min |
number |
Longueur minimale de la valeur. |
railColor |
string |
Chaîne de couleur CSS pour personnaliser l’arrière-plan du rail. |
resetFallbackValue |
number |
Valeur à rétablir si l’utilisateur clique sur le bouton de réinitialisation (activé par allowReset). |
separatorType |
string |
Définit si la ligne de séparation au-dessus ou en dessous de la rangée de contrôles doit être désactivée ou occuper toute la largeur. Par défaut, elle est placée en dessous, sans souligner l’icône du contrôle. |
shiftStep |
number |
Valeur d’incrément lorsque la touche MAJ est maintenue. Cette valeur est un multiplicateur de la valeur step. Par exemple, si step vaut 5 et shiftStep vaut 10, chaque saut augmente ou diminue la valeur de 50. |
showTooltip |
boolean |
Force l’affichage ou le masquage de l’info-bulle UI. Cette option est remplacée par false lorsque step correspond à la chaîne spéciale any. |
step |
number |
Valeur de modification à chaque incrément ou décrément. Elle intervient aussi dans la validation : la valeur doit être un multiple de step (décalé de min, si spécifié) pour être valide. Accepte la chaîne spéciale any, qui annule la contrainte de validation et fait que les actions d’incrémentation ou de décrémentation modifient la valeur de 1. |
trackColor |
string |
Chaîne de couleur CSS pour personnaliser l’arrière-plan de la piste. |
withInputField |
boolean |
Détermine si le champ numérique est affiché à côté du contrôle de plage. Cette option est remplacée par false lorsque step correspond à la chaîne spéciale any. |
select
Affiche un champ de sélection permettant de choisir une ou plusieurs options.
{
"type": "select",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
],
"multiple": false
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
array | string | number |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
array | string | number |
Valeur de repli affichée lorsque la valeur du champ est vide. |
multiple |
boolean |
Si cette valeur est true, plusieurs options peuvent être sélectionnées. stylisedUi est alors activé automatiquement. |
options |
array |
Options disponibles. |
returnFormat |
string |
Définit le format de la valeur renvoyée. |
populate |
object |
|
stylisedUi |
boolean |
Affiche une version stylisée du champ de sélection, avec la possibilité de rechercher parmi les éléments. |
allowNull |
boolean | string |
Autorise la sélection d’une option vide. Si cette valeur est true, le libellé est vide ; sinon, l’option affiche la chaîne spécifiée. |
allowReset |
boolean |
Si cette propriété vaut true, un bouton permettant de réinitialiser le champ de sélection est affiché. |
tabs
Affiche une interface à onglets pour regrouper des champs.
{
"type": "tabs"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
tabs |
array |
Onglets à afficher. |
text
Affiche un champ de saisie de texte sur une seule ligne.
{
"type": "text",
"min": 0,
"max": 100
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
max |
number |
Longueur maximale de la valeur. |
min |
number |
Longueur minimale de la valeur. |
textarea
Affiche un champ de saisie de texte multiligne.
{
"type": "textarea",
"min": 0,
"max": 100,
"rows": 4
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
max |
number |
Longueur maximale de la valeur. |
min |
number |
Longueur minimale de la valeur. |
rows |
number |
Nombre de lignes que le champ de texte multiligne doit contenir. |
toggle
Affiche un bouton à bascule vrai/faux.
{
"type": "toggle"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
boolean |
Valeur par défaut à appliquer lors du premier ajout du bloc. |
fallback |
boolean |
Valeur de repli affichée lorsque la valeur du champ est vide. |
repeater
Affiche un ensemble de champs pouvant être répétés.
{
"type": "repeater",
"min": 0,
"max": 100
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
array |
Lignes avec lesquelles un nouveau bloc commence. Chaque ligne est un objet contenant des valeurs de champ. Ces lignes sont prioritaires sur celles créées par min. |
min |
number |
Nombre minimal de lignes. |
max |
number |
Nombre maximal de lignes. |
minimized |
boolean |
Réduit les lignes existantes à l’ouverture de l’éditeur. Les lignes ajoutées dans l’éditeur restent développées. |
textButton |
string |
Texte du bouton d’ajout. |
textMinimized |
string | object |
Texte affiché lorsque les lignes sont réduites. |
textRemove |
string | boolean |
Question de confirmation affichée dans l’éditeur lors de la suppression d’une ligne du répéteur. Une chaîne non vide remplace la question ; false supprime immédiatement sans boîte de dialogue. Si cette option est omise, définie sur true ou sur une chaîne vide, la question par défaut est utilisée. |
attributes |
array |
Accepte tous les autres types de champs, sauf un autre champ d’onglets. |
richtext
Champ d’attribut pour les champs RichText.
{
"type": "richtext"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut appliquée lors de l’ajout initial du bloc. |
fallback |
string |
Valeur de repli affichée lorsque le champ est vide. |
unit
Affiche un champ de saisie numérique avec un menu déroulant d’unités.
{
"type": "unit"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut appliquée lors de l’ajout initial du bloc. |
fallback |
string |
Valeur de repli affichée lorsque le champ est vide. |
disableUnits |
boolean |
Si la valeur est true, le champ de sélection de l’unité est masqué. |
isPressEnterToChange |
boolean |
Si la valeur est true, il faut appuyer sur la touche ENTER pour déclencher un onChange. Si cette option est activée, un changement est également déclenché lors du passage à un autre champ avec la touche Tab. |
isResetValueOnUnitChange |
boolean |
Si la valeur est true et que l’unité sélectionnée fournit une valeur par défaut, celle-ci est définie lors du changement d’unité. |
isUnitSelectTabbable |
boolean |
Détermine si le champ de sélection de l’unité peut recevoir le focus avec la touche Tab. |
units |
array |
wysiwyg
Affiche un éditeur WYSIWYG.
{
"type": "wysiwyg"
}
Propriétés
| Propriété | Type | Description |
|---|---|---|
default |
string |
Valeur par défaut appliquée lors de l’ajout initial du bloc. |
fallback |
string |
Valeur de repli affichée lorsque la valeur du champ est vide. |
toolbar |
object |
Configuration de la barre d’outils de l’éditeur. |
mode |
string |
code ouvre le champ en mode code. both ajoute un bouton permettant de basculer entre le mode visuel et le mode code. |
Chargement des icônes
L’éditeur charge un ensemble d’icônes lorsque vous activez son sélecteur pour la première fois ou que vous changez d’ensemble ou de sous-ensemble, et non lorsque vous sélectionnez le bloc. Les champs qui demandent le même ensemble partagent la requête en cours. Le nom de l’icône enregistrée reste visible avant le chargement, et le sélecteur réessaie une requête échouée lorsqu’on le rouvre.
tabler-icons prend en charge outline et filled. Un sous-ensemble configuré explicitement pour l’ensemble choisi est prioritaire ; sinon, le sélecteur utilise solid si disponible, ou le premier sous-ensemble de l’ensemble. Les ensembles sans sous-ensembles omettent subSet. Les noms d’ensemble correspondent uniquement aux fichiers intégrés. Le rendu côté frontend met en cache les icônes individuellement plutôt que de stocker des ensembles complets dans les transients de la base de données.
Valeurs d’options importées
Les cases à cocher et les sélecteurs avec "multiple": true stockent normalement un tableau d’objets { "value": "...", "label": "..." }. Ils acceptent aussi un objet d’option unique, une chaîne ou un nombre scalaire, ou un tableau de valeurs scalaires importés via REST API ou des outils de contenu. Cela fonctionne aussi dans les lignes du répéteur.
L’éditeur affiche ces valeurs comme des sélections sans modifier leur structure enregistrée lors d’une sauvegarde sans changement. L’ajout ou la suppression d’une sélection enregistre un tableau standard d’objets d’option. Les sélections numériques 0 et textuelles "0" sont valides. Les modèles reçoivent le returnFormat configuré pour le champ, comme pour les valeurs sélectionnées dans l’éditeur. Les options doivent toujours correspondre aux choix déclarés ou renseignés dans le champ.
Un sélecteur natif à choix unique sans valeur enregistrée ni valeur par défaut affiche un espace réservé vide désactivé, et non sa première option. Le choix explicite de la première option l’enregistre. Une fois un choix enregistré, l’espace réservé disparaît. Utilisez allowNull si les éditeurs doivent aussi pouvoir effacer une sélection ; un espace réservé vide ne permet pas d’effacer un choix par ailleurs obligatoire.
Lignes initiales du répéteur
Dans l’éditeur, les valeurs par défaut incluent les lignes minimales imbriquées avant l’insertion. Vous n’avez pas besoin d’ouvrir les réglages du bloc pour les initialiser, et l’insertion du bloc n’ajoute pas une deuxième étape d’annulation pour ces lignes.
Lorsqu’un répéteur possède min, mais aucune valeur enregistrée ni default explicite, le serveur initialise ce nombre de lignes à partir des valeurs par défaut des champs. Cela s’applique aussi aux intégrations PHP, aux balises de bloc et aux sources de page stockées dans des fichiers qui n’ont jamais été ouvertes dans l’éditeur. Par exemple, "min": 2 avec un champ texte dont la valeur par défaut est "New item" affiche deux lignes contenant cette valeur.
Les lignes enregistrées et un default explicite du répéteur ont la priorité. Une liste vide explicitement enregistrée, false ou null ne recrée pas les lignes supprimées. Le rendu n’enregistre pas ces valeurs par défaut générées dans l’article. min et max limitent les contrôles de l’éditeur ; ils ne tronquent ni ne complètent une liste enregistrée lors du rendu. Utilisez bs_validate_block() pour signaler les violations des limites de lignes dans le contenu importé.
Les champs de ligne sans default sont false dans une ligne générée ; une telle ligne ne contient donc aucun contenu. Les lignes ajoutées par les éditeurs et laissées vides ont le même aspect. Un modèle qui affiche une carte, un titre ou un élément de liste pour chaque ligne doit ignorer les lignes sans contenu en dehors de l’éditeur et les conserver dans l’éditeur afin que leurs champs restent modifiables :
<?php foreach ( $a['items'] as $item ) : ?>
<?php if ( ! $isEditor && ! $item['title'] && ! $item['text'] ) continue; ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['text']; ?></p>
</div>
<?php endforeach; ?>
Suppression de répéteur
La suppression d’une ligne ouvre la boîte de dialogue de confirmation de l’éditeur, avec les boutons Supprimer et Annuler. Annuler ou appuyer sur Échap laisse la ligne inchangée. La ligne n’est supprimée qu’après confirmation, y compris dans les répéteurs imbriqués.
textRemove contrôle le même comportement pour chaque répéteur :
| Valeur | Comportement |
|---|---|
Omise, true ou "" |
Affiche la question de confirmation par défaut. |
| Chaîne non vide | Affiche cette question personnalisée à l’aide du mécanisme de traduction de texte personnalisé existant. |
false |
Supprime immédiatement la ligne sans boîte de dialogue. |
Par exemple, "textRemove": "Remove this team member?" modifie la question.
La restriction min existante empêche toujours la suppression de lignes en dessous du minimum.
Imbrication de répéteurs
Une ligne de répéteur accepte tous les types de champs sauf tabs. Un champ tabs dans une ligne, même à l’intérieur d’un groupe sans id, affiche un avis dans l’éditeur au lieu de ses champs. L’extension PHPStan le signale pour block.json et field.json. Gardez les champs de la ligne à plat ou déplacez les onglets à l’extérieur du répéteur.
Liens WYSIWYG
Par défaut, la barre d’outils des liens WYSIWYG insère des liens qui s’ouvrent dans le même onglet, sans ajouter target ni rel. Activez l’option de nouvel onglet avec toolbar.formats.link.opensInNewTab :
{
"id": "content",
"type": "wysiwyg",
"toolbar": {
"formats": {
"link": {
"opensInNewTab": true
}
}
}
}
Choisir un nouvel onglet ajoute target="_blank" et rel="noreferrer noopener".
Désactiver cette option supprime ces attributs automatiques. Pour appliquer des attributs à chaque lien de ce champ, définissez toolbar.formats.link.attributes, par exemple
{ "class": "content-link", "rel": "nofollow" }. La configuration explicite est conservée, et les jetons de sécurité pour les nouveaux onglets sont ajoutés à rel configuré.
Saisir un URL ne le transforme pas automatiquement en lien, et cliquer sur un lien existant dans le champ ne fait pas quitter l’éditeur. Les attributs des liens précédemment enregistrés restent dans le contenu existant ; ils ne sont pas migrés automatiquement.