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

الإضافات

تتيح لك الإضافات توسيع أي كتلة مسجّلة في تثبيت WordPress لديك باستخدام API بسيط يستند إلى .json، وهو مشابه لإعداد block.json. ويشمل ذلك الكتل الأساسية وكتل الجهات الخارجية والكتل المُنشأة باستخدام Blockstudio.

يمكن إضافة جميع أنواع الحقول إلى أي كتلة، مع حفظ البيانات في سمات الكتلة. وتتوفر للإضافات مجموعة الميزات الكاملة للسمات، مثل التصفية والتعطيل والمنطق الشرطي وملء الخيارات.

أنواع الإضافات

يمكن استخدام القيم الموسّعة بطرق متعددة:

  • class: أضف فئة إلى الكتلة باستخدام قيمة السمة
  • style: أضف أنماطًا مضمنة إلى الكتلة باستخدام قيمة السمة
  • attributes: عيّن أي قيمة سمة مباشرةً على الكتلة
  • سمات البيانات: استخدم قيم الإضافة لتعيين سمات بيانات محددة

الإعداد

تخيّل السيناريو التالي: تريد إضافة حقل class مخصص select إلى كل كتلة أساسية. كل ما عليك هو إضافة ملف .json هذا إلى أي مكان داخل مجلد الكتل، وسيُسجّل تلقائيًا كإضافة.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "priority": 10,
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Custom color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

سيضيف هذا حقل customColor إلى كل كتلة أساسية، ما يتيح لك تعيين لون نص الكتلة.

اسم الملف

نظرًا إلى عدم وجود قالب عرض، لا تحتاج الإضافة إلى ملف index مطابق، ولا يلزم أن يكون اسمها block.json. وهذا يتيح تخزين جميع الإضافات بسهولة في مجلد واحد. ويمكن لعدة ملفات توسيع الكتل نفسها، مثل ملفين يحملان "name": "core/*"؛ إذ يسجّل كل منهما حقوله الخاصة.

المخطط

يوفر Blockstudio مخطط JSON مخصصًا لإعدادات الإضافات:

عرض مخطط الإضافة

الاسم

تحدد الخاصية name في كائن الإعدادات الكتل التي ينبغي توسيعها. تتوفر ثلاثة خيارات بحسب احتياجاتك:

  • blockName: اسم كتلة واحد، e.g. core/paragraph
  • [blockNameA, blockNameB]: مصفوفة من أسماء الكتل، e.g. ["core/paragraph", "core/heading"]
  • core/*: حرف بدل لتوسيع كل الكتل من نوع معين

أي اسم ينتهي بعلامة النجمة هو حرف بدل للبادئة، وليس core/* وحده. ينطبق الامتداد التالي على كل كتلة يبدأ اسمها بـ my-plugin/، بما في ذلك الكتل المنشأة باستخدام Blockstudio:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

استبعاد الكتل

استخدم مصفوفة exclude على المستوى الأعلى لتخطي الكتل التي كانت ستطابق name لولا ذلك:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

تستخدم الاستثناءات مطابقة الاسم الدقيق ومطابقة البادئة بعلامة * اللاحقة نفسها المستخدمة في name. ولها الأولوية على الأسماء المفردة وقوائم الأسماء وأحرف البدل. لا تحصل الكتلة المستثناة على حقول المحرر الخاصة بالامتداد ولا على سمات الواجهة الأمامية أو أصولها. لا تتأثر الامتدادات المطابقة الأخرى. احذف exclude أو استخدم مصفوفة فارغة للإبقاء على السلوك الحالي.

مفتاح Blockstudio

كما هو الحال عند استخدام block.json للكتل المخصصة، يجب أن تكون الخاصية blockstudio موجودة في كائن الإعدادات وأن تكون قيمة extend هي true.

الموضع

تعرض الإضافات افتراضيًا في علامة تبويب خاصة بها ضمن أداة فحص الكتلة. إذا أردت نقلها إلى موضع آخر، يمكنك استخدام الخاصية group:

  • settings: الموضع الافتراضي
  • styles: علامة تبويب الأنماط
  • advanced: علامة تبويب الإعدادات المتقدمة
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

الأولوية

تتيح لك الخاصية priority تحديد ترتيب عرض الإضافات. وتُعرض الإضافات ذات الأولوية الأعلى في وقت لاحق. عيّنها في المستوى الأعلى من الملف، كما في مثال الإعداد، أو داخل extend:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

عند تعيين القيمتين، تكون الأولوية لـ blockstudio.extend.priority.

السمات

لمزيد من المعلومات حول طريقة عمل السمات، يُرجى الرجوع إلى قسم السمات.

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

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Heading color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

الحصول على القيم

يُستخدم الترميز بالنقاط داخل الأقواس المعقوفة للحصول على قيمة سمة.

يمكن أيضًا الحصول على قيم متداخلة عندما لا تُرجع السمات قيمة واحدة، مثلًا عند ضبط تنسيق الإرجاع على both لأنواع الحقول التي تتضمن خيارات.

JSON
{
  "attributes": [
    {
      "id": "customColor",
      "type": "select",
      "label": "Heading color",
      "options": [
        {
          "value": "#f00",
          "label": "Red"
        },
        {
          "value": "#00f",
          "label": "Blue"
        }
      ],
      "returnFormat": "both",
      "set": [
        {
          "attribute": "style",
          "value": "color: {attributes.customColor.value}"
        },
        {
          "attribute": "data-color",
          "value": "{attributes.customColor.label}"
        }
      ]
    }
  ]
}

يضبط المثال أعلاه السمة style على color: #f00 أو color: #00f، والسمة data-color على Red أو Blue، بحسب القيمة.

حاليًا، لا يمكن استخدام سوى قيم السمة الحالية داخل تعريفات set. وقد تُضاف مستقبلًا إمكانية استخدام قيم من سمات أخرى.

المصفوفات

عند استخدام المصفوفات، تُطبّق الخاصية set على كل عنصر فيها.

يضيف كل عنصر فئته أو تصريح النمط الخاص به. وتحمل أي سمة أخرى قيمة واحدة، لذا يستبدلها كل عنصر وتكون الغلبة للعنصر الأخير. عيّن join إلى true لكتابة نتائج كل العناصر بدلاً من ذلك، مع الفصل بينها بمسافات ومن دون قيم فارغة أو مكررة، بحيث يطابق محدد مثل [data-langs~="en"] كل عنصر مختار. لا يؤثر join في class وstyle، ولا في الحقول التي تعيد قيمة واحدة.

JSON
{
  "id": "langs",
  "type": "checkbox",
  "label": "Languages",
  "options": [
    {
      "value": "en",
      "label": "English"
    },
    {
      "value": "de",
      "label": "German"
    }
  ],
  "set": [
    {
      "attribute": "data-langs",
      "value": "{attributes.langs}",
      "join": true
    }
  ]
}

يؤدي اختيار الخيارين معًا إلى عرض data-langs="en de". ومن دون join، يُعرض data-langs="de".

حقل السمات

عند استخدام حقل attributes، لا حاجة إلى الخاصية set، إذ يعيّن الحقل القيم تلقائيًا إلى اسم السمة وقيمتها.

فحص حقول الامتدادات

يعيد bs_block_extension_fields('core/paragraph') تعريفات الحقول لكل امتداد يطابق كتلة. راجع فحص الكتل لمعرفة القيمة المعادة وعلاقتها بـ bs_block_fields().