إنشاء نوع حقل مخصص
بعض القيم تتألف من أكثر من قيمة أولية. فالسعر يتكون من مبلغ وعملة. باستخدام الحقول المدمجة، ستحتاج إلى تمثيله بحقل رقم وحقل اختيار جنبًا إلى جنب، كما سيتعين على كل كتلة تعرض سعرًا تكرار الزوج وتسمياته والمنطق الذي يبقيهما مرتبطين. وفي البيانات الوصفية للمنشور، يتحول إلى مفتاحين، وداخل الحقل المتكرر إلى قائمتين متوازيتين.
يحوّل نوع الحقل المخصص هاتين القيمتين إلى حقل واحد. سجّل نوعًا مثل acme/price مرة واحدة في PHP وفي JavaScript، ثم استخدمه في أي block.json كحقل أصلي: في المستوى الأعلى، وداخل المجموعات والحقول المتكررة، مع تخزين بيانات المنشور أو الخيارات، وفي القوالب PHP وTwig وBlade. يستنتج Blockstudio سمة WordPress ومخطط REST للتخزين من التسجيل.
يختلف هذا عن حقل مخصص.
تعيد مرجعية custom/{name} استخدام مجموعة من الحقول الموجودة. أما نوع الحقل المخصص فيضيف عنصر تحكم جديدًا له بنية قيمة خاصة به.
يبني هذا الدليل acme/price من البداية إلى النهاية: تسجيل PHP، وعنصر تحكم المحرر، وكتلة تسعير تستخدمه في المستوى الأعلى وداخل حقل متكرر، وتخزين بيانات المنشور بمخطط REST صارم، ثم عرض الناتج.
سجّل النوع في PHP
يحدّد جانب PHP نوع السمة، والقيمة الافتراضية، والبرنامج النصي للمحرر الذي يوفّر عنصر التحكم، وكيفية تخزين القيمة خارج الكتلة:
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 هو نوع السمة WordPress، وهنا object. storage.type هو نوع القيمة المستخدم عند تخزين الحقل في بيانات المنشور الوصفية أو الخيارات، وstorage.rest_schema هو مخطط WordPress الذي يتحقق من REST عند الكتابة.
من دون rest_schema، تحصل قيمة الكائن على مخطط متساهل يقبل أي خصائص.
سجّل عبر init بالأولوية الافتراضية. يكتشف Blockstudio الكتل متأخرًا على init، وأي نوع لم يُسجّل حينها لا يُضمّن في سمات الكتل المُنشأة.
تعرض bs_register_field_type() القيمة true عند النجاح وfalse عندما يكون الاسم أو التعريف غير صالح. يجب أن تكون الأسماء بأحرف صغيرة، وضمن مساحة أسماء، وبصيغة شرطات، كما أن مساحتي الأسماء التاليتين محجوزتان:
| الاسم | النتيجة |
|---|---|
acme/price |
true |
Acme/Price |
false، ليس بأحرف صغيرة |
custom/price |
false، محجوزة لمجموعات الحقول القابلة لإعادة الاستخدام |
blockstudio/price |
false، محجوزة لنواة Blockstudio |
يزيل bs_unregister_field_type() تسجيلًا سابقًا، ويقبل المرشّح blockstudio/field_types التعريفات نفسها في مصفوفة مفاتيحها الأسماء.
أنشئ عنصر تحكم المحرر
يوفّر البرنامج النصي المسجّل أعلاه المكوّن React. ويستخدم مكوّنات WordPress المحمّلة بالفعل في المحرر، لذا لا يحتاج إلى خطوة بناء:
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 });
},
}),
),
);
},
});
يتلقى المكوّن كل خاصية في تعريف الحقل، لذا يصل المفتاح currencies الذي تضعه في block.json بوصفه props.currencies. كما يتلقى خصائص ثابتة: value وonChange وfield وdefaultValue وattributes وblock وclientId وdisabled وinRepeater مع repeaterId عند عرضه داخل صف في حقل متكرر. يخزّن onChange القيمة كما أُعطيت تمامًا. وتتجاوز القيم المخصصة تطبيع الخيارات الذي تطبقه الحقول الأصلية select وradio وcolor وgradient.
تحقّق من أن القيم كائنات، كما تفعل الأسطر الأولى. ينبغي أن تظل الكتلة المحفوظة قبل وجود الحقل، أو ببنية مختلفة، قابلة للفتح في المحرر.
يضيف Blockstudio acme-field-price إلى محرر الكتل فقط عند تسجيل كتلة تستخدم acme/price. إذا أخفق البرنامج النصي في تسجيل عنصر التحكم، يحتفظ المحرر بالقيمة المحفوظة ويعرض إشعارًا غير قابل للتحرير بدلًا من الحقل، مع استمرار عرض القيمة في الواجهة الأمامية.
استخدمه في كتلة
تستخدم كتلة التسعير النوع مرتين: مرةً لسعر ابتدائي ينبغي أن يكون قابلًا للاستعلام من خارج الكتلة، ومرةً لكل صف في حقل شرائح متكرر:
{
"$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 على مستوى الحقل على القيمة الافتراضية في السجل. يحوّل Blockstudio كلا الحقلين إلى سمات WordPress من التسجيل. ويحتوي نوع الكتلة المسجّل على:
{
"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" }
}
]
}
}
اعرض القيمة
في القالب، تكون القيمة مصفوفة عادية. تحقّق من نوعها قبل استخدامها، لأن موثوقية القيمة المخزّنة لا تتجاوز موثوقية آخر من كتبها:
<?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>
السطر ?: array() مهم. يصل الحقل المتكرر الذي لا يحتوي على صفوف إلى القالب بالقيمة false، لا كمصفوفة فارغة، ويؤدي استخدام foreach عليه مباشرةً إلى تحذير PHP. وشرح سطر @var ضمن قسم التحليل الساكن أدناه.
عرض الكتلة بسعر ابتدائي وشريحتين:
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>
إذا لم توجد أي بيانات، تُطبّق القيمة الافتراضية للحقل وتعرض الكتلة From 19.00 EUR بلا شرائح. تقرأ Twig وBlade القيمة نفسها على أنها a.price.amount و$a['price']['amount']، ويمكن لقوالب الامتداد الوصول إليها بالصيغة {attributes.price.amount}.
التخزين ومخطط REST
يعلن كلا الحقلين عن تخزين postMeta، لذا يسجّل Blockstudio مفتاحي بيانات وصفية عند إنشاء الكتلة. ويستخدم الحقل في المستوى الأعلى مخطط التخزين المسجّل كما هو:
{
"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
}
}
}
يخزّن الحقل داخل الحقل المتكرر قيمةً واحدة لكل صف، لذا يعتمد مفتاح بياناته الوصفية على مصفوفة، ويصبح المخطط نفسه مخطط العناصر:
{
"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
}
}
}
}
تؤدي عملية حفظ منشور يحتوي على الكتلة إلى مزامنة كلا المفتاحين. وباستخدام الشريحتين المذكورتين أعلاه، تعرض get_post_meta( $id, 'acme_price', true ) القيمة {"amount":19,"currency":"EUR"}، بينما تعرض acme_tier_prices قائمة أسعار الصفوف:
[
{ "amount": 19, "currency": "EUR" },
{ "amount": 49, "currency": "EUR" }
]
يظهر المفتاحان في استجابة REST للمنشور ضمن meta، وتُتحقّق عمليات الكتابة إلى REST من مطابقتها للمخطط. ويُرفض إدخال بعملة أحرفها صغيرة:
{
"code": "rest_invalid_pattern",
"message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
"data": { "status": 400 }
}
البيانات الوصفية نسخة. تظل سمات الكتلة في محتوى المنشور هي المصدر، وتزامنها كل عملية حفظ مجددًا مع المفاتيح المُعدّة، لذا تُستبدل في المرة التالية التي يُحفظ فيها المنشور أي قيمة كُتبت مباشرةً إلى البيانات الوصفية. يعمل تخزين الخيارات بالطريقة نفسها عبر register_setting(). تتوفر أنواع الحقول المخصصة، بما فيها التخزين المعتمد على المصفوفات داخل الحقول المتكررة، منذ Blockstudio 7.5.0.
التحليل الساكن
يتعرّف امتداد PHPStan إلى أنواع الحقول المدمجة، لا الأنواع التي يسجّلها المشروع وقت التشغيل. لذا، عند استخدام acme/price في كتلة، يعرض نوع الحقل على أنه غير معروف ويحدّد نوع قيمته بـ mixed:
2 block.json field "price" has unknown type "acme/price" in
blockstudio/pricing/block.json
🪪 blockstudio.blockJson.type
تجاهل هذا التشخيص لأنواعك الخاصة في إعدادات المشروع، وأبقِ التحقق من النوع في القالب، إذ يحتاج PHPStan إليه لقبول قيمة mixed عند المستوى max:
parameters:
level: max
ignoreErrors:
-
identifier: blockstudio.blockJson.type
message: '#unknown type "acme/price"#'
باستخدام هذا الإعداد والقالب أعلاه، ينجح التحليل. في الإصدار 7.6 يحتاج القالب أيضًا إلى سطر @var، مع وضع mixed في مواضع الحقول المخصصة؛ أما Blockstudio 7.7 فيستنتج هذه البنية تلقائيًا، ويمكن حذف السطر. راجع القوالب المتحقَّق منها باستخدام PHPStan لمعرفة كيفية إجراء التحليل.
الخطوات التالية
- أنواع الحقول المخصصة: كل مفاتيح التعريف، والمرشّح API، والقائمة الكاملة لخصائص المكوّن.
- التخزين: تخزين بيانات المنشور والخيارات لأي حقل.
- دليل أنماط الحقول: المجموعات والحقول المتكررة وبنى الحقول القابلة لإعادة الاستخدام.
- الحقول المخصصة: مجموعات الحقول القابلة لإعادة الاستخدام عبر
custom/{name}.