دليل أنماط الحقول
نظام الحقول في Blockstudio بسيط عند النظر إليه منفردًا: أضف حقلًا إلى blockstudio.attributes، ثم اعرضه باستخدام $a في القالب. لكن الكتل الحقيقية نادرًا ما تقتصر على حقل واحد. فهي تضم إعدادات مترابطة، وحقولًا تظهر أو تختفي بحسب حقول أخرى، وحقولًا مكررة ذات بنى صفوف معقدة، وبيانات تحتاج إلى إمكانية الاستعلام عنها خارج محرر الكتل.
يجمع هذا الدليل وصفات عملية لأنماط الحقول الشائعة. تعرض كل وصفة إعداد block.json والشفرة المقابلة في القالب. انسخها مباشرة إلى كتلِك وعدّلها حسب الحاجة.
الحقول الشرطية
النمط الأكثر شيوعًا: إظهار الحقول أو إخفاؤها بناءً على قيمة حقل آخر. يساعد ذلك على إبقاء المحرر مرتبًا بعرض الخيارات المناسبة فقط.
إظهار الخيارات بمفتاح تبديل
كتلة دعوة إلى إجراء تظهر فيها إعدادات إضافية عند تفعيل المستخدم لزر:
{
"name": "my-theme/cta",
"title": "Call to Action",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Ready to get started?" },
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "showButton", "type": "toggle", "label": "Show Button", "default": true },
{
"id": "buttonText",
"type": "text",
"label": "Button Text",
"default": "Get Started",
"conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
},
{
"id": "buttonUrl",
"type": "link",
"label": "Button Link",
"conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
}
]
}
}
لا تظهر حقول نص الزر والرابط إلا عند تفعيل مفتاح التبديل. في القالب، تحقق من حالة المفتاح قبل العرض:
<div useBlockProps>
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<?php if ( $a['description'] ) : ?>
<p><?php echo esc_html( $a['description'] ); ?></p>
<?php endif; ?>
<?php if ( $a['showButton'] && $a['buttonUrl'] ) : ?>
<a href="<?php echo esc_url( $a['buttonUrl']['url'] ); ?>">
<?php echo esc_html( $a['buttonText'] ); ?>
</a>
<?php endif; ?>
</div>
التبديل بين مجموعات الحقول باستخدام قائمة اختيار
كتلة واجهة رئيسية يحدد فيها نوع الخلفية الحقول التي تظهر:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading" },
{
"id": "bgType",
"type": "select",
"label": "Background Type",
"default": "color",
"options": [
{ "value": "color", "label": "Solid Color" },
{ "value": "gradient", "label": "Gradient" },
{ "value": "image", "label": "Image" },
{ "value": "video", "label": "Video" }
]
},
{
"id": "bgColor",
"type": "color",
"label": "Background Color",
"conditions": [[{ "id": "bgType", "operator": "==", "value": "color" }]]
},
{
"id": "bgGradient",
"type": "gradient",
"label": "Background Gradient",
"conditions": [[{ "id": "bgType", "operator": "==", "value": "gradient" }]]
},
{
"id": "bgImage",
"type": "files",
"label": "Background Image",
"multiple": false,
"conditions": [[{ "id": "bgType", "operator": "==", "value": "image" }]]
},
{
"id": "bgVideo",
"type": "files",
"label": "Background Video",
"multiple": false,
"allowedTypes": ["video"],
"conditions": [[{ "id": "bgType", "operator": "==", "value": "video" }]]
},
{
"id": "overlay",
"type": "range",
"label": "Overlay Opacity",
"default": 50,
"min": 0,
"max": 100,
"conditions": [[{ "id": "bgType", "operator": "!=", "value": "color" }]]
}
]
}
}
يستخدم حقل عتامة الطبقة المتراكبة != ليظهر مع كل الأنواع عدا اللون المصمت. لا يظهر سوى حقل خلفية واحد في كل مرة. يعيد حقل color مصفوفة تتضمن value اللون وname وslug، لذا يقرأ القالب ['value']:
<?php
$bg_style = match ( $a['bgType'] ) {
'color' => $a['bgColor'] ? "background-color: {$a['bgColor']['value']}" : '',
'gradient' => $a['bgGradient'] ? "background: {$a['bgGradient']}" : '',
'image' => $a['bgImage'] ? "background-image: url({$a['bgImage']['url']})" : '',
default => '',
};
?>
<div useBlockProps style="<?php echo esc_attr( $bg_style ); ?>">
<?php if ( $a['bgType'] === 'video' && $a['bgVideo'] ) : ?>
<video autoplay muted loop playsinline>
<source src="<?php echo esc_url( $a['bgVideo']['url'] ); ?>" />
</video>
<?php endif; ?>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</div>
شروط OR
أظهر حقلًا عندما يتحقق أي شرط من عدة شروط. تمثل كل مصفوفة داخلية مجموعة AND، بينما تجمع المصفوفة الخارجية بينها باستخدام OR:
{
"id": "caption",
"type": "text",
"label": "Caption",
"conditions": [
[{ "id": "bgType", "operator": "==", "value": "image" }],
[{ "id": "bgType", "operator": "==", "value": "video" }]
]
}
يُظهر هذا حقل التسمية التوضيحية عندما تكون bgType هي “image” أو “video”.
الشروط المتسلسلة
تستخدم الشروط المتعددة في المصفوفة الداخلية نفسها منطق AND:
{
"id": "altText",
"type": "text",
"label": "Alt Text",
"conditions": [[
{ "id": "bgType", "operator": "==", "value": "image" },
{ "id": "bgImage", "operator": "!empty" }
]]
}
لا يظهر حقل النص البديل إلا عندما تكون bgType هي “image” AND تكون قد حُددت صورة.
الشروط العامة
أظهر الحقول بناءً على نوع المنشور أو معرّفه أو دور المستخدم بدلًا من قيم الحقول الأخرى:
{
"id": "seoTitle",
"type": "text",
"label": "SEO Title",
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
أنواع الشروط العامة المتاحة: postType، postId، userRole، userId.
تنظيم الإعدادات
مع ازدياد تعقيد الكتل، يساعد تنظيم الحقول في مجموعات منطقية على إبقاء لوحة الفحص سهلة الاستخدام.
مجموعات للتنظيم المرئي
تنشئ المجموعات أقسامًا قابلة للطي في لوحة الفحص. المجموعة مجهولة الاسم (من دون id) مخصصة للتنظيم المرئي فقط؛ ويمكن الوصول إلى حقولها باستخدام معرّفاتها كما هي:
{
"name": "my-theme/card",
"title": "Card",
"blockstudio": {
"attributes": [
{
"type": "group",
"title": "Content",
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" },
{ "id": "image", "type": "files", "label": "Image", "multiple": false }
]
},
{
"type": "group",
"title": "Link",
"attributes": [
{ "id": "url", "type": "link", "label": "URL" },
{ "id": "openInNewTab", "type": "toggle", "label": "Open in New Tab" }
]
},
{
"type": "group",
"title": "Appearance",
"attributes": [
{
"id": "style",
"type": "select",
"label": "Style",
"default": "elevated",
"options": [
{ "value": "elevated", "label": "Elevated" },
{ "value": "outlined", "label": "Outlined" },
{ "value": "flat", "label": "Flat" }
]
},
{ "id": "accentColor", "type": "color", "label": "Accent Color" }
]
}
]
}
}
<div useBlockProps>
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['description'] ); ?></p>
</div>
يمكن الوصول إلى الحقول مباشرة: $a['title']، $a['style']، $a['accentColor']. تؤثر المجموعات في تخطيط لوحة الفحص فقط.
مجموعات مسماة باستخدام bs_get_group
عندما يكون للمجموعة id، تُضاف بادئة إلى معرّفات حقولها الفرعية. استخدم bs_get_group() لإزالة البادئة:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" },
{ "id": "avatar", "type": "files", "label": "Avatar", "multiple": false }
]
}
من دون المساعد، يمكن الوصول إلى الحقول باستخدام $a['author_name']، $a['author_role']، $a['author_avatar']. ومع المساعد:
<?php $author = bs_get_group( $a, 'author' ); ?>
<div class="author">
<?php if ( $author['avatar'] ) : ?>
<img src="<?php echo esc_url( $author['avatar']['url'] ); ?>" alt="" />
<?php endif; ?>
<p><?php echo esc_html( $author['name'] ); ?></p>
<p><?php echo esc_html( $author['role'] ); ?></p>
</div>
تكون المجموعات المسماة مفيدة عندما تتكرر أسماء الحقول نفسها في مجموعات متعددة (مثل e.g وauthor_name وcompany_name)، أو عندما تريد تمرير المجموعة كوحدة واحدة إلى قالب جزئي.
تخطيط الشبكة داخل المجموعات
استخدم الخاصية style لترتيب الحقول الفرعية للمجموعة جنبًا إلى جنب:
{
"type": "group",
"title": "Dimensions",
"style": {
"display": "grid",
"grid-template-columns": "1fr 1fr",
"grid-gap": "16px"
},
"attributes": [
{ "id": "width", "type": "unit", "label": "Width", "default": "100%", "switch": false },
{ "id": "height", "type": "unit", "label": "Height", "default": "auto", "switch": false }
]
}
يظهر حقلا الوحدات جنبًا إلى جنب في لوحة الفحص بدلًا من تكديسهما. يناسب ذلك أزواج الأبعاد وقيم الهوامش والحشو، وأي حقلين يرتبطان مفاهيميًا.
علامات تبويب للأقسام الرئيسية
عندما تضم الكتلة إعدادات كثيرة، توفر علامات التبويب تنظيمًا أوضح من قائمة طويلة من المجموعات:
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "body", "type": "wysiwyg", "label": "Body" }
]
},
{
"title": "Media",
"attributes": [
{ "id": "image", "type": "files", "label": "Image", "multiple": false },
{ "id": "video", "type": "files", "label": "Video", "multiple": false, "allowedTypes": ["video"] }
]
},
{
"title": "Settings",
"attributes": [
{ "id": "layout", "type": "select", "label": "Layout", "options": [
{ "value": "left", "label": "Media Left" },
{ "value": "right", "label": "Media Right" }
]},
{ "id": "fullWidth", "type": "toggle", "label": "Full Width" }
]
}
]
}
يمكن الوصول إلى حقول كل علامة تبويب كما لو كانت حقولًا في المستوى الأعلى: $a['title']، $a['image']، $a['layout']. علامات التبويب حاوية UI بحتة.
أنماط الحقول المكررة
تتيح الحقول المكررة للمستخدمين إضافة صفوف متعددة من الحقول. وهي ضرورية للقوائم والشبكات والجداول الزمنية وأي مكوّن يضم عددًا متغيرًا من العناصر.
حقل مكرر أساسي مع قيود
قائمة ميزات تضم من عنصر واحد إلى 6 عناصر:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 6,
"textButton": "Add Feature",
"attributes": [
{ "id": "icon", "type": "icon", "label": "Icon" },
{ "id": "title", "type": "text", "label": "Title", "default": "Feature" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<div useBlockProps class="grid grid-cols-3 gap-8">
<?php foreach ( $a['features'] as $feature ) : ?>
<div>
<?php if ( $feature['icon'] ) : ?>
<?php bs_render_icon( $feature['icon'] ); ?>
<?php endif; ?>
<h3><?php echo esc_html( $feature['title'] ); ?></h3>
<p><?php echo esc_html( $feature['description'] ); ?></p>
</div>
<?php endforeach; ?>
</div>
تسميات مخصصة للصفوف
تعرض صفوف الحقول المكررة المصغرة تسمية عامة افتراضيًا. استخدم textMinimized لعرض قيمة أحد الحقول بدلًا منها:
{
"id": "team",
"type": "repeater",
"label": "Team Members",
"textMinimized": { "id": "name", "fallback": "Team Member" },
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" },
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
]
}
عند طي الصف، يظهر اسم الشخص بدلًا من “Row 1”. يُستخدم fallback إذا كان حقل الاسم فارغًا. ويمكنك أيضًا إضافة السلاسل prefix وsuffix.
الشروط داخل الحقول المكررة
يمكن للحقول داخل حقل مكرر الإشارة إلى حقول أخرى في الصف نفسه باستخدام id الخاص بها كما هو (لا حاجة إلى بادئة):
{
"id": "links",
"type": "repeater",
"label": "Links",
"attributes": [
{ "id": "label", "type": "text", "label": "Label" },
{ "id": "url", "type": "link", "label": "URL" },
{
"id": "isExternal",
"type": "toggle",
"label": "External Link"
},
{
"id": "externalNote",
"type": "message",
"label": "Note",
"description": "External links open in a new tab with rel=\"noopener\".",
"conditions": [[{ "id": "isExternal", "operator": "==", "value": true }]]
}
]
}
الإشارة إلى الحقول الخارجية من داخل حقل مكرر
عندما يحتاج شرط داخل حقل مكرر إلى التحقق من حقل خارجه، أضف "context": "main":
{
"id": "showDescriptions",
"type": "toggle",
"label": "Show Descriptions",
"default": true
},
{
"id": "items",
"type": "repeater",
"label": "Items",
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{
"id": "description",
"type": "textarea",
"label": "Description",
"conditions": [[{
"id": "showDescriptions",
"operator": "==",
"value": true,
"context": "main"
}]]
}
]
}
من دون "context": "main"، سيبحث الشرط عن حقل showDescriptions داخل صف الحقل المكرر. ومعه، يتحقق الشرط من مفتاح التبديل على مستوى الجذر.
علامات التبويب داخل الحقول المتكررة
لا تتوفر علامات التبويب داخل الحقول المتكررة: يعرض حقل tabs داخل صف حقل متكرر تنبيهًا في المحرر بدلًا من حقوله، كما يبلّغ امتداد PHPStan عن ذلك. أبقِ حقول الصف مسطحة بدلًا من ذلك. وفي الصفوف الطويلة، تجعل تسمية صف مخصصة (textMinimized) الصفوف المطوية سهلة القراءة، كما يمكن للشروط داخل الصف إخفاء الحقول التي تحتاج إليها بعض الصفوف فقط، وفقًا للأنماط أعلاه.
عيّن "minimized": true لحقل متكرر لبدء طيّ الصفوف الحالية. تُفتح الصفوف المضافة حديثًا فورًا. تُحفظ الاستثناءات الموسّعة في هذا المتصفح بين مرات إعادة تحميل المحرر؛ وهذا تفضيل للتحرير وليس محتوى محفوظًا للمقالة.
وتحتفظ الحقول المتكررة التي لا تحتوي على minimized بسلوكها الحالي الذي يعرض الصفوف موسّعة افتراضيًا.
أنماط الوسائط
صورة واحدة مع صورة بديلة
{
"id": "image",
"type": "files",
"label": "Image",
"multiple": false
}
<?php if ( $a['image'] ) : ?>
<img
src="<?php echo esc_url( $a['image']['url'] ); ?>"
alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
<?php if ( isset( $a['image']['sizes']['full-width'], $a['image']['sizes']['full-height'] ) ) : ?>
width="<?php echo esc_attr( $a['image']['sizes']['full-width'] ); ?>"
height="<?php echo esc_attr( $a['image']['sizes']['full-height'] ); ?>"
<?php endif; ?>
/>
<?php endif; ?>
القيمة الافتراضية لـ returnFormat هي "object"، التي توفر ID وtitle وalt وcaption وdescription وhref وurl وsizes. يحتوي sizes على URL لكل حجم صورة مسجل (sizes['large']) مع أبعاده (sizes['large-width'] وsizes['large-height']). راجع سمات العرض للاطلاع على القائمة الكاملة.
معرض مع حد أقصى
{
"id": "gallery",
"type": "files",
"label": "Gallery",
"multiple": true,
"max": 6,
"allowedTypes": ["image"]
}
<?php if ( $a['gallery'] ) : ?>
<div class="grid grid-cols-3 gap-4">
<?php foreach ( $a['gallery'] as $image ) : ?>
<img
src="<?php echo esc_url( $image['url'] ); ?>"
alt="<?php echo esc_attr( $image['alt'] ); ?>" />
<?php endforeach; ?>
</div>
<?php endif; ?>
صورة قابلة للتعطيل بمفتاح تبديل
تضيف الخاصية switch أيقونة عين تتيح للمستخدمين تعطيل الحقل دون حذف قيمته:
{
"id": "logo",
"type": "files",
"label": "Logo",
"multiple": false,
"switch": true
}
<?php
$is_disabled = ! empty( $a['_disabled'] ) && in_array( 'logo', $a['_disabled'], true );
if ( $a['logo'] && ! $is_disabled ) : ?>
<img src="<?php echo esc_url( $a['logo']['url'] ); ?>" alt="" />
<?php endif; ?>
يمكن للمستخدم إيقاف الشعار دون إزالة الملف الذي رفعه. وعند إعادة تفعيله، يعود الملف نفسه.
تنويعات تنسيق الإرجاع
تحكم في القيمة التي يعيدها حقل الملفات:
// Full object (default)
{ "id": "photo", "type": "files", "returnFormat": "object", "multiple": false }
// $a['photo']['url'], $a['photo']['alt'], $a['photo']['sizes']['full-width'], etc.
// Just the ID
{ "id": "photo", "type": "files", "returnFormat": "id", "multiple": false }
// $a['photo'] = 42
// Just the URL
{ "id": "photo", "type": "files", "returnFormat": "url", "multiple": false }
// $a['photo'] = "https://example.com/photo.jpg"
استخدم "id" عندما تحتاج إلى استدعاء wp_get_attachment_image() بنفسك. واستخدم "url" لصور الخلفية البسيطة. واستخدم "object" (الإعداد الافتراضي) لكل ما عدا ذلك.
عند استخدام "returnFormat": "id"، يُمرر مرجع سلسلة مستورد مثل "buckshair-home" كما هو. يعرض المحرر بطاقة احتياطية بلا صورة مصغرة، بما في ذلك داخل صفوف الحقول المتكررة. لا يؤدي فتح الصفحة أو حفظها إلى تحويل مرجع مفرد إلى مصفوفة. وتعمل أيضًا القوائم المختلطة من معرّفات المرفقات ومراجع السلاسل؛ ولا يُبحث في مكتبة الوسائط إلا عن معرّفات المرفقات الموجبة.
لا يحل Blockstudio مراجع السلاسل المخصصة إلى مرفقات. عند استخدام أسماء قابلة للنقل بين المواقع، حلّها في مرشح العرض أو القالب الخاص بك. يؤدي اختيار بديل في مكتبة الوسائط إلى تخزين معرّف المرفق كالمعتاد.
الخيارات الديناميكية
الملء من المنشورات
حقل اختيار يعرض جميع الصفحات المنشورة:
{
"id": "linkedPage",
"type": "select",
"label": "Linked Page",
"stylisedUi": true,
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "page",
"post_status": "publish",
"posts_per_page": -1
}
}
}
يُملأ الحقل تلقائيًا بعناوين الصفحات كتسميات ومعرّفات المنشورات كقيم. استخدم returnFormat في إعدادات الملء لتخصيص الربط:
"populate": {
"type": "query",
"query": "posts",
"arguments": { "post_type": "page" },
"returnFormat": { "value": "ID", "label": "post_title" }
}
الملء من مصطلحات التصنيف
{
"id": "category",
"type": "select",
"label": "Category",
"stylisedUi": true,
"populate": {
"type": "query",
"query": "terms",
"arguments": {
"taxonomy": "category",
"hide_empty": true
}
}
}
الملء من دالة PHP
{
"id": "postType",
"type": "select",
"label": "Post Type",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": { "public": true }
}
}
خيارات ثابتة مع إضافات مملوءة ديناميكيًا
اجمع بين الخيارات المحددة مسبقًا والخيارات الديناميكية. استخدم position للتحكم في موضع ظهور الخيارات المملوءة:
{
"id": "source",
"type": "select",
"label": "Source",
"options": [
{ "value": "manual", "label": "Manual Entry" },
{ "value": "latest", "label": "Latest Posts" }
],
"populate": {
"type": "query",
"query": "posts",
"arguments": { "post_type": "page" },
"position": "after"
}
}
تظهر الخيارات الثابتة أولًا، تليها الصفحات المملوءة ديناميكيًا.
تخزين البيانات للاستعلامات
تُخزن قيم الحقول افتراضيًا في سمات الكتل داخل post_content. ولا يمكن الاستعلام عنها باستخدام WP_Query. عند الحاجة إلى تصفية المنشورات أو ترتيبها حسب قيمة حقل، استخدم التخزين.
بيانات المنشور الوصفية للحقول القابلة للاستعلام
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
},
{
"id": "priority",
"type": "number",
"label": "Priority",
"default": 0,
"min": 0,
"max": 100,
"storage": {
"type": "postMeta",
"postMetaKey": "priority_score"
}
}
يمكنك الآن الاستعلام عن المنشورات المميزة:
$featured = new WP_Query( array(
'meta_query' => array(
array(
'key' => 'is_featured',
'value' => '1',
),
),
'orderby' => 'meta_value_num',
'meta_key' => 'priority_score',
'order' => 'DESC',
) );
تُسجل مفاتيح البيانات الوصفية تلقائيًا باستخدام show_in_rest، لذا فهي متاحة أيضًا في REST API.
التخزين المزدوج
خزّن البيانات في كل من سمات الكتلة والبيانات الوصفية للمنشور. تُبقي سمة الكتلة القيمة متاحة في القوالب عبر $a، بينما تتيح البيانات الوصفية الاستعلام عنها:
{
"id": "eventDate",
"type": "date",
"label": "Event Date",
"storage": {
"type": ["block", "postMeta"],
"postMetaKey": "event_date"
}
}
تخزين الخيارات للقيم العامة
استخدم تخزين الخيارات للإعدادات على مستوى الموقع التي ينبغي أن تكون موحدة في كل مكان:
{
"id": "companyName",
"type": "text",
"label": "Company Name",
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
تُخزن القيمة في wp_options ويمكن الوصول إليها من أي مكان باستخدام get_option('site_company_name'). وعندما يعدل المستخدم هذا الحقل في أي نسخة من الكتلة، تُحدّث القيمة على مستوى الموقع كله.
تعريفات الحقول القابلة لإعادة الاستخدام
عندما تشترك كتل متعددة في بنية الحقول نفسها، عرّفها مرة واحدة كحقل مخصص وأشِر إليها في كل مكان.
إنشاء حقل مخصص
أنشئ field.json في دليل blockstudio/fields/ الخاص بسمة موقعك:
theme/
└── blockstudio/
└── fields/
└── cta/
└── field.json
{
"name": "cta",
"title": "Call to Action",
"attributes": [
{ "id": "label", "type": "text", "label": "Button Label", "default": "Learn More" },
{ "id": "url", "type": "link", "label": "Button URL" },
{ "id": "style", "type": "select", "label": "Button Style", "default": "primary", "options": [
{ "value": "primary", "label": "Primary" },
{ "value": "secondary", "label": "Secondary" },
{ "value": "outline", "label": "Outline" }
]}
]
}
استخدام الحقل المخصص
أشِر إليه في أي كتلة باستخدام "type": "custom/cta":
{
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading" },
{ "type": "custom/cta" }
]
}
}
تُضمّن حقول الدعوة إلى إجراء داخل الكتلة. ويمكن الوصول إليها مباشرة: $a['label']، $a['url']، $a['style'].
الحقول المخصصة ذات البادئة باستخدام idStructure
عند استخدام الحقل المخصص نفسه عدة مرات، أضف idStructure لوضع بادئة للمعرّفات:
{
"blockstudio": {
"attributes": [
{ "type": "custom/cta", "idStructure": "primary_{id}" },
{ "type": "custom/cta", "idStructure": "secondary_{id}" }
]
}
}
تصبح حقول الدعوة إلى إجراء الأولى primary_label، primary_url، primary_style. والثانية secondary_label، وهكذا.
تجاوز القيم الافتراضية
خصّص حقولًا معينة عند الإشارة إلى حقل مخصص:
{
"type": "custom/cta",
"idStructure": "hero_{id}",
"overrides": {
"label": { "default": "Get Started", "label": "CTA Label" },
"style": { "default": "primary" }
}
}
تُدمج التجاوزات مع التعريف الأصلي. يمكنك تغيير القيم الافتراضية أو التسميات أو الشروط أو أي خاصية أخرى.
أنماط العرض
التحقق من القيم الفارغة
تعيد معظم أنواع الحقول false عندما تكون فارغة. تحقق دائمًا من القيمة قبل عرضها:
<?php if ( $a['title'] ) : ?>
<h2><?php echo esc_html( $a['title'] ); ?></h2>
<?php endif; ?>
بالنسبة إلى الأعداد، تُعد 0 قيمة صالحة. استخدم مقارنة صارمة إذا كنت بحاجة إلى التمييز بين «فارغ» و«صفر»:
<?php if ( $a['count'] !== 0 || $a['count'] !== false ) : ?>
<span><?php echo esc_html( $a['count'] ); ?></span>
<?php endif; ?>
قائمة اختيار مع returnFormat: both
عندما تحتاج إلى القيمة (للمنطق) والتسمية (للعرض) معًا:
{
"id": "status",
"type": "select",
"label": "Status",
"returnFormat": "both",
"options": [
{ "value": "active", "label": "Active" },
{ "value": "paused", "label": "On Hold" },
{ "value": "closed", "label": "Closed" }
]
}
<?php if ( $a['status'] ) : ?>
<span class="badge badge--<?php echo esc_attr( $a['status']['value'] ); ?>">
<?php echo esc_html( $a['status']['label'] ); ?>
</span>
<?php endif; ?>
سمات البيانات من حقل السمات
يتيح نوع الحقل attributes للمستخدمين إضافة سمات بيانات مخصصة:
{
"id": "dataAttrs",
"type": "attributes",
"label": "Data Attributes",
"link": true,
"media": true
}
<div useBlockProps <?php bs_render_data_attributes( $a['dataAttrs'] ); ?>>
Content here.
</div>
متغيرات CSS من قيم الحقول
أنشئ خصائص CSS مخصصة من الحقول المحددة:
{
"id": "textColor", "type": "color", "label": "Text Color"
},
{
"id": "fontSize", "type": "unit", "label": "Font Size", "default": "1rem"
}
<div useBlockProps style="<?php bs_render_variables( $a, array( 'textColor', 'fontSize' ) ); ?>">
<p>Styled content.</p>
</div>
ينتج عن ذلك style="--text-color: #333; --font-size: 1rem;" (تُحوّل معرّفات الحقول إلى صيغة kebab-case). استخدم المتغيرات في CSS:
p {
color: var(--text-color);
font-size: var(--font-size);
}
الخطوات التالية
- تسجيل السمات: خصائص
idوtypeوlabelوdefaultوhelpوpositionوconditions. - مرجع أنواع الحقول: مرجع مُنشأ تلقائيًا يتضمن كل خاصية لكل نوع حقل.
- المنطق الشرطي: العوامل والشروط العامة ومرشحات الشروط المخصصة وسياق الحقول المكررة.
- ملء الخيارات: أوضاع الاستعلام والدوال والخيارات المخصصة والجلب لحقول الخيارات الديناميكية.
- الحقول المخصصة:
field.jsonومسارات الاكتشاف ومرشحblockstudio/fieldsوأنماطidStructureالمتقدمة. - العرض:
$aو$bو$cوالقيم الفارغة والدوال المساعدة.