このページは Gutenberg の MediaUpload コンポーネントのリファレンス 2019年11月18日版を和訳したものです。

MediaUpload

MediaUpload は WordPress のメディアモーダルを開くボタンを描画するコンポーネントです。

設定

これはメディアファイルを扱うコアブロックとの統合を可能にするために必要なプレースホルダコンポーネントです。デフォルトでは何も描画しませんが、components.MediaUpload フィルタでオーバーライドする方法を提供します。

import { addFilter } from '@wordpress/hooks';
import MediaUpload from './media-upload';

const replaceMediaUpload = () => MediaUpload;

addFilter(
	'editor.MediaUpload',
	'core/edit-post/components/media-upload/replace-media-upload',
	replaceMediaUpload
);

投稿の編集ページで wp.media モジュールを使用してこのコンポーネントがどのように実装されているかは edit-post で確認できます。

使い方

現在のユーザがアップロード権限を持つことを確実にするため、MediaUpload コンポーネントは MediaUploadCheck コンポーネントでラップする必要があります。

import { Button } from '@wordpress/components';
import { MediaUpload, MediaUploadCheck } from '@wordpress/block-editor';

const ALLOWED_MEDIA_TYPES = [ 'audio' ];

function MyMediaUploader() {
	return (
		<MediaUploadCheck>
			<MediaUpload
				onSelect={ ( media ) => console.log( 'selected ' + media.length ) }
				allowedTypes={ ALLOWED_MEDIA_TYPES }
				value={ mediaId }
				render={ ( { open } ) => (
					<Button onClick={ open }>
						メディアライブラリを開く
					</Button>
				) }
			/>
		</MediaUploadCheck>
	);
}

プロパティ

以下のプロパティを受け付けます。このセットに含まれないプロパティは Popover コンテントをラップするエレメントに適用されます。

allowedTypes

メディアライブラリにアップロード、またはそこで選択できるメディアの型を示す配列。
各型は汎用的な mime type を含む文字列(例: 'image', 'audio', 'text')、または完全な mime type (例: 'audio/mpeg', 'image/gif') です。
この値を省略するとすべての mime type が許可されます。

型: Array
必須: いいえ
プラットフォーム: Web | Mobile

multiple

複数選択を許可するかどうか。

型: Boolean
必須: いいえ
デフォルト: false
プラットフォーム: Web

value

メディアライブラリを開いたとき、デフォルトで選択されている Media ID (multiple が true のときは複数の media ID)。

型: Number|Array
必須: いいえ
プラットフォーム: Web

onClose

メディアモーダルが閉じられたときのコールバック関数

メディアが選択されたとき、およびユーザがメディアを選ばずにモーダルを閉じたときの両方呼ばれる。

型: Function
必須: いいえ

onSelect

メディア選択後にモーダルが閉じられたときに呼ばれるコールバック関数。

これはメディアを選択しているとき onClose の次に呼ばれる。選択されたメディアは引数に渡される。

型: Function
必須: はい
プラットフォーム: Web | Mobile

title

メディアモーダルに表示するタイトル。

型: String
必須: いいえ
デフォルト: Select or Upload Media
プラットフォーム: Web

modalClass

メディアモーダルのフレームに追加される CSS クラス。

型: String
必須: いいえ
プラットフォーム: Web

addToGallery

true にすると、ユーザが画像を追加できるように、ギャラリーメディアモーダルをメディアライブラリ内で直接開きます。
false にすると、ギャラリーメディアモーダルは編集モードで開き、ユーザが既存の画像などを編集、削除、並び替え、属性の変更ができます。
gallery === true のときのみ適用されます。

型: Boolean
必須: いいえ
デフォルト: false
プラットフォーム: Web

gallery

true にするとコンポーネントはすべてのステートをギャラリー用に設定します。メディアモーダルはデフォルトでギャラリー編集フレームで開きます。ただし、addToGallery フラグを使用しなければ変更はできません。

型: Boolean
必須: いいえ
デフォルト: false
プラットフォーム: Web

render

メディアライブラリを開くボタンを描画するときに呼び出されるコールバック。

型: Function
必須: はい
プラットフォーム: Web | Mobile

コールバックの第一引数は以下のプロパティを含むオブジェクトとなります:

open: コール時にメディアモーダルを開く関数

訳注

Create Guten Block 使用時の初期化例です。

import './style.scss';
import './editor.scss';

const { registerBlockType } = wp.blocks;
const { RichText } = wp.editor;

// MediaUploadコンポーネント
const { MediaUpload, MediaUploadCheck } = wp.editor;
const { Button } = wp.components;
const ALLOWED_MEDIA_TYPES = [ 'image' ];

wp.blocks.registerBlockType( 'gutenberg-examples/myBlock', {
...