Gå til indhold

Brugerdefinerede felttyper

Brugerdefinerede felttyper lader et tema eller plugin tilføje nye Blockstudio-feltkontroller. De er forskellige fra brugerdefinerede felter:

  • custom/{name} henviser til en genanvendelig gruppe af eksisterende felter.
  • namespace/type-name bruger en registreret felttype med sin egen redigeringskontrol og værdistruktur.

Blockstudio leverer registreringssystemet. Dit tema eller plugin leverer kontrollen.

Hvornår skal de bruges

Brug en brugerdefineret felttype, når et projekt har brug for en specialiseret redigeringskontrol, der skal fungere som et indbygget Blockstudio-felt overalt:

  • blokattributter
  • genanvendelige custom/{name}-feltgrupper
  • grupper, faner og repeatere
  • PHP-, Twig- og Blade-skabeloner
  • lagring af indlægsmetadata og indstillinger
  • udvidelsesskabeloner som {attributes.margin.top}

For eksempel kan en afstandskontrol gemme ét objekt i stedet for fire separate tekstfelter:

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

Navngivning

Navne på brugerdefinerede felttyper skal være med små bogstaver, have et navnerum og bruge bindestreger:

Text
namespace/type-name

Gyldige eksempler:

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

Reserverede navnerum:

  • custom/ er reserveret til genanvendelige brugerdefinerede feltgrupper.
  • blockstudio/ er reserveret til Blockstudio-kernen.

Ugyldige navne ignoreres af filteret API og afvises af hjælpefunktionen API.

Registrering af PHP

Registrer felttypens metadata i 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() returnerer true, når registreringen lykkes, og false, når navnet eller definitionen er ugyldig. Du kan fjerne en manuel registrering med bs_unregister_field_type().

Du kan også bruge filteret API:

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

    return $types;
});

Definitionsnøgler

Nøgle Type Beskrivelse
attribute string, array, null WordPress attributtype. Brug string, number, boolean, object, array eller et array af disse typer.
default mixed Standardværdi på registreringsniveau, når et felt ikke definerer sin egen standardværdi.
source string WordPress attributkilde til brugerdefinerede serialiseringstilfælde.
produces_attribute boolean Sæt til false for kontrolelementer, der kun viser indhold. Standardværdien er true.
editor_script string or array Registreret script-handle eller handles, der skal indlæses i blokeditoren, når typen bruges.
editor_style string or array Registreret stil-handle eller handles, der skal indlæses i blokeditoren, når typen bruges.
storage array Lagerets værditype og REST skemahints til postmeta og indstillinger.
supports array Valgfrie kapabilitetsflag til dit eget kontrolelement.
translate boolean Sæt til true, når værdien er tekst, som WPML skal oversætte. Kræver attribute string.

En definition med en translate-værdi, der ikke er en boolean, eller med translate sat til true og en attribute, der ikke er string, er ugyldig. bs_register_field_type() returnerer false, og filteret API ignorerer den.

WPML

wp bs wpml config kan ikke ud fra registreringen alene afgøre, om værdien for en brugerdefineret felttype er tekst, så sådanne felter udelades, og der vises en advarsel for hvert felt. Sæt translate til true i registreringen af en felttype, der gemmer en almindelig tekststreng, så erklærer kommandoen felterne som text-felter. Et felt kan stadig fravælges med "translate": false. Se WPMLbærbare mediehenvisninger.

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

Registrering af JavaScript

Editorscriptet registrerer den tilhørende React-kontrol:

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() returnerer true, når registreringen godkendes. Fjern en klientregistrering med:

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

Komponenten modtager feltddefinitionens egenskaber samt disse stabile props:

Prop Beskrivelse
type Felttypens navn.
id Felt-ID.
field Fuldstændig feltdefinition fra block.json.
value Aktuel gemt værdi.
defaultValue Feltets standardværdi.
onChange Gem en ny værdi direkte.
attributes Aktuelle blokattributter.
block Aktuel bloktypeddefinition.
clientId Aktuelt klient-ID for editorblokken.
inRepeater Om feltet er inde i en repeaterrække.
repeaterId Aktuel repeatersti, hvis der er en.
disabled Om feltet er deaktiveret i editoren.

Værdier for brugerdefinerede felttyper gemmes direkte. De gennemgår ikke normalisering af indstillinger for indbyggede select, radio, color eller gradient.

Gengivelse af værdier

Objektværdier er tilgængelige som alle andre Blockstudio-attributter.

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>

Indlejrede objektstier fungerer også i udvidelsesskabeloner:

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

Lagring

Når en brugerdefineret felttype bruges med lagring i postMeta eller option, bruger Blockstudio den registrerede lagringsværditype og REST-skemaet.

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

For værdier af typen array og object skal du definere storage.rest_schema ved registrering af felttypen. Repeaterens underordnede felter fortsætter med at bruge arraybaseret lagring, fordi en repeater gemmer rækker.

Reserveadfærd

Hvis PHP kender felttypen, men editorscriptet ikke registrerer en tilsvarende kontrol, bevarer Blockstudio den gemte værdi og viser en ikke-redigerbar besked i editoren. Frontend-gengivelse modtager stadig den gemte værdi.

Hvis en felttype ikke er registreret i PHP, udelader Blockstudio den fra de genererede WordPress-attributter. Registrer PHP-definitionen, før blokregistreringen køres, normalt på init før Blockstudio bygger blokke.