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

MediaPlaceholder

يوفر المكوّن MediaPlaceholder عنصرًا نائبًا لإضافة عناصر الوسائط إلى كتلة. ويُستخدم المكوّن نفسه في كتلة core/image. وهو مبني على المكوّن React الذي يحمل الاسم نفسه.

الاستخدام الأساسي

لاستخدام MediaPlaceholder بأبسط صورة، أضف السمة المناسبة إلى block.json وأضف المكوّن MediaPlaceholder إلى كتلتك.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/media-placeholder",
  "title": "Native Block",
  "category": "text",
  "icon": "star-filled",
  "description": "Native Blockstudio MediaPlaceholder block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "media",
        "type": "files"
      }
    ]
  }
}

PHP

PHP
<MediaPlaceholder attribute="media" />
<?php foreach ($a['media'] as $file) {
  echo wp_get_attachment_image($file['ID']);
} ?>

Twig

Twig
<MediaPlaceholder attribute="media" />
{% for file in a.media %}
  {{ fn('wp_get_attachment_image', file.ID) }}
{% endfor %}

بعد تحديد ملف وسائط، لن يعود المكوّن MediaPlaceholder معروضًا.

الخصائص

قبول

سلسلة نصية تُمرّر إلى FormFileUpload لتحديد أنواع الملفات التي يمكن تحميلها في نافذة التحميل التي يستخدم فيها المتصفح e.g.: image/* أو video/*. يتوفر مزيد من المعلومات حول هذه السلسلة في وثائق MDN.

allowedTypes

مصفوفة بأنواع الوسائط التي يمكن تحميلها أو اختيارها من مكتبة الوسائط. كل نوع سلسلة نصية يمكن أن تحتوي على نوع MIME عام e.g.: image أو audio أو text، أو نوع MIME كامل e.g.: audio/mpeg أو image/gif. إذا لم تُعيّن allowedTypes، فينبغي السماح بجميع أنواع MIME.

PHP

PHP
<MediaPlaceholder allowedTypes="<?php echo esc_attr(wp_json_encode(['image', 'video'])); ?>" />

Twig

Twig
<MediaPlaceholder allowedTypes="{{ ['image', 'video']|json_encode|escape('html_attr') }}" />

autoOpenMediaUpload

إذا كانت القيمة true، يفتح مكوّن MediaUpload تلقائيًا أداة اختيار المنصة المعنية.

disableDropZone

إذا كانت القيمة true، فلن تُعرض منطقة الإسقاط. لن يتمكن المستخدمون من سحب أي وسائط وإفلاتها في المكوّن أو الكتلة. ستظل عناصر التحكم UI لتحميل الوسائط عبر ملف أو URL أو مكتبة الوسائط متاحة.

dropZoneUIOnly

إذا كانت القيمة true، فلن تُعرض سوى منطقة الإسقاط. لن تظهر عناصر التحكم UI لتحميل الوسائط. تظل الخاصية disableDropZone لها الأولوية على dropZoneUIOnly؛ وسيؤدي تحديد كليهما بالقيمة true إلى عدم عرض أي شيء.

أيقونة

أيقونة Dashicon التي ستظهر إلى يسار العنوان.

isAppender

إذا كانت القيمة true، تغيّر الخاصية مظهر العنصر النائب ليلائم الحالات التي تُضاف فيها ملفات جديدة إلى مجموعة ملفات موجودة، e.g، مثل إضافة ملفات إلى معرض. وإذا كانت القيمة false، يُستخدم نمط العنصر النائب الافتراضي.

disableMediaButtons

إذا كانت القيمة true، فلن تُعرض سوى منطقة الإسقاط. لن تظهر عناصر التحكم UI لتحميل الوسائط.

التسميات

كائن يمكن أن يحتوي على خاصيتي العنوان والتعليمات.

PHP

PHP
<MediaPlaceholder labels="<?php echo esc_attr(wp_json_encode(['title' => 'Custom title', 'instructions' => 'Custom instructions'])); ?>" />

Twig

Twig
<MediaPlaceholder labels="{{ {title: 'Custom title', instructions: 'Custom instructions'}|json_encode|escape('html_attr') }}" />

حقول التكرار

يعمل MediaPlaceholder داخل حقول التكرار. استخدم تدوين الأقواس مع فهرس الحلقة لاستهداف الصف الصحيح.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "items",
        "type": "repeater",
        "attributes": [
          {
            "id": "image",
            "type": "files"
          }
        ]
      }
    ]
  }
}
PHP
<?php foreach ($a['items'] as $index => $item) : ?>
  <MediaPlaceholder attribute="items[<?php echo $index; ?>].image" />
<?php endforeach; ?>
Twig
{% for item in a.items %}
  <MediaPlaceholder attribute="items[{{ loop.index0 }}].image" />
{% endfor %}

تتبع قيمة attribute النمط repeaterId[index].fieldId، حيث index هو رقم الصف بدءًا من الصفر في الحلقة.