React Native实现上传进度条AWS SDK for React Native TransferUtility 进度事件深度解析【免费下载链接】aws-sdk-react-nativeAWS SDK for React Native (developer preview)项目地址: https://gitcode.com/gh_mirrors/aw/aws-sdk-react-nativeAWS SDK for React Native是官方为移动端打造的开发预览版 SDK其TransferUtility模块把 Amazon S3 的上传 / 下载封装成请求对象 事件回调让你用极少的代码就能在 React Native 应用里画出真实的上传进度条。本文将带你吃透 TransferUtility 的进度事件机制——从原生的字节级回调到 JS 层的progressEvent与completionHandlerEvent一步步把进度数据接进你的 UI。一、认识 TransferUtility为什么它天生适合做进度条 普通 REST 式上传很少告诉你传到百分之几了。而 TransferUtility 在设计上就内建了可订阅的进度流每个上传 / 下载任务都有一个唯一的requestID作为追踪这张车票的凭证只要建请求时把subscribe设为true原生层就会持续把已传输字节数、总字节数、完成比例推送到 JS传输结束完成 / 失败 / 取消时再通过独立的完成事件通知你结果。这种创建请求 → 执行传输 → 订阅进度 → 完成回调的拆分天然契合进度条这种流式 UI 需求而不需要你去轮询或解析响应头。 模块核心实现在 TransferUtility/src/AWSS3TransferUtility.js对外导出在 TransferUtility/src/index.js 中安装后即可通过import { AWSS3TransferUtility } from aws-sdk-react-native-transfer-utility直接拿到一个单例。二、进度事件如何流到 JS 层一条隐藏的事件通道 这是本文最关键的机制理解它你就掌握了全部进度逻辑。JS 层构造函数里注册了两条独立的监听通道见 AWSS3TransferUtility.js事件通道触发时机对应 JS 方法平台监听器ProgressEventUtility每次字节进度变化 / 传输报错progressEventiOS:NativeAppEventEmitterAndroid:DeviceEventEmitterCompletionHandlerEvent完成 / 失败 / 取消completionHandlerEvent同上关键点在于这两个方法默认是空函数你需要给它赋值一个函数来接管数据。以 Android 原生层为例AWSRNS3TransferUtility.java 里的subscribe()把原生的TransferListener挂到任务上onProgressChanged(id, bytesCurrent, bytesTotal)→ 组装出completedunitcount、totalunitcount、fractioncompleted并发出ProgressEventUtilityonStateChanged(...)到达终态时 → 发出CompletionHandlerEvent。iOS 侧 AWSRNS3TransferUtility.m 则通过expression.progressBlock拿到NSProgress同样映射成completedunitcount / totalunitcount / fractioncompleted后发往ProgressEventUtility。两端字段完全对齐所以你写的 JS 代码跨平台通用。三、上传进度条四步走从初始化到收进度 下面以上传一张照片到 S3为例串起完整链路可对照官方示例 TransferUtility/example/app/TransferUtility.js。第 1 步初始化凭据与 S3 区域TransferUtility 依赖 Cognito 凭据先初始化凭据再初始化 S3注意两者区域可能不同AWSCognitoCredentials.initWithOptions({ region: CognitoRegion, identity_pool_id: poolId }); AWSS3TransferUtility.initWithOptions({ region: S3Region });第 2 步创建上传请求拿到 requestIDcreateUploadRequest只是登记任务并返回一个requestID此时尚未开始传输AWSS3TransferUtility.createUploadRequest({ path: localFilePath, // 本地文件路径 / URI bucket: BucketName, key: UploadKeyName, contenttype: image/jpeg, // iOS 必填 subscribe: true, // ✅ 关键开启进度订阅 completionhandler: true // ✅ 开启完成回调 }, (error, value) { const requestID value; // 这就是后面追踪进度的车票 });⚠️ 两个开关要分清subscribe控制进度事件completionhandler控制完成事件想让进度条动起来subscribe必须为true。第 3 步触发上传async function startUpload() { try { await AWSS3TransferUtility.upload({ requestid: requestID }); } catch (e) { console.log(upload failed: e); } }第 4 步监听进度事件驱动 UI在组件里给单例的两个方法赋值即可把原生数据接进setStateAWSS3TransferUtility.progressEvent (requestid, completedUnits, totalUnits, fractionCompleted, type) { this.setState({ requestid, type, completedUnits, totalUnits, fractionCompleted }); }; AWSS3TransferUtility.completionHandlerEvent (requestid, error, request) { console.log(requestID:, requestid, error:, error, result:, request); };至此fractionCompleted0.0 → 1.0就是你的进度条百分比来源。四、progressEvent 五个参数逐个拆解 progressEvent(requestid, completedUnits, totalUnits, fractionCompleted, type)的每个参数都对应原生层的一个字段参数含义用途requestid任务的唯一 IDUUID 字符串多任务时区分是哪一条进度completedUnits已完成字节数bytesCurrent显示已传 xx MBtotalUnits总字节数bytesTotal显示共 xx MB、算速度fractionCompleted完成比例 0.0–1.0直接喂给进度条typeupload或download同屏多任务时分流一个值得注意的细节原生层对除零做了保护——当bytesTotal 0时fractionCompleted被固定为0否则才计算bytesCurrent / bytesTotal。所以你的进度条不会因总字节未知而崩溃。五、completionHandlerEvent上传的两种结局 传输进入终态后completionHandlerEvent(requestid, error, request)被调用只有两种结局成功error为空request里带回bucket、key下载场景还含本地location此时原生层会自动清掉这张任务记录失败 / 取消error非空携带error、description、code方便你把原因透传给用户。建议在这里把进度条重置 / 置灰并提示结果形成进度 → 终态的完整闭环。六、暂停 / 恢复 / 取消editEvent 三把钥匙 ⏯️TransferUtility 不止能看进度还能控任务。editEvent(options)通过config指定动作并通过request单个任务或option按类型批量二选一动作 config精确到单任务按类型批量optionpause暂停{config:pause, request: requestID}upload/download/allresume恢复{config:resume, request: requestID}同上cancel取消{config:cancel, request: requestID}同上例如暂停当前上传AWSS3TransferUtility.editEvent({ config: pause, request: requestID })。这套能力对弱网分次传、用户手动中断等场景非常实用。七、上传进度条避坑指南 别漏subscribesubscribe为false时不会有任何ProgressEventUtility事件进度条自然纹丝不动。凭据要先初始化AWSS3TransferUtility.initWithOptions之前必须先跑AWSCognitoCredentials.initWithOptions否则原生层会直接抛 not initialized。区域region别填错Cognito 区域与 S3 桶区域常常不同分别对应两个initWithOptions。requestID要存好暂停 / 恢复 / 取消全靠它多任务时也要用它配合type分流。iOS 上传要带contenttype原生层在上传时会校验该字段。进度是高频事件progressEvent触发非常频繁赋值进去的函数保持轻量例如只做setState避免在回调里做重计算。八、核心 API 速查表 ⚡方法作用关键入参initWithOptions初始化 S3 客户端regioncreateUploadRequest登记上传任务path/bucket/key/contenttype/subscribe/completionhandlercreateDownloadRequest登记下载任务path/bucket/key/subscribe/completionhandlerupload执行上传requestiddownload执行下载requestideditEvent暂停 / 恢复 / 取消configrequest或optionprogressEvent进度回调需赋值requestid, completedUnits, totalUnits, fractionCompleted, typecompletionHandlerEvent完成回调需赋值requestid, error, request小结TransferUtility 把S3 传输抽象成requestID 两条事件流。你只要在建请求时打开subscribe/completionhandler两个开关再给progressEvent赋值即可拿到fractionCompleted就能在 React Native 里轻松画出真实、跨平台的上传进度条配合editEvent还能对任务做暂停、恢复与取消。掌握这套进度事件机制是你用好 AWS SDK for React Native 移动端传输能力的第一步。【免费下载链接】aws-sdk-react-nativeAWS SDK for React Native (developer preview)项目地址: https://gitcode.com/gh_mirrors/aw/aws-sdk-react-native创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考