7626eb8351
主要变更： 1. 新增 EPImageUploader.swift 和 EPProgressHUD.swift，提供图片批量上传和进度显示功能。 2. 新建 EPMomentAPISwiftHelper.swift，封装动态 API 的 Swift 版本。 3. 更新 EPMomentPublishViewController，集成新上传功能并实现发布成功通知。 4. 创建多个文档，包括实施报告、检查清单和快速使用指南，详细记录功能实现和使用方法。 5. 更新 Bridging Header，确保 Swift 和 Objective-C 代码的互操作性。 此功能旨在提升用户体验，简化动态发布流程，并提供清晰的文档支持。
261 lines
6.3 KiB
Markdown
261 lines
6.3 KiB
Markdown
# EP 模块 Swift 组件快速使用指南
|
||
|
||
## 🎯 核心组件
|
||
|
||
### EPSDKManager - 统一 SDK 管理入口
|
||
|
||
**功能**: QCloud 等第三方 SDK 的统一管理器
|
||
|
||
**使用方式**:
|
||
```objc
|
||
// 在任何 ViewController 中
|
||
#import "YuMi-Swift.h"
|
||
|
||
// 上传图片（自动初始化 QCloud）
|
||
[[EPSDKManager shared] uploadImages:imageArray
|
||
progress:^(NSInteger uploaded, NSInteger total) {
|
||
// 进度回调
|
||
[EPProgressHUD showProgress:uploaded total:total];
|
||
}
|
||
success:^(NSArray<NSDictionary *> *resList) {
|
||
// 上传成功
|
||
// resList: [{resUrl, width, height, format}, ...]
|
||
}
|
||
failure:^(NSString *error) {
|
||
// 上传失败
|
||
NSLog(@"上传失败: %@", error);
|
||
}];
|
||
```
|
||
|
||
### EPProgressHUD - 进度显示组件
|
||
|
||
**使用方式**:
|
||
```objc
|
||
// 显示进度
|
||
[EPProgressHUD showProgress:3 total:9]; // 上传中 3/9
|
||
|
||
// 关闭
|
||
[EPProgressHUD dismiss];
|
||
```
|
||
|
||
### EPMomentAPISwiftHelper - 动态 API 封装
|
||
|
||
**使用方式**:
|
||
```objc
|
||
EPMomentAPISwiftHelper *api = [[EPMomentAPISwiftHelper alloc] init];
|
||
|
||
// 发布动态
|
||
[api publishMomentWithType:@"2" // "0"=文本, "2"=图片
|
||
content:@"动态内容"
|
||
resList:uploadedImages
|
||
completion:^{
|
||
NSLog(@"发布成功");
|
||
}
|
||
failure:^(NSInteger code, NSString *msg) {
|
||
NSLog(@"发布失败: %@", msg);
|
||
}];
|
||
```
|
||
|
||
## 📦 完整发布流程示例
|
||
|
||
```objc
|
||
- (void)publishMomentWithText:(NSString *)text images:(NSArray<UIImage *> *)images {
|
||
EPMomentAPISwiftHelper *api = [[EPMomentAPISwiftHelper alloc] init];
|
||
|
||
if (images.count > 0) {
|
||
// 有图片：先上传图片，后发布
|
||
[[EPSDKManager shared] uploadImages:images
|
||
progress:^(NSInteger uploaded, NSInteger total) {
|
||
[EPProgressHUD showProgress:uploaded total:total];
|
||
}
|
||
success:^(NSArray<NSDictionary *> *resList) {
|
||
[EPProgressHUD dismiss];
|
||
|
||
// 图片上传成功，发布动态
|
||
[api publishMomentWithType:@"2"
|
||
content:text ?: @""
|
||
resList:resList
|
||
completion:^{
|
||
NSLog(@"发布成功");
|
||
// 关闭页面或刷新列表
|
||
}
|
||
failure:^(NSInteger code, NSString *msg) {
|
||
NSLog(@"发布失败: %@", msg);
|
||
}];
|
||
}
|
||
failure:^(NSString *error) {
|
||
[EPProgressHUD dismiss];
|
||
NSLog(@"图片上传失败: %@", error);
|
||
}];
|
||
} else {
|
||
// 纯文本：直接发布
|
||
[api publishMomentWithType:@"0"
|
||
content:text
|
||
resList:@[]
|
||
completion:^{
|
||
NSLog(@"发布成功");
|
||
}
|
||
failure:^(NSInteger code, NSString *msg) {
|
||
NSLog(@"发布失败: %@", msg);
|
||
}];
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🏗️ 架构说明
|
||
|
||
### 组件关系
|
||
|
||
```
|
||
EPSDKManager (统一入口)
|
||
├── uploadImages() ← 对外接口
|
||
├── QCloud 初始化管理
|
||
└── 内部持有 EPImageUploader
|
||
|
||
EPImageUploader (内部类)
|
||
└── 批量上传实现（直接使用 QCloud SDK）
|
||
|
||
EPProgressHUD (工具类)
|
||
└── 进度显示
|
||
|
||
EPMomentAPISwiftHelper (API 封装)
|
||
└── 发布动态 API
|
||
```
|
||
|
||
### 调用者只需要知道
|
||
|
||
- ✅ `EPSDKManager.shared` - SDK 管理
|
||
- ✅ `EPProgressHUD` - 进度显示
|
||
- ✅ `EPMomentAPISwiftHelper` - API 调用
|
||
|
||
### 调用者不需要知道
|
||
|
||
- ❌ EPImageUploader（内部实现）
|
||
- ❌ EPQCloudConfig（内部模型）
|
||
- ❌ QCloud SDK 的细节
|
||
- ❌ Token 的管理
|
||
- ❌ 初始化的时机
|
||
|
||
## 🔧 常见问题
|
||
|
||
### Q1: 首次上传会比较慢吗？
|
||
|
||
**A**: 首次上传需要初始化 QCloud（获取 Token），大约增加 0.5-1 秒。后续上传会复用配置，无等待。
|
||
|
||
### Q2: Token 过期了怎么办？
|
||
|
||
**A**: 自动处理。`EPSDKManager` 会检测 Token 是否过期，过期时自动重新获取，用户无感知。
|
||
|
||
### Q3: 并发上传如何控制？
|
||
|
||
**A**: 内部使用 `DispatchSemaphore(value: 3)` 控制，最多同时上传 3 张图片，避免占用过多网络资源。
|
||
|
||
### Q4: 如何显示上传进度？
|
||
|
||
**A**: 使用 `EPProgressHUD`：
|
||
```objc
|
||
progress:^(NSInteger uploaded, NSInteger total) {
|
||
[EPProgressHUD showProgress:uploaded total:total];
|
||
}
|
||
```
|
||
|
||
### Q5: 上传失败如何处理？
|
||
|
||
**A**: 在 failure 回调中处理：
|
||
```objc
|
||
failure:^(NSString *error) {
|
||
[EPProgressHUD dismiss];
|
||
// 显示错误 Toast 或 Alert
|
||
NSLog(@"上传失败: %@", error);
|
||
}
|
||
```
|
||
|
||
### Q6: 新旧代码会冲突吗？
|
||
|
||
**A**: 不会。新旧代码完全隔离：
|
||
- 新代码（EP 前缀）使用 `EPSDKManager`
|
||
- 旧代码继续使用 `UploadFile`
|
||
- 两者共享 QCloudCOSXML SDK 底层，互不干扰
|
||
|
||
## 📝 代码规范
|
||
|
||
### 导入头文件
|
||
|
||
```objc
|
||
#import "YuMi-Swift.h" // 必须导入，才能使用 Swift 类
|
||
```
|
||
|
||
### 错误处理
|
||
|
||
```objc
|
||
// ✅ 推荐：提供友好的错误提示
|
||
failure:^(NSString *error) {
|
||
[EPProgressHUD dismiss];
|
||
[self showErrorToast:error]; // 显示 Toast
|
||
}
|
||
|
||
// ❌ 不推荐：只打印日志
|
||
failure:^(NSString *error) {
|
||
NSLog(@"%@", error); // 用户看不到
|
||
}
|
||
```
|
||
|
||
### 内存管理
|
||
|
||
```objc
|
||
// ✅ 推荐：使用 weak self
|
||
[[EPSDKManager shared] uploadImages:images
|
||
success:^(NSArray *resList) {
|
||
__weak typeof(self) weakSelf = self;
|
||
[weakSelf doSomething];
|
||
}
|
||
...
|
||
];
|
||
```
|
||
|
||
## 🚀 未来扩展
|
||
|
||
### 计划中的功能
|
||
|
||
```swift
|
||
// 视频上传
|
||
EPSDKManager.shared.uploadVideo(video, ...)
|
||
|
||
// 音频上传
|
||
EPSDKManager.shared.uploadAudio(audio, ...)
|
||
|
||
// IM SDK 初始化
|
||
EPSDKManager.shared.initializeIM()
|
||
|
||
// 推送 SDK 初始化
|
||
EPSDKManager.shared.initializePush()
|
||
```
|
||
|
||
### 扩展方式
|
||
|
||
在 `EPSDKManager.swift` 中添加新方法：
|
||
|
||
```swift
|
||
@objc func uploadVideo(
|
||
_ video: URL,
|
||
progress: @escaping (Double) -> Void,
|
||
success: @escaping ([String: Any]) -> Void,
|
||
failure: @escaping (String) -> Void
|
||
) {
|
||
// 实现视频上传逻辑
|
||
}
|
||
```
|
||
|
||
## 📚 相关文档
|
||
|
||
- [完整实施报告](SWIFT_QCLOUD_REWRITE_FINAL.md)
|
||
- [SDK 管理器说明](SDK_MANAGER_IMPLEMENTATION.md)
|
||
- [检查清单](IMPLEMENTATION_CHECKLIST.md)
|
||
|
||
---
|
||
|
||
**文档版本**: 1.0
|
||
**最后更新**: 2025-10-11
|
||
**维护者**: AI Assistant
|
||
|