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

أنواع الحقول المخصصة

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

  • custom/{name} يشير إلى مجموعة قابلة لإعادة الاستخدام من الحقول الموجودة.
  • namespace/type-name يستخدم نوع حقل مسجّلًا له عنصر تحكم خاص به في المحرر وبنية قيمة خاصة به.

Blockstudio يوفر نظام التسجيل. أما النسق أو الإضافة فيوفر عنصر التحكم.

متى تستخدمها

استخدم نوع حقل مخصصًا عندما يحتاج المشروع إلى عنصر تحكم تحرير مخصص لغرض واحد، وينبغي أن يعمل مثل حقل Blockstudio أصلي في كل مكان:

  • سمات الكتل
  • مجموعات حقول custom/{name} القابلة لإعادة الاستخدام
  • المجموعات وعلامات التبويب والمكررات
  • القوالب PHP وTwig وBlade
  • تخزين البيانات الوصفية للمنشورات والخيارات
  • قوالب الإضافات مثل {attributes.margin.top}

على سبيل المثال، يمكن لعنصر تحكم التباعد تخزين كائن واحد بدلًا من أربعة حقول نصية منفصلة:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

التسمية

يجب أن تكون أسماء أنواع الحقول المخصصة بأحرف صغيرة، وأن تتضمن مساحة أسماء، وأن تستخدم الشرطات للفصل بين الكلمات:

Text
namespace/type-name

أمثلة صالحة:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

مساحات الأسماء المحجوزة:

  • custom/ محجوز لمجموعات الحقول المخصصة القابلة لإعادة الاستخدام.
  • blockstudio/ محجوز للنواة Blockstudio.

يتجاهل المرشح API الأسماء غير الصالحة، ويرفضها المساعد API.

التسجيل باستخدام PHP

سجّل بيانات تعريف نوع الحقل في PHP:

PHP
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});

تعيد bs_register_field_type() القيمة true عند نجاح التسجيل، وfalse عندما يكون الاسم أو التعريف غير صالح. يمكنك إلغاء تسجيل تسجيل يدوي باستخدام bs_unregister_field_type().

يمكنك أيضًا استخدام المرشح API:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

مفاتيح التعريف

المفتاح النوع الوصف
attribute string، array، null نوع السمة WordPress. استخدم string أو number أو boolean أو object أو array، أو مصفوفة من تلك الأنواع.
default mixed قيمة افتراضية على مستوى السجل عندما لا يحدد الحقل قيمة افتراضية خاصة به.
source string مصدر السمة WordPress لحالات التسلسل المخصصة.
produces_attribute boolean اضبطها على false لعناصر التحكم المخصصة للعرض فقط. القيمة الافتراضية هي true.
editor_script string or array معرّف البرنامج النصي المسجّل أو معرّفاته لإضافتها إلى قائمة الانتظار في محرر الكتل عند استخدام النوع.
editor_style string or array معرّف النمط المسجّل أو معرّفاته لإضافتها إلى قائمة الانتظار في محرر الكتل عند استخدام النوع.
storage array تلميحات نوع قيمة التخزين ومخطط REST للبيانات الوصفية للمنشور والخيارات.
supports array أعلام إمكانات اختيارية لعناصر التحكم الخاصة بك.
translate boolean اضبطها على true عندما تكون القيمة نصًا لـ WPML لترجمتها. يتطلب ذلك attribute string.

يكون التعريف غير صالح إذا كانت قيمة translate ليست قيمة منطقية، أو إذا ضُبطت translate على true وكانت قيمة attribute غير string. يُرجع bs_register_field_type() القيمة false ويتجاهل المرشح API هذا التعريف.

WPML

wp bs wpml config لا يمكنه معرفة ما إذا كانت قيمة نوع الحقل المخصص نصًا بمجرد التسجيل، لذا يستثني هذه الحقول ويصدر تحذيرًا لكل منها. عيّن translate إلى true في تسجيل نوع الحقل الذي يخزّن سلسلة نصية عادية، وسيُدرج الأمر حقوله مثل حقول text. يمكن للحقل مع ذلك استبعاد نفسه باستخدام "translate": false. راجع WPMLالمستندات.

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

التسجيل باستخدام JavaScript

يسجّل نص المحرر البرمجي عنصر التحكم المطابق React:

JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

تعيد registerFieldType() القيمة true عند قبول التسجيل. أزل تسجيلًا من العميل باستخدام:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

يتلقى المكوّن خصائص تعريف الحقل، بالإضافة إلى الخصائص الثابتة التالية:

الخاصية الوصف
type اسم نوع الحقل.
id معرّف الحقل.
field تعريف الحقل الكامل من block.json.
value القيمة المحفوظة الحالية.
defaultValue القيمة الافتراضية للحقل.
onChange تخزين قيمة جديدة مباشرة.
attributes سمات الكتلة الحالية.
block تعريف نوع الكتلة الحالية.
clientId معرّف العميل لكتلة المحرر الحالية.
inRepeater ما إذا كان الحقل داخل صف مكرر.
repeaterId مسار المكرر الحالي، إن وجد.
disabled ما إذا كان الحقل معطّلًا في المحرر.

تُخزّن قيم أنواع الحقول المخصصة مباشرةً. ولا تمر عبر تطبيع الخيارات الأصلي select أو radio أو color أو gradient.

عرض القيم

تتوفر قيم الكائنات مثل أي سمة Blockstudio أخرى.

PHP

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

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

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

التخزين

عند استخدام نوع حقل مخصص مع تخزين postMeta أو option، يستخدم Blockstudio نوع قيمة التخزين المسجّل ومخطط REST.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

بالنسبة إلى قيم array وobject، عرّف storage.rest_schema في تسجيل نوع الحقل. وتواصل العناصر التابعة للمكرر استخدام التخزين المعتمد على المصفوفات لأن المكرر يخزن صفوفًا.

السلوك الاحتياطي

إذا كان PHP يعرف نوع الحقل لكن النص البرمجي للمحرر لا يسجّل عنصر تحكم مطابقًا، يحتفظ Blockstudio بالقيمة المحفوظة ويعرض إشعارًا غير قابل للتحرير في المحرر. ويظل العرض في الواجهة الأمامية يتلقى القيمة المحفوظة.

إذا لم يُسجّل نوع حقل في PHP، يستبعده Blockstudio من سمات WordPress المُنشأة. سجّل تعريف PHP قبل بدء اكتشاف الكتل، عادةً في init قبل أن ينشئ Blockstudio الكتل.