抠丁客 抠丁客
项目
版本
编辑 (2024/7/10)

Uppy 表单

@uppy/form 插件与现有的 HTML <form> 元素集成，从表单中提取输入数据，并与 Uppy 上传一起发送。然后，它通过一个隐藏的输入字段将上传结果追加回表单。

我应该在何时使用？

当你有一个现有的 HTML <form> 元素，并希望：

  • 将表单输入值附加到文件。 这在你想要将表单（例如，名称、位置、ID）中的元数据与上传的文件关联时非常有用，以便在后端处理。@uppy/form 在上传/处理文件之前提取输入值，将其添加到 Uppy 的元数据状态（uppy.state.meta）以及每个文件的元数据中，并以 [文件输入名称属性] -> [文件输入值] 键/值对的形式追加到上传中。
  • 上传文件并将响应（如文件 URL）放入一个隐藏字段（<input type="hidden" name="uppyResult">）。然后你可以自己 POST 和处理表单。追加的结果是调用 uppy.upload() 或监听 complete 事件返回的结果的序列化版本。
  • 在提交时自动开始文件上传，或者在文件上传后提交表单。 默认情况下这是关闭的。详情请参阅 submitOnSuccess 和 triggerUploadOnSubmit 选项。

注意：

如果你使用的是像 React、Vue 或 Svelte 这样的 UI 框架或库，你可能也会在那里处理表单数据，因此可能不需要这个插件。相反，可以通过调用 uppy.setMeta() 将元数据传递给 Uppy，并监听 uppy.on('complete') 事件以获取上传结果。

安装

  • npm

    npm install @uppy/form

  • yarn

    yarn add @uppy/form

  • CDN

    <!-- 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, Form } from "https://releases.transloadit.com/uppy/v3.27.3/uppy.min.mjs"
    const uppy = new Uppy()
    uppy.use(Form, {
    // Options
    })
</script>

使用

import Uppy from "@uppy/core";
import Form from "@uppy/form";
import DragDrop from "@uppy/drag-drop";

import "@uppy/core/dist/style.min.css";
import "@uppy/drag-drop/dist/style.min.css";

new Uppy().use(Form, {
  target: "#my-form",
});

<form id="my-form" action="/submit" method="get">
  <label for="name">请输入你的名字: </label>
  <input type="text" name="name" required />

  <label for="dob">出生日期: </label>
  <input type="date" name="dob" />

  <input type="submit" value="保存" />
</form>

默认情况下，上述代码会：

  1. 从表单 #my-form 中提取元数据。
  2. 将其与 Uppy 上传一起发送。
  3. 这些字段将被添加到 Uppy 元数据状态（uppy.state.meta）和每个文件的元数据中，并以对象形式（元数据）追加到上传中，键/值对为 [文件输入名称属性] -> [文件输入值]。
  4. 当 Uppy 完成上传/处理后，它会在表单中添加一个 <input type="hidden" name="uppyResult">，其中包含上传结果对象的序列化版本。

注意：

你可以禁用这两个功能，详情请参阅下面的选项。

API

选项

id

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

target

表单元素的 DOM 元素或 CSS 选择器（ string 或 Element，默认：null ）。

这是插件正常工作所必需的。

resultName

结果将被添加的 <input type="hidden"> 的 name 属性（ string，默认：uppyResult ）。

getMetaFromForm

配置是否从表单中提取元数据（ boolean，默认：true ）。

当设置为 true 时，表单插件将在上传开始前从 <form> 元素中提取所有字段。这些字段随后将被添加到 Uppy 元数据状态（uppy.state.meta）和每个文件的元数据中，并以对象形式（元数据）追加到上传中，键/值对为 [文件输入名称属性] -> [文件输入值] 。

addResultToForm

配置是否将上传/编码结果添加回表单中的 <input name="uppyResult" type="hidden"> 元素（ boolean，默认：true ）。

triggerUploadOnSubmit

配置是否在表单提交时开始上传（ boolean，默认：false ）。

当用户提交表单（通过提交按钮、按下 Enter 键或其他方式）时，此选项将阻止表单的常规提交，而是通过Uppy上传文件。然后你可以：

  • 如果需要在所有文件上传完成后实际提交表单，则设置 submitOnSuccess: true 。
  • 监听 uppy.on('complete') 事件，如果文件上传是你所需要的全部，可以执行其他操作。例如，如果表单仅用于文件元数据。

submitOnSuccess

配置是否在 Uppy 完成上传/编码后提交表单（ boolean，默认：false ）。

在本文档中