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

الحقول المخصصة

تتيح لك الحقول المخصصة تعريف مجموعات حقول قابلة لإعادة الاستخدام يمكن الرجوع إليها عبر كتل متعددة. اعتبرها قوالب للحقول: عرّفها مرة واستخدمها في كل مكان.

الحقول المخصصة ليست هي نفسها أنواع الحقول المخصصة. استخدم custom/{name} للمجموعات القابلة لإعادة الاستخدام من الحقول الموجودة. استخدم نوع حقل مخصص ذي مساحة أسماء مثل acme/dimensions عندما يسجّل النسق أو الإضافة عنصر تحكم جديدًا في المحرر وبنية قيمة جديدة.

التسجيل عبر نظام الملفات

أنشئ ملف field.json داخل المجلد fields/ في دليل blockstudio الخاص بك:

الكود
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

التسجيل باستخدام المرشح PHP

سجّل الحقول المخصصة برمجيًا باستخدام المرشح blockstudio/fields:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

الاستخدام في block.json

أشِر إلى حقل مخصص باستخدام النوع custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

يُدرج هذا الحقول المحددة في تعريف الحقل المخصص مباشرةً. وتستخدم الحقول الموسعة معرّفاتها الأصلية (heading وdescription وenabled).

يمكن للحقول المخصصة أيضًا إعادة استخدام تعريفات مجموعات كاملة:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

تُخزّن العناصر التابعة للمجموعة كـsection-header_kicker وsection-header_title وما إلى ذلك. في القوالب، استخدم bs_get_group() لاستخراجها في كائن مجموعة منظم.

بنية المعرّف

استخدم idStructure لإضافة بادئة إلى معرّفات الحقول أو تحويلها. ويُستبدل العنصر النائب {id} بمعرّف الحقل الأصلي:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

ينشئ هذا حقولًا بالمعرّفات: hero_heading وhero_description وhero_enabled.

التجاوزات

خصّص الحقول الفردية لكل مثيل باستخدام overrides. المفاتيح هي معرّفات الحقول الأصلية من التعريف:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

تُدمج خصائص التجاوز مع تعريف الحقل الأصلي. ويتجاوز التجاوز id النمط idStructure. في المثال أعلاه، يصبح enabled هو active بدلًا من hero_enabled.

الدمج بمستوى واحد: الخاصية التي تتجاوزها تحل محل الخاصية الأصلية بالكامل. تجاوز options هو قائمة الخيارات كاملة، وليس إضافة إليها، وينطبق الأمر نفسه على conditions وعلى attributes الخاصة بمجموعة. تظل شروط المرجع تُضاف بعد ذلك.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

لا يوفر هذا المكوّن سوى الأبيض والرمادي، مهما بلغ عدد الخيارات الواردة في التعريف.

الشروط

تُعاد كتابة الشروط داخل تعريفات الحقول المخصصة تلقائيًا عند تطبيق idStructure. ويظل الحقل الذي يعتمد شرطه على حقل شقيق يعمل بعد التوسيع.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

يوسّع Blockstudio ذلك إلى title_font_enable وtitle_font_min وtitle_font_max، ويعيد كتابة الشروط للإشارة إلى title_font_enable بدلًا من enable. وتعمل عناصر التحكم بمفتاح التبديل تمامًا كما لو كانت الحقول معرفة مباشرةً.

شروط مستوى المرجع

أضف conditions إلى المرجع لتطبيقها على كل حقل موسّع. يفيد ذلك في إخفاء مجموعة كاملة خلف مفتاح تبديل خارجي:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

تُدمج هذه الشروط مع أي شروط محددة مسبقًا داخل تعريف الحقل. وتُعاد كتابة معرّفات الشروط أيضًا عبر idStructure.

حقول مخصصة متعددة

يمكنك استخدام عدة حقول مخصصة في كتلة واحدة إلى جانب الحقول العادية:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

التداخل

تعمل الحقول المخصصة داخل المجموعات وعلامات التبويب والمكررات:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

مسارات اكتشاف إضافية

استخدم المرشح blockstudio/fields/paths لإضافة أدلة أخرى لاكتشاف الحقول:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

التحليل الثابت

توسّع الحزمة blockstudio/phpstan المراجع custom/* المعتمدة على الملفات عند التحقق من PHP وTwig وBlade وعلامات الكتل وأشكال السمات المستنتجة. ويتبع التوسيع قواعد التداخل وidStructure وoverrides نفسها الموضحة أعلاه.

للتعريفات خارج المشروع الذي يجري تحليله، أضف دليل المكتبة إلى blockstudioScanRoots في phpstan.neon. أما الحقول المسجلة عبر مرشح blockstudio/fields PHP فقط، فتكون متاحة أثناء التشغيل ولا يمكن استنتاجها في التحليل الثابت.