Gutenberg区块：如何利用`MediaUpload`组件处理媒体文件上传？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

Gutenberg区块：利用`MediaUpload`组件处理媒体文件上传

大家好，今天我们要深入探讨Gutenberg区块开发中一个非常重要的组件：MediaUpload。MediaUpload是WordPress提供的用于处理媒体文件上传的核心组件，它简化了在自定义区块中集成媒体上传功能的过程。我们将从基本概念开始，逐步深入，通过实际代码示例，详细讲解如何有效利用MediaUpload组件。

1. `MediaUpload`组件简介

MediaUpload组件是 @wordpress/block-editor 包的一部分，它的主要作用是提供一个用户友好的界面，让用户可以从本地上传图片、视频或音频文件，或者从WordPress媒体库中选择已有文件。它封装了上传逻辑和媒体库选择界面，开发者无需从头开始构建这些功能，从而大大提高了开发效率。

MediaUpload组件的核心功能包括：

文件上传: 允许用户从本地计算机上传文件。
媒体库选择: 允许用户从WordPress媒体库中选择已存在的媒体文件。
预览: 提供上传或选择的媒体文件的预览功能。
回调函数: 提供上传成功、上传失败、文件选择等事件的回调函数，允许开发者自定义处理这些事件。

2. `MediaUpload`组件的基本用法

首先，我们需要在我们的区块组件中引入MediaUpload组件：

import { MediaUpload } from '@wordpress/block-editor';
import { Button } from '@wordpress/components'; // 引入 Button 组件

接下来，我们将演示一个最基本的MediaUpload组件的用法：

function MyBlockEdit( { attributes, setAttributes } ) {
  const { mediaId, mediaUrl } = attributes;

  const onSelectMedia = ( media ) => {
    setAttributes( {
      mediaId: media.id,
      mediaUrl: media.url,
    } );
  };

  return (
    <div>
      { mediaUrl && (
        <img src={ mediaUrl } alt="Selected Media" style={{maxWidth: '200px'}}/>
      ) }

      <MediaUpload
        onSelect={ onSelectMedia }
        allowedTypes={ [ 'image' ] } // 限制上传类型为图片
        value={ mediaId }
        render={ ( { open } ) => (
          <Button onClick={ open }>
            { mediaUrl ? '更换图片' : '上传图片' }
          </Button>
        ) }
      />
    </div>
  );
}

在这个例子中：

attributes 和 setAttributes 是Gutenberg区块编辑器的标准属性，用于获取和更新区块属性。
mediaId 和 mediaUrl 是我们在 attributes 中定义的两个属性，用于存储媒体文件的ID和URL。
onSelectMedia 是一个回调函数，当用户选择或上传媒体文件时，这个函数会被调用。它接收一个包含媒体文件信息的对象，并更新区块的 mediaId 和 mediaUrl 属性。
allowedTypes 属性限制了允许上传的文件类型，这里我们只允许上传图片。
value 属性用于指定当前选中的媒体文件的ID。
render 属性接收一个包含 open 函数的对象，open 函数用于打开媒体库选择界面。我们使用 Button 组件来触发 open 函数。

重要提示: 区块的 attributes 需要在 block.json 文件中定义，例如：

{
  "attributes": {
    "mediaId": {
      "type": "number",
      "default": 0
    },
    "mediaUrl": {
      "type": "string",
      "default": ""
    }
  }
}

3. `MediaUpload`组件的属性详解

MediaUpload 组件提供了许多属性，可以用来定制其行为。以下是一些常用的属性：

属性名	类型	描述
`onSelect`	function	必需。当用户选择或上传媒体文件时调用的回调函数。接收一个包含媒体文件信息的对象。
`allowedTypes`	array	可选。允许上传的文件类型数组。例如：`[ 'image', 'video' ]`。如果未指定，则允许所有文件类型。
`value`	number	可选。当前选中的媒体文件的ID。
`render`	function	必需。一个渲染函数，接收一个包含 `open` 函数的对象，`open` 函数用于打开媒体库选择界面。可以使用任何React组件来渲染触发媒体库选择界面的元素。
`multiple`	boolean	可选。是否允许选择多个媒体文件。默认为 `false`。
`gallery`	boolean	可选。是否显示媒体库中的图片库选项卡。默认为 `false`。
`title`	string	可选。媒体库选择界面的标题。
`onError`	function	可选。当上传或选择媒体文件时发生错误时调用的回调函数。
`onClose`	function	可选。当媒体库选择界面关闭时调用的回调函数。
`className`	string	可选。添加到 `MediaUpload` 组件的CSS类名。
`label`	string	可选。`MediaUpload` 组件的标签。
`accept`	string	可选。指定允许上传的文件类型的MIME类型。例如：`'image/*'`。
`addToGallery`	boolean	可选。是否将上传的图片添加到媒体库。默认为 `true`。
`notices`	array	可选。一个包含通知消息的数组，用于显示错误或警告信息。
`modalClass`	string	可选。应用于媒体模态框的 CSS 类名。
`description`	string	可选。提供给用户的描述，位于上传按钮下方。
`mediaPreview`	element	可选。自定义媒体预览元素。如果提供，则覆盖默认的预览。
`disableMediaButton`	boolean	可选。如果设置为 true，则禁用“选择媒体”按钮。默认为 `false`。
`mediaPosition`	string	可选。指定媒体选择器在模态框中的位置。可以是 `'top'` 或 `'bottom'`。默认为 `'bottom'`。
`origin`	string	可选。指定请求的来源。可以是 `'core'` 或 `'plugin'`。这会影响媒体库加载的资源。

4. 处理多个媒体文件

如果需要处理多个媒体文件，可以将 multiple 属性设置为 true。同时，需要修改 onSelect 回调函数来处理多个媒体文件：

function MyBlockEdit( { attributes, setAttributes } ) {
  const { mediaIds, mediaUrls } = attributes;

  const onSelectMedia = ( media ) => {
    const ids = media.map( m => m.id );
    const urls = media.map( m => m.url );
    setAttributes( {
      mediaIds: ids,
      mediaUrls: urls,
    } );
  };

  return (
    <div>
      { mediaUrls && mediaUrls.map( (url, index) => (
        <img key={index} src={ url } alt={`Selected Media ${index}`} style={{maxWidth: '100px', marginRight: '5px'}}/>
      ) ) }

      <MediaUpload
        onSelect={ onSelectMedia }
        allowedTypes={ [ 'image' ] }
        multiple={ true }
        value={ mediaIds }
        render={ ( { open } ) => (
          <Button onClick={ open }>
            { mediaUrls && mediaUrls.length > 0 ? '更换图片' : '上传图片' }
          </Button>
        ) }
      />
    </div>
  );
}

相应的 block.json 文件需要更新：

{
  "attributes": {
    "mediaIds": {
      "type": "array",
      "default": []
    },
    "mediaUrls": {
      "type": "array",
      "default": []
    }
  }
}

在这个例子中，mediaIds 和 mediaUrls 现在是数组，分别存储多个媒体文件的ID和URL。onSelectMedia 回调函数使用 map 方法提取每个媒体文件的ID和URL，并将它们存储到相应的数组中。

5. 自定义渲染函数

render 属性允许我们完全自定义触发媒体库选择界面的元素。这使得我们可以创建更复杂的用户界面，例如，使用图标按钮或自定义文本：

function MyBlockEdit( { attributes, setAttributes } ) {
  const { mediaId, mediaUrl } = attributes;

  const onSelectMedia = ( media ) => {
    setAttributes( {
      mediaId: media.id,
      mediaUrl: media.url,
    } );
  };

  return (
    <div>
      { mediaUrl && (
        <img src={ mediaUrl } alt="Selected Media" style={{maxWidth: '200px'}}/>
      ) }

      <MediaUpload
        onSelect={ onSelectMedia }
        allowedTypes={ [ 'image' ] }
        value={ mediaId }
        render={ ( { open } ) => (
          <div style={{ display: 'flex', alignItems: 'center' }}>
            <Button onClick={ open } isSecondary>选择图片</Button>
            <span style={{ marginLeft: '10px' }}>{mediaUrl ? '已选择图片' : '未选择图片'}</span>
          </div>
        ) }
      />
    </div>
  );
}

在这个例子中，我们使用一个 div 元素来包裹 Button 组件和一个 span 元素。div 元素的 style 属性用于创建一个水平对齐的布局。Button 组件的 isSecondary 属性用于设置按钮的样式。span 元素用于显示当前是否已选择图片。

6. 使用 `onError` 处理上传错误

onError 属性允许我们处理上传过程中发生的错误。这对于向用户显示有用的错误消息非常重要：

function MyBlockEdit( { attributes, setAttributes } ) {
  const { mediaId, mediaUrl } = attributes;

  const onSelectMedia = ( media ) => {
    setAttributes( {
      mediaId: media.id,
      mediaUrl: media.url,
    } );
  };

  const onError = ( error ) => {
    console.error( 'Error uploading media:', error );
    // 可以使用 Notices 组件显示错误消息
    // 例如：dispatch( 'core/notices' ).createErrorNotice( '上传图片失败：' + error.message );
    alert( '上传图片失败：' + error.message ); // 简单示例
  };

  return (
    <div>
      { mediaUrl && (
        <img src={ mediaUrl } alt="Selected Media" style={{maxWidth: '200px'}}/>
      ) }

      <MediaUpload
        onSelect={ onSelectMedia }
        allowedTypes={ [ 'image' ] }
        value={ mediaId }
        onError={ onError }
        render={ ( { open } ) => (
          <Button onClick={ open }>
            { mediaUrl ? '更换图片' : '上传图片' }
          </Button>
        ) }
      />
    </div>
  );
}

在这个例子中，onError 回调函数接收一个包含错误信息的对象。我们可以使用 console.error 来记录错误信息，并使用 Notices 组件或 alert 函数向用户显示错误消息。注意: 在实际项目中，建议使用 Notices 组件来显示错误消息，因为它提供了更好的用户体验。你可以使用 wp.data.dispatch( 'core/notices' ).createErrorNotice( message, options ) 来创建错误通知。

7. 使用 `accept` 属性限制文件类型

accept 属性允许我们使用 MIME 类型来限制允许上传的文件类型。例如，只允许上传 JPEG 和 PNG 图片：

<MediaUpload
  onSelect={ onSelectMedia }
  accept="image/jpeg, image/png"
  render={ ( { open } ) => (
    <Button onClick={ open }>
      上传图片
    </Button>
  ) }
/>

8. 使用 `mediaPreview` 进行自定义预览

mediaPreview属性可以用来完全自定义媒体预览的显示方式。这允许你根据你的需求创建更高级的预览效果。例如，你可以使用一个视频播放器来预览视频文件：

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

function MyBlockEdit( { attributes, setAttributes } ) {
    const { mediaId, mediaUrl, mediaType } = attributes;

    const onSelectMedia = ( media ) => {
        setAttributes( {
            mediaId: media.id,
            mediaUrl: media.url,
            mediaType: media.type,
        } );
    };

    const renderMediaPreview = () => {
        if (!mediaUrl) {
            return null;
        }

        if (mediaType === 'image') {
            return <img src={ mediaUrl } alt="Selected Media" style={{maxWidth: '200px'}}/>;
        } else if (mediaType === 'video') {
            return (
                <video width="200" controls>
                    <source src={ mediaUrl } type="video/mp4" />
                    Your browser does not support HTML5 video.
                </video>
            );
        } else {
            return <p>Unsupported media type</p>;
        }
    };

    return (
        <div>
            {renderMediaPreview()}

            <MediaUpload
                onSelect={ onSelectMedia }
                allowedTypes={ [ 'image', 'video' ] }
                value={ mediaId }
                render={ ( { open } ) => (
                    <Button onClick={ open }>
                        { mediaUrl ? '更换媒体' : '上传媒体' }
                    </Button>
                ) }
            />
        </div>
    );
}

对应的 block.json 应当包含 mediaType 属性:

{
  "attributes": {
    "mediaId": {
      "type": "number",
      "default": 0
    },
    "mediaUrl": {
      "type": "string",
      "default": ""
    },
    "mediaType": {
      "type": "string",
      "default": ""
    }
  }
}

在这个例子中，我们添加了一个 mediaType 属性来存储媒体文件的类型。 onSelectMedia 函数更新 mediaType 属性。 renderMediaPreview 函数根据 mediaType 的值来渲染不同的预览元素。

9. 使用 `MediaPlaceholder` 代替 `MediaUpload`

在某些情况下，你可能需要更灵活的布局和控制。 MediaPlaceholder 组件提供了一种更底层的处理媒体上传的方式。它允许你完全控制媒体上传区域的渲染方式，并自定义上传流程。

import { MediaPlaceholder } from '@wordpress/block-editor';
import { Button } from '@wordpress/components';

function MyBlockEdit( { attributes, setAttributes } ) {
    const { mediaId, mediaUrl } = attributes;

    const onSelectMedia = ( media ) => {
        setAttributes( {
            mediaId: media.id,
            mediaUrl: media.url,
        } );
    };

    const onSelectURL = ( url ) => {
      // 从 URL 选择媒体文件的处理逻辑
      // 通常你需要调用 WordPress API 来将 URL 上传到媒体库
      console.log("Selected URL: ", url);
      alert("从 URL 选择媒体的功能需要自行实现。");
    }

    const onRemoveMedia = () => {
        setAttributes( {
            mediaId: 0,
            mediaUrl: '',
        } );
    };

    return (
        <div>
            {mediaUrl ? (
                <div>
                    <img src={ mediaUrl } alt="Selected Media" style={{maxWidth: '200px'}}/>
                    <Button onClick={ onRemoveMedia } isDestructive>移除图片</Button>
                </div>
            ) : (
                <MediaPlaceholder
                    icon="format-image"
                    className="wp-block-my-custom-block"
                    labels={ {
                        title: '选择图片',
                        instructions: '上传或选择媒体库中的图片',
                    } }
                    onSelect={ onSelectMedia }
                    onSelectURL={ onSelectURL }
                    accept="image/*"
                    allowedTypes={ [ 'image' ] }
                    multiple={ false }
                    onError={ ( error ) => console.error( error ) }
                />
            )}
        </div>
    );
}

在这个例子中，我们使用了 MediaPlaceholder 组件来创建一个自定义的媒体上传区域。 labels 属性用于设置标题和说明文字。 onSelectURL 函数用于处理从URL选择媒体文件的情况。需要注意的是，从 URL 选择媒体的功能需要自行实现，通常涉及到调用 WordPress API 将 URL 上传到媒体库。我们还添加了一个 onRemoveMedia 函数，用于移除已选择的媒体文件。

总结

MediaUpload 组件是Gutenberg区块开发中处理媒体文件上传的强大工具。通过掌握其各种属性和用法，我们可以轻松地在自定义区块中集成媒体上传功能，并创建用户友好的界面。掌握了 MediaUpload 组件，我们可以更加灵活的处理各种媒体文件的上传和展示，极大的提升用户体验。

Gutenberg区块：利用MediaUpload组件处理媒体文件上传

1. MediaUpload组件简介

2. MediaUpload组件的基本用法

3. MediaUpload组件的属性详解

4. 处理多个媒体文件

5. 自定义渲染函数

6. 使用 onError 处理上传错误

7. 使用 accept 属性限制文件类型

8. 使用 mediaPreview 进行自定义预览

9. 使用 MediaPlaceholder 代替 MediaUpload

总结

发表回复 取消回复