WordPress 的媒体编辑器组件。

安装

npm install @wordpress/media-editor --save

此包假定你的代码将在 ES2015+ 环境中运行。如果你使用的环境对此类语言特性和 API 的支持有限或没有支持，应在代码中包含 @wordpress/babel-preset-default 附带的 polyfill。

用法

import {
    MediaEditorProvider,
    MediaPreview,
    MediaForm,
    type Field,
} from '@wordpress/media-editor';
import { useSelect, useDispatch } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';

function MyMediaEditor( { mediaId } ) {
    const media = useSelect(
        ( select ) =>
            select( coreStore ).getEditedEntityRecord(
                'postType',
                'attachment',
                mediaId
            ),
        [ mediaId ]
    );

    const { editEntityRecord } = useDispatch( coreStore );

    const handleChange = ( updates ) => {
        editEntityRecord( 'postType', 'attachment', mediaId, updates );
    };

    // 使用 @wordpress/dataviews 中的 Field 类型定义字段
    const fields: Field[] = [
        { id: 'title', label: 'Title', type: 'text' },
        { id: 'alt_text', label: 'Alt Text', type: 'text' },
        { id: 'caption', label: 'Caption', type: 'textarea' },
        { id: 'description', label: 'Description', type: 'textarea' },
    ];

    return (
        <MediaEditorProvider
            value={ media }
            onChange={ handleChange }
            settings={ { fields } }
        >
            <div style={ { display: 'flex', gap: '24px' } }>
                <div style={ { flex: 1 } }>
                    <MediaPreview />
                </div>
                <div style={ { width: '360px' } }>
                    <MediaForm />
                </div>
            </div>
        </MediaEditorProvider>
    );
}

API

<MediaEditorProvider>

为子组件提供媒体数据和操作的上下文提供者。

属性：

  • value：（可选）来自 WordPress REST API 的媒体对象
  • onChange：（可选）媒体更新时的回调函数 (updates: Partial<Media>) => void。如果未提供，MediaEditor 可用于只读模式，这适用于仅预览且无需编辑的场景。
  • settings：（可选）配置对象
    • settings.fields：字段定义数组（使用来自 @wordpress/dataviews 的 Field 类型）
  • children：子组件

<MediaPreview>

显示媒体文件的预览。它会自动检测并基于 MIME 类型渲染图像、视频、音频或通用文件。

属性：

接受将传递到预览容器元素上的任意属性（适用于点击处理程序、无障碍属性等）。

<MediaForm>

使用来自 @wordpress/dataviews 的 DataForm 编辑媒体元数据的表单。

属性：

  • form：可选的表单配置（使用来自 @wordpress/dataviews 的 Form 类型）
  • header：显示在表单上方的可选头部内容

TypeScript

此包使用 TypeScript 编写，并导出所有相关类型：

import type {
    Media,
    MediaEditorProviderProps,
    MediaPreviewProps,
    MediaFormProps,
    Field,
    Form,
} from '@wordpress/media-editor';

为此包做贡献

这是 Gutenberg 项目中的一个独立包。该项目以 monorepo 形式组织。它由多个自包含的软件包组成，每个包都有特定用途。此 monorepo 中的包会发布到 npm，并由 WordPress 以及其他软件项目使用。

要了解有关为此包或整个 Gutenberg 做贡献的更多信息，请阅读项目的主要 贡献者指南。