Files
real-e-party-iOS/QUICK_START_GUIDE.md
edwinQQQ 7626eb8351 feat: 添加动态发布功能及相关文档
主要变更:
1. 新增 EPImageUploader.swift 和 EPProgressHUD.swift,提供图片批量上传和进度显示功能。
2. 新建 EPMomentAPISwiftHelper.swift,封装动态 API 的 Swift 版本。
3. 更新 EPMomentPublishViewController,集成新上传功能并实现发布成功通知。
4. 创建多个文档,包括实施报告、检查清单和快速使用指南,详细记录功能实现和使用方法。
5. 更新 Bridging Header,确保 Swift 和 Objective-C 代码的互操作性。

此功能旨在提升用户体验,简化动态发布流程,并提供清晰的文档支持。
2025-10-11 17:16:30 +08:00

6.3 KiB
Raw Blame History

EP 模块 Swift 组件快速使用指南

🎯 核心组件

EPSDKManager - 统一 SDK 管理入口

功能: QCloud 等第三方 SDK 的统一管理器

使用方式:

// 在任何 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 - 进度显示组件

使用方式:

// 显示进度
[EPProgressHUD showProgress:3 total:9];  // 上传中 3/9

// 关闭
[EPProgressHUD dismiss];

EPMomentAPISwiftHelper - 动态 API 封装

使用方式:

EPMomentAPISwiftHelper *api = [[EPMomentAPISwiftHelper alloc] init];

// 发布动态
[api publishMomentWithType:@"2"  // "0"=文本, "2"=图片
                   content:@"动态内容"
                   resList:uploadedImages
                completion:^{
    NSLog(@"发布成功");
}
failure:^(NSInteger code, NSString *msg) {
    NSLog(@"发布失败: %@", msg);
}];

📦 完整发布流程示例

- (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

progress:^(NSInteger uploaded, NSInteger total) {
    [EPProgressHUD showProgress:uploaded total:total];
}

Q5: 上传失败如何处理?

A: 在 failure 回调中处理:

failure:^(NSString *error) {
    [EPProgressHUD dismiss];
    // 显示错误 Toast 或 Alert
    NSLog(@"上传失败: %@", error);
}

Q6: 新旧代码会冲突吗?

A: 不会。新旧代码完全隔离:

  • 新代码EP 前缀)使用 EPSDKManager
  • 旧代码继续使用 UploadFile
  • 两者共享 QCloudCOSXML SDK 底层,互不干扰

📝 代码规范

导入头文件

#import "YuMi-Swift.h"  // 必须导入,才能使用 Swift 类

错误处理

// ✅ 推荐:提供友好的错误提示
failure:^(NSString *error) {
    [EPProgressHUD dismiss];
    [self showErrorToast:error];  // 显示 Toast
}

// ❌ 不推荐:只打印日志
failure:^(NSString *error) {
    NSLog(@"%@", error);  // 用户看不到
}

内存管理

// ✅ 推荐:使用 weak self
[[EPSDKManager shared] uploadImages:images 
    success:^(NSArray *resList) {
        __weak typeof(self) weakSelf = self;
        [weakSelf doSomething];
    }
    ...
];

🚀 未来扩展

计划中的功能

// 视频上传
EPSDKManager.shared.uploadVideo(video, ...)

// 音频上传
EPSDKManager.shared.uploadAudio(audio, ...)

// IM SDK 初始化
EPSDKManager.shared.initializeIM()

// 推送 SDK 初始化
EPSDKManager.shared.initializePush()

扩展方式

EPSDKManager.swift 中添加新方法:

@objc func uploadVideo(
    _ video: URL,
    progress: @escaping (Double) -> Void,
    success: @escaping ([String: Any]) -> Void,
    failure: @escaping (String) -> Void
) {
    // 实现视频上传逻辑
}

📚 相关文档


文档版本: 1.0
最后更新: 2025-10-11
维护者: AI Assistant