media utils 包提供了一组用于抽象媒体功能的构件，这些构件在需要处理媒体上传或媒体库的场景中可能很有用，例如扩展或实现 block-editor 的构件。
该包预期由 WordPress 核心使用。在 WordPress 之外的使用场景中，它可能无法按预期工作。

安装

安装模块

npm install @wordpress/media-utils --save

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

API

Attachment

未记录的声明。

MediaUpload

未记录的声明。

privateApis

@wordpress/media-utils 私有 API。

RestAttachment

未记录的声明。

SubSizeData

未记录的声明。

transformAttachment

将附件对象从 REST API 结构转换为区块编辑器和其他使用方所期望的结构。

参数

  • attachment RestAttachment：REST API 附件对象。

uploadMedia

在文件上传按钮被激活时，或通过拖放将文件添加到编辑器时，上传媒体文件。

参数

  • $0 UploadMediaArgs：传递给函数的参数对象。
  • $0.allowedTypes UploadMediaArgs[ 'allowedTypes' ]：包含可上传媒体类型的数组；如果未设置，则允许所有类型。
  • $0.additionalData UploadMediaArgs[ 'additionalData' ]：要包含在请求中的附加数据。
  • $0.filesList UploadMediaArgs[ 'filesList' ]：文件列表。
  • $0.maxUploadFileSize UploadMediaArgs[ 'maxUploadFileSize' ]：站点允许的最大上传大小（以字节为单位）。
  • $0.onError UploadMediaArgs[ 'onError' ]：发生错误时调用的函数。
  • $0.onFileChange UploadMediaArgs[ 'onFileChange' ]：每次文件或文件的临时表示可用时调用的函数。
  • $0.wpAllowedMimeTypes UploadMediaArgs[ 'wpAllowedMimeTypes' ]：允许的 MIME 类型和文件扩展名列表。
  • $0.signal UploadMediaArgs[ 'signal' ]：中止信号。
  • $0.multiple UploadMediaArgs[ 'multiple' ]：是否允许上传多个文件。

validateFileSize

验证文件是否在站点文件上传大小限制范围内。

参数

  • file File：文件对象。
  • maxUploadFileSize number：站点允许的最大上传大小（以字节为单位）。

validateMimeType

验证调用方（例如区块）是否支持此 MIME 类型。

参数

  • file File：文件对象。
  • allowedTypes string[]：允许的 MIME 类型列表。

validateMimeTypeForUser

验证用户是否被允许上传此 MIME 类型。

参数

  • file File：文件对象。
  • wpAllowedMimeTypes Record< string, string > | null：允许的 MIME 类型和文件扩展名列表。

用法

uploadMedia

媒体上传工具是一个允许调用方向 WordPress 媒体库上传文件的函数。
例如，假设 myFiles 是一个文件对象数组，handleFileChange 是用于 onFileChange 的函数，该函数接收一个包含 WordPress 媒体项目描述的对象数组，而 handleFileError 是接收描述可能错误的对象的函数，那么以下代码会将文件上传到 WordPress 媒体库：

wp.mediaUtils.utils.uploadMedia( {
    filesList: myFiles,
    onFileChange: handleFileChange,
    onError: handleFileError,
} );

以下代码会将一个名为 foo.txt、内容为 foo 的文件上传到媒体库，并弹出提示其 URL：

wp.mediaUtils.utils.uploadMedia( {
    filesList: [ new File( [ 'foo' ], 'foo.txt', { type: 'text/plain' } ) ],
    onFileChange: ( [ fileObj ] ) => alert( fileObj.url ),
    onError: console.error,
} );

请注意，onFileChange 首先会使用临时 blob URL 被调用，然后使用最终 URL 被调用；这允许以乐观式 UI 显示结果，就像上传已经完成一样。例如：在上传图片时，即使上传尚未完成，也可以在界面中立即显示该图片。

MediaUpload

媒体上传组件提供了一个 UI 按钮，允许用户打开 WordPress 媒体库。它通常与过滤器 editor.MediaUpload 配合使用。
该组件遵循 https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-upload/README.md 中指定的接口，有关其用法的更多详情可在该处查看。

为此包做贡献

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

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