Types de champs personnalisés
Les types de champs personnalisés permettent à un thème ou à une extension d’ajouter de nouveaux contrôles de champ Blockstudio. Ils diffèrent des champs personnalisés :
custom/{name}fait référence à un groupe réutilisable de champs existants.namespace/type-nameutilise un type de champ enregistré avec son propre contrôle d’éditeur et sa propre structure de valeur.
Blockstudio fournit le système d’enregistrement. Votre thème ou extension fournit le contrôle.
Quand les utiliser
Utilisez un type de champ personnalisé lorsqu’un projet a besoin d’un contrôle d’édition dédié qui doit se comporter comme un champ Blockstudio natif partout :
- attributs de bloc
- groupes de champs
custom/{name}réutilisables - groupes, onglets et répéteurs
- modèles PHP, Twig et Blade
- stockage des métadonnées d’article et des options
- modèles d’extension tels que
{attributes.margin.top}
Par exemple, un contrôle d’espacement peut stocker un seul objet au lieu de quatre champs texte distincts :
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Nommage
Les noms de types de champs personnalisés doivent être en minuscules, avec un espace de noms et des mots séparés par des tirets :
namespace/type-name
Exemples valides :
acme/dimensionsacme/text-optionstheme/spacing-token
Espaces de noms réservés :
custom/est réservé aux groupes de champs personnalisés réutilisables.blockstudio/est réservé au cœur de Blockstudio.
Les noms non valides sont ignorés par le filtre API et rejetés par l’aide API.
Enregistrement de PHP
Enregistrez les métadonnées du type de champ dans PHP :
add_action('init', function () {
wp_register_script(
'acme-field-dimensions',
get_stylesheet_directory_uri() . '/fields/dimensions.js',
['blockstudio-blocks', 'wp-components', 'wp-element'],
'1.0.0',
true
);
bs_register_field_type('acme/dimensions', [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
'storage' => [
'type' => 'object',
'rest_schema' => [
'type' => 'object',
'additionalProperties' => ['type' => 'string'],
],
],
]);
});
bs_register_field_type() renvoie true lorsque l’enregistrement réussit et false lorsque le nom ou la définition n’est pas valide. Vous pouvez annuler un enregistrement manuel avec bs_unregister_field_type().
Vous pouvez également utiliser le filtre API :
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Clés de définition
| Clé | Type | Description |
|---|---|---|
attribute |
string, array, null |
Type d’attribut WordPress. Utilisez string, number, boolean, object, array ou un tableau de ces types. |
default |
mixte | Valeur par défaut au niveau du registre lorsqu’un champ ne définit pas sa propre valeur par défaut. |
source |
chaîne | Source d’attribut WordPress pour les cas de sérialisation personnalisés. |
produces_attribute |
booléen | Définissez sur false pour les contrôles en lecture seule. La valeur par défaut est true. |
editor_script |
chaîne ou tableau | Identifiant de script enregistré, ou identifiants, à charger dans l’éditeur de blocs lorsque le type est utilisé. |
editor_style |
chaîne ou tableau | Identifiant de style enregistré, ou identifiants, à charger dans l’éditeur de blocs lorsque le type est utilisé. |
storage |
tableau | Type de valeur de stockage et indications de schéma REST pour les métadonnées d’article et les options. |
supports |
tableau | Indicateurs de capacité facultatifs pour votre propre contrôle. |
translate |
booléen | Définissez sur true lorsque la valeur est du texte à traduire avec WPML. Nécessite attribute string. |
Une définition dont la valeur translate n’est pas un booléen, ou dont translate est défini sur true avec un attribute différent de string, est invalide.
bs_register_field_type() renvoie false et le filtre API l’ignore.
WPML
wp bs wpml config ne peut pas déterminer à partir de la seule déclaration si la valeur d’un type de champ personnalisé est du texte ; il ignore donc ces champs et affiche un avertissement pour chacun. Définissez translate sur true dans la déclaration d’un type de champ qui stocke une chaîne de texte brut ; la commande déclare alors ses champs comme des champs text. Un champ peut toujours être exclu avec "translate": false. Voir WPML.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Enregistrement de JavaScript
Le script de l’éditeur enregistre le contrôle React correspondant :
const { createElement: el } = wp.element;
const { TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/dimensions', {
component(props) {
const value =
props.value &&
typeof props.value === 'object' &&
!Array.isArray(props.value)
? props.value
: {};
const sides = props.sides || ['top', 'right', 'bottom', 'left'];
return el(
'div',
{},
sides.map((side) =>
el(TextControl, {
key: side,
label: side,
value: value[side] || '',
onChange(nextValue) {
props.onChange({
...value,
[side]: nextValue,
});
},
}),
),
);
},
});
registerFieldType() renvoie true lorsque l’enregistrement est accepté. Supprimez un enregistrement client avec :
window.blockstudio.unregisterFieldType('acme/dimensions');
Le composant reçoit les propriétés de définition du champ ainsi que ces propriétés stables :
| Prop | Description |
|---|---|
type |
Nom du type de champ. |
id |
ID du champ. |
field |
Définition complète du champ provenant de block.json. |
value |
Valeur actuellement enregistrée. |
defaultValue |
Valeur par défaut du champ. |
onChange |
Enregistrer directement une nouvelle valeur. |
attributes |
Attributs du bloc actuel. |
block |
Définition du type de bloc actuel. |
clientId |
ID client du bloc actuel dans l’éditeur. |
inRepeater |
Indique si le champ se trouve dans une ligne de répéteur. |
repeaterId |
Chemin actuel du répéteur, le cas échéant. |
disabled |
Indique si le champ est désactivé dans l’éditeur. |
Les valeurs des types de champs personnalisés sont stockées directement. Elles ne passent pas par la normalisation native des options select, radio, color ou gradient.
Rendu des valeurs
Les valeurs objet sont accessibles comme n’importe quel autre attribut Blockstudio.
PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
Les chemins d’objet imbriqués fonctionnent également dans les modèles d’extension :
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Stockage
Lorsqu’un type de champ personnalisé est utilisé avec le stockage postMeta ou option, Blockstudio utilise le type de valeur de stockage enregistré et le schéma REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Pour les valeurs array et object, définissez storage.rest_schema lors de l’enregistrement du type de champ. Les descendants de répéteur continuent d’utiliser un stockage basé sur des tableaux, car un répéteur stocke des lignes.
Comportement de repli
Si PHP connaît le type de champ, mais que le script de l’éditeur n’enregistre pas de contrôle correspondant, Blockstudio conserve la valeur enregistrée et affiche un avis non modifiable dans l’éditeur. Le rendu côté interface reçoit toujours la valeur enregistrée.
Si un type de champ n’est pas enregistré dans PHP, Blockstudio l’exclut des attributs WordPress générés. Enregistrez la définition PHP avant l’exécution de la découverte des blocs, généralement sur init avant que Blockstudio ne construise les blocs.