أنواع الحقول
يوفر Blockstudio مجموعة متنوعة من أنواع الحقول لإنشاء واجهات الكتل.
يمكن للمشاريع أيضًا تسجيل أنواع حقول خاصة بها مع مساحة أسماء باستخدام
blockstudio/field_types. استخدم ذلك
عندما تحتاج إلى عنصر تحكم جديد في المحرر أو بنية قيمة منظّمة. استخدم حقول
custom/{name} عندما تحتاج فقط إلى إعادة استخدام مجموعة من الحقول الموجودة.
وصفات عملية: مجموعات شرطية، وقوائم اختيار ذكية، ومكررات، وتخزين قابل للاستعلام.
الخصائص العامة
يسرد الجدول أدناه الخصائص المشتركة وخيارات القيم الشائعة. يُدعم default وfallback حيثما وردا في جدول الخصائص لكل نوع حقل.
| الخاصية | النوع | الوصف |
|---|---|---|
id |
string | معرّف فريد للسمة |
type |
string | نوع الحقل |
label |
string | التسمية المعروضة في المحرر |
description |
string | نص الوصف المعروض أسفل الحقل |
default |
mixed | القيمة الافتراضية للحقل |
fallback |
mixed | القيمة الاحتياطية عندما يكون الحقل فارغًا |
help |
string | نص المساعدة المعروض كتلميح بجانب التسمية |
hidden |
boolean | إخفاء الحقل من UI |
switch |
boolean | عرض مفتاح تبديل يمكنه تعطيل الحقل. القيمة الافتراضية هي false. |
translate |
boolean | عيّنها إلى false لاستبعاد الحقل من إعداد WPML |
conditions |
array | قواعد المنطق الشرطي |
تحافظ حقول الملفات التي تتضمن "returnFormat": "id" على مراجع السلاسل المستوردة، بما فيها القيم المفردة داخل الحقول المكررة. تظهر الأسماء التي تعذّر حلها على شكل بطاقات احتياطية بلا صور مصغرة؛ ولا يحلّها Blockstudio إلى معرّفات المرفقات. راجع مراجع الوسائط القابلة للنقل لمزيد من التفاصيل.
راجع تحميل الأيقونات لمعرفة طلبات أداة الاختيار، وإعادات المحاولة، ومجموعات الأيقونات الفرعية.
السمات
يعرض حقول إدخال سمات البيانات.
{
"type": "attributes"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
array |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
array |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
link |
boolean |
يتيح اختيار الروابط من قائمة منسدلة. |
media |
boolean |
يتيح اختيار الوسائط من قائمة منسدلة. |
كتلة
يشير إلى كتلة Blockstudio أخرى، ويعرض حقولها ضمن السطر. في القوالب، تُرجع القيمة مخرجات الكتلة المعروضة.
{
"type": "block"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
block |
string |
اسم الكتلة المراد الإشارة إليها (e.g، "mytheme/card"). |
returnFormat |
string |
كيفية إرجاع القيمة في القوالب. |
مربع اختيار
يعرض مجموعة من حقول مربعات الاختيار.
{
"type": "checkbox",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
array | string | number |
القيمة الافتراضية التي ينبغي تطبيقها عند إضافة الكتلة لأول مرة. |
fallback |
array | string | number |
القيمة الاحتياطية التي ستُعرض عند فراغ قيمة الحقل. |
options |
array |
الخيارات المتاحة للاختيار. |
returnFormat |
string |
تحدد تنسيق القيمة المُعادة. |
populate |
object |
|
toggle |
boolean | string |
يضيف مربع اختيار أعلى الخيارات لتحديدها كلها أو إلغاء تحديدها. تُستخدم سلسلة نصية كتسمية له، بينما تستخدم القيمة true التسمية الافتراضية. |
الفئات
يعرض حقلاً لاختيار فئات CSS.
{
"type": "classes"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
tailwind |
boolean |
يحدد ما إذا كان سيتم تفعيل فئات Tailwind لهذا الحقل. |
الكود
يعرض محررًا للأكواد.
{
"type": "code"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبَّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
autoCompletion |
boolean |
ما إذا كان ينبغي تفعيل الإكمال التلقائي. |
foldGutter |
boolean |
ما إذا كان ينبغي إظهار هامش الطي. |
height |
string |
ارتفاع المحرر. |
language |
string |
اللغة المستخدمة لإبراز بناء الجملة. |
lineNumbers |
boolean |
ما إذا كان ينبغي عرض أرقام الأسطر. |
maxHeight |
string |
أقصى ارتفاع للمحرر. |
minHeight |
string |
أدنى ارتفاع للمحرر. |
popout |
boolean |
ما إذا كان ينبغي إظهار زر يفتح المحرر في نافذة منبثقة. |
asset |
boolean |
يعرض CSS أو SCSS أو JavaScript من الحقل كأصل للكتلة، فلا يحتاج القالب إلى طباعة وسم النمط أو البرنامج النصي. |
اللون
يعرض لوحة ألوان وأداة لاختيار اللون.
{
"type": "color",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
قيمة الخيار الذي ينبغي تحديده عند إضافة الكتلة لأول مرة. |
fallback |
string |
قيمة الخيار التي ستُعرض عندما تكون قيمة الحقل فارغة. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
ما إذا كان ينبغي أن تحتوي لوحة الألوان على زر لمسح التحديد. |
disableCustomColors |
boolean |
ما إذا كان ينبغي السماح بلون مخصص. |
التاريخ
يعرض أداة لاختيار التاريخ.
{
"type": "date"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
startOfWeek |
number |
يوم بدء الأسبوع. استخدم 0 للأحد، و1 للاثنين، وهكذا. |
التاريخ والوقت
يعرض أداة لاختيار التاريخ والوقت.
{
"type": "datetime"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
is12Hour |
boolean |
يحدد ما إذا كنا نستخدم تنسيق 12 ساعة. عند استخدام هذا التنسيق، تظهر أداة AM/PM ويُفترض أن يكون تنسيق الوقت MM-DD-YYYY (بدلاً من التنسيق الافتراضي DD-MM-YYYY). |
الملفات
يعرض زرًا لفتح مكتبة الوسائط. يمكن إعادة ترتيب العناصر المحددة ضمن السطر.
{
"type": "files",
"min": 0,
"max": 100,
"multiple": false
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
array | object | number |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
array | object | number |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
addToGallery |
boolean |
إذا كانت القيمة true، تُفتح نافذة وسائط المعرض مباشرةً في مكتبة الوسائط ليتمكن المستخدم من إضافة صور أخرى. وإذا كانت false، تُفتح نافذة وسائط المعرض في وضع التحرير، حيث يمكن للمستخدم تعديل الصور الحالية بإعادة ترتيبها أو إزالتها أو تغيير سماتها. ينطبق ذلك فقط إذا كانت gallery === true. |
allowedTypes |
array | string |
مصفوفة بأنواع الوسائط المراد تحميلها أو اختيارها من مكتبة الوسائط. كل نوع عبارة عن سلسلة يمكن أن تحتوي على نوع MIME عام e.g: ‘image’ أو ‘audio’ أو ‘text’، أو نوع MIME كامل e.g: ‘audio/mpeg’ أو ‘image/gif’. إذا لم يتم تعيين allowedTypes، يُسمح بجميع أنواع MIME. |
gallery |
boolean |
إذا كانت القيمة true، فسيهيئ المكوّن جميع الحالات اللازمة لعرض معرض. افتراضيًا، تُفتح نافذة الوسائط في إطار تحرير المعرض، ويمكن تغيير ذلك باستخدام addToGalleryflag. |
max |
number |
الحد الأقصى لعدد الملفات التي يمكن إضافتها. |
min |
number |
الحد الأدنى لعدد الملفات التي يمكن إضافتها. |
multiple |
boolean |
يحدد ما إذا كان يُسمح بتحديد عناصر متعددة. |
size |
boolean |
يضيف قائمة منسدلة لأحجام الوسائط إلى الحقل. |
textMediaButton |
string |
نص زر الوسائط. |
title |
string |
العنوان المعروض في نافذة الوسائط. |
returnFormat |
string |
يحدد تنسيق القيمة المُعادة. |
returnSize |
string |
حجم الوسائط المطلوب إرجاعه عند استخدام تنسيق الإرجاع URL. |
التدرج
يعرض لوحة تدرجات وأداة لاختيار التدرج.
{
"type": "gradient",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
قيمة الخيار الذي ينبغي تحديده عند إضافة الكتلة لأول مرة. |
fallback |
string |
قيمة الخيار التي ستُعرض عندما تكون قيمة الحقل فارغة. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
ما إذا كان ينبغي أن تحتوي لوحة الألوان على زر لمسح التحديد. |
disableCustomGradients |
boolean |
ما إذا كان ينبغي السماح بلون مخصص. |
المجموعة
يعرض حقولاً متعددة داخل حاوية قابلة للطي اختياريًا.
{
"type": "group"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
title |
string |
نص العنوان. يظل ظاهرًا حتى عندما يكون المكوّن مغلقًا. |
opened |
boolean |
عند تعيينه إلى true، يظل المكوّن مفتوحًا بصرف النظر عن الخاصية initialOpen و |
initialOpen |
boolean |
يحدد ما إذا كانت اللوحة ستبدأ مفتوحة. |
scrollAfterOpen |
boolean |
يمرر المحتوى إلى إطار العرض عند ظهوره. |
class |
string |
فئة CSS مخصصة تُطبّق على المجموعة. |
style |
object |
أنماط CSS مخصصة تُطبّق على المجموعة. |
attributes |
array |
يقبل جميع أنواع الحقول الأخرى باستثناء tabs آخر. |
وسم html
يعرض محددًا لوسم HTML. يفيد في اختيار مستويات العناوين أو العناصر الدلالية.
{
"type": "html-tag"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
tags |
string | array |
الوسوم المطلوب تضمينها. استخدم سلسلة إعداد مسبق أو مصفوفة من أسماء الوسوم. |
exclude |
array |
الوسوم المطلوب استبعادها من الإعداد المسبق. ينطبق ذلك فقط عند استخدام سلسلة إعداد مسبق للوسوم. |
الأيقونة
يعرض أيقونة SVG من مجموعة أيقونات.
{
"type": "icon"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
object |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
object |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
sets |
array | string |
مجموعة الأيقونات المطلوب تضمينها. اتركه فارغًا لتضمينها كلها. |
subSets |
array | string |
مجموعة الأيقونات الفرعية المطلوب تضمينها. اتركه فارغًا لتضمينها كلها. |
returnFormat |
string |
التنسيق الذي ستُعاد به الأيقونة. |
الرابط
يعرض عنصر تحكم للروابط لاختيار روابط داخلية أو خارجية.
{
"type": "link"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
object |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
object |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
hasRichPreviews |
boolean |
يحدد ما إذا كانت ستُعرض معاينات منسقة عند إضافة URL. |
noDirectEntry |
boolean |
يحدد ما إذا كان يُسمح بتحويل استعلام بحث شبيه بـ URL مباشرةً إلى رابط. |
noURLSuggestion |
boolean |
يحدد ما إذا كان سيتم إضافة اقتراح احتياطي يعامل استعلام البحث على أنه URL. |
opensInNewTab |
boolean |
يضيف عنصر تحكم للتبديل إلى نافذة الروابط. |
showSuggestions |
boolean |
يحدد ما إذا كانت ستظهر اقتراحات أثناء كتابة URL. |
textButton |
string |
نص مخصص يُعرض داخل زر الرابط. |
withCreateSuggestion |
boolean |
يحدد ما إذا كان البحث عن رابط غير مطابق يمكن أن ينشئ اقتراحًا لصفحة مسودة جديدة. |
الرسالة
يعرض رسالة بمحتوى مخصص.
{
"type": "message"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
value |
string |
الرسالة المطلوب عرضها. تتوفر بيانات الكتلة والسمات بصيغة الأقواس، e.g: {block.title} أو {attributes.text} |
الرقم
يعرض حقل إدخال رقم.
{
"type": "number",
"min": 0,
"max": 100,
"step": 1
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
number |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
number |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
dragDirection |
string |
يحدد محور السحب لزيادة القيمة أو إنقاصها. |
dragThreshold |
number |
إذا كانت isDragEnabled تساوي true، فهذا يحدد عدد px التي يجب سحبها قبل تغيير القيمة. |
hideHTMLArrows |
boolean |
إذا كانت القيمة true، فسيتم إخفاء أسهم الإدخال الافتراضية HTML. |
isShiftStepEnabled |
boolean |
إذا كانت القيمة true، فسيُفعّل إيماءة سحب الماوس لزيادة الرقم أو إنقاصه. يؤدي الضغط على SHIFT أثناء السحب إلى زيادة القيمة بمقدار shiftStep. |
max |
number |
الحد الأقصى لطول القيمة. |
min |
number |
الحد الأدنى لطول القيمة. |
required |
boolean |
إذا كانت القيمة true، يُفرض إدخال رقم صالح ضمن نطاق min/max لعنصر التحكم. وإذا كانت false، يُسمح بالسلسلة الفارغة كقيمة صالحة. |
shiftStep |
number |
مقدار الزيادة عند الضغط على مفتاح SHIFT. قيمة shift هذه مضاعف لقيمة step. على سبيل المثال، إذا كانت قيمة step هي 5 وكانت shiftStep هي 10، فستكون كل قفزة بمقدار 50 زيادةً أو نقصانًا. |
step |
number |
مقدار تغير القيمة عند زيادتها أو إنقاصها. ويُستخدم أيضًا في التحقق، إذ يجب أن تكون القيمة من مضاعفات step (مع إزاحتها بمقدار min، إن حُدد) لتكون صالحة. تقبل القيمة الخاصة any التي تلغي قيد التحقق وتجعل إجراءات الخطوة تزيد القيمة أو تنقصها بمقدار 1. |
الراديو
يعرض مجموعة من حقول الاختيار الأحادي.
{
"type": "radio",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string | number |
القيمة الافتراضية التي تُطبَّق عند إضافة الكتلة لأول مرة. |
fallback |
string | number |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
options |
array |
الخيارات المتاحة للاختيار. |
returnFormat |
string |
يحدد تنسيق القيمة المُعادة. |
populate |
object |
|
display |
string |
اضبطه على buttonGroup لعرض الخيارات كمجموعة أزرار بدلًا من عناصر اختيار أحادية. |
allowNull |
boolean |
يتيح للمستخدم مسح القيمة بالنقر مجددًا على عنصر الاختيار المحدد. |
النطاق
يعرض حقل نطاق لتعيين قيمة رقمية بين نقطتين.
{
"type": "range",
"min": 0,
"max": 100,
"step": 1
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
number |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
number |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
allowReset |
boolean |
إذا كانت هذه الخاصية true، فسيُعرض زر لإعادة تعيين شريط التمرير. |
initialPosition |
number |
موضع بدء شريط التمرير، ويُستخدم عند عدم تمرير قيمة. سيتم حصر initialPosition بين قيمتي الخاصيتين min وmax المقدمتين. |
isShiftStepEnabled |
boolean |
إذا كانت القيمة true، فسيُفعّل إيماءة سحب الماوس لزيادة الرقم أو إنقاصه. يؤدي الضغط على SHIFT أثناء السحب إلى زيادة القيمة بمقدار shiftStep. |
marks |
array |
يعرض تمثيلاً مرئيًا لعلامات الخطوات. يمكن توفير مؤشرات علامات مخصصة باستخدام Array. |
max |
number |
الحد الأقصى لطول القيمة. |
min |
number |
الحد الأدنى لطول القيمة. |
railColor |
string |
سلسلة لون CSS لتخصيص خلفية عنصر المسار. |
resetFallbackValue |
number |
القيمة المطلوب الرجوع إليها عند النقر على زر Reset (المفعّل بواسطة allowReset). |
separatorType |
string |
يحدد ما إذا كان يجب تعطيل خط الفاصل أسفل/أعلى صف عنصر التحكم أو جعله بعرض كامل. افتراضيًا، يوضع أسفله باستثناء خط التسطير تحت أيقونة التحكم. |
shiftStep |
number |
مقدار الزيادة عند الضغط على مفتاح SHIFT. قيمة shift هذه مضاعف لقيمة step. على سبيل المثال، إذا كانت قيمة step هي 5 وكانت shiftStep هي 10، فستكون كل قفزة بمقدار 50 زيادةً أو نقصانًا. |
showTooltip |
boolean |
فرض إظهار تلميح الأدوات UI أو إخفائه. يتم تجاوز هذا الإعداد إلى false عند تعيين step إلى القيمة الخاصة any. |
step |
number |
مقدار تغير القيمة عند زيادتها أو إنقاصها. ويُستخدم أيضًا في التحقق، إذ يجب أن تكون القيمة من مضاعفات step (مع إزاحتها بمقدار min، إن حُدد) لتكون صالحة. تقبل القيمة الخاصة any التي تلغي قيد التحقق وتجعل إجراءات الخطوة تزيد القيمة أو تنقصها بمقدار 1. |
trackColor |
string |
سلسلة لون CSS لتخصيص خلفية عنصر المسار. |
withInputField |
boolean |
يحدد ما إذا كان سيتم عرض حقل إدخال الرقم بجوار RangeControl. يتم تجاوز هذا الإعداد إلى false عند تعيين step إلى القيمة الخاصة any. |
تحديد
يعرض حقل تحديد يدعم اختيار عنصر واحد أو عدة عناصر.
{
"type": "select",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
],
"multiple": false
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
array | string | number |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
array | string | number |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
multiple |
boolean |
إذا كانت القيمة true، يمكن تحديد خيارات متعددة. سيتم تفعيل stylisedUi تلقائيًا. |
options |
array |
الخيارات المتاحة للاختيار. |
returnFormat |
string |
يحدد تنسيق القيمة المُعادة. |
populate |
object |
|
stylisedUi |
boolean |
يعرض نسخة منمقة من حقل التحديد مع إمكانية البحث بين العناصر. |
allowNull |
boolean | string |
يتيح للمستخدم اختيار خيار فارغ. إذا كانت القيمة true، سيكون التصنيف فارغًا، وإلا فسيعرض الخيار السلسلة المحددة. |
allowReset |
boolean |
إذا كانت هذه الخاصية true، فسيُعرض زر لإعادة تعيين حقل التحديد. |
علامات التبويب
يعرض واجهة بعلامات تبويب لتجميع الحقول.
{
"type": "tabs"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
tabs |
array |
علامات التبويب المطلوب عرضها. |
النص
يعرض حقل إدخال نص في سطر واحد.
{
"type": "text",
"min": 0,
"max": 100
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
max |
number |
الحد الأقصى لطول القيمة. |
min |
number |
الحد الأدنى لطول القيمة. |
منطقة النص
يعرض حقل إدخال لمنطقة نص.
{
"type": "textarea",
"min": 0,
"max": 100,
"rows": 4
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
max |
number |
الحد الأقصى لطول القيمة. |
min |
number |
الحد الأدنى لطول القيمة. |
rows |
number |
عدد الصفوف التي ينبغي أن تحتوي عليها منطقة النص. |
مفتاح التبديل
يعرض مفتاح تبديل بين true وfalse.
{
"type": "toggle"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
boolean |
القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة. |
fallback |
boolean |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
مكرر
يعرض مجموعة من الحقول القابلة للتكرار.
{
"type": "repeater",
"min": 0,
"max": 100
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
array |
الصفوف التي تبدأ بها كتلة جديدة. كل صف كائن من قيم الحقول. لها الأولوية على الصفوف التي تنشئها min. |
min |
number |
الحد الأدنى لعدد الصفوف. |
max |
number |
الحد الأقصى لعدد الصفوف. |
minimized |
boolean |
اطوِ الصفوف الموجودة عند فتح المحرر. تبدأ الصفوف المضافة في المحرر موسعة. |
textButton |
string |
نص زر الإضافة. |
textMinimized |
string | object |
النص الذي سيظهر عند تصغير الصفوف. |
textRemove |
string | boolean |
سؤال التأكيد الذي يظهر في المحرر عند إزالة صف مكرر. تؤدي السلسلة غير الفارغة إلى تغيير السؤال؛ أما false فتزيل الصف فورًا دون مربع حوار. وعند حذف هذا الخيار أو ضبطه على true أو سلسلة فارغة، يُستخدم السؤال الافتراضي. |
attributes |
array |
يقبل جميع أنواع الحقول الأخرى باستثناء حقل tabs آخر. |
النص المنسق
حقل سمة لحقول النص المنسق.
{
"type": "richtext"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي ينبغي تطبيقها عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
الوحدة
يعرض حقل إدخال رقم مع قائمة منسدلة للوحدات.
{
"type": "unit"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي ينبغي تطبيقها عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
disableUnits |
boolean |
إذا كانت القيمة true، فسيُخفى حقل اختيار الوحدة. |
isPressEnterToChange |
boolean |
إذا كانت القيمة true، فيلزم الضغط على مفتاح ENTER لتفعيل onChange. وعند التفعيل، يُفعّل التغيير أيضًا عند الانتقال إلى حقل آخر باستخدام مفتاح الجدولة. |
isResetValueOnUnitChange |
boolean |
إذا كانت القيمة true وكانت الوحدة المحددة توفر قيمة افتراضية، تُضبط هذه القيمة عند تغيير الوحدات. |
isUnitSelectTabbable |
boolean |
يحدد ما إذا كان يمكن الانتقال إلى حقل اختيار الوحدة باستخدام مفتاح الجدولة. |
units |
array |
محرر مرئي
يعرض محرر WYSIWYG.
{
"type": "wysiwyg"
}
الخصائص
| الخاصية | النوع | الوصف |
|---|---|---|
default |
string |
القيمة الافتراضية التي تُطبَّق عند إضافة الكتلة لأول مرة. |
fallback |
string |
القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة. |
toolbar |
object |
إعدادات شريط الأدوات للمحرر. |
mode |
string |
يفتح code الحقل في عرض الكود. ويضيف both زرًا للتبديل بين العرض المرئي وعرض الكود. |
تحميل الأيقونات
يحمّل المحرر مجموعة أيقونات عند التركيز على منتقيها لأول مرة أو عند تغيير المجموعة أو المجموعة الفرعية، وليس عند تحديد الكتلة. تشترك الحقول التي تطلب المجموعة نفسها في الطلب الجاري. يظل اسم الأيقونة المخزن ظاهرًا قبل التحميل، وتؤدي إعادة التركيز على المنتقي إلى إعادة محاولة الطلب الفاشل.
يدعم tabler-icons كلًا من outline وfilled. تكون للمجموعة الفرعية التي أُعدّت صراحةً للمجموعة المختارة الأولوية؛ وإلا يستخدم المنتقي solid إن كانت متاحة، أو أول مجموعة فرعية. لا تتضمن المجموعات التي ليس لها مجموعات فرعية subSet. تُطابق أسماء المجموعات الملفات المضمّنة فقط. ويخزّن العرض في الواجهة الأمامية الأيقونات كلًّا على حدة بدلًا من تخزين مجموعات الأيقونات كاملةً في القيم المؤقتة لقاعدة البيانات.
قيم الخيارات المستوردة
تخزّن خانات الاختيار والقوائم المنسدلة التي تحتوي على "multiple": true عادةً مصفوفة من كائنات { "value": "...", "label": "..." }. كما تقبل كائن خيار واحدًا، أو سلسلة أو رقمًا مفردًا، أو مصفوفة من القيم المفردة المستوردة عبر REST API أو أدوات المحتوى. وينطبق ذلك أيضًا داخل صفوف الحقول المكررة.
يعرض المحرر هذه القيم كتحديدات دون تغيير شكل تخزينها عند الحفظ دون تعديل. تؤدي إضافة تحديد أو إزالته إلى كتابة مصفوفة كائنات الخيارات المعتادة. يُعد كل من 0 الرقمي و"0" النصي تحديدًا صالحًا. تتلقى القوالب returnFormat المُعدّ للحقل، كما يحدث مع القيم المحددة في المحرر. ويظل من الضروري أن تطابق الخيارات الاختيارات المعلنة للحقل أو المعبأة فيه.
تعرض القائمة المنسدلة الأصلية ذات الخيار الواحد عنصرًا نائبًا فارغًا ومعطلًا إذا لم تكن لها قيمة مخزنة أو قيمة افتراضية، ولا تعرض خيارها الأول. يؤدي اختيار الخيار الأول صراحةً إلى تخزينه. ويختفي العنصر النائب بمجرد تخزين خيار. استخدم allowNull عندما ينبغي أن يتمكن المحررون أيضًا من مسح تحديد؛ فالعنصر النائب الفارغ لا يجعل الخيار المطلوب قابلًا للمسح.
الصفوف الأولية للحقول المكررة
في المحرر، تشمل القيم الافتراضية الحد الأدنى من الصفوف المتداخلة قبل الإدراج. لا تحتاج إلى فتح إعدادات الكتلة لتهيئتها، ولا تؤدي إضافة الكتلة إلى إنشاء خطوة تراجع ثانية لهذه الصفوف.
عندما يكون للمكرر min دون قيمة محفوظة أو default صريح، يهيئ الخادم هذا العدد من الصفوف باستخدام القيم الافتراضية لحقول الصف. ينطبق هذا أيضًا على تضمينات PHP، ووسوم الكتل، ومصادر الصفحات المعتمدة على الملفات التي لم تُفتح قط في المحرر. على سبيل المثال، يعرض "min": 2 الذي يحتوي على حقل نصي قيمته الافتراضية "New item" صفين يتضمنان تلك القيمة.
تكون للصفوف المخزنة وdefault الصريح للمكرر الأولوية. لا تؤدي قائمة فارغة محفوظة صراحةً، أو false، أو null إلى إنشاء الصفوف المحذوفة من جديد. لا يحفظ العرض هذه القيم الافتراضية المُنشأة في المنشور. يقيّد min وmax عناصر التحكم في المحرر؛ ولا يختصران قائمة محفوظة أو يضيفان إليها صفوفًا عند العرض. استخدم bs_validate_block() للإبلاغ عن انتهاكات حدود الصفوف في المحتوى المستورد.
تكون حقول الصفوف التي لا تحتوي على default false في الصف المُنشأ، لذا لا يحتوي هذا الصف على محتوى. وتبدو الصفوف التي يضيفها المحررون ويتركونها فارغة بالطريقة نفسها. ينبغي للقالب الذي يعرض بطاقة أو عنوانًا أو عنصر قائمة لكل صف تخطي الصفوف التي لا تحتوي على محتوى خارج المحرر، مع إبقائها في المحرر لتظل حقولها قابلة للتحرير:
<?php foreach ( $a['items'] as $item ) : ?>
<?php if ( ! $isEditor && ! $item['title'] && ! $item['text'] ) continue; ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['text']; ?></p>
</div>
<?php endforeach; ?>
إزالة المكرر
تؤدي إزالة صف إلى فتح مربع حوار التأكيد في المحرر، وفيه زرا حذف وإلغاء. يؤدي اختيار «إلغاء» أو الضغط على Escape إلى إبقاء الصف دون تغيير. لا يُزال الصف إلا بعد التأكيد، بما في ذلك داخل المكررات المتداخلة.
يتحكم textRemove في السلوك نفسه لكل مكرر:
| القيمة | السلوك |
|---|---|
محذوفة أو true أو "" |
عرض سؤال التأكيد الافتراضي. |
| سلسلة غير فارغة | عرض السؤال المخصص باستخدام آلية ترجمة النصوص المخصصة الحالية. |
false |
إزالة الصف فورًا دون مربع حوار. |
على سبيل المثال، يغيّر "textRemove": "Remove this team member?" السؤال.
ويظل قيد min الحالي يمنع إزالة الصفوف التي يقل عددها عن الحد الأدنى.
تداخل المكررات
يقبل صف المكرر كل أنواع الحقول باستثناء tabs. ويعرض حقل tabs ضمن صف، حتى داخل مجموعة لا تحتوي على id، إشعارًا في المحرر بدلًا من حقوله. ويُبلغ امتداد PHPStan عن ذلك في block.json وfield.json. أبقِ حقول الصف مسطحة، أو انقل علامات التبويب إلى خارج المكرر.
روابط WYSIWYG
يدرج شريط أدوات الروابط في WYSIWYG روابط تفتح في علامة التبويب نفسها، دون إضافة target أو rel افتراضيًا. فعّل خيار الفتح في علامة تبويب جديدة باستخدام toolbar.formats.link.opensInNewTab:
{
"id": "content",
"type": "wysiwyg",
"toolbar": {
"formats": {
"link": {
"opensInNewTab": true
}
}
}
}
يضيف اختيار علامة تبويب جديدة target="_blank" وrel="noreferrer noopener".
ويؤدي إيقاف هذا الخيار إلى إزالة تلك السمات التلقائية. لتطبيق السمات على كل رابط في ذلك الحقل، اضبط toolbar.formats.link.attributes، مثلًا
{ "class": "content-link", "rel": "nofollow" }. ويُحافَظ على الإعدادات الصريحة، وتُضاف رموز الأمان الخاصة بعلامة التبويب الجديدة إلى rel المُعدّ.
لا يؤدي كتابة URL إلى تحويله تلقائيًا إلى رابط، كما أن النقر على رابط موجود في الحقل لا ينقلك بعيدًا عن المحرر. تظل سمات الروابط المحفوظة سابقًا في المحتوى الحالي؛ ولا تُرحّل تلقائيًا.