跳转到正文

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,该属性会将占位符样式调整为适用于向现有文件集合添加新文件的场景,例如向图库添加文件。如果为 false,则使用默认占位符样式。e.g

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 是循环中的从零开始的行号。