MediaPlaceholder — это React-компонент, предоставляемый редактором блоков WordPress, используемый для отображения интерфейса загрузки и выбора медиафайлов. Этот компонент идеально подходит для блоков, которым необходимо работать с изображениями, видео, аудио или другими типами медиафайлов.
Основы использования MediaPlaceholder
Простой пример компонента MediaPlaceholder, где выбранное изображение сохраняется в атрибут imageURL блока:
import { MediaPlaceholder } from '@wordpress/block-editor';
const MediaBlock = ({ attributes, setAttributes }) => (
<MediaPlaceholder
onSelect={(media) => setAttributes({ imageURL: media.url })}
allowedTypes={['image']}
multiple={false}
labels={{ title: 'Выберите изображение' }}
/>
);
Параметры MediaPlaceholder
Ниже перечислены все параметры MediaPlaceholder с их описанием, типами и примерами использования.
1. accept
- Описание: Определяет, какие типы файлов можно загрузить. Формат совпадает с атрибутом
acceptHTML-тега<input type="file">. - Тип:
string - Обязательный: Нет
<MediaPlaceholder
accept="image/*,video/*"
labels={{ title: 'Загрузите изображение или видео' }}
/>
2. addToGallery
- Описание: Управляет режимом добавления файлов в галерею.
- Тип:
boolean - Значение по умолчанию:
false - Обязательный: Нет
<MediaPlaceholder
gallery
addToGallery={true}
labels={{ title: 'Добавьте изображения в галерею' }}
/>
3. allowedTypes
- Описание: Массив строк, представляющих типы файлов, которые можно выбрать/загрузить. Например:
image,audio,text. - Тип:
Array - Обязательный: Нет
<MediaPlaceholder
allowedTypes={['image', 'audio']}
labels={{ title: 'Выберите изображение или аудиофайл' }}
/>
4. autoOpenMediaUpload
- Описание: Автоматически открывает окно выбора медиафайлов.
- Тип:
boolean - Значение по умолчанию:
false - Обязательный: Нет
<MediaPlaceholder
autoOpenMediaUpload={true}
labels={{ title: 'Автоматическое открытие окна загрузки' }}
/>
5. className
- Описание: Пользовательский CSS-класс для стилизации.
- Тип:
string - Обязательный: Нет
<MediaPlaceholder
className="custom-media-placeholder"
labels={{ title: 'Кастомный плейсхолдер' }}
/>
6. disableDropZone
- Описание: Отключает возможность перетаскивания файлов.
- Тип:
boolean - Значение по умолчанию:
false - Обязательный: Нет
<MediaPlaceholder
disableDropZone={true}
labels={{ title: 'Загрузка файлов только через UI' }}
/>
7. dropZoneUIOnly
- Описание: Показывает только область перетаскивания без UI элементов.
- Тип:
boolean - Значение по умолчанию:
false - Обязательный: Нет
<MediaPlaceholder
dropZoneUIOnly={true}
labels={{ title: 'Перетащите файлы сюда' }}
/>
8. icon
- Описание: Иконка, отображаемая слева от заголовка. Может быть строкой (Dashicon) или компонентом.
- Тип:
string | Component - Обязательный: Нет
import { upload } from '@wordpress/icons';
<MediaPlaceholder
icon={upload}
labels={{ title: 'Загрузить медиафайл' }}
/>
9. isAppender
- Описание: Используется для добавления файлов к уже существующему набору, например, в галерею.
- Тип:
boolean - Значение по умолчанию:
false - Обязательный: Нет
<MediaPlaceholder
isAppender={true}
labels={{ title: 'Добавить дополнительные изображения' }}
/>10. disableMediaButtons
- Описание: Убирает кнопки UI для загрузки файлов.
- Тип:
boolean - Значение по умолчанию:
false - Обязательный: Нет
<MediaPlaceholder
disableMediaButtons={true}
labels={{ title: 'Только область для перетаскивания' }}
/>
11. labels
- Описание: Объект с текстовыми метками, такими как
titleиinstructions. - Тип:
Object - Обязательный: Нет
<MediaPlaceholder
labels={{
title: 'Выберите медиа',
instructions: 'Поддерживаются изображения и видео'
}}
/>
12. multiple
- Описание: Разрешает выбор нескольких файлов.
- Тип:
boolean | string - Значение по умолчанию:
false - Обязательный: Нет
<MediaPlaceholder
multiple={true}
labels={{ title: 'Выберите несколько файлов' }}
/>
13. onSelect
- Описание: Колбэк, вызываемый при выборе/загрузке файлов. Получает массив с объектами выбранных медиа.
- Тип:
Function - Обязательный: Да
<MediaPlaceholder
onSelect={(media) => console.log('Выбрано медиа:', media)}
allowedTypes={['image']}
labels={{ title: 'Выберите изображение' }}
/>
14. onSelectURL
- Описание: Колбэк, вызываемый при вставке URL файла.
- Тип:
Function - Обязательный: Нет
<MediaPlaceholder
onSelectURL={(url) => console.log('URL:', url)}
labels={{ title: 'Введите URL изображения' }}
/>
Пример с кастомным интерфейсом и Drop Zone
<MediaPlaceholder
disableDropZone={false}
dropZoneUIOnly={false}
onSelect={(files) => alert(`Файлы выбраны: ${files.length}`)}
labels={{
title: 'Выберите файлы',
instructions: 'Перетащите сюда или выберите из библиотеки'
}}
/>
Заключение
Компонент MediaPlaceholder предоставляет гибкий интерфейс для работы с медиафайлами. Благодаря множеству параметров вы можете настроить компонент под конкретные потребности вашего блока, будь то загрузка изображений, видео, аудио или других типов файлов.