Hoppa till innehåll

Anpassade fälttyper

Med anpassade fälttyper kan ett tema eller tillägg lägga till nya Blockstudio-fältkontroller. De skiljer sig från anpassade fält:

  • custom/{name} refererar till en återanvändbar grupp med befintliga fält.
  • namespace/type-name använder en registrerad fälttyp med en egen redigeringskontroll och värdestruktur.

Blockstudio tillhandahåller registreringssystemet. Ditt tema eller tillägg tillhandahåller kontrollen.

När du ska använda dem

Använd en anpassad fälttyp när ett projekt behöver en redigeringskontroll med ett enda syfte som ska fungera som ett inbyggt Blockstudio-fält överallt:

  • blockattribut
  • återanvändbara custom/{name}-fältgrupper
  • grupper, flikar och repeaters
  • mallar för PHP, Twig och Blade
  • lagring av metadata för inlägg och alternativ
  • tilläggsmallar som {attributes.margin.top}

En mellanrumskontroll kan till exempel lagra ett objekt i stället för fyra separata textfält:

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

Namngivning

Namn på anpassade fälttyper måste bestå av gemener, ha ett namnområde och använda bindestreck:

Text
namespace/type-name

Giltiga exempel:

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

Reserverade namnområden:

  • custom/ är reserverat för återanvändbara anpassade fältgrupper.
  • blockstudio/ är reserverat för kärnan i Blockstudio.

Ogiltiga namn ignoreras av filtret API och avvisas av hjälpfunktionen API.

PHP-registrering

Registrera metadata för fälttypen 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() returnerar true om registreringen lyckas och false om namnet eller definitionen är ogiltig. Du kan avregistrera en manuell registrering med bs_unregister_field_type().

Du kan också använda filtret API:

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

    return $types;
});

Definitionsnycklar

Nyckel Typ Beskrivning
attribute string, array, null Attributtyp för WordPress. Använd string, number, boolean, object, array eller en array med dessa typer.
default mixed Standardvärde på registernivå när ett fält inte har ett eget standardvärde.
source string Attributkälla för anpassade serialiseringsfall: WordPress.
produces_attribute boolean Ange false för kontroller som endast visar information. Standardvärdet är true.
editor_script string or array Registrerat skripthandtag eller registrerade skripthandtag som ska köas i blockredigeraren när typen används.
editor_style string or array Registrerat stilhandtag eller registrerade stilhandtag som ska köas i blockredigeraren när typen används.
storage array Lagringsvärdets typ och REST-schematips för inläggsmeta och alternativ.
supports array Valfria kapabilitetsflaggor för din egen kontroll.
translate boolean Ange true när värdet är text som WPML ska översätta. Kräver attribute string.

En definition med ett translate-värde som inte är en boolean, eller med translate satt till true och ett attribute annat än string, är ogiltig. bs_register_field_type() returnerar false och filtret API ignorerar den.

WPML

wp bs wpml config kan inte avgöra enbart utifrån registreringen om värdet för en anpassad fälttyp är text, så sådana fält utelämnas och en varning skrivs ut för varje fält. Ange translate till true i registreringen av en fälttyp som lagrar en vanlig textsträng, så deklarerar kommandot dess fält som text-fält. Ett fält kan fortfarande välja att inte delta med "translate": false. Se WPMLbärbara medierreferenser.

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

JavaScript-registrering

Redigerarskriptet registrerar motsvarande React-kontroll:

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() returnerar true när registreringen godkänns. Ta bort en klientregistrering med:

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

Komponenten tar emot egenskaperna från fältdefinitionen samt dessa beständiga egenskaper:

Egenskap Beskrivning
type Fälttypens namn.
id Fält-ID.
field Fullständig fältdefinition från block.json.
value Aktuellt sparat värde.
defaultValue Fältets standardvärde.
onChange Spara ett nytt värde direkt.
attributes Aktuella blockattribut.
block Aktuell blocktypdefinition.
clientId Aktuellt klient-ID för redigerarblocket.
inRepeater Anger om fältet ligger i en repeaterad.
repeaterId Aktuell repeater-sökväg, om det finns någon.
disabled Anger om fältet är inaktiverat i redigeraren.

Värden för anpassade fälttyper lagras direkt. De passerar inte genom normalisering av inbyggda alternativ i select, radio, color eller gradient.

Återgivning av värden

Objektvärden är tillgängliga precis som alla andra Blockstudio-attribut.

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>

Kapslade objektsökvägar fungerar också i tilläggsmallar:

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 anpassad fälttyp används med lagringen postMeta eller option använder Blockstudio den registrerade lagringsvärdestypen och schemat REST.

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

För värdena array och object definierar du storage.rest_schema i fälttypens registrering. Underordnade repeaterfält fortsätter att använda arraybaserad lagring eftersom en repeater lagrar rader.

Reservbeteende

Om PHP känner till fälttypen men redigerarskriptet inte registrerar en motsvarande kontroll behåller Blockstudio det sparade värdet och visar ett icke-redigerbart meddelande i redigeraren. Återgivning i frontend får fortfarande det sparade värdet.

Om en fälttyp inte är registrerad i PHP tar Blockstudio inte med den i de genererade attributen WordPress. Registrera definitionen PHP innan blockidentifieringen körs, vanligtvis vid init innan Blockstudio skapar block.