Membangun Jenis Bidang Kustom
Sebagian nilai terdiri dari lebih dari satu nilai primitif. Harga mencakup nominal dan mata uang. Dengan bidang bawaan, Anda memodelkannya sebagai bidang angka dan bidang pilihan yang berdampingan; setiap blok yang menampilkan harga harus mengulang pasangan, label, dan logika yang menyatukannya. Di meta pos, hasilnya menjadi dua kunci, dan di dalam repeater menjadi dua daftar paralel.
Jenis bidang kustom menggabungkan pasangan itu menjadi satu bidang. Daftarkan satu kali jenis seperti acme/price di PHP dan JavaScript, lalu gunakan di block.json seperti bidang bawaan: di tingkat teratas, di dalam grup dan repeater, dengan penyimpanan meta pos atau opsi, serta di templat PHP, Twig, dan Blade. Blockstudio menghasilkan atribut WordPress dan skema penyimpanan REST dari pendaftaran tersebut.
Ini berbeda dari bidang kustom.
Referensi custom/{name} menggunakan kembali sekelompok bidang yang sudah ada. Jenis bidang kustom menambahkan kontrol baru dengan bentuk nilainya sendiri.
Panduan ini membangun acme/price secara menyeluruh: pendaftaran PHP, kontrol editor, blok harga yang menggunakannya di tingkat teratas dan di dalam repeater, penyimpanan meta pos dengan skema REST yang ketat, serta hasil render.
Daftarkan jenisnya di PHP
Bagian PHP menetapkan jenis atribut, nilai default, skrip editor yang menyediakan kontrol, dan cara nilai disimpan di luar blok:
add_action( 'init', function () {
wp_register_script(
'acme-field-price',
get_stylesheet_directory_uri() . '/fields/price.js',
array( 'blockstudio-blocks', 'wp-components', 'wp-element' ),
'1.0.0',
true
);
bs_register_field_type( 'acme/price', array(
'attribute' => 'object',
'default' => array(),
'editor_script' => 'acme-field-price',
'storage' => array(
'type' => 'object',
'rest_schema' => array(
'type' => 'object',
'properties' => array(
'amount' => array( 'type' => 'number', 'minimum' => 0 ),
'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
),
'additionalProperties' => false,
),
),
) );
} );
attribute adalah jenis atribut WordPress, dalam contoh ini object. storage.type adalah jenis nilai yang digunakan saat bidang disimpan dalam meta pos atau opsi, dan storage.rest_schema adalah skema yang memvalidasi penulisan WordPress terhadap REST. Tanpa rest_schema, nilai objek mendapat skema permisif yang menerima properti apa pun.
Daftarkan pada init dengan prioritas default. Blockstudio menemukan blok setelahnya di init, sehingga jenis yang belum didaftarkan saat itu tidak akan disertakan dalam atribut blok yang dihasilkan.
bs_register_field_type() mengembalikan true jika berhasil dan false jika nama atau definisinya tidak valid. Nama harus menggunakan huruf kecil, memiliki namespace, dan memakai format dashcase; dua namespace dicadangkan:
| Nama | Hasil |
|---|---|
acme/price |
true |
Acme/Price |
false, bukan huruf kecil |
custom/price |
false, dicadangkan untuk grup bidang yang dapat digunakan kembali |
blockstudio/price |
false, dicadangkan untuk inti Blockstudio |
bs_unregister_field_type() menghapus pendaftaran, sedangkan filter blockstudio/field_types menerima definisi yang sama dalam bentuk larik dengan kunci berupa nama.
Buat Kontrol Editor
Skrip yang didaftarkan di atas menyediakan komponen React. Komponen ini menggunakan komponen WordPress yang sudah dimuat di editor, jadi tidak memerlukan langkah build:
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/price', {
component(props) {
const value =
props.value && typeof props.value === 'object' && !Array.isArray(props.value)
? props.value
: {};
const currencies = props.currencies || ['EUR'];
return el(
Flex,
{ align: 'flex-end' },
el(
FlexBlock,
{},
el(TextControl, {
label: props.label,
type: 'number',
min: 0,
step: 0.01,
disabled: props.disabled,
value: value.amount ?? '',
onChange(next) {
props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
},
}),
),
el(
FlexItem,
{},
el(SelectControl, {
label: 'Currency',
hideLabelFromVision: true,
disabled: props.disabled,
value: value.currency || currencies[0],
options: currencies.map((code) => ({ label: code, value: code })),
onChange(next) {
props.onChange({ ...value, currency: next });
},
}),
),
);
},
});
Komponen menerima setiap properti definisi bidang, sehingga kunci currencies yang Anda masukkan di block.json diterima sebagai props.currencies. Komponen ini juga menerima props yang stabil: value, onChange, field, defaultValue, attributes, block, clientId, disabled, dan inRepeater dengan repeaterId saat dirender di dalam baris repeater. onChange menyimpan nilai persis seperti yang diberikan. Nilai kustom melewati normalisasi opsi yang diterapkan oleh bidang bawaan select, radio, color, dan gradient.
Pastikan nilai yang bukan objek ditangani dengan aman, seperti pada beberapa baris pertama. Blok yang disimpan sebelum bidang ini tersedia, atau dengan bentuk berbeda, tetap harus dapat dibuka di editor.
Blockstudio memasukkan acme-field-price ke editor blok hanya jika ada blok terdaftar yang menggunakan acme/price. Jika skrip gagal mendaftarkan kontrol, editor tetap menyimpan nilai yang sudah ada dan menampilkan pemberitahuan yang tidak dapat diedit sebagai pengganti bidang, sementara frontend tetap merender nilainya.
Gunakan di Blok
Blok harga menggunakan jenis ini dua kali: sekali untuk harga awal yang harus dapat dikueri dari luar blok, lalu sekali per baris dalam repeater tingkatan harga:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/pricing",
"title": "Pricing",
"blockstudio": {
"attributes": [
{
"id": "price",
"type": "acme/price",
"label": "Starting price",
"currencies": ["EUR", "USD"],
"default": { "amount": 19, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_price"
}
},
{
"id": "tiers",
"type": "repeater",
"label": "Tiers",
"min": 0,
"max": 4,
"attributes": [
{ "id": "name", "type": "text", "label": "Name", "default": "" },
{
"id": "price",
"type": "acme/price",
"label": "Price",
"currencies": ["EUR", "USD"],
"default": { "amount": 0, "currency": "EUR" },
"storage": {
"type": "postMeta",
"postMetaKey": "acme_tier_prices"
}
}
]
}
]
}
}
default pada tingkat bidang mengesampingkan default registry. Blockstudio mengubah kedua bidang menjadi atribut WordPress dari pendaftaran tersebut. Jenis blok yang terdaftar memiliki:
{
"price": {
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 19, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_price" }
},
"tiers": {
"blockstudio": true,
"type": "array",
"field": "repeater",
"id": "tiers",
"attributes": [
{ "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
{
"blockstudio": true,
"type": "object",
"field": "acme/price",
"id": "price",
"default": { "amount": 0, "currency": "EUR" },
"storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
}
]
}
}
Render Nilai
Di templat, nilai berbentuk larik biasa. Persempit tipenya sebelum digunakan karena nilai tersimpan hanya seandal proses terakhir yang menulisnya:
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
if ( ! is_array( $price ) ) {
return '';
}
$amount = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';
return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
<p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
<?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
<div class="acme-tier">
<h3><?php echo esc_html( $tier['name'] ); ?></h3>
<p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
</div>
<?php endforeach; ?>
</section>
Baris ?: array() penting. Repeater tanpa baris diteruskan ke templat sebagai false, bukan sebagai larik kosong, dan foreach tanpa pemeriksaan terhadapnya akan memunculkan peringatan PHP. Baris @var dijelaskan di bagian analisis statis di bawah.
Merender blok dengan harga awal dan dua tingkatan:
echo bs_block( array(
'name' => 'acme/pricing',
'data' => array(
'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
'tiers' => array(
array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
),
),
) );
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
<p>From 19.00 EUR</p>
<div class="acme-tier">
<h3>Starter</h3>
<p>19.00 EUR</p>
</div>
<div class="acme-tier">
<h3>Team</h3>
<p>49.00 EUR</p>
</div>
</section>
Tanpa data sama sekali, default bidang akan diterapkan dan blok dirender sebagai From 19.00 EUR tanpa tingkatan harga. Twig dan Blade membaca nilai yang sama dengan a.price.amount dan $a['price']['amount'], sedangkan templat ekstensi dapat mengaksesnya sebagai {attributes.price.amount}.
Penyimpanan dan Skema REST
Kedua bidang menetapkan penyimpanan postMeta, sehingga Blockstudio mendaftarkan dua kunci meta saat membangun blok. Bidang tingkat teratas menggunakan skema penyimpanan yang terdaftar apa adanya:
{
"type": "object",
"single": true,
"show_in_rest": {
"schema": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
Bidang di dalam repeater menyimpan satu nilai per baris, sehingga kunci metanya berbasis larik dan skema yang sama menjadi skema item:
{
"type": "array",
"single": true,
"show_in_rest": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": { "type": "number", "minimum": 0 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
},
"additionalProperties": false
}
}
}
}
Menyimpan pos yang memuat blok akan menyinkronkan kedua kunci. Dengan dua tingkatan harga di atas, get_post_meta( $id, 'acme_price', true ) mengembalikan {"amount":19,"currency":"EUR"} dan acme_tier_prices mengembalikan daftar harga setiap baris:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
Kedua kunci muncul dalam respons REST pos di bawah meta, dan penulisan REST divalidasi terhadap skema. Penulisan dengan mata uang berhuruf kecil akan ditolak:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
Meta adalah salinan. Atribut blok di dalam konten pos tetap menjadi sumbernya, dan setiap kali disimpan, atribut tersebut disinkronkan kembali ke kunci yang dikonfigurasi. Karena itu, nilai yang langsung ditulis ke meta akan diganti saat pos disimpan berikutnya. Penyimpanan opsi bekerja dengan cara yang sama melalui register_setting(). Jenis bidang kustom, termasuk penyimpanan berbasis larik di dalam repeater, tersedia sejak Blockstudio 7.5.0.
Analisis Statis
Ekstensi PHPStan mengenali jenis bidang bawaan, bukan jenis yang didaftarkan proyek saat runtime. Pada blok yang menggunakan acme/price, ekstensi ini melaporkan jenis bidang sebagai tidak diketahui dan memberi nilai bidang tersebut tipe mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
Abaikan diagnostik itu untuk jenis buatan Anda sendiri di konfigurasi proyek, dan pertahankan penyempitan tipe di templat. Penyempitan tersebut diperlukan agar PHPStan menerima nilai mixed pada tingkat max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
Dengan konfigurasi dan templat di atas, analisis berhasil. Pada versi 7.6, templat juga memerlukan baris @var dengan mixed pada posisi bidang kustom; pada versi 7.7, Blockstudio menyimpulkan bentuknya sendiri sehingga baris tersebut dapat dihapus. Lihat Templat Terverifikasi dengan PHPStan untuk menjalankan analisis.
Langkah berikutnya
- Jenis Bidang Kustom: setiap kunci definisi, filter API, dan daftar lengkap props komponen.
- Penyimpanan: penyimpanan meta pos dan opsi untuk bidang apa pun.
- Buku Resep Pola Bidang: grup, repeater, dan struktur bidang yang dapat digunakan kembali.
- Bidang Kustom: grup bidang yang dapat digunakan kembali melalui
custom/{name}.