Uppy Transloadit

@uppy/transloadit 插件可用于将文件直接上传到 Transloadit 进行各种处理，如转码视频、调整图片大小、压缩/解压缩等更多功能。

何时使用它？

[!TIP] 不确定哪个上传器最适合您？阅读 “选择适合您的上传器” 。

Transloadit 的优势在于多功能性。通过处理视频、音频、图像、文档等，您只需一个供应商即可满足所有文件处理需求。@uppy/transloadit 插件直接上传至 Transloadit，因此您只需担心创建一个模板。Transloadit 接受文件，根据模板中的指令进行处理，并将结果存储在您选择的存储服务中，如自有的 S3 存储桶。Transloadit 插件在底层使用Tus ，因此您不必牺牲可靠、可恢复的上传。

如果您不想托管自己的 Tus 或 Companion 服务器，（可选）需要文件处理，并将其存储在您喜欢的服务（如 S3 或 GCS）中，应使用 @uppy/transloadit。这一切只需最少的努力。

安装

npm
```
npm install @uppy/transloadit
```
yarn
```
yarn add @uppy/transloadit
```

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, Transloadit } from "https://releases.transloadit.com/uppy/v3.27.3/uppy.min.mjs"
  	new Uppy().use(Transloadit, { /* see options */ })
  </script>

使用

API 的快速概览。

import Uppy from "@uppy/core";
import Dashboard from "@uppy/dashboard";
import Transloadit from "@uppy/transloadit";

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

const uppy = new Uppy()
  .use(Dashboard, { inline: true, target: "body" })
  .use(Transloadit, {
    assemblyOptions: {
      params: {
        auth: { key: "your-transloadit-key" },
        template_id: "your-template-id",
      },
    },
  });
// 可选地监听事件
uppy.on("transloadit:assembly-created", (assembly, fileIDs) => {});
uppy.on("transloadit:upload", (file, assembly) => {});
uppy.on("transloadit:assembly-executing", (assembly) => {});
uppy.on("transloadit:result", (stepName, result, assembly) => {});
uppy.on("transloadit:complete", (assembly) => {});

与 Companion 一起使用

注意

所有 Transloadit 计划均包含托管的 Companion 服务。

您可以将此插件与 Transloadit 托管的 Companion 服务一起使用，以允许您的用户从网络上的第三方来源导入文件。为此，每个提供商插件都必须使用 Transloadit 的 Companion URL 进行配置：

import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from "@uppy/transloadit";
import Dropbox from "@uppy/dropbox";

uppy.use(Dropbox, {
  companionUrl: COMPANION_URL,
  companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});

这已经可以工作了。默认情况下，Transloadit 的 OAuth 应用程序用于验证您的用户。您的用户可能会被要求向 Transloadit 提供其文件的访问权限。由于您的用户可能不知道 Transloadit，这可能会令人困惑或降低信任度。您也可能遇到速率限制，因为 OAuth 应用程序是由使用 Transloadit 的所有人共享的。

要解决这个问题，您可以使用您自己的 OAuth 密钥与 Transloadit 托管的 Companion 服务器，通过使用 Transloadit 模板凭证。创建模板凭证在 Transloadit 网站上。选择“Companion OAuth”作为服务，并输入您想使用的提供商的密钥和秘密。然后，您可以将新凭证的名称传递给该提供商：

import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from "@uppy/transloadit";
import Dropbox from "@uppy/dropbox";

uppy.use(Dropbox, {
  companionUrl: COMPANION_URL,
  companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
  companionKeysParams: {
    key: "YOUR_TRANSLOADIT_API_KEY",
    credentialsName: "my_companion_dropbox_creds",
  },
});

API

选项

`id`

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

`service`

要使用的 Transloadit API URL（ string，默认值：https://api2.transloadit.com ）。

默认情况下，它会根据用户的地理位置尝试高效地路由流量。例如，如果你需要流量保持在特定区域内，可以将其设置为 https://api2-us-east-1.transloadit.com 。

`limit`

限制同时进行的上传数量（ number，默认：20 ）。

设置为 0 表示不限制并发上传，但我们建议使用 5 到 20 之间的值。此选项会传递给内部使用的 @uppy/tus 插件。

`assemblyOptions`

配置组装指令、要发送给组装的字段以及认证（ object | function，默认：null ）。

你可以传递或从函数返回的对象具有以下结构：

{
  params: {
    auth: { key: 'key-from-transloadit' },
    template_id: 'id-from-transloadit',
    steps: {
      // 运行时覆盖模板
    },
    notify_url: 'https://your-domain.com/assembly-status',
  },
  signature: 'generated-signature',
  fields: {
    // 动态或静态字段
  },
}

params 用于通过 Transloadit 进行认证并使用所需的模板。
- auth.key （必需） 是你的认证密钥，可以在账户的 “Credentials” 页面找到。
- template_id （必需） 是唯一标识符，用于使用账户中正确的模板。
- steps （可选） 可以用于在运行时覆盖模板。一个典型的用例可能是根据会话用户 ID 动态更改存储路径。对于大多数用例，我们建议让模板处理动态情况（它们也可以接受 fields 并执行任意 JavaScript），而不是从浏览器传递 steps 。模板编辑器还有额外的验证和上下文。
- notify_url （可选） 是带有组装状态的 JSON 的 pingback。例如，如果你不想通过让用户等待你的模板完成 waitForEncoding 来影响用户体验，但你确实想异步获取更新，你可以提供一个 URL，该 URL 将被 “ping” 以获取组装状态。
signature （可选，但推荐） 是在不受信任的环境中提供进一步信任的加密签名。详情请参考 “Signature Authentication” 。
fields （可选） 可用于发送键/值对，这些可以在模板中动态使用。

示例

作为函数

自定义的 assemblyOptions() 选项应返回一个对象或对象的 Promise。
uppy.use(Transloadit, {
  assemblyOptions(file) {
    return {
      params: {
        auth: { key: "TRANSLOADIT_AUTH_KEY_HERE" },
        template_id: "xyz",
      },
      fields: {
        caption: file.meta.caption,
      },
    };
  },
});
${fields.caption} 变量将在从模板 xyz 生成的组装中可用。你可以用它来动态地给图片加水印，例如。

assemblyOptions() 也可以返回一个 Promise，因此它可以从前端服务器检索已签名的组装参数。例如，假设有一个端点 /transloadit-params ，响应为带有 { params, signature } 属性的 JSON 对象：
uppy.use(Transloadit, {
  async assemblyOptions(file) {
    const res = await fetch("/transloadit-params");
    return response.json();
  },
});
作为对象

如果你不需要动态改变任何东西，也可以直接传递一个对象。
uppy.use(Transloadit, {
  assemblyOptions: {
    params: { auth: { key: "transloadit-key" } },
  },
});
与@uppy/form 一起使用

结合 assemblyOptions() 选项与 Form 插件，将 <form> 中的用户输入传递给 Transloadit 组装：
// 这将把表单字段值添加到每个文件的`.meta`对象中：
uppy.use(Form, { getMetaFromForm: true });
uppy.use(Transloadit, {
  getAssemblyOptions(file) {
    return {
      params: {
        /* ... */
      },
      // 传递你需要的字段：
      fields: {
        message: file.meta.message,
      },
    };
  },
});

进入生产环境时，请确保始终设置 signature 。不使用 Signature Authentication 可能会有安全风险。签名认证是一种安全措施，可以防止外人篡改你的组装指令。在未实现签名认证的情况下，我们建议禁用模板中的 allow_steps_override ，以避免外人代表你传递任何指令和存储目标。

`waitForEncoding`

等待模板完成，而不仅仅是上传，再标记上传为完成（ boolean，默认：false ）。

当设置为 false 时，Assembly 将在后台完成（或出错），但 Uppy 不会知道或关心这一点。您可能需要让 Transloadit 通过 notify_url 向您发送通知，并异步地通知您的用户（例如，通过电子邮件或应用内通知）。
当设置为 true 时，Transloadit 插件会等待 Assembly 完成后再标记文件为已完成。这意味着用户可能需要等待相当长的时间，具体取决于您的 Assembly 指令有多复杂。但是，您可以以较少的努力在客户端接收最终状态和转码结果。

启用此选项后，您可以监听 transloadit:result 和 transloadit:complete 事件。

`waitForMetadata`

仅等待 Transloadit 后端捕获早期错误，而不是整个 Assembly 完成。（ boolean，默认值：false ）

当设置为 true 时，Transloadit 插件会等待 Transloadit 后端从所有上传的文件中提取元数据。这在您希望提供快速用户体验（因此您的用户不必等待所有编码完成）的情况下特别有用，但您确实想让用户了解一些可以提前发现的错误类型，比如文件格式问题。

当启用此选项或 waitForEncoding 时，您可以监听 transloadit:upload 事件。

`importFromUploadURLs`

允许其他插件上传文件，然后将这些文件导入到 Transloadit Assembly 中。（ boolean，默认值：false ）

启用此选项后，Transloadit 将不会配置 Tus 插件向 Transloadit 上传。相反，必须使用单独的上传插件。一旦上传完成，Transloadit 插件会将上传的文件添加到 Assembly 中。

例如，将文件上传到 S3 存储桶然后进行转码：

uppy.use(AwsS3, {
  getUploadParameters(file) {
    return {
      /* 上传参数 */
    };
  },
});
uppy.use(Transloadit, {
  importFromUploadURLs: true,
  assemblyOptions: {
    params: {
      auth: { key: "YOUR_API_KEY" },
      template_id: "YOUR_TEMPLATE_ID",
    },
  },
});

Transloadit 会下载这些文件，并将它们作为 :original 曝光给您的模板，就像直接从 Uppy 客户端上传的一样。

提示

为了使这一功能工作，上传插件必须为上传的文件对象分配一个可公开访问的 uploadURL 属性。Tus 和 S3 插件都会自动这样做，但您必须配置 S3 存储桶以拥有可公开读取的对象。对于 XHRUpload 插件，您可能需要指定一个自定义的 getResponseData 函数。

`alwaysRunAssembly`

即使没有选择任何文件，在调用 uppy.upload() 时也总是创建并运行一个 Assembly。（ boolean，默认值：false ）

这允许创建不接收文件的 Assembly，而是使用像 /s3/import 这样的机器人从其他地方下载文件，例如，用于批量转码作业。

`locale`

export default {
  strings: {
    // 在为上传创建 Assembly 时显示。
    creatingAssembly: "正在准备上传...",
    // 如果无法创建 Assembly，则显示。
    creatingAssemblyFailed: "Transloadit: 无法创建 Assembly",
    // 在上传成功后，但 Assembly 仍在执行时显示。
    // 这只在启用了 `waitForMetadata` 或 `waitForEncoding` 时显示。
    encoding: "编码中...",
  },
};

`clientName`

在创建 Assembly 时，向 Transloadit-Client 头字段追加自定义客户端名称。（ string，默认值：null ）

Transloadit-Client 头默认包含所使用的 SDK 信息，并在 Assembly 状态的 transloadit_client 属性下提供。通过提供一个值，如 homepage-file-uploader，您可以识别创建给定 Assembly 的客户端和 SDK。

已废弃的选项

以下选项已被废弃，推荐使用 assemblyOptions 来满足所有使用场景。您仍然可以使用这些选项，但在下一个主要版本中它们将被移除。

getAssemblyOptions

此函数的行为与向 assemblyOptions 传递函数相同。

params

用于上传的 Assembly 参数。（object，默认值：null）有关更多信息，请参阅 Transloadit 文档中的 Assembly 指令。

auth.key Assembly 参数是必需的。您也可以在此处使用 steps 或 template_id 选项，如 Transloadit 文档所述。
uppy.use(Transloadit, {
  params: {
    auth: { key: "YOUR_TRANSLOADIT_KEY" },
    steps: {
      encode: {
        robot: "/video/encode",
        use: {
          steps: [":original"],
          fields: ["file_input_field2"],
        },
        preset: "iphone",
      },
    },
  },
});
signature

Assembly 参数的可选签名。有关更多信息，请参阅 Transloadit 文档中的签名认证。

如果提供了 signature，则 params 应该是一个 JSON 字符串而不是 JavaScript 对象，因为否则浏览器生成的 JSON 可能与用于生成签名的 JSON 字符串不同。

fields

要随 Assembly 发送的表单字段对象。键是字段名，值是字段值。另请参阅 Transloadit 文档中的指令中的表单字段。
uppy.use(Transloadit, {
  // ...
  fields: {
  	message: '这是一个表单字段',
  },
});
您也可以传递一个字段名数组，以将全局或文件元数据发送到 Assembly。全局元数据通过 Uppy 构造函数中的 meta选项设置，或使用 setMeta方法设置。文件元数据则通过 setFileMeta 方法设置。Form 插件也会根据表单中 <input /> 的值来设置全局元数据，提供了一种方便的方法来使用 HTML 表单字段的值：
uppy.use(Form, { target: "form#upload-form", getMetaFromForm: true });
uppy.use(Transloadit, {
  fields: ["field_name", "other_field_name"],
  params: {
    /* ... */
  },
});
表单字段也可以通过使用自定义逻辑动态计算，通过使用 getAssemblyOptions(file) 选项。

静态导出

`COMPANION_URL`

Transloadit 托管的 Companions 的主要端点。您可以在远程提供商选项中这样使用它：

import Dropbox from "@uppy/dropbox";
import { COMPANION_URL } from "@uppy/transloadit";

uppy.use(Dropbox, {
  companionUrl: COMPANION_URL,
});

当使用 COMPANION_URL 时，您还应该配置 companionAllowedHosts 。

此常量的值是 https://api2.transloadit.com/companion 。如果您正在使用自定义的 service 选项，也应该在您的提供商插件中设置一个自定义主机选项，通过取一个 Transloadit API URL 并附加 /companion ：

uppy.use(Dropbox, {
  companionUrl: "https://api2-us-east-1.transloadit.com/companion",
});

`COMPANION_ALLOWED_HOSTS`

匹配 Transloadit 托管的 Companion 端点的正则表达式模式。该模式用于远程提供商的 companionAllowedHosts 选项，以确保第三方认证消息不能被攻击者的页面伪造，而只能源自 Transloadit 的服务器。

每当您使用 companionUrl: COMPANION_URL 时，请这样使用：

import Dropbox from "@uppy/dropbox";
import { COMPANION_ALLOWED_HOSTS } from "@uppy/transloadit";

uppy.use(Dropbox, {
  companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});

此常量涵盖了 Transloadit 的所有 Companion 服务器，因此如果您使用的是 *.transloadit.com 以外的服务器，则不需要更改。但是，如果未使用位于 *.transloadit.com 的 Transloadit Companion 服务器，请确保将 companionAllowedHosts 选项设置为您实际使用的匹配项。

事件

`transloadit:assembly-created`

当创建 Assembly 时触发。

参数

assembly - 初始 Assembly 状态。
fileIDs - 将上传到此 Assembly 的文件的 ID 。

uppy.on("transloadit:assembly-created", (assembly, fileIDs) => {
  console.group("创建了", assembly.assembly_id, "针对文件:");
  for (const id of fileIDs) {
    console.log(uppy.getFile(id).name);
  }
  console.groupEnd();
});

`transloadit:upload`

当 Transloadit 收到上传时触发。需要设置 waitForMetadata 。

参数

file - 已上传的 Transloadit 文件对象。
assembly - 文件被上传到的 Assembly 的 Assembly 状态。

`transloadit:assembly-executing`

当 Transloadit 收到所有上传并正在执行 Assembly 时触发。

参数

assembly - 正在执行的 Assembly 的 Assembly 状态。

`transloadit:result`

当从 Assembly 收到结果时触发。需要设置 waitForEncoding 。

参数

stepName - 生成此结果的 Assembly 步骤的名称。
result - 来自 Transloadit 的结果对象。这个结果对象还有一个额外的属性，即 localId 。这是 Uppy 本地状态中的文件 ID，可以与 uppy.getFile(id) 一起使用。
assembly - 生成此结果的 Assembly 的 Assembly 状态。

uppy.on("transloadit:result", (stepName, result) => {
  const file = uppy.getFile(result.localId);
  document.body.appendChild(html`
    <div>
      <h2>来自${file.name}</h2>
      <a href=${result.ssl_url}> 查看 </a>
    </div>
  `);
});

`transloadit:complete`

当 Assembly 完成时触发。需要设置 waitForEncoding 。

参数

assembly - 完成的组装的最终组装状态。

uppy.on("transloadit:complete", (assembly) => {
  // 可以用这个做点有趣的事情！
  console.log(assembly.results);
});

常见问题解答

当发生错误时访问组装

如果在组装已经开始后发生错误，你可以在错误对象的 assembly 属性上找到组装状态。

uppy.on("error", (error) => {
  if (error.assembly) {
    console.log(`组装ID ${error.assembly.assembly_id}失败！`);
    console.log(error.assembly);
  }
});

当 Uppy 关闭时的组装行为

当将 @uppy/transloadit 与 @uppy/dashboard 集成时，关闭仪表板会导致在服务器上继续进行组装。当用户手动取消上传时，任何正在运行的组装将被取消。