MediaPlaceholder
يوفر المكوّن MediaPlaceholder عنصرًا نائبًا لإضافة عناصر الوسائط إلى كتلة. ويُستخدم المكوّن نفسه في كتلة core/image. وهو مبني على المكوّن React الذي يحمل الاسم نفسه.
الاستخدام الأساسي
لاستخدام MediaPlaceholder بأبسط صورة، أضف السمة المناسبة إلى block.json وأضف المكوّن MediaPlaceholder إلى كتلتك.
{
"$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
<MediaPlaceholder attribute="media" />
<?php foreach ($a['media'] as $file) {
echo wp_get_attachment_image($file['ID']);
} ?>
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
<MediaPlaceholder allowedTypes="<?php echo esc_attr(wp_json_encode(['image', 'video'])); ?>" />
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
<MediaPlaceholder labels="<?php echo esc_attr(wp_json_encode(['title' => 'Custom title', 'instructions' => 'Custom instructions'])); ?>" />
Twig
<MediaPlaceholder labels="{{ {title: 'Custom title', instructions: 'Custom instructions'}|json_encode|escape('html_attr') }}" />
حقول التكرار
يعمل MediaPlaceholder داخل حقول التكرار. استخدم تدوين الأقواس مع فهرس الحلقة لاستهداف الصف الصحيح.
{
"blockstudio": {
"attributes": [
{
"id": "items",
"type": "repeater",
"attributes": [
{
"id": "image",
"type": "files"
}
]
}
]
}
}
<?php foreach ($a['items'] as $index => $item) : ?>
<MediaPlaceholder attribute="items[<?php echo $index; ?>].image" />
<?php endforeach; ?>
{% for item in a.items %}
<MediaPlaceholder attribute="items[{{ loop.index0 }}].image" />
{% endfor %}
تتبع قيمة attribute النمط repeaterId[index].fieldId، حيث index هو رقم الصف بدءًا من الصفر في الحلقة.