发送图片、视频和文件

XHIM 会处理分片上传、断点续传、校验、缓存和失败重试。应用只需要选择文件、调用当前 平台的媒体发送方法，并根据进度更新页面。

基本流程

用户选择文件
  -> App 检查类型和大小
  -> 调用图片、视频、语音或文件发送方法
  -> 显示上传进度
  -> SDK 上传并发送消息
  -> 成功后使用消息中的媒体信息展示或下载

具体方法名、参数和示例请在 SDK API Reference 选择当前 平台查看。

发送前检查

• 先申请相册、相机、麦克风或文件访问权限；
• 给用户显示文件名、大小和取消入口；
• 根据业务规则限制文件类型与大小；
• 不要把本地文件路径写进消息正文或业务日志；
• 不要在页面中保存临时上传地址或授权信息。

显示上传进度

开始发送后，页面保存 SDK 返回的媒体任务 ID。收到媒体任务变化事件时，重新查询该任务， 再更新进度、失败原因和重试按钮。

收到 media task changed
  -> 用 task ID 查询最新状态
  -> 更新进度条
  -> ready：显示已发送
  -> failed：显示重试
  -> canceled：移除进度状态

事件只是“状态变了”的通知，不要只靠事件内容累计百分比。

取消与重试

• 用户取消时调用 SDK 的媒体任务取消方法；
• 断网、超时或临时服务错误由 SDK 按策略重试；
• App 重启后重新查询未完成任务，不要重新创建另一条相同消息；
• 已经发送成功的任务再次查询会返回原结果，不会重复发送；
• 换号后不要把旧账号的进度更新到新账号页面。

下载和本地展示

下载完成后通过 SDK 提供的媒体读取接口读取内容。应用不应猜测 SDK 缓存目录，也不应 直接拼接缓存文件路径。需要保存到相册或“文件”App 时，先从 SDK 读取，再通过系统公开 接口写到用户选择的位置。

图片和视频列表建议先显示缩略图，原文件在用户打开时再下载。页面退出后可以停止读取， 不会破坏已经缓存的完整文件。

内容审核

服务端可能在上传完成后进行文件类型、病毒或内容审核。审核期间页面显示“处理中”，不要 提前把文件当成可以下载：

状态	页面建议
上传中	显示进度与取消按钮
处理中	显示处理中，不提供下载
已完成	正常展示或下载
已拒绝	显示安全提示，不自动重试
临时失败	提供重试按钮

审核规则由部署方配置。客户端不要把审核失败改写成网络错误，也不要在日志中记录文件内容。

上线前验证

• [ ] 图片、视频、语音、普通文件都能发送和下载；
• [ ] 断网后恢复可以继续，不会生成重复消息；
• [ ] 页面退出、取消和 App 重启后的状态正确；
• [ ] 文件过大、格式不支持和审核拒绝有明确提示；
• [ ] 磁盘空间不足时不会导致页面卡死；
• [ ] 换号后任务和缓存不会串到另一个账号；
• [ ] 日志中没有本地路径、上传地址、Token 或文件内容。