Pāriet uz saturu

Pielāgoti lauku tipi

Pielāgoti lauku tipi ļauj tēmai vai spraudnim pievienot jaunas Blockstudio lauku vadīklas. Tās atšķiras no pielāgotajiem laukiem:

  • custom/{name} apzīmē atkārtoti izmantojamu esošo lauku grupu.
  • namespace/type-name izmanto reģistrētu lauka tipu ar savu redaktora vadīklu un vērtības struktūru.

Blockstudio nodrošina reģistrācijas sistēmu. Jūsu tēma vai spraudnis nodrošina vadīklu.

Kad tos izmantot

Izmantojiet pielāgotu lauka tipu, ja projektam nepieciešama īpašam mērķim paredzēta rediģēšanas vadīkla, kurai visur jādarbojas kā iebūvētam Blockstudio laukam:

  • bloka atribūti
  • atkārtoti izmantojamas custom/{name} lauku grupas
  • grupas, cilnes un atkārtotāji
  • PHP, Twig un Blade veidnes
  • ierakstu metadati un opciju krātuve
  • paplašinājumu veidnes, piemēram, {attributes.margin.top}

Piemēram, atstarpju vadīkla var saglabāt vienu objektu četru atsevišķu teksta lauku vietā:

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

Nosaukumu veidošana

Pielāgotu lauku tipu nosaukumiem jābūt ar mazajiem burtiem, nosaukumvietu un vārdiem, kas atdalīti ar defisēm:

Text
namespace/type-name

Derīgi piemēri:

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

Rezervētās nosaukumvietas:

  • custom/ ir rezervēta atkārtoti izmantojamām pielāgoto lauku grupām.
  • blockstudio/ ir rezervēta Blockstudio kodolam.

Nederīgus nosaukumus filtrs API ignorē, bet palīgfunkcija API noraida.

PHP reģistrācija

Reģistrējiet lauka tipa metadatus failā 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() atgriež true, ja reģistrācija izdodas, un false, ja nosaukums vai definīcija nav derīga. Manuālu reģistrāciju var atcelt ar bs_unregister_field_type().

Varat izmantot arī filtru API:

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

    return $types;
});

Definīcijas atslēgas

Atslēga Tips Apraksts
attribute string, array, null WordPress atribūta tips. Izmantojiet string, number, boolean, object, array vai šo tipu masīvu.
default jaukts Reģistra līmeņa noklusējuma vērtība, ja laukam nav norādīta sava noklusējuma vērtība.
source virkne WordPress atribūta avots pielāgotas serializācijas gadījumiem.
produces_attribute Būla vērtība Iestatiet uz false tikai attēlošanai paredzētām vadīklām. Noklusējuma vērtība ir true.
editor_script virkne vai masīvs Reģistrēta skripta rokturis vai rokturi, ko iekļaut bloku redaktorā, kad tips tiek izmantots.
editor_style virkne vai masīvs Reģistrēta stila rokturis vai rokturi, ko iekļaut bloku redaktorā, kad tips tiek izmantots.
storage masīvs Krātuves vērtības tipa un REST shēmas norādes ziņu metadatiem un opcijām.
supports masīvs Neobligāti iespēju karodziņi jūsu vadīklai.
translate Būla vērtība Iestatiet uz true, ja vērtība ir teksts, ko var tulkot ar WPML. Nepieciešams attribute string.

Definīcija ar translate vērtību, kas nav Būla vērtība, vai ar translate, kas iestatīts uz true, un attribute, kura vērtība nav string, ir nederīga. bs_register_field_type() atgriež false, un filtrs API to ignorē.

WPML

wp bs wpml config pēc reģistrācijas vien nevar noteikt, vai pielāgotā lauka tipa vērtība ir teksts, tāpēc šādus laukus izlaiž un par katru parāda brīdinājumu. Reģistrējot lauka tipu, kurā tiek glabāta vienkārša teksta virkne, iestatiet translate uz true, un komanda tā laukus deklarēs tāpat kā text laukus. Laukam joprojām var norādīt izņēmumu, izmantojot "translate": false. Skatiet Tulkojamie laukiWPML.

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

JavaScript reģistrācija

Redaktora skripts reģistrē atbilstošo React vadīklu:

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() atgriež true, ja reģistrācija tiek pieņemta. Lai noņemtu klienta puses reģistrāciju:

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

Komponentam tiek nodoti lauka definīcijas rekvizīti un šie nemainīgie rekvizīti:

Rekvizīts Apraksts
type Lauka tipa nosaukums.
id Lauka ID.
field Pilna lauka definīcija no block.json.
value Pašreizējā saglabātā vērtība.
defaultValue Lauka noklusējuma vērtība.
onChange Saglabāt jaunu vērtību tieši.
attributes Pašreizējie bloka atribūti.
block Pašreizējā bloka tipa definīcija.
clientId Pašreizējā redaktora bloka klienta ID.
inRepeater Vai lauks atrodas atkārtotāja rindā.
repeaterId Pašreizējais atkārtotāja ceļš, ja tāds ir.
disabled Vai lauks redaktorā ir atspējots.

Pielāgotu lauku tipu vērtības tiek glabātas tieši. Tās netiek normalizētas kā iebūvētās opcijas, select, radio, color vai gradient.

Vērtību attēlošana

Objektu vērtības ir pieejamas tāpat kā jebkurš cits Blockstudio atribūts.

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>

Ligzdoti objektu ceļi darbojas arī paplašinājumu veidnēs:

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

Krātuve

Ja pielāgotu lauka tipu izmanto kopā ar postMeta vai option krātuvi, Blockstudio izmanto reģistrēto krātuves vērtības tipu un REST shēmu.

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

Vērtībām array un object definējiet storage.rest_schema lauka tipa reģistrācijā. Atkārtotāju pēcteči turpina izmantot masīvos balstītu krātuvi, jo atkārtotājā tiek glabātas rindas.

Rezerves darbība

Ja PHP pazīst lauka tipu, bet redaktora skripts nereģistrē atbilstošu vadīklu, Blockstudio patur saglabāto vērtību un redaktorā rāda paziņojumu, ko nevar rediģēt. Priekšgala attēlošana joprojām saņem saglabāto vērtību.

Ja lauka tips nav reģistrēts failā PHP, Blockstudio neiekļauj to ģenerētajos WordPress atribūtos. Reģistrējiet PHP definīciju, pirms tiek sākta bloku noteikšana, parasti failā init pirms Blockstudio veido blokus.