Lewati ke konten

Jenis Field Kustom

Jenis field kustom memungkinkan tema atau plugin menambahkan kontrol field Blockstudio baru. Jenis ini berbeda dari field kustom:

  • custom/{name} merujuk pada grup field yang sudah ada dan dapat digunakan kembali.
  • namespace/type-name menggunakan jenis field terdaftar dengan kontrol editor dan bentuk nilai tersendiri.

Blockstudio menyediakan sistem pendaftaran. Tema atau plugin Anda menyediakan kontrolnya.

Kapan Menggunakannya

Gunakan jenis field kustom saat proyek memerlukan kontrol pengeditan dengan satu tujuan yang harus berperilaku seperti field Blockstudio bawaan di mana pun:

  • atribut blok
  • grup field custom/{name} yang dapat digunakan kembali
  • grup, tab, dan repeater
  • templat PHP, Twig, dan Blade
  • penyimpanan post meta dan opsi
  • templat ekstensi seperti {attributes.margin.top}

Misalnya, kontrol jarak dapat menyimpan satu objek alih-alih empat field teks terpisah:

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

Penamaan

Nama jenis field kustom harus menggunakan huruf kecil, namespace, dan format dashcase:

Text
namespace/type-name

Contoh yang valid:

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

Namespace yang dicadangkan:

  • custom/ dicadangkan untuk grup field kustom yang dapat digunakan kembali.
  • blockstudio/ dicadangkan untuk inti Blockstudio.

Nama yang tidak valid akan diabaikan oleh filter API dan ditolak oleh helper API.

Pendaftaran PHP

Daftarkan metadata jenis field di 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() mengembalikan true jika pendaftaran berhasil dan false jika nama atau definisinya tidak valid. Anda dapat membatalkan pendaftaran manual dengan bs_unregister_field_type().

Anda juga dapat menggunakan filter API:

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

    return $types;
});

Kunci Definisi

Kunci Jenis Deskripsi
attribute string, array, null Jenis atribut WordPress. Gunakan string, number, boolean, object, array, atau array yang berisi jenis-jenis tersebut.
default mixed Nilai default tingkat registry saat field tidak menetapkan default-nya sendiri.
source string Sumber atribut WordPress untuk kasus serialisasi kustom.
produces_attribute boolean Atur ke false untuk kontrol khusus tampilan. Default-nya true.
editor_script string or array Handle skrip terdaftar atau beberapa handle untuk dimuat di editor blok saat jenis ini digunakan.
editor_style string or array Handle gaya terdaftar atau beberapa handle untuk dimuat di editor blok saat jenis ini digunakan.
storage array Jenis nilai penyimpanan dan petunjuk skema REST untuk meta pos dan opsi.
supports array Flag kapabilitas opsional untuk kontrol Anda sendiri.
translate boolean Atur ke true jika nilainya berupa teks yang akan diterjemahkan oleh WPML. Memerlukan attribute string.

Definisi dengan nilai translate yang bukan boolean, atau dengan translate yang diatur ke true dan attribute yang bukan string, tidak valid. bs_register_field_type() mengembalikan false dan filter API mengabaikannya.

WPML

wp bs wpml config tidak dapat mengetahui hanya dari registrasi apakah nilai tipe bidang khusus berupa teks, sehingga bidang seperti itu tidak disertakan dan peringatan dicetak untuk masing-masing bidang. Atur translate menjadi true dalam registrasi tipe bidang yang menyimpan string teks biasa, dan perintah akan mendeklarasikan bidangnya sebagai bidang text. Bidang tetap dapat memilih untuk tidak disertakan dengan "translate": false. Lihat WPML.

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

Pendaftaran JavaScript

Skrip editor mendaftarkan kontrol React yang sesuai:

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() mengembalikan true jika pendaftaran diterima. Hapus pendaftaran klien dengan:

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

Komponen menerima properti definisi field beserta prop stabil berikut:

Prop Deskripsi
type Nama jenis field.
id ID field.
field Definisi field lengkap dari block.json.
value Nilai tersimpan saat ini.
defaultValue Nilai default field.
onChange Simpan nilai baru secara langsung.
attributes Atribut blok saat ini.
block Definisi jenis blok saat ini.
clientId ID klien blok editor saat ini.
inRepeater Apakah field berada di dalam baris repeater.
repeaterId Jalur repeater saat ini, jika ada.
disabled Apakah field dinonaktifkan di editor.

Nilai jenis field kustom disimpan secara langsung. Nilai tersebut tidak melalui normalisasi opsi bawaan select, radio, color, atau gradient.

Merender Nilai

Nilai objek tersedia seperti atribut Blockstudio lainnya.

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>

Jalur objek bertingkat juga berfungsi di templat ekstensi:

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

Penyimpanan

Saat jenis field kustom digunakan dengan penyimpanan postMeta atau option, Blockstudio menggunakan jenis nilai penyimpanan terdaftar dan skema REST.

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

Untuk nilai array dan object, tentukan storage.rest_schema pada pendaftaran jenis field. Turunan repeater tetap menggunakan penyimpanan berbasis array karena repeater menyimpan baris.

Perilaku Fallback

Jika PHP mengenali jenis field tetapi skrip editor tidak mendaftarkan kontrol yang sesuai, Blockstudio mempertahankan nilai tersimpan dan menampilkan pemberitahuan yang tidak dapat diedit di editor. Rendering frontend tetap menerima nilai tersimpan.

Jika jenis field tidak didaftarkan di PHP, Blockstudio tidak menyertakannya dalam atribut WordPress yang dihasilkan. Daftarkan definisi PHP sebelum penemuan blok dijalankan, biasanya di init sebelum Blockstudio membangun blok.