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-namemenggunakan 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:
{
"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:
namespace/type-name
Contoh yang valid:
acme/dimensionsacme/text-optionstheme/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:
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:
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.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Pendaftaran JavaScript
Skrip editor mendaftarkan kontrol React yang sesuai:
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:
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
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
Jalur objek bertingkat juga berfungsi di templat ekstensi:
{
"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.
{
"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.