Uppy 仪表板

全方位的仪表板 —— 强大、响应式且可插拔。启动您的上传体验，并逐步添加更多功能。从远程源添加文件、编辑图片、生成缩略图等。

查看集成部分以获取完整插件列表，这些插件您可以集成。

尝试带有所有插件的在线示例或在 StackBlitz 中体验它。

何时使用此功能？

您可能需要使用仪表板的原因有很多，但其中一些可能是：

当您需要一个经过实战检验即插即用的上传用户界面来节省时间时。
当您的用户需要从远程源，如 [Google Drive]、[Dropbox] 等，添加文件时。
当您需要按文件从用户那里收集元数据时。
当您的用户希望使用网络摄像头拍照或捕捉屏幕时。

安装

npm
```
npm install @uppy/core @uppy/dashboard
```
yarn
```
yarn add @uppy/core @uppy/dashboard
```

CDN

警告

此捆绑包包含了大部分Uppy插件，因此不建议在生产环境中使用此方法，因为尽管您可能仅仅用到其中一小部分插件，但用户却需要下载全部插件。
然而，这对于加速您的开发环境非常有帮助，所以在起步阶段，请放心使用它来提升开发速度。

<!-- 1. Add CSS to `<head>` -->
<link href="https://releases.transloadit.com/uppy/v3.27.3/uppy.min.css" rel="stylesheet">

<!-- 2. Initialize -->
<div id="uppy"></div>

<script type="module">
    import { Uppy, Dashboard, ScreenCapture } from "https://releases.transloadit.com/uppy/v3.27.3/uppy.min.mjs"
    const uppy = new Uppy()
    uppy.use(Dashboard, { inline: true, target: 'body' })
    uppy.use(ScreenCapture)
</script>

使用

import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';

import '@uppy/core/dist/style.min.css';
import '@uppy/dashboard/dist/style.min.css';

new Uppy().use(Dashboard, { inline: true, target: '#uppy-dashboard' });

注意

@uppy/dashboard 插件包含了仪表板本身的CSS以及仪表板所使用的各种插件的CSS，例如( @uppy/status-bar 和 @uppy/informer )。如果您还直接使用了 @uppy/status-bar 或 @uppy/informer 插件，则不应包含它们的 CSS 文件，而应该只使用来自 @uppy/dashboard 插件的 CSS 。

注意

提供程序插件（如 Google Drive 和 Instagram ）的样式也与仪表板样式捆绑在一起。其他插件，如 @uppy/url 和 @uppy/webcam 的样式并未包含在内。如果您正在使用这些插件，请参阅它们的文档并确保也包含它们的样式。

API

选项

`id`

此插件的唯一标识符（ string ，默认值：'Dashboard' ）。

由仪表板添加的插件会基于此ID获得唯一的ID，如 'Dashboard:StatusBar' 和 'Dashboard:Informer' 。

`target`

仪表板渲染的位置（ string 或 Element ，默认值：'body' ）。

您可以传递一个元素、类名或ID作为字符串。仪表板默认隐藏，并且仅在点击 trigger 时作为模态框打开。

`inline`

以模态或内联方式渲染仪表板（ boolean，默认值：false ）。

当 false 时，仪表板通过点击 trigger 打开。如果 inline: true ，仪表板将被渲染到 target 并适应其中。

`trigger`

用于触发打开仪表板模态框的按钮的CSS选择器（ string ，默认值：null ）。

可以使用多个按钮或链接，只要它们使用相同的选择器（例如 .select-file-button ）。

`width`

仪表板的宽度（像素），当 inline: true 时使用（ number ，默认值：750 ）。

`height`

仪表板的高度（像素），当 inline: true 时使用（ number ，默认值：550 ）。

`waitForThumbnailsBeforeUpload`

是否在开始上传之前等待 @uppy/thumbnail-generator 的所有缩略图准备就绪（ boolean，默认 false ）。

如果设置为 true，缩略图生成器将调用Uppy的内部处理阶段，显示 “正在生成缩略图...” 消息，并等待 thumbnail:all-generated 事件，然后继续到上传阶段。

这是有用的，因为缩略图生成器也会向图像添加EXIF数据，如果我们等待它完成处理，在上传后这些数据将在服务器上可用。

`showLinkToFileUploadResult`

将仪表板中的文件图标和缩略图变为上传文件的链接（ boolean，默认值：false ）。

请确保从您的服务器返回 url 键（或通过 responseUrlFieldName 设置的键）。

`showProgressDetails`

在状态栏中显示或隐藏进度详细信息（ boolean ，默认值：false ）。

默认情况下，状态栏中的进度以百分比形式显示。如果您还想显示剩余上传大小和时间，请将此设置为 true 。

showProgressDetails: false: 正在上传: 45%

showProgressDetails: true: 正在上传: 45%・43 MB / 101 MB・剩余 8 秒

`hideUploadButton`

显示或隐藏上传按钮（ boolean，默认值：false ）。

当您在其他地方提供了自定义上传按钮，并使用了 uppy.upload() API 时，可以使用此选项。

`hideRetryButton`

隐藏状态栏和每个单独文件上的重试按钮（ boolean，默认值：false ）。

当您在别处提供了自定义重试按钮，并且正在使用 uppy.retryAll() 或 uppy.retryUpload(fileID) API 时，可以使用此选项。

`hidePauseResumeButton`

隐藏暂停/恢复按钮（对于可恢复的上传，例如通过 tus ），在状态栏和每个单独的文件上（ boolean，默认值：false ）。

如果您在其他地方提供了自定义取消或暂停/恢复按钮，并且正在使用 uppy.pauseResume(fileID) 或 uppy.removeFile(fileID) API 时，可以使用此选项。

`hideCancelButton`

隐藏状态栏和每个单独文件上的取消按钮（ boolean，默认值：false ）。

当您在其他地方提供了自定义取消按钮，并且正在使用 uppy.cancelAll() API 时，可以使用此选项。

`hideProgressAfterFinish`

上传完成后隐藏状态栏（ boolean，默认值：false ）。

`doneButtonHandler`

此选项传递给状态栏，将在上传/编码完成时渲染一个 “完成” 按钮，替代暂停/恢复/取消按钮。该 “完成” 按钮的行为由这个处理函数定义，比如关闭文件选择模态框或清除上传状态。

这是 Dashboard 默认设置的：

const doneButtonHandler = () => {
  this.uppy.cancelAll();
  this.requestCloseModal();
};

设为 null 以禁用 “完成” 按钮。

`showSelectedFiles`

显示已添加文件的列表，包括预览和文件信息（ boolean，默认值：true ）。

如果您在自己的应用 UI 中显示了选定的文件，并希望 Uppy Dashboard 仅作为选择器，则可以使用此选项隐藏列表。

另见 disableStatusBar 选项，它可以隐藏进度和上传按钮。

`showRemoveButtonAfterComplete`

成功上传后，在每个文件上显示移除按钮（ boolean，默认值：false ）。

启用此选项仅在 Dashboard UI 中显示移除 X 按钮，但要实际发送请求，您应该监听 file-removed 事件并在那里添加逻辑。

示例：

uppy.on("file-removed", (file, reason) => {
  if (reason === "removed-by-user") {
    sendDeleteRequestForFile(file);
  }
});

实现示例，请参阅 #2301 。

`singleFileFullScreen`

当仅选择一个文件时，其预览和元信息将居中并放大（ boolean，默认值：true ）。

通常，Uppy 用于照片/个人形象上传，或者可能是一个单一的文档。这时占据 Dashboard 所有可用界面是有意义的，给予这个单一文件足够的展示空间。当 Dashboard 高度较小时，此功能会自动禁用，因为没有足够的空间。

`note`

要放置在 Dashboard UI 中的文本字符串（ string，默认值：null ）。

这可以用来解释所设置的任何【限制】(restrictions)。例如：'仅限图片和视频，2-3个文件，最多1 MB'。

`metaFields`

为用户提供填写的文本或自定义输入字段（ Array<Object> 或 Function ，默认值：null ）。

这将在用户点击文件上的 “编辑” 按钮时显示。

注意

元数据仅在用户输入时才会设置在文件对象上。如果用户不编辑文件的元数据，它不会具有默认值；相反，一切都会是 undefined 。如果您想在用户行为之外为某个元字段设置特定值，请在 Uppy 构造函数选项中设置 meta 。

每个对象可以包含：

id。元字段的名称。这也会在 CSS/HTML 中作为 id 属性的一部分，因此最好避免使用像句点、分号等字符。
name。界面上显示的标签。
placeholder。当字段中未设置值时显示的文本。（使用自定义渲染函数时不需要）
render: ({value, onChange, required, form}, h) => void（可选）。用于渲染自定义表单元素的函数。
- value 是当前元字段的值
- onChange: (newVal) => void 是一个保存新值的函数，h 是来自 Preact 的 createElement 函数。
- required 是一个布尔值，表示当字段 id 位于 restrictedMetaFields 限制中时为真。
- form 是关联的 <form> 元素的 id 。
- h 在直接使用 JavaScript 而非 JSX 编写 Uppy 时非常有用。

示例：配置为 Array 形式的元数据字段

uppy.use(Dashboard, {
	trigger: '#pick-files',
	metaFields: [
		{ id: 'name', name: 'Name', placeholder: 'file name' },
		{ id: 'license', name: 'License', placeholder: 'specify license' },
		{
			id: 'caption',
			name: 'Caption',
			placeholder: 'describe what the image is about',
		},
		{
			id: 'public',
			name: 'Public',
			render({ value, onChange, required, form }, h) {
				return h('input', {
					type: 'checkbox',
					required,
					form,
					onChange: (ev) => onChange(ev.target.checked ? 'on' : ''),
					defaultChecked: value === 'on',
				});
			},
		},
	],
});

示例：基于文件类型动态生成元数据字段的函数

uppy.use(Dashboard, {
	trigger: '#pick-files',
	metaFields: (file) => {
		const fields = [{ id: 'name', name: 'File name' }];
		if (file.type.startsWith('image/')) {
			fields.push({ id: 'location', name: 'Photo Location' });
			fields.push({ id: 'alt', name: 'Alt text' });
			fields.push({
				id: 'public',
				name: 'Public',
				render: ({ value, onChange, required, form }, h) => {
					return h('input', {
						type: 'checkbox',
						onChange: (ev) => onChange(ev.target.checked ? 'on' : ''),
						defaultChecked: value === 'on',
						required,
						form,
					});
				},
			});
		}
		return fields;
	},
});

`closeModalOnClickOutside`

设置为 true 以便在用户点击外部时自动关闭模态框（ boolean，默认：false ）。

`closeAfterFinish`

设置为 true 以在所有当前上传完成后自动关闭模态框（ boolean，默认：false ）。

使用此选项，仅当上传完成且成功时，模态框才会自动关闭。如果有上传失败，模态框保持打开状态，以便用户可以重试失败的上传或取消当前批次并上传完全不同的文件集。

提示

您可以将此与 Uppy 核心中的 allowMultipleUploads: false 选项结合使用，为上传单个（一批）文件创建流畅的体验。
这是推荐的做法。对于多个上传批次，自动关闭的行为可能会让用户感到相当困惑。

`disablePageScrollWhenModalOpen`

在模态框打开时禁用页面滚动（ boolean，默认：true ）。

默认情况下，当 Dashboard 模态框打开时，页面滚动会禁用，因此当您在 Uppy 中滚动文件列表时，网站背景保持静止。设为 false 可覆盖此行为并保持页面滚动不变。

`animateOpenClose`

在模态对话框打开或关闭时添加动画，以提供更令人满意的用户体验（ boolean，默认：true ）。

`fileManagerSelectionType`

配置通过文件管理器选择窗口浏览文件系统时允许的选择类型（ string，默认：'files' ）。

可以是 'files'、'folders' 或 'both'。选择整个文件夹进行上传可能不被所有浏览器支持。

`proudlyDisplayPoweredByUppy`

显示带有链接的 Uppy 徽标（ boolean，默认：true ）。

Uppy 是由 Transloadit 团队免费向世界提供的。作为回报，我们请求您考虑保留 Uppy 的微小徽标在底部，以便更多人可以发现和使用 Uppy。

`disableStatusBar`

完全禁用状态栏（ boolean，默认：false ）。

Dashboard 集成了 StatusBar 插件，用于显示上传进度和暂停/恢复/取消按钮。如果您愿意，可以禁用 StatusBar 以提供自己的自定义解决方案。

`disableInformer`

完全禁用通知器（显示为 toast 形式的通知）（ boolean，默认：false ）。

Dashboard 集成了 Informer 插件，用于在浏览器离线时通知，或者如果 Webcam 正在拍照时提示微笑。如果您愿意，您可以禁用 Informer 并/或提供自己的自定义解决方案。

`disableThumbnailGenerator`

完全禁用缩略图生成器（ boolean，默认：false ）。

Dashboard 集成了 ThumbnailGenerator 插件，该插件为预览目的向图像添加了小尺寸的缩略图。如果您愿意，您可以禁用 ThumbnailGenerator 或提供自己的自定义解决方案。

`locale`

module.exports = {
	strings: {
		// 当`inline: false`时，用作关闭模态框的按钮的屏幕阅读器标签。
		closeModal: '关闭模态框',
		// 用作显示“添加更多文件”屏幕的加号（+）按钮的屏幕阅读器标签。
		addMoreFiles: '添加更多文件',
		addingMoreFiles: '正在添加更多文件',
		// 用作导入面板的标题，例如“从Google Drive导入”。
		importFrom: '从 %{name} 导入',
		// 当`inline: false`时，用作仪表板模态框的屏幕阅读器标签。
		dashboardWindowTitle: 'Uppy仪表板窗口（按Esc键关闭）',
		// 当`inline: true`时，用作仪表板区域的屏幕阅读器标签。
		dashboardTitle: 'Uppy仪表板',
		// 当链接复制到剪贴板时，在通知栏中显示。
		copyLinkToClipboardSuccess: '链接已复制到剪贴板。',
		// 当链接无法自动复制时——用户需要从下面的输入元素中选择文本。
		copyLinkToClipboardFallback: '请复制下方的链接',
		// 用作复制文件链接按钮的悬停标题和屏幕阅读器标签。
		copyLink: '复制链接',
		back: '返回',
		// 用作删除文件按钮的屏幕阅读器标签。
		removeFile: '移除文件',
		// 用作打开文件元数据编辑面板的按钮的屏幕阅读器标签。
		editFile: '编辑文件',
		// 作为元数据编辑面板标题显示。呈现为“编辑 image.png”。
		editing: '正在编辑 %{file}',
		// 用作保存元数据编辑并返回文件列表视图的按钮的屏幕阅读器标签。
		finishEditingFile: '完成文件编辑',
		saveChanges: '保存更改',
		// 用作打开系统文件选择对话框的标签按钮的标签。
		myDevice: '我的设备',
		dropHint: '将您的文件拖到这里',
		// 当文件上传完成时，用作文件进度指示器的悬停文本和屏幕阅读器标签。
		uploadComplete: '上传完成',
		uploadPaused: '上传已暂停',
		// 用作恢复暂停上传的按钮的悬停文本和屏幕阅读器标签。
		resumeUpload: '继续上传',
		// 用作暂停上传的按钮的悬停文本和屏幕阅读器标签。
		pauseUpload: '暂停上传',
		// 用作重试失败上传的按钮的悬停文本和屏幕阅读器标签。
		retryUpload: '重试上传',
		// 用作取消上传的按钮的悬停文本和屏幕阅读器标签。
		cancelUpload: '取消上传',
		// 在标题中显示当前选定的文件数量
		xFilesSelected: {
			0: '%{smart_count} 个文件已选择',
			1: '%{smart_count} 个文件已选择',
		},
		uploadingXFiles: {
			0: '正在上传 %{smart_count} 个文件',
			1: '正在上传 %{smart_count} 个文件',
		},
		processingXFiles: {
			0: '正在处理 %{smart_count} 个文件',
			1: '正在处理 %{smart_count} 个文件',
		},
		// 位于Dashboard底部的“由Uppy提供支持”的链接。
		poweredBy: '由 %{uppy} 提供支持',
		addMore: '添加更多',
		editFileWithFilename: '编辑文件 %{file}',
		save: '保存',
		cancel: '取消',
		dropPasteFiles: '在此处拖放文件或 %{browseFiles}',
		dropPasteFolders: '在此处拖放文件夹或 %{browseFolders}',
		dropPasteBoth: '在此处拖放文件、文件夹或 %{browseFiles}、%{browseFolders}',
		dropPasteImportFiles: '在此处拖放文件，或 %{browseFiles} 或从以下导入:',
		dropPasteImportFolders: '在此处拖放文件夹，或 %{browseFolders} 或从以下导入:',
		dropPasteImportBoth:
			'在此处拖放文件、文件夹，或 %{browseFiles}、%{browseFolders}，或从以下导入:',
		importFiles: '从以下导入文件:',
		browseFiles: '浏览文件',
		browseFolders: '浏览文件夹',
		recoveredXFiles: {
			0: '我们未能完全恢复 1 个文件，请重新选择并继续上传。',
			1: '我们未能完全恢复 %{smart_count} 个文件，请重新选择它们并继续上传。',
		},
		recoveredAllFiles: '我们已恢复所有文件，现在您可以继续上传了。',
		sessionRestored: '会话已恢复',
		reSelect: '重新选择',
		missingRequiredMetaFields: {
			0: '缺少必需的元数据字段：%{fields}。',
			1: '缺少必需的元数据字段：%{fields}。',
		},
	},
};

`theme`

Dashboard 的主题（亮色或暗色）（ string，默认：'light' ）。

Uppy Dashboard 支持 “深色模式” 。你可以在 Uppy 的 Dashboard 示例页面上尝试它。

它支持以下值：

light — 默认值
dark
auto — 尊重用户的系统设置并自动切换

`autoOpen`

用户刚拖放/选择文件时自动打开文件编辑器。如果添加了一个文件，则为该文件打开编辑器；如果添加了 10 个文件，则仅对第一个文件打开编辑器。

此选项支持以下值：

null - 默认值
"metaEditor" - 如果启用了元数据字段，则打开元数据字段编辑器。
"imageEditor" - 如果启用了插件，则打开 @uppy/image-editor 。

`disabled`

启用此选项会使 Dashboard 变灰且不可交互（ boolean，默认：false ）。

用户将无法点击按钮或拖放文件。当你需要根据应用程序中的条件有条件地启用/禁用文件上传或操作时非常有用。可以在初始化时设置或通过 API 设置：

const dashboard = uppy.getPlugin("Dashboard");
dashboard.setOptions({ disabled: true });

userNameInput.addEventListener("change", () => {
  dashboard.setOptions({ disabled: false });
});

`disableLocalFiles`

禁用本地文件上传（ boolean，默认：false ）。

启用此选项将禁用拖放功能，隐藏 “浏览” 和 “我的设备” 按钮，只允许从插件（如 Webcam、屏幕捕获、Google Drive、Instagram）上传。

`onDragOver(event)`

ondragover 事件处理器的回调函数。

`onDrop(event)`

ondrop 事件处理器的回调函数。

`onDragLeave(event)`

ondragleave 事件处理器的回调函数。

方法

提示

Dashboard 还具有在 UIPlugin 和 BasePlugin 中描述的方法。

`openModal()`

显示 Dashboard 模态框。使用如下：

uppy.getPlugin("Dashboard").openModal();

`closeModal()`

隐藏 Dashboard 模态框。使用如下：

uppy.getPlugin("Dashboard").closeModal();

`isModalOpen()`

如果 Dashboard 模态框是打开的，则返回 true，否则返回 false 。

const dashboard = uppy.getPlugin("Dashboard");
if (dashboard.isModalOpen()) {
  dashboard.closeModal();
}

事件

提示

你可以使用 on 和 once 来监听这些事件。

`dashboard:modal-open`

当 Dashboard 模态框打开时触发。

uppy.on("dashboard:modal-open", () => {
  console.log("模态框已打开");
});

`dashboard:modal-closed`

当 Dashboard 模态框关闭时触发。

`dashboard:file-edit-start`

参数：

file — 代表被打开进行编辑的文件的 [文件对象] 。

当用户点击 Dashboard 中文件旁边的“编辑”图标时触发。随后，FileCard 面板将打开，可编辑文件元数据。

`dashboard:file-edit-complete`

参数：

file — 代表被编辑的文件的 [文件对象] 。

当用户完成文件元数据编辑时触发。

集成

这些是专门为 Dashboard 设计的插件。这并不是所有 Uppy 插件的列表。

数据源

@uppy/audio — 录制音频。
@uppy/box — 从 Box 导入文件。
@uppy/dropbox — 从 Dropbox 导入。
@uppy/facebook — 从 Facebook 导入。
@uppy/google-drive — 从 Google Drive 导入。
@uppy/google-photos — 从 Google Photos 导入。
@uppy/instagram — 从 Instagram 导入。
@uppy/onedrive — 从 OneDrive 导入。
@uppy/screen-capture — 记录你的屏幕，可选包括麦克风。
@uppy/unsplash — 从 Unsplash 导入文件。
@uppy/url — 从任何 URL 导入文件。
@uppy/webcam — 使用网络摄像头录制或拍照。
@uppy/zoom — 从 Zoom 导入文件。

UI

@uppy/image-editor — 允许用户对添加到 Uppy 中的图片进行裁剪、旋转、缩放和翻转。
@uppy/informer — 显示通知。
@uppy/status-bar — 高级上传进度状态栏。
@uppy/thumbnail-generator — 为待上传的图片生成预览缩略图。

框架

@uppy/angular — 为 Angular 提供的 Dashboard 组件。
@uppy/react — 为 React 提供的 Dashboard 组件。
@uppy/svelte — 为 Svelte 提供的 Dashboard 组件。
@uppy/vue — 为 Vue 提供的 Dashboard 组件。

Uppy 仪表板

何时使用此功能？

安装

使用

API

选项

id

target

inline

trigger

width

height

waitForThumbnailsBeforeUpload

showLinkToFileUploadResult

showProgressDetails

hideUploadButton

hideRetryButton

hidePauseResumeButton

hideCancelButton

hideProgressAfterFinish

doneButtonHandler

showSelectedFiles

showRemoveButtonAfterComplete

singleFileFullScreen

note

metaFields

closeModalOnClickOutside

closeAfterFinish

disablePageScrollWhenModalOpen

animateOpenClose

fileManagerSelectionType

proudlyDisplayPoweredByUppy

disableStatusBar

disableInformer

disableThumbnailGenerator

locale

theme

autoOpen

disabled

disableLocalFiles

onDragOver(event)

onDrop(event)

onDragLeave(event)

方法

openModal()

closeModal()

isModalOpen()

事件

dashboard:modal-open

dashboard:modal-closed

dashboard:file-edit-start

dashboard:file-edit-complete

集成

数据源

UI

框架

在本文档中