
前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载导读uppy/box是 Uppy 生态中用于从用户的 Box 云盘账号导入文件的官方插件用户可以在 Uppy 的 Dashboard 中选择 Box 作为远程文件来源登录授权后浏览、勾选并导入文件。本篇文章将围绕该插件的源码实现与其 CHANGELOG 中记录的技术演进讲解插件的工作原理、配套的 Companion 服务端实现、安装配置方式以及历次版本变更背后的工程决策帮助你理解一个远程来源remote source插件在 Uppy 中从能跑到工程化的完整路径。插件是什么从 Box 账号导入文件一个acquirer类型的 UIPlugin从源码看Box.tsx 中的Box类继承自UIPlugin类型为acquirer实现了UnknownProviderPlugin接口。它本质上是一个文件获取器——不负责把文件上传到最终目的地而是负责把用户 Box 云盘里的文件取进 Uppy 的文件队列再交给后续的 tus、XHR、S3 等上传插件完成实际传输。import Uppy from uppy/core import Box from uppy/box const uppy new Uppy() uppy.use(Box, { // Options })这段用法来自插件 README是接入 Box 插件的最基本形态。安装方式同样是标准的 npm$ npm install uppy/boxCompanion 是必需品带宽节省的设计Box 插件的关键约束是必须配合一个 Companion 实例才能工作。README 中明确说明A Companion instance is required for the Box plugin to work. Companion handles authentication with Box, downloads files from Box and uploads them to the destination. This saves the user bandwidth, especially helpful if they are on a mobile connection.也就是说认证、从 Box 下载文件、再上传到目的地这三件事全部由服务端的 Companion 完成浏览器客户端只负责浏览与勾选。这种架构最大的收益是节省用户带宽——文件数据不经过用户的浏览器中转而是由服务器直传。对于移动网络下的用户这个设计尤其有价值。插件自身也在构造函数里把provider: box传给客户端侧的Provider见 Box.tsx并通过getAllowedHosts处理companionAllowedHosts配置建立客户端与 Companion 之间的信任关系。客户端实现插件骨架与可配置项BoxOptions 与默认值BoxOptions由CompanionPluginOptions扩展而来只额外增加了一个可选的localeexport type BoxOptions CompanionPluginOptions { locale?: LocaleStringstypeof locale }完整的可用选项来自 CompanionPluginOptions.ts选项类型说明companionUrlstring必填Companion 实例的 URL所有远程请求都发往这里companionHeadersRecordstring, string附加到每个 Companion 请求上的自定义请求头companionKeysParams{ key: string; credentialsName: string }OAuth 凭证参数设置后客户端会先向 Companion 请求preauthtoken 再发起登录companionCookiesRulesame-origin \| include请求时携带 Cookie 的策略companionAllowedHostsstring \| RegExp \| (string \| RegExp)[]允许连接的主机白名单由getAllowedHosts结合companionUrl计算storageAsyncStore存储认证 token 的异步存储默认使用 tokenStorage.ts即 LocalStorage 的 Async 封装idstring插件实例 id默认BoxlocaleLocaleStrings界面文案的本地化字符串几个值得注意的默认值来自 Box.tsx 的构造函数this.id this.opts.id || Box、this.storage this.opts.storage || tokenStorage。同时supportsRefreshToken: false——Box 插件不支持自动刷新 token这与支持 refresh token 的 Google Drive 等插件形成对比客户端侧 Provider.ts 会依据该标志决定是否在 401 后尝试刷新 token 并重试请求。生命周期与渲染install()中插件创建了ProviderViews传入loadAllFiles: true、virtualList: true两个关键选项并挂载到targetuninstall()则负责tearDown()与unmount()render(state)直接把状态交给this.view.render(state)渲染。因此 Box 插件的文件浏览器界面完全复用 Uppy 核心的 ProviderViews 组件体系。loadAllFiles: true意味着 ProviderView 会在 ProviderView.tsx 中通过do ... while (this.opts.loadAllFiles currentPagePath)循环翻页把当前目录下的所有文件全部加载出来而不是只加载第一页virtualList: true则配合 Browser.tsx 使用虚拟列表渲染保证文件很多时界面依然流畅。这两个选项正是 CHANGELOG 2.1.2 中Load Google Drive / OneDrive lists 5-10x faster always load all files这一改动的客户端侧落点。类型注册与国际化插件通过declare module uppy/core把自己的Box类注册进PluginTypeRegistry见 Box.tsx。这与 CHANGELOG 4.1.0 中Add PluginTypeRegistry and typed getPlugin overload以及Register plugin ids across packages souppy.getPlugin(Dashboard | Webcam)returns the concrete plugin type的改动一一对应——注册之后uppy.getPlugin(Box)无需再传泛型即可返回具体插件类型。国际化方面locale.ts 目前只声明了一个字符串键export default { strings: { pluginNameBox: Box, }, }CHANGELOG 3.2.3 中make locale strings optional的改动让这些字符串变为可选提升了与本地化工具链的兼容性。Companion 服务端Box Provider 的完整能力客户端插件只是遥控器真正干活的是 Companion 端的BoxProvider。其实现位于 packages/uppy/companion/src/server/provider/box/index.ts并在 provider/index.ts 中注册到 providers 集合。OAuth 与文件列表Provider 类声明了static override get oauthProvider() { return box }这意味着 Box 走标准 OAuth 流程。客户端login()会通过 Provider.ts 的loginOAuth打开弹窗、建立 WebSocket 等待认证回调服务端则依据oauthProvider处理/connect/box等路由见 companion.ts。list()方法并行调用两个 Box APIGET users/me获取用户登录名用于在界面上显示当前账号GET folders/{id}/items列出目录内容根目录 id 为0单页limit: 1000通过offset实现翻页并只请求id,modified_at,name,permissions,size,type六个字段以减小响应体积。返回数据经过 adapter.ts 的adaptData归一化为 Uppy 统一格式isFolder、icon、name、mimeType、id、thumbnail、requestPath、modifiedDate、size其中getNextPagePath根据total_count / limit / offset计算下一页游标——这就是客户端loadAllFiles循环翻页的数据基础。下载、缩略图、文件大小与登出其余方法覆盖了远程来源插件的完整操作面download({ id })流式请求files/{id}/content经prepareStream返回{ stream, size }文件数据直接在服务端流转不经浏览器thumbnail({ id })请求files/{id}/thumbnail.jpg固定 256×256处理 Box 缩略图生成延迟时的Retry-After语义返回contentType: image/jpeg服务端转发时需要 Cookie 认证构造函数中设置this.needsCookieAuth truesize({ id })单独请求files/{id}读取size字段兼容字符串与数字两种类型logout()调用 Box 的oauth2/revoke吊销 token。所有方法都包在#withErrorHandling里通过withProviderErrorHandling统一处理 401 鉴权错误与错误信息提取。版本演进CHANGELOG 里的工程化轨迹CHANGELOGpackages/uppy/box/CHANGELOG.md记录了 Box 插件从 v1 到 v5 的完整变迁这些条目恰好勾勒出 Uppy monorepo 近年来的工程化主线2.xESM 化与加载性能2.0.0Uppy v3.0.0Switch to ESM插件全面切换为 ES Modules此前的 1.0.6 已有refactor to ESM的铺垫2.1.2 Load Google Drive / OneDrive lists 5-10x faster always load all files文件列表加载提速 5-10 倍并总是加载全部文件。服务端对应的正是list()中Promise.all并行请求与limit: 1000分页客户端对应loadAllFiles循环2.2.1 fetchPreAuthToken in box too为 Box 补上了 preauth token 获取能力对应客户端 Provider.ts 中的fetchPreAuthToken()——当配置了companionKeysParams时先向/box/preauth/换取预授权 token再拼进 OAuth 链接的uppyPreAuthToken参数。3.xTypeScript 化与打包产物规范化3.0.0-beta.1 / 2.3.0 refactor to TypeScript插件本体重写为 TypeScript3.3.0 Use TypeScript compiler instead of Babel构建工具链从 Babel 切换到tsc当前 package.json 中的build: tsc --build tsconfig.build.json正是这一决策的延续3.1.0 export plugin options导出BoxOptions类型当前 index.ts 中export type { BoxOptions } from ./Box.js即源于此3.2.0 / 3.1.2 / 3.2.3tsconfig 清理、paths移除、locale 字符串变为可选等跨包一致性改动。4.x导出映射与类型注册4.0.0 Export maps for all packages这是对使用方影响最大的破坏性变更。所有包引入 export maps 后CSS 导入路径从uppy[package]/dist/styles.min.css改为uppy[package]/css/styles.min.css未在根导出中声明的内部路径如uppy/core/lib/foo.js不再允许导入对uppy/react/uppy/vue/uppy/svelte而言需要 peer dependency 的组件被拆到子路径导入例如// Before import { Dashboard, StatusBar } from uppy/react; // Now import Dashboard from uppy/react/dashboard; import StatusBar from uppy/react/status-bar;对应 Box 插件当前 package.json 的 export map 为.指向./lib/index.js./package.json指向自身且files字段只发布src、lib、dist、CHANGELOG.md4.0.1 Removed main from package.json, since export maps serve as the contract for the public API彻底删除main字段export map 成为公共 API 的唯一契约4.1.0 PluginTypeRegistry 与类型化getPlugin如前述Box 通过declare module uppy/core注册插件类型让getPlugin(Box)具备完整类型推断。5.0.0运行时依赖收敛5.0.0 的两个变更体现了 Uppy 对依赖治理的持续投入Import Preact fromuppy/coreutilities to guarantee a single version across packagesh与ComponentChild改为从uppy/core/utils/preact导入见 Box.tsx保证整个依赖树只有一个 Preact 版本避免多实例冲突Bump shared runtime dependencies一次性升级 preact、nanoid、lodash、classnames、shallow-equal、pretty-bytes、p-queue、tus-js-client、transloadit/types、transloadit/prettier-bytes、is-mobile、exifr、compressorjs、rxjs、tslib 等共享运行时依赖同时包含uppy/companion中jwt.ts、request.ts的类型修正跟踪types/jsonwebtokenv9 与types/node。当前版本 5.0.0 中插件对uppy/core是 peer dependencyworkspace:^自身依赖收敛到只剩preact一个运行时包依赖面非常精简。从 CHANGELOG 到使用建议综合以上源码与版本记录可以给出几条基于仓库事实的实践建议必须自建或接入 CompanionBox 插件离开 Companion 无法工作。Companion 的部署配置、OAuth 凭证key/secret与 provider 注册是启用 Box 来源的前提服务端实现与配置细节可在 packages/uppy/companion 目录中查阅。按需升级到 4.x如果你正在从老版本升级4.0.0 的 export map 变更是破坏性的——检查所有uppy/*的 CSS 导入路径与子路径导入写法4.0.1 之后不再有main字段兜底。用类型系统约束集成4.1.0 之后uppy.getPlugin(Box)自带完整类型配合 index.ts 导出的BoxOptions在 TypeScript 项目中可以获得完善的 IDE 提示。关注 5.0.0 的依赖收敛若你的项目同时使用多个 Uppy 插件5.0.0 保证 Preact 单一版本的做法能规避多份 Preact 共存导致的运行时异常升级时留意所有uppy/*包版本需与uppy/core6.x对齐。延伸阅读插件入口与选项类型Box.tsx、index.ts客户端与服务端的通信契约Provider.ts、CompanionPluginOptions.ts服务端 Box Provider 与数据适配provider/box/index.ts、provider/box/adapter.ts远程文件浏览与分页逻辑ProviderView.tsx、Browser.tsx版本变更全记录packages/uppy/box/CHANGELOG.md赞分享前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载相关推荐Corsair Box 插件深度指南让 AI Agent 安全地读写企业云盘文件与文件夹Corsair Box 插件深度指南让 AI Agent 安全地读写企业云盘文件与文件夹 导读 本文围绕 Corsair 仓库中 packages/box/R后端API网关使用 WebdriverIO 与 GitHub Actions 搭建零成本跨平台原生移动 App E2E 测试流水线iOS Android使用 WebdriverIO 与 GitHub Actions 搭建零成本跨平台原生移动 App E2E 测试流水线iOS Android 本文以 We前端UI组件后端Flutter Server Box插件贡献第三方插件开发指南Flutter Server Box插件贡献第三方插件开发指南 ? 为什么需要插件系统 在服务器管理领域每个团队都有独特的需求和工作流程。Flutter运维观测指标监控监控大盘运维上一篇基于事件驱动的游戏自动化框架罗技鼠标宏技术深度解析下一篇KKManager基于BepInEx的Illusion游戏模组管理架构深度解析创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考