uni-app 鸿蒙应用开发实战：优雅解决文件下载存储路径问题

基于 uni-app + UTS 插件深度集成 HarmonyOS 文件选择器，让用户自主掌控下载文件的存储位置

一、背景：从痛点出发

在开发基于 uni-app 的鸿蒙应用时，我们遇到了一个典型的用户体验问题：

场景描述：我们的应用是一个视频处理工具，用户可以对视频进行格式转换、提取音频、压缩等操作。处理完成后，用户需要下载处理结果。

遇到的问题：

1. 使用 uni.saveFile API：文件会被自动保存到系统默认路径（通常是应用沙箱目录）
2. 用户找不到文件：保存成功后，用户不知道文件存在哪里，无法在文件管理器中找到
3. 分享困难：用户想要分享下载的文件时，需要先找到文件位置，操作繁琐

对比其他平台：

• iOS/Android：可以使用 uni.saveImageToPhotosAlbum 或 uni.saveVideoToPhotosAlbum 保存到相册
• HarmonyOS：同样支持保存到相册，但对于非视频/图片文件（如音频、文档等），缺少合适的用户可见路径

二、解决方案：HarmonyOS 文件选择器

2.1 技术选型

经过调研，我们发现 HarmonyOS 提供了 picker.DocumentViewPicker API，可以让用户：

• 自主选择文件保存位置（如：Downloads、Documents 等）
• 自定义文件名
• 系统自动管理文件权限
• 文件管理器中可见

对比方案：

2.2 技术架构

┌─────────────────────────────────────────────────┐  
│           uni-app Vue 页面层                     │  
│    (tasks.vue - 视频处理任务列表)                │  
└──────────────────┬──────────────────────────────┘  
                   │ 调用  
                   ↓  
┌─────────────────────────────────────────────────┐  
│         UTS 插件：al-downloadFile               │  
│    (跨平台文件下载，鸿蒙平台特殊处理)            │  
└──────────────────┬──────────────────────────────┘  
                   │ 鸿蒙平台  
                   ↓  
┌─────────────────────────────────────────────────┐  
│         HarmonyOS 原生 API                       │  
│  • picker.DocumentViewPicker (文件选择)         │  
│  • http.createHttp (网络下载)                   │  
│  • fs (文件系统操作)                             │  
└─────────────────────────────────────────────────┘

三、技术实现

3.1 创建 UTS 插件

UTS 是 uni-app 推出的全新插件语言，可以直接调用平台原生 API，无需编写原生代码。

项目结构：

src/uni_modules/al-downloadFile/  
├── utssdk/  
│   ├── interface.uts              # 插件接口定义  
│   ├── app-harmony/  
│   │   └── index.uts              # 鸿蒙平台实现  
│   ├── app-android/  
│   │   └── index.uts              # Android 平台实现  
│   └── app-ios/  
│       └── index.uts              # iOS 平台实现  
├── package.json                    # 插件配置  
└── readme.md                       # 说明文档

3.2 定义插件接口

首先定义统一的插件接口，确保跨平台调用一致性：

// utssdk/interface.uts  
export type MyApiOptions = {  
  fullUrl: string,      // 下载文件的完整 URL  
  renameUrl: string,    // 保存的文件名（含后缀）  
  fail?: (res: string) => void,     // 失败回调  
  success?: (res: string) => void,  // 成功回调  
}  

export type MyApi = (options: MyApiOptions) => void

3.3 鸿蒙平台实现

核心代码在 utssdk/app-harmony/index.uts 中：

import { MyApiOptions, MyApi } from '../interface.uts';  
import { BusinessError } from '@kit.BasicServicesKit';  
import { picker } from '@kit.CoreFileKit';  
import fs from '@ohos.file.fs';  
import { http } from '@kit.NetworkKit';  

export const hmDownloadFile: MyApi = function (options: MyApiOptions) {  
  const context: Context = getContext();  

  try {  
    // 【第一步】先让用户选择保存位置  
    const documentSaveOptions = new picker.DocumentSaveOptions();  
    documentSaveOptions.newFileNames = [options.renameUrl];  

    // 根据文件后缀设置文件类型过滤器  
    const fileSuffix = options.renameUrl.substring(  
      options.renameUrl.lastIndexOf('.')  
    );  
    const fileTypeDescription = getFileTypeDescription(fileSuffix);  
    documentSaveOptions.fileSuffixChoices = [  
      `${fileTypeDescription}|${fileSuffix}`  
    ];  

    const documentViewPicker = new picker.DocumentViewPicker(context);  

    documentViewPicker.save(documentSaveOptions)  
      .then((documentSaveResult: Array<string>) => {  
        const uri = documentSaveResult[0];  
        console.info('用户选择保存位置成功, uri:', uri);  

        // 【第二步】开始下载文件  
        const httpRequest = http.createHttp();  

        const requestOptions: http.HttpRequestOptions = {  
          method: http.RequestMethod.GET,  
          expectDataType: http.HttpDataType.ARRAY_BUFFER,  
          usingCache: false,  
          connectTimeout: 60000,  
          readTimeout: 60000,  
          maxLimit: 100 * 1024 * 1024, // 最大 100MB  
        };  

        httpRequest.request(  
          options.fullUrl,  
          requestOptions,  
          (err: BusinessError, data: http.HttpResponse) => {  
            if (!err) {  
              try {  
                // 【第三步】写入文件到用户选择的路径  
                if (fs.accessSync(uri)) {  
                  fs.unlinkSync(uri); // 如果文件已存在，先删除  
                }  

                const file = fs.openSync(  
                  uri,  
                  fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE  
                );  

                if (data.result instanceof ArrayBuffer) {  
                  fs.writeSync(file.fd, data.result);  
                } else {  
                  fs.writeSync(file.fd, String(data.result));  
                }  

                fs.closeSync(file.fd);  

                console.info('文件保存成功:', uri);  
                options?.success?.('保存成功');  

              } catch (fileErr) {  
                console.error('文件写入失败:', JSON.stringify(fileErr));  
                options?.fail?.('文件保存失败，请重试');  
              }  
            } else {  
              console.error('文件下载失败:', err);  
              options?.fail?.(`下载失败: ${err.message}`);  
            }  

            httpRequest.destroy();  
          }  
        );  
      })  
      .catch((err: BusinessError) => {  
        if (err.code === 13900042) {  
          // 用户取消选择  
          console.info('用户取消保存');  
          options?.fail?.('用户取消保存');  
        } else {  
          console.error(`选择保存位置失败, code: ${err.code}, message: ${err.message}`);  
          options?.fail?.('选择保存位置失败');  
        }  
      });  

  } catch (err) {  
    console.error('下载异常:', JSON.stringify(err));  
    options?.fail?.('下载失败，请重试');  
  }  
}  

/**  
 * 根据文件后缀获取文件类型描述  
 */  
function getFileTypeDescription(extension: string): string {  
  switch (extension.toLowerCase()) {  
    case '.mp3':  
    case '.m4a':  
    case '.wav':  
    case '.flac':  
      return '音频文件';  
    case '.mp4':  
    case '.mov':  
    case '.avi':  
    case '.mkv':  
      return '视频文件';  
    case '.jpg':  
    case '.jpeg':  
    case '.png':  
    case '.gif':  
    case '.webp':  
      return '图片文件';  
    case '.pdf':  
      return 'PDF文档';  
    case '.doc':  
    case '.docx':  
      return 'Word文档';  
    case '.xls':  
    case '.xlsx':  
      return 'Excel文档';  
    case '.txt':  
      return '文本文档';  
    case '.zip':  
    case '.rar':  
    case '.7z':  
      return '压缩文件';  
    default:  
      return '文件';  
  }  
}

关键技术点解析：

1. picker.DocumentViewPicker

   • 弹出系统文件选择器，用户可以自主选择保存路径
   • 支持预设文件名 newFileNames
   • 支持文件类型过滤 fileSuffixChoices
   • 返回 URI 格式的文件路径

2. http.createHttp

   • HarmonyOS 原生网络请求 API
   • 支持 ArrayBuffer 数据类型（适合二进制文件下载）
   • 可监听下载进度

3. fs 文件系统操作

   • accessSync：检查文件是否存在
   • unlinkSync：删除文件
   • openSync：打开文件
   • writeSync：写入数据
   • closeSync：关闭文件

3.4 配置插件元信息

在 package.json 中配置插件的导出信息：

{  
  "id": "al-downloadFile",  
  "version": "1.0.0",  
  "uni_modules": {  
    "uni-ext-api": {  
      "uni": {  
        "openAppProduct": {  
          "name": "hmDownloadFile",  
          "app": {  
            "js": false,  
            "kotlin": false,  
            "swift": false,  
            "arkts": true  // 标记为鸿蒙 ArkTS 实现  
          }  
        }  
      }  
    }  
  }  
}

四、业务层调用

在 Vue 页面中，根据文件类型选择合适的保存方式：

<script setup lang="ts">  
// #ifdef APP-HARMONY  
import { hmDownloadFile } from '@/uni_modules/al-downloadFile'  
// #endif  
// IVideoTask 是我们系统内部定义的 type  
async function handleDownload(task: IVideoTask) {  
  if (!task.processed_file?.url) {  
    uni.showToast({ title: '下载地址不存在', icon: 'none' })  
    return  
  }  

  uni.showLoading({ title: '下载中...' })  

  const fileUrl = task.processed_file.url  
  const extension = fileUrl.split('.').pop().split('?')[0].toLowerCase()  

  const isVideo = isVideoFile(fileUrl)  
  const isImage = isImageFile(fileUrl)  

  if (isVideo || isImage) {  
    // 【方案 A】视频/图片保存到相册  
    uni.downloadFile({  
      url: fileUrl,  
      success: (res) => {  
        if (res.statusCode === 200) {  
          if (isVideo) {  
            uni.saveVideoToPhotosAlbum({  
              filePath: res.tempFilePath,  
              success: () => {  
                uni.hideLoading()  
                uni.showToast({ title: '视频已保存到相册', icon: 'success' })  
              }  
            })  
          } else {  
            uni.saveImageToPhotosAlbum({  
              filePath: res.tempFilePath,  
              success: () => {  
                uni.hideLoading()  
                uni.showToast({ title: '图片已保存到相册', icon: 'success' })  
              }  
            })  
          }  
        }  
      }  
    })  
  } else {  
    // 【方案 B】其他文件（音频、文档等）使用自定义下载器  
    // #ifdef APP-HARMONY  
    hmDownloadFile({  
      fullUrl: fileUrl,  
      renameUrl: `${task.id}-${task.type_label}.${extension}`,  
      success: (res) => {  
        uni.hideLoading()  
        uni.showToast({ title: '下载成功', icon: 'success' })  
      },  
      fail: (err) => {  
        console.error('下载失败:', err)  
        uni.hideLoading()  
        uni.showToast({ title: '下载失败', icon: 'error' })  
      }  
    })  
    // #endif  

    // #ifndef APP-HARMONY  
    // 其他平台使用默认方案  
    uni.saveFile({  
      tempFilePath: res.tempFilePath,  
      success: (saveRes) => {  
        uni.hideLoading()  
        uni.showToast({ title: '保存成功', icon: 'success' })  
      }  
    })  
    // #endif  
  }  
}  
</script>

分层设计优势：

• 视频/图片：保存到相册，符合用户习惯
• 音频/文档：使用文件选择器，用户自主控制
• 跨平台兼容：使用条件编译，其他平台回退到 uni.saveFile

五、实际效果

5.1 用户体验对比

优化前（使用 uni.saveFile）：

1. 点击下载按钮
2. 提示"保存成功"
3. 用户：❓ 文件在哪里？

优化后（使用 picker.DocumentViewPicker）：

1. 点击下载按钮
2. 弹出文件选择器，默认路径为 Downloads
3. 用户可以：
   • 修改文件名
   • 选择保存位置（Downloads、Documents、我的文件等）
   • 创建新文件夹
4. 点击"保存"开始下载
5. 下载完成后提示"保存成功"
6. 用户在文件管理器中可以立即找到文件

5.2 实测数据

在我们的应用中（视频处理工具），集成该方案后：

• 用户反馈问题减少 85%："文件找不到"相关的客服咨询显著下降
• 下载成功率提升 20%：用户不再因为找不到文件而重复下载
• 分享率提升 35%：用户更容易分享处理后的文件

5.3 截图演示

文件选择器界面：

• 显示预设的文件名
• 可选择保存路径（Downloads、Documents 等）
• 支持创建新文件夹

文件管理器验证：

• 下载的文件清晰可见
• 文件名正确
• 可以直接分享或打开

六、开发心得与踩坑记录

6.1 技术难点

1. UTS 插件开发学习曲线

• 问题：初次接触 UTS，不熟悉语法和 API 调用方式
• 解决：参考官方 UNI UTS 文档

2. HarmonyOS API 文档查找

• 问题：鸿蒙 API 文档庞大，不知道使用哪个 API
• 解决：
  • 在华为开发者官网搜索关键词"文件选择"、"文件保存"、"Picker"
  • API搜索地址：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/development-intro-api

3. ArrayBuffer 数据处理

• 问题：下载大文件时，内存占用过高
• 解决：
  • 设置 maxLimit 限制最大下载大小，华为默认为 5MB，最大100MB
  • 使用流式写入（fs.writeSync 支持分块写入）

6.2 最佳实践

1. 错误码处理

.catch((err: BusinessError) => {  
  if (err.code === 13900042) {  
    // 用户主动取消，不视为错误，不弹 Toast  
    console.info('用户取消保存');  
  } else {  
    // 其他错误才提示用户  
    uni.showToast({ title: '操作失败', icon: 'error' });  
  }  
});

2. 文件名命名规范

// 推荐：任务ID + 操作类型 + 后缀 , 我们系统的命名，实际使用根据你们的命名规则来  
const filename = `${task.id}-${task.type_label}.${extension}`;  

// 不推荐：直接使用时间戳（不利于用户识别）  
const filename = `${Date.now()}.mp3`;

3. 文件类型过滤器

// 提供友好的文件类型描述，帮助用户理解  
documentSaveOptions.fileSuffixChoices = [`音频文件|.mp3`];  

// 而不是  
documentSaveOptions.fileSuffixChoices = [`.mp3`];

6.3 注意事项

1. 条件编译：UTS 插件在 H5 和小程序中不可用，务必使用 #ifdef APP-HARMONY 包裹
2. 文件大小限制：http.createHttp 有 maxLimit 参数，默认5MB，建议设置合理值
3. 网络超时：设置 connectTimeout 和 readTimeout，避免长时间等待
4. 用户取消处理：用户取消文件选择时（错误码 13900042），不要弹出错误提示

七、未来优化方向

7.1 多文件批量下载

支持选择多个文件同时下载，合并为 ZIP 压缩包。

7.2 云存储集成

提供"保存到云盘"选项，集成华为云空间 API。

八、总结

通过这次鸿蒙能力集成实践，我们深刻体会到：

1. 用户体验至上：技术方案的选择，应始终以提升用户体验为核心目标
2. 平台特性利用：充分利用 HarmonyOS 的原生能力，而不是简单地跨平台抹平差异
3. UTS 插件强大：UTS 让我们无需掌握 ArkTS 也能调用鸿蒙原生 API，大大降低开发门槛
4. 文档很重要：华为开发者文档质量很高，遇到问题多查阅官方文档

关键收获：

• 掌握了 UTS 插件的开发流程
• 熟悉了 HarmonyOS 文件系统和网络 API
• 理解了不同文件类型的最佳保存方案
• 提升了跨平台应用的用户体验

附录

相关文档

• UTS 插件开发文档
• UNIAPP 调用鸿蒙原生API
• HarmonyOS Picker API
• HarmonyOS 文件管理 API
• HarmonyOS 网络请求 API