أنواع الحقول المخصصة
تتيح أنواع الحقول المخصصة للنسق أو الإضافة إضافة عناصر تحكم جديدة للحقول Blockstudio. وهي تختلف عن الحقول المخصصة:
custom/{name}يشير إلى مجموعة قابلة لإعادة الاستخدام من الحقول الموجودة.namespace/type-nameيستخدم نوع حقل مسجّلًا له عنصر تحكم خاص به في المحرر وبنية قيمة خاصة به.
Blockstudio يوفر نظام التسجيل. أما النسق أو الإضافة فيوفر عنصر التحكم.
متى تستخدمها
استخدم نوع حقل مخصصًا عندما يحتاج المشروع إلى عنصر تحكم تحرير مخصص لغرض واحد، وينبغي أن يعمل مثل حقل Blockstudio أصلي في كل مكان:
- سمات الكتل
- مجموعات حقول
custom/{name}القابلة لإعادة الاستخدام - المجموعات وعلامات التبويب والمكررات
- القوالب PHP وTwig وBlade
- تخزين البيانات الوصفية للمنشورات والخيارات
- قوالب الإضافات مثل
{attributes.margin.top}
على سبيل المثال، يمكن لعنصر تحكم التباعد تخزين كائن واحد بدلًا من أربعة حقول نصية منفصلة:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
التسمية
يجب أن تكون أسماء أنواع الحقول المخصصة بأحرف صغيرة، وأن تتضمن مساحة أسماء، وأن تستخدم الشرطات للفصل بين الكلمات:
namespace/type-name
أمثلة صالحة:
acme/dimensionsacme/text-optionstheme/spacing-token
مساحات الأسماء المحجوزة:
custom/محجوز لمجموعات الحقول المخصصة القابلة لإعادة الاستخدام.blockstudio/محجوز للنواة Blockstudio.
يتجاهل المرشح API الأسماء غير الصالحة، ويرفضها المساعد API.
التسجيل باستخدام 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() القيمة true عند نجاح التسجيل، وfalse عندما يكون الاسم أو التعريف غير صالح. يمكنك إلغاء تسجيل تسجيل يدوي باستخدام bs_unregister_field_type().
يمكنك أيضًا استخدام المرشح API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
مفاتيح التعريف
| المفتاح | النوع | الوصف |
|---|---|---|
attribute |
string، array، null |
نوع السمة WordPress. استخدم string أو number أو boolean أو object أو array، أو مصفوفة من تلك الأنواع. |
default |
mixed | قيمة افتراضية على مستوى السجل عندما لا يحدد الحقل قيمة افتراضية خاصة به. |
source |
string | مصدر السمة WordPress لحالات التسلسل المخصصة. |
produces_attribute |
boolean | اضبطها على false لعناصر التحكم المخصصة للعرض فقط. القيمة الافتراضية هي true. |
editor_script |
string or array | معرّف البرنامج النصي المسجّل أو معرّفاته لإضافتها إلى قائمة الانتظار في محرر الكتل عند استخدام النوع. |
editor_style |
string or array | معرّف النمط المسجّل أو معرّفاته لإضافتها إلى قائمة الانتظار في محرر الكتل عند استخدام النوع. |
storage |
array | تلميحات نوع قيمة التخزين ومخطط REST للبيانات الوصفية للمنشور والخيارات. |
supports |
array | أعلام إمكانات اختيارية لعناصر التحكم الخاصة بك. |
translate |
boolean | اضبطها على true عندما تكون القيمة نصًا لـ WPML لترجمتها. يتطلب ذلك attribute string. |
يكون التعريف غير صالح إذا كانت قيمة translate ليست قيمة منطقية، أو إذا ضُبطت translate على true وكانت قيمة attribute غير string.
يُرجع bs_register_field_type() القيمة false ويتجاهل المرشح API هذا التعريف.
WPML
wp bs wpml config لا يمكنه معرفة ما إذا كانت قيمة نوع الحقل المخصص نصًا بمجرد التسجيل، لذا يستثني هذه الحقول ويصدر تحذيرًا لكل منها. عيّن translate إلى true في تسجيل نوع الحقل الذي يخزّن سلسلة نصية عادية، وسيُدرج الأمر حقوله مثل حقول text. يمكن للحقل مع ذلك استبعاد نفسه باستخدام "translate": false. راجع WPMLالمستندات.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
التسجيل باستخدام JavaScript
يسجّل نص المحرر البرمجي عنصر التحكم المطابق React:
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() القيمة true عند قبول التسجيل. أزل تسجيلًا من العميل باستخدام:
window.blockstudio.unregisterFieldType('acme/dimensions');
يتلقى المكوّن خصائص تعريف الحقل، بالإضافة إلى الخصائص الثابتة التالية:
| الخاصية | الوصف |
|---|---|
type |
اسم نوع الحقل. |
id |
معرّف الحقل. |
field |
تعريف الحقل الكامل من block.json. |
value |
القيمة المحفوظة الحالية. |
defaultValue |
القيمة الافتراضية للحقل. |
onChange |
تخزين قيمة جديدة مباشرة. |
attributes |
سمات الكتلة الحالية. |
block |
تعريف نوع الكتلة الحالية. |
clientId |
معرّف العميل لكتلة المحرر الحالية. |
inRepeater |
ما إذا كان الحقل داخل صف مكرر. |
repeaterId |
مسار المكرر الحالي، إن وجد. |
disabled |
ما إذا كان الحقل معطّلًا في المحرر. |
تُخزّن قيم أنواع الحقول المخصصة مباشرةً. ولا تمر عبر تطبيع الخيارات الأصلي select أو radio أو color أو gradient.
عرض القيم
تتوفر قيم الكائنات مثل أي سمة Blockstudio أخرى.
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>
تعمل مسارات الكائنات المتداخلة أيضًا في قوالب الإضافات:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
التخزين
عند استخدام نوع حقل مخصص مع تخزين postMeta أو option، يستخدم Blockstudio نوع قيمة التخزين المسجّل ومخطط REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
بالنسبة إلى قيم array وobject، عرّف storage.rest_schema في تسجيل نوع الحقل. وتواصل العناصر التابعة للمكرر استخدام التخزين المعتمد على المصفوفات لأن المكرر يخزن صفوفًا.
السلوك الاحتياطي
إذا كان PHP يعرف نوع الحقل لكن النص البرمجي للمحرر لا يسجّل عنصر تحكم مطابقًا، يحتفظ Blockstudio بالقيمة المحفوظة ويعرض إشعارًا غير قابل للتحرير في المحرر. ويظل العرض في الواجهة الأمامية يتلقى القيمة المحفوظة.
إذا لم يُسجّل نوع حقل في PHP، يستبعده Blockstudio من سمات WordPress المُنشأة. سجّل تعريف PHP قبل بدء اكتشاف الكتل، عادةً في init قبل أن ينشئ Blockstudio الكتل.