云策 WordPress 开发者社区

块编辑器开发文档

@wordpress/upload-media

查看官方原文 ↗
💡 云策文档标注

概述

@wordpress/upload-media 是一个实验性的 WordPress 包，提供基于 @wordpress/data 存储的媒体上传队列处理系统，支持客户端文件预处理（如图像压缩）。它主要用于 @wordpress/block-editor，但也可独立使用。

关键要点

  • 该包处于实验阶段，API 可能发生重大变更
  • 核心功能包括添加、取消、重试上传项，以及查询上传状态
  • 通过 dispatch 和 select 与 uploadStore 交互，支持设置更新和文件批量处理
  • 提供 TypeScript 类型定义，建议参考 API 文档或类型声明获取详细信息

代码示例

import { store as uploadStore } from '@wordpress/upload-media';
import { dispatch } from '@wordpress/data';

dispatch( uploadStore ).updateSettings( /* ... */ );
dispatch( uploadStore ).addItems( [
    /* ... */
] );

注意事项

  • 实验性包不适用于生产环境，需谨慎评估稳定性风险
  • 使用 addItems 时需注意参数如 onChange、onSuccess 等回调函数的配置
  • 上传设置和状态管理依赖于 @wordpress/data 存储机制
📄 原文内容
This package is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

This module is a media upload handler with a queue-like system that is implemented using a custom @wordpress/data store.

Such a system is useful for additional client-side processing of media files (e.g. image compression) before uploading them to a server.

It is typically used by @wordpress/block-editor but can also be leveraged outside of it.

Installation

Install the module

npm install @wordpress/upload-media --save

Usage

This is a basic example of how one can interact with the upload data store:

import { store as uploadStore } from '@wordpress/upload-media';
import { dispatch } from '@wordpress/data';

dispatch( uploadStore ).updateSettings( /* ... */ );
dispatch( uploadStore ).addItems( [
    /* ... */
] );

Refer to the API reference below or the TypeScript types for further help.

API Reference

Actions

The following set of dispatching action creators are available on the object returned by wp.data.dispatch( 'core/upload-media' ):

addItems

Adds a new item to the upload queue.

Parameters

  • $0 AddItemsArgs:
  • $0.files AddItemsArgs[ 'files' ]: Files
  • $0.onChange [AddItemsArgs[ 'onChange' ]]: Function called each time a file or a temporary representation of the file is available.
  • $0.onSuccess [AddItemsArgs[ 'onSuccess' ]]: Function called after the file is uploaded.
  • $0.onBatchSuccess [AddItemsArgs[ 'onBatchSuccess' ]]: Function called after a batch of files is uploaded.
  • $0.onError [AddItemsArgs[ 'onError' ]]: Function called when an error happens.
  • $0.additionalData [AddItemsArgs[ 'additionalData' ]]: Additional data to include in the request.
  • $0.allowedTypes [AddItemsArgs[ 'allowedTypes' ]]: Array with the types of media that can be uploaded, if unset all types are allowed.

cancelItem

Cancels an item in the queue based on an error.

Parameters

  • id QueueItemId: Item ID.
  • error Error: Error instance.
  • silent Whether to cancel the item silently, without invoking its onError callback.

retryItem

Retries a failed item in the queue.

Parameters

  • id QueueItemId: Item ID.

Selectors

The following selectors are available on the object returned by wp.data.select( 'core/upload-media' ):

getItems

Returns all items currently being uploaded.

Parameters

  • state State: Upload state.

Returns

  • QueueItem[]: Queue items.

getSettings

Returns the media upload settings.

Parameters

  • state State: Upload state.

Returns

  • Settings: Settings

isUploading

Determines whether any upload is currently in progress.

Parameters

  • state State: Upload state.

Returns

  • boolean: Whether any upload is currently in progress.

isUploadingById

Determines whether an upload is currently in progress given an attachment ID.

Parameters

  • state State: Upload state.
  • attachmentId number: Attachment ID.

Returns

  • boolean: Whether upload is currently in progress for the given attachment.

isUploadingByUrl

Determines whether an upload is currently in progress given an attachment URL.

Parameters

  • state State: Upload state.
  • url string: Attachment URL.

Returns

  • boolean: Whether upload is currently in progress for the given attachment.