انتقل إلى المحتوى

أنواع الحقول

يوفر 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 إلى معرّفات المرفقات. راجع مراجع الوسائط القابلة للنقل لمزيد من التفاصيل.

راجع تحميل الأيقونات لمعرفة طلبات أداة الاختيار، وإعادات المحاولة، ومجموعات الأيقونات الفرعية.

السمات

يعرض حقول إدخال سمات البيانات.

JSON
{
  "type": "attributes"
}

الخصائص

الخاصية النوع الوصف
default array القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback array القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
link boolean يتيح اختيار الروابط من قائمة منسدلة.
media boolean يتيح اختيار الوسائط من قائمة منسدلة.

كتلة

يشير إلى كتلة Blockstudio أخرى، ويعرض حقولها ضمن السطر. في القوالب، تُرجع القيمة مخرجات الكتلة المعروضة.

JSON
{
  "type": "block"
}

الخصائص

الخاصية النوع الوصف
block string اسم الكتلة المراد الإشارة إليها (e.g، "mytheme/card").
returnFormat string كيفية إرجاع القيمة في القوالب.

مربع اختيار

يعرض مجموعة من حقول مربعات الاختيار.

JSON
{
  "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.

JSON
{
  "type": "classes"
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
tailwind boolean يحدد ما إذا كان سيتم تفعيل فئات Tailwind لهذا الحقل.

الكود

يعرض محررًا للأكواد.

JSON
{
  "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 من الحقل كأصل للكتلة، فلا يحتاج القالب إلى طباعة وسم النمط أو البرنامج النصي.

اللون

يعرض لوحة ألوان وأداة لاختيار اللون.

JSON
{
  "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 ما إذا كان ينبغي السماح بلون مخصص.

التاريخ

يعرض أداة لاختيار التاريخ.

JSON
{
  "type": "date"
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
startOfWeek number يوم بدء الأسبوع. استخدم 0 للأحد، و1 للاثنين، وهكذا.

التاريخ والوقت

يعرض أداة لاختيار التاريخ والوقت.

JSON
{
  "type": "datetime"
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
is12Hour boolean يحدد ما إذا كنا نستخدم تنسيق 12 ساعة. عند استخدام هذا التنسيق، تظهر أداة AM/PM ويُفترض أن يكون تنسيق الوقت MM-DD-YYYY (بدلاً من التنسيق الافتراضي DD-MM-YYYY).

الملفات

يعرض زرًا لفتح مكتبة الوسائط. يمكن إعادة ترتيب العناصر المحددة ضمن السطر.

JSON
{
  "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.

التدرج

يعرض لوحة تدرجات وأداة لاختيار التدرج.

JSON
{
  "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 ما إذا كان ينبغي السماح بلون مخصص.

المجموعة

يعرض حقولاً متعددة داخل حاوية قابلة للطي اختياريًا.

JSON
{
  "type": "group"
}

الخصائص

الخاصية النوع الوصف
title string نص العنوان. يظل ظاهرًا حتى عندما يكون المكوّن مغلقًا.
opened boolean عند تعيينه إلى true، يظل المكوّن مفتوحًا بصرف النظر عن الخاصية initialOpen و
initialOpen boolean يحدد ما إذا كانت اللوحة ستبدأ مفتوحة.
scrollAfterOpen boolean يمرر المحتوى إلى إطار العرض عند ظهوره.
class string فئة CSS مخصصة تُطبّق على المجموعة.
style object أنماط CSS مخصصة تُطبّق على المجموعة.
attributes array يقبل جميع أنواع الحقول الأخرى باستثناء tabs آخر.

وسم html

يعرض محددًا لوسم HTML. يفيد في اختيار مستويات العناوين أو العناصر الدلالية.

JSON
{
  "type": "html-tag"
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
tags string | array الوسوم المطلوب تضمينها. استخدم سلسلة إعداد مسبق أو مصفوفة من أسماء الوسوم.
exclude array الوسوم المطلوب استبعادها من الإعداد المسبق. ينطبق ذلك فقط عند استخدام سلسلة إعداد مسبق للوسوم.

الأيقونة

يعرض أيقونة SVG من مجموعة أيقونات.

JSON
{
  "type": "icon"
}

الخصائص

الخاصية النوع الوصف
default object القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback object القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
sets array | string مجموعة الأيقونات المطلوب تضمينها. اتركه فارغًا لتضمينها كلها.
subSets array | string مجموعة الأيقونات الفرعية المطلوب تضمينها. اتركه فارغًا لتضمينها كلها.
returnFormat string التنسيق الذي ستُعاد به الأيقونة.

يعرض عنصر تحكم للروابط لاختيار روابط داخلية أو خارجية.

JSON
{
  "type": "link"
}

الخصائص

الخاصية النوع الوصف
default object القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback object القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
hasRichPreviews boolean يحدد ما إذا كانت ستُعرض معاينات منسقة عند إضافة URL.
noDirectEntry boolean يحدد ما إذا كان يُسمح بتحويل استعلام بحث شبيه بـ URL مباشرةً إلى رابط.
noURLSuggestion boolean يحدد ما إذا كان سيتم إضافة اقتراح احتياطي يعامل استعلام البحث على أنه URL.
opensInNewTab boolean يضيف عنصر تحكم للتبديل إلى نافذة الروابط.
showSuggestions boolean يحدد ما إذا كانت ستظهر اقتراحات أثناء كتابة URL.
textButton string نص مخصص يُعرض داخل زر الرابط.
withCreateSuggestion boolean يحدد ما إذا كان البحث عن رابط غير مطابق يمكن أن ينشئ اقتراحًا لصفحة مسودة جديدة.

الرسالة

يعرض رسالة بمحتوى مخصص.

JSON
{
  "type": "message"
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
value string الرسالة المطلوب عرضها. تتوفر بيانات الكتلة والسمات بصيغة الأقواس، e.g: {block.title} أو {attributes.text}

الرقم

يعرض حقل إدخال رقم.

JSON
{
  "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.

الراديو

يعرض مجموعة من حقول الاختيار الأحادي.

JSON
{
  "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 يتيح للمستخدم مسح القيمة بالنقر مجددًا على عنصر الاختيار المحدد.

النطاق

يعرض حقل نطاق لتعيين قيمة رقمية بين نقطتين.

JSON
{
  "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.

تحديد

يعرض حقل تحديد يدعم اختيار عنصر واحد أو عدة عناصر.

JSON
{
  "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، فسيُعرض زر لإعادة تعيين حقل التحديد.

علامات التبويب

يعرض واجهة بعلامات تبويب لتجميع الحقول.

JSON
{
  "type": "tabs"
}

الخصائص

الخاصية النوع الوصف
tabs array علامات التبويب المطلوب عرضها.

النص

يعرض حقل إدخال نص في سطر واحد.

JSON
{
  "type": "text",
  "min": 0,
  "max": 100
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
max number الحد الأقصى لطول القيمة.
min number الحد الأدنى لطول القيمة.

منطقة النص

يعرض حقل إدخال لمنطقة نص.

JSON
{
  "type": "textarea",
  "min": 0,
  "max": 100,
  "rows": 4
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
max number الحد الأقصى لطول القيمة.
min number الحد الأدنى لطول القيمة.
rows number عدد الصفوف التي ينبغي أن تحتوي عليها منطقة النص.

مفتاح التبديل

يعرض مفتاح تبديل بين true وfalse.

JSON
{
  "type": "toggle"
}

الخصائص

الخاصية النوع الوصف
default boolean القيمة الافتراضية التي تُطبّق عند إضافة الكتلة لأول مرة.
fallback boolean القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.

مكرر

يعرض مجموعة من الحقول القابلة للتكرار.

JSON
{
  "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 آخر.

النص المنسق

حقل سمة لحقول النص المنسق.

JSON
{
  "type": "richtext"
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي ينبغي تطبيقها عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.

الوحدة

يعرض حقل إدخال رقم مع قائمة منسدلة للوحدات.

JSON
{
  "type": "unit"
}

الخصائص

الخاصية النوع الوصف
default string القيمة الافتراضية التي ينبغي تطبيقها عند إضافة الكتلة لأول مرة.
fallback string القيمة الاحتياطية التي ستظهر عندما تكون قيمة الحقل فارغة.
disableUnits boolean إذا كانت القيمة true، فسيُخفى حقل اختيار الوحدة.
isPressEnterToChange boolean إذا كانت القيمة true، فيلزم الضغط على مفتاح ENTER لتفعيل onChange. وعند التفعيل، يُفعّل التغيير أيضًا عند الانتقال إلى حقل آخر باستخدام مفتاح الجدولة.
isResetValueOnUnitChange boolean إذا كانت القيمة true وكانت الوحدة المحددة توفر قيمة افتراضية، تُضبط هذه القيمة عند تغيير الوحدات.
isUnitSelectTabbable boolean يحدد ما إذا كان يمكن الانتقال إلى حقل اختيار الوحدة باستخدام مفتاح الجدولة.
units array

محرر مرئي

يعرض محرر WYSIWYG.

JSON
{
  "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
<?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 روابط تفتح في علامة التبويب نفسها، دون إضافة target أو rel افتراضيًا. فعّل خيار الفتح في علامة تبويب جديدة باستخدام toolbar.formats.link.opensInNewTab:

JSON
{
  "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 إلى تحويله تلقائيًا إلى رابط، كما أن النقر على رابط موجود في الحقل لا ينقلك بعيدًا عن المحرر. تظل سمات الروابط المحفوظة سابقًا في المحتوى الحالي؛ ولا تُرحّل تلقائيًا.