Treci la conținut

Tipuri de câmpuri personalizate

Tipurile de câmpuri personalizate permit unei teme sau unui plugin să adauge controale noi pentru câmpurile Blockstudio. Acestea diferă de câmpurile personalizate:

  • custom/{name} face referire la un grup reutilizabil de câmpuri existente.
  • namespace/type-name folosește un tip de câmp înregistrat, cu propriul control de editor și propria structură a valorii.

Blockstudio furnizează sistemul de înregistrare. Tema sau pluginul dvs. furnizează controlul.

Când să le folosiți

Folosiți un tip de câmp personalizat când un proiect are nevoie de un control de editare cu un scop precis, care să se comporte peste tot ca un câmp Blockstudio nativ:

  • atribute de bloc
  • grupuri de câmpuri custom/{name} reutilizabile
  • grupuri, file și repetitoare
  • șabloane PHP, Twig și Blade
  • metadate ale articolelor și stocarea opțiunilor
  • șabloane de extensie precum {attributes.margin.top}

De exemplu, un control pentru spațiere poate stoca un singur obiect în locul a patru câmpuri text separate:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

Denumire

Numele tipurilor de câmp personalizate trebuie să fie scrise cu litere mici, să aibă spații de nume și să folosească formatul dashcase:

Text
namespace/type-name

Exemple valide:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

Spații de nume rezervate:

  • custom/ este rezervat pentru grupurile reutilizabile de câmpuri personalizate.
  • blockstudio/ este rezervat pentru nucleul Blockstudio.

Numele invalide sunt ignorate de filtrul API și respinse de funcția ajutătoare API.

Înregistrare PHP

Înregistrați metadatele tipului de câmp în 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() returnează true dacă înregistrarea reușește și false dacă numele sau definiția nu sunt valide. Puteți anula o înregistrare manuală cu bs_unregister_field_type().

Puteți folosi și filtrul API:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

Cheile definiției

Cheie Tip Descriere
attribute string, array, null Tipul de atribut WordPress. Folosiți string, number, boolean, object, array sau un tablou cu aceste tipuri.
default mixed Valoare implicită la nivel de registru atunci când un câmp nu își definește propria valoare implicită.
source string Sursa atributului WordPress pentru cazuri de serializare personalizate.
produces_attribute boolean Setați la false pentru controale doar pentru afișare. Valoarea implicită este true.
editor_script string or array Handle-ul sau handle-urile de script înregistrate care vor fi încărcate în editorul de blocuri când este folosit tipul.
editor_style string or array Handle-ul sau handle-urile de stil înregistrate care vor fi încărcate în editorul de blocuri când este folosit tipul.
storage array Indicații privind tipul valorii stocate și schema REST pentru metadatele postărilor și opțiuni.
supports array Indicatori opționali de capabilități pentru propriul control.
translate boolean Setați la true când valoarea este text destinat traducerii de către WPML. Necesită attribute string.

O definiție cu o valoare translate care nu este booleană sau cu translate setat la true și un attribute diferit de string este nevalidă. bs_register_field_type() returnează false, iar filtrul API o ignoră.

WPML

wp bs wpml config nu poate determina doar din înregistrare dacă valoarea unui tip de câmp personalizat este text, așa că omite aceste câmpuri și afișează câte un avertisment pentru fiecare. Setați translate la true în înregistrarea unui tip de câmp care stochează un șir de text simplu, iar comanda declară câmpurile acestuia ca text. Un câmp poate renunța în continuare la acest comportament folosind "translate": false. Consultați WPMLdocumentația.

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

Înregistrare JavaScript

Scriptul editorului înregistrează controlul React corespunzător:

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() returnează true când înregistrarea este acceptată. Eliminați o înregistrare client cu:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

Componenta primește proprietățile definiției câmpului, plus aceste proprietăți stabile:

Proprietate Descriere
type Numele tipului de câmp.
id ID-ul câmpului.
field Definiția completă a câmpului din block.json.
value Valoarea salvată curentă.
defaultValue Valoarea implicită a câmpului.
onChange Stochează direct o valoare nouă.
attributes Atributele blocului curent.
block Definiția tipului blocului curent.
clientId ID-ul client al blocului curent din editor.
inRepeater Dacă câmpul se află într-un rând al repetitorului.
repeaterId Calea repetitorului curent, dacă există.
disabled Dacă acest câmp este dezactivat în editor.

Valorile tipurilor de câmpuri personalizate sunt stocate direct. Ele nu trec prin normalizarea opțiunilor native select, radio, color sau gradient.

Redarea valorilor

Valorile obiectelor sunt disponibile ca orice alt atribut 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>

Căile imbricate ale obiectelor funcționează și în șabloanele de extensie:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Stocare

Când se folosește un tip de câmp personalizat cu stocarea postMeta sau option, Blockstudio folosește tipul valorii stocate înregistrate și schema REST.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

Pentru valorile array și object, definiți storage.rest_schema în înregistrarea tipului de câmp. Descendenții repetitoarelor continuă să folosească stocarea bazată pe tablouri, deoarece un repetitor stochează rânduri.

Comportamentul de rezervă

Dacă PHP cunoaște tipul de câmp, dar scriptul editorului nu înregistrează un control corespunzător, Blockstudio păstrează valoarea salvată și afișează o notificare needitabilă în editor. Redarea în partea publică primește în continuare valoarea salvată.

Dacă un tip de câmp nu este înregistrat în PHP, Blockstudio îl omite din atributele WordPress generate. Înregistrați definiția PHP înainte de rularea descoperirii blocurilor, de obicei în init înainte ca Blockstudio să construiască blocurile.