Pereiti prie turinio

Tinkinti laukų tipai

Tinkintų laukų tipai leidžia temai arba papildiniui pridėti naujus Blockstudio laukų valdiklius. Jie skiriasi nuo tinkintų laukų:

  • custom/{name} nurodo pakartotinai naudojamą esamų laukų grupę.
  • namespace/type-name naudoja registruotą lauko tipą su atskiru redaktoriaus valdikliu ir reikšmės struktūra.

Blockstudio pateikia registravimo sistemą. Jūsų tema arba papildinys pateikia valdiklį.

Kada juos naudoti

Naudokite tinkintą lauko tipą, kai projektui reikia vienos paskirties redagavimo valdiklio, kuris visur veiktų kaip įtaisytasis Blockstudio laukas:

  • bloko atributai
  • pakartotinai naudojamos custom/{name} laukų grupės
  • grupės, kortelės ir kartotuvai
  • PHP, Twig ir Blade šablonai
  • įrašo metaduomenys ir parinkčių saugykla
  • plėtinių šablonai, pvz., {attributes.margin.top}

Pavyzdžiui, tarpų valdiklis gali saugoti vieną objektą, o ne keturis atskirus teksto laukus:

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

Pavadinimai

Tinkintų laukų tipų pavadinimai turi būti mažosiomis raidėmis, su vardų sritimi ir brūkšneliais:

Text
namespace/type-name

Tinkami pavyzdžiai:

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

Rezervuotos vardų sritys:

  • custom/ rezervuota pakartotinai naudojamoms tinkintų laukų grupėms.
  • blockstudio/ rezervuota Blockstudio branduoliui.

Netinkamus pavadinimus filtras API ignoruoja, o pagalbinė funkcija API atmeta.

PHP registravimas

Užregistruokite lauko tipo metaduomenis faile 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() grąžina true, jei registracija pavyksta, ir false, jei pavadinimas arba aprašas netinkamas. Rankinę registraciją galite atšaukti naudodami bs_unregister_field_type().

Taip pat galite naudoti filtrą API:

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

    return $types;
});

Aprašo raktai

Raktas Tipas Aprašymas
attribute string, array, null WordPress atributo tipas. Naudokite string, number, boolean, object, array arba šių tipų masyvą.
default mixed Registro lygmens numatytoji reikšmė, kai laukas neturi savo numatytosios reikšmės.
source string WordPress atributo šaltinis tinkintiems serializavimo atvejams.
produces_attribute boolean Tik rodymo valdikliams nustatykite false. Numatytoji reikšmė yra true.
editor_script string or array Užregistruota scenarijaus programa arba programos, kurias reikia įtraukti į bloko redaktorių, kai naudojamas šis tipas.
editor_style string or array Užregistruotas stiliaus išteklius arba ištekliai, kuriuos reikia įtraukti į bloko redaktorių, kai naudojamas šis tipas.
storage array Saugyklos reikšmės tipo ir REST schemos užuominos įrašo metaduomenims ir parinktims.
supports array Pasirenkamos jūsų valdiklio galimybių vėliavėlės.
translate boolean Nustatykite true, kai reikšmė yra tekstas, kurį turi išversti WPML. Reikia attribute string.

Apibrėžtis, kurios translate reikšmė nėra loginė, arba kurioje translate nustatytas į true, o attribute nėra string, yra netinkama. bs_register_field_type() grąžina false, o filtras API jos nepaiso.

WPML

wp bs wpml config vien iš registracijos negali nustatyti, ar pasirinktinio lauko tipo reikšmė yra tekstas, todėl tokius laukus praleidžia ir pateikia įspėjimą apie kiekvieną iš jų. Užregistruodami lauko tipą, kuriame saugoma paprasto teksto eilutė, nustatykite translate į true; tuomet komanda deklaruoja jo laukus kaip text laukus. Laukui vis tiek galima išjungti šią parinktį naudojant "translate": false. Žr. WPMLtekstinių laukų dokumentaciją.

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

JavaScript registravimas

Redaktoriaus scenarijus užregistruoja atitinkamą React valdiklį:

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() grąžina true, jei registracija priimama. Kliento registraciją pašalinkite taip:

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

Komponentas gauna lauko aprašo savybes ir šias nekintančias ypatybes:

Ypatybė Aprašymas
type Lauko tipo pavadinimas.
id Lauko ID.
field Visas lauko aprašas iš block.json.
value Dabartinė išsaugota reikšmė.
defaultValue Numatytoji lauko reikšmė.
onChange Tiesiogiai išsaugoti naują reikšmę.
attributes Dabartiniai bloko atributai.
block Dabartinio bloko tipo aprašas.
clientId Dabartinio redaktoriaus bloko kliento ID.
inRepeater Ar laukas yra kartotuvo eilutėje.
repeaterId Dabartinis kartotuvo kelias, jei toks yra.
disabled Ar laukas redaktoriuje išjungtas.

Tinkintų laukų tipų reikšmės saugomos tiesiogiai. Jos neapdorojamos naudojant įprastą select, radio, color ar gradient parinkčių normalizavimą.

Reikšmių atvaizdavimas

Objektų reikšmės pasiekiamos kaip ir bet kuris kitas Blockstudio atributas.

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>

Įdėtuosiuose šablonuose taip pat veikia įdėtų objektų keliai:

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

Saugykla

Kai tinkintas lauko tipas naudojamas su postMeta arba option saugykla, Blockstudio naudoja registruotą saugyklos reikšmės tipą ir REST schemą.

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

array ir object reikšmėms lauko tipo registracijoje apibrėžkite storage.rest_schema. Kartotuvo žemesni elementai toliau naudoja masyvais pagrįstą saugyklą, nes kartotuvas saugo eilutes.

Atsarginė elgsena

Jei PHP žino lauko tipą, bet redaktoriaus scenarijus neužregistruoja atitinkamo valdiklio, Blockstudio išsaugo įrašytą reikšmę ir redaktoriuje rodo pranešimą, kurio negalima redaguoti. Svetainės atvaizdavimas vis tiek gauna išsaugotą reikšmę.

Jei lauko tipas neužregistruotas PHP, Blockstudio neįtraukia jo į sugeneruotus WordPress atributus. Užregistruokite PHP aprašą prieš vykdant blokų aptikimą, paprastai faile init, kad Blockstudio galėtų sukurti blokus.