Aller au contenu

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-name utilise 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 :

JSON
{
  "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 :

Text
namespace/type-name

Exemples valides :

  • acme/dimensions
  • acme/text-options
  • theme/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 :

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 :

PHP
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.

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

Enregistrement de JavaScript

Le script de l’éditeur enregistre le contrôle React correspondant :

JavaScript
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 :

JavaScript
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

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

Les chemins d’objet imbriqués fonctionnent également dans les modèles d’extension :

JSON
{
  "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.

JSON
{
  "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.