# mindspore_lite_model_download

**Repository Path**: ybf521/mindspore_lite_model_download

## Basic Information

- **Project Name**: mindspore_lite_model_download
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MindSporeLite 线上模型异步下载模块

## 项目简介

一个基于 **HarmonyOS Next** 开发的异步后台文件下载模块，支持用户无感知的后台下载、进度监控、断点续传和文件管理功能。该模块使用 **ArkTS** 语言开发，遵循 HarmonyOS 应用架构规范，可帮助开发者快速集成稳定高效的下载能力 [1,2](@ref)。

## 功能特性

### ✅ 核心功能
- **异步后台下载**：使用 `TaskPool` 实现真正的后台异步下载，不阻塞主线程
- **用户无感知**：应用启动时自动在后台下载，不影响用户体验
- **进度实时监控**：支持实时下载进度显示和文件大小信息
- **多网络环境适配**：支持 Wi-Fi 和移动网络下载策略
- **自动重试机制**：下载失败时自动重试，最多 3 次

### ✅ 文件管理
- 文件完整性检查
- 下载文件信息查看
- 文件删除和清理
- 存储空间管理

### ✅ 用户界面
- 实时进度条显示
- 下载状态指示器
- 文件信息查看面板
- 操作反馈提示

## 工程结构
    entry/src/main/ets/
    ├── MainAbility/
    │ └── MainAbility.ets # 应用主入口
    ├── pages/
    │ └── Index.ets # 主页面，包含下载控制UI
    ├── service/
    │ └── ModelDownloadService.ets # 后台下载服务
    ├── utils/
    │ └── DownloadUtils.ets # 下载工具类
    └── resources/ # 资源文件

### 模块时序
![img.png](entry/src/main/resources/base/media/img.png)

### 模块说明

1. **DownloadUtils (下载工具类)**
    - **位置**: `utils/DownloadUtils.ets`
    - 核心下载功能实现，基于 `request.downloadFile` API
    - 提供文件下载配置管理、进度回调处理、错误处理和重试、文件操作工具方法

2. **ModelDownloadService (后台下载服务)**
    - **位置**: `service/ModelDownloadService.ets`
    - 单例服务，管理后台下载任务
    - 异步任务池管理、下载状态维护、自动重试逻辑、文件处理回调

3. **Index (主页面)**
    - **位置**: `pages/Index.ets`
    - 用户界面和控制层
    - 下载进度展示、控制按钮交互、状态轮询更新、文件信息查看

## 快速开始

### 1. 环境要求
- **HarmonyOS SDK** 5.0.0+
- **DevEco Studio** 5.1+ [1](@ref)
- 支持 API 15+ 的设备

### 2. 权限配置
 在 `module.json5` 中添加网络权限：

    {
       "module": {
          "requestPermissions": [
             {
               "name": "ohos.permission.INTERNET"
             }
          ]
       }
    }
复制
### 3. 基本使用

#### 应用启动时自动开始下载：
在 `EntryAbility` 中配置：

    onCreate() {
       const context = this.context;
       modelDownloadService.setContext(context);
       modelDownloadService.startDownload();
    }

#### 手动控制下载：

    // 开始下载
    modelDownloadService.startDownload();
    // 取消下载
    modelDownloadService.cancelDownload();
    // 检查下载状态
    const status = modelDownloadService.getDownloadStatus();
    // 检查是否下载完成
    const isComplete = modelDownloadService.isDownloadComplete();

#### 进度监控：

    // 设置进度回调
    modelDownloadService.setOnProgressCallback((progress, received, total) => {
      console.log(进度: ${progress}%, 已下载: ${received}, 总大小: ${total});
    });
    // 设置完成回调
    modelDownloadService.setOnCompleteCallback((result) => {
      if (result.success) {
         console.log('下载成功:', result.filePath);
      }
    });

### 4. 配置自定义下载

#### 4.1 自定义下载配置

    const config: DownloadConfig = {
       url: 'https://example.com/file.zip',
       fileName: 'custom_file.zip',
       override: true,
       headers: {
         'User-Agent': 'MyApp/1.0',
         'Authorization': 'Bearer token'
       }
    };
    const downloader = new DownloadUtils(config, context);
    downloader.startDownload();

#### 4.2 高级配置选项

    // 设置连接超时（秒）
    config.connectTimeout = 60;
    // 设置读取超时（秒）
    config.readTimeout = 300;
    // 设置网络策略
    config.enableMetered = false; // 仅Wi-Fi下载
    config.enableRoaming = false; // 禁用漫游网络下载

## API 参考

### DownloadUtils 类

#### 构造函数

    constructor(config: DownloadConfig, context: common.UIAbilityContext)

#### 主要方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `startDownload()` | - | `void` | 开始下载 |
| `pauseDownload()` | - | `void` | 暂停下载 |
| `cancelDownload()` | - | `void` | 取消下载 |
| `getDownloadStatus()` | - | `DownloadStatus` | 获取下载状态 |
| `isDownloadComplete()` | - | `boolean` | 检查是否完成 |
| `setOnProgressCallback()` | `(progress, received, total) => void` | `DownloadUtils` | 设置进度回调 |
| `setOnCompleteCallback()` | `(result) => void` | `DownloadUtils` | 设置完成回调 |
| `setOnErrorCallback()` | `(error) => void` | `DownloadUtils` | 设置错误回调 |

### ModelDownloadService 类

#### 单例获取

    const service = ModelDownloadService.getInstance();

#### 主要方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `setContext()` | `common.UIAbilityContext` | `void` | 设置应用上下文 |
| `startDownload()` | - | `Promise<void>` | 启动后台下载 |
| `cancelDownload()` | - | `void` | 取消下载任务 |
| `getDownloadStatus()` | - | `DownloadStatus` | 获取下载状态 |
| `isDownloadComplete()` | - | `boolean` | 检查下载完成 |
| `getDownloadedFilePath()` | - | `string \| null` | 获取文件路径 |
| `setOnProgressCallback()` | `(progress, received, total) => void` | `ModelDownloadService` | 设置进度回调 |
| `setOnCompleteCallback()` | `(result) => void` | `ModelDownloadService` | 设置完成回调 |
| `setOnErrorCallback()` | `(error) => void` | `ModelDownloadService` | 设置错误回调 |

### 数据类型

#### DownloadConfig

    interface DownloadConfig {
       url: string; // 下载URL
       fileName: string; // 保存文件名
       savePath?: string; // 自定义保存路径
       override?: boolean; // 是否覆盖已存在文件
       headers?: Record<string, string>; // 自定义请求头
    }

#### DownloadResult

    interface DownloadResult {
       success: boolean; // 是否成功
       filePath?: string; // 文件路径
       error?: BusinessError<void>; // 错误信息
       fileSize?: number; // 文件大小
    }

#### DownloadStatus

    interface DownloadStatus {
       isDownloading: boolean; // 是否正在下载
       progress: number; // 进度百分比
       received: number; // 已接收字节数
       total: number; // 总字节数
    }

## 使用示例

### 示例1：简单下载

    const config: DownloadConfig = {
       url: 'https://example.com/file.zip',
       fileName: 'file.zip',
       override: true
    };
    const downloader = new DownloadUtils(config, context);
    downloader.startDownload();

### 示例2：带进度显示

    const downloader = new DownloadUtils(config, context);
    downloader.setOnProgressCallback((progress, received, total) => {
      console.log(进度: ${progress}%);
      console.log(已下载: ${formatBytes(received)} / ${formatBytes(total)});
    });
    downloader.setOnCompleteCallback((result) => {
       if (result.success) {
         console.log('下载成功!');
       } else {
         console.error('下载失败:', result.error);
       }
    });
    downloader.startDownload();

### 示例3：后台服务集成

    // 在应用启动时
    modelDownloadService.setContext(this.context);
    modelDownloadService.setOnCompleteCallback((result) => {
      if (result.success) {
       console.log('后台下载完成');
      }
    });
    modelDownloadService.startDownload();
    // 在页面中显示进度
    setInterval(() => {
      const status = modelDownloadService.getDownloadStatus();
      updateUI(status);
    }, 1000);

## 注意事项

### 1. 权限要求
- **网络权限**：`ohos.permission.INTERNET`
- **存储权限**：自动管理应用沙箱目录

### 2. 网络限制
- 默认允许移动网络下载 (`enableMetered: true`)
- 禁止漫游网络下载 (`enableRoaming: false`)
- 建议在 Wi-Fi 环境下下载大文件

### 3. 存储管理
- 文件默认保存在应用沙箱的 `filesDir` 目录
- 支持自定义保存路径
- 自动清理部分下载的临时文件

### 4. 生命周期
- 应用退出时自动暂停下载
- 应用重启后不支持断点续传（需重新开始）
- 建议在网络恢复时自动重试

### 5. 性能考虑
- 大文件下载时注意内存使用
- 建议分片下载超过 100MB 的文件
- 定期清理下载缓存

## 常见问题

### Q1: 下载进度不更新
**原因**: 任务池中无法实时回调进度到主线程  
**解决方案**:
- 使用轮询方式获取状态：`setInterval(() => getDownloadStatus(), 500)`
- 或实现事件机制进行进度通知

### Q2: 下载速度慢
**原因**: 网络环境或服务器限制  
**解决方案**:
- 检查网络连接
- 调整下载超时设置
- 考虑分片下载

### Q3: 文件保存失败
**原因**: 存储空间不足或权限问题  
**解决方案**:
- 检查存储空间
- 确认文件路径可写
- 尝试使用默认保存路径

### Q4: 后台下载被系统中断
**原因**: 系统资源管理或省电策略  
**解决方案**:
- 确保应用在后台有运行权限
- 避免在低电量时进行大文件下载
- 使用前台服务进行重要下载

### Q5: 如何处理大文件下载
**建议**:
- 分片下载，每片 10-50MB
- 定期保存下载状态
- 提供暂停/继续功能
- 显示预计剩余时间

## 最佳实践

### 1. 用户体验优化

    // 显示友好的进度信息
    function formatProgress(status: DownloadStatus): string {
    if (status.total > 0) {
    const percent = (status.received / status.total * 100).toFixed(1);
      return ${percent}% (${formatBytes(status.received)} / ${formatBytes(status.total)});
    }
    return '计算中...';
    }

### 2. 错误处理优化

    downloader.setOnErrorCallback((error) => {
       if (error.code === -1) {
         showMessage('网络连接失败，请检查网络');
       } else if (error.code === -2) {
         showMessage('存储空间不足');
       } else {
         showMessage(下载失败: ${error.message});
       }
    });

### 3. 网络状态监听

    // 监听网络变化
    network.on('change', (type) => {
    if (type === network.NetworkType.WIFI) {
      // Wi-Fi下恢复下载
      resumeDownload();
    }
    });

## 扩展建议

### 1. 支持断点续传

    // 实现思路：
    // 1. 保存已下载的字节位置
    // 2. 请求时添加 Range 头部
    // 3. 支持暂停后继续下载

### 2. 多文件同时下载

    // 实现思路：
    // 1. 创建下载队列
    // 2. 限制同时下载数量
    // 3. 分别管理每个文件的状态

### 3. 下载管理器

    // 功能规划：
    // 1. 下载历史记录
    // 2. 下载速度限制
    // 3. 定时下载
    // 4. 批量下载

## 版本历史

### v1.0.0 (当前版本)
- 基础异步下载功能
- 后台任务池支持
- 进度监控和 UI 展示
- 错误处理和重试机制
- 文件管理功能

## 计划功能
- 断点续传支持
- 多文件下载队列
- 下载速度限制
- 定时下载任务
- 下载历史记录

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。

### 开发规范
- 遵循 ArkTS 编码规范
- 添加必要的类型注释
- 确保向后兼容性
- 添加单元测试

### 提交信息
使用约定式提交格式：
- `feat`: 新功能
- `fix`: 修复问题
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构代码
- `test`: 测试相关

## 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

## 支持与联系

如有问题或建议，请通过以下方式联系：
- 提交 GitHub Issue
- 查看在线文档
- 参考 HarmonyOS 官方文档 [2](@ref)

---

**注意**: 本模块基于 HarmonyOS Next 开发，API 和功能可能会随着系统更新而变化。请定期检查更新和兼容性。