HarmonyOS应用开发实战：小事记 - 多媒体文件上传：@ohos.net.http 的 multipart/form-data 请求构造

前言

多媒体文件上传 是应用常见功能，如上传照片、视频等。HarmonyOS 的 @ohos.net.http 支持构造 multipart/form-data 请求，实现文件上传。本文以小事记（xiaoshiji_ohos_app）的照片上传场景为背景，深入解析 multipart 请求的构造。

本文参考 HarmonyOS 官方文档：http 文档和文件上传。

一、multipart/form-data 请求

1.1 基本实现

typescript 复制代码

// 文件上传
import { http } from '@kit.NetworkKit';
import { fileIo } from '@kit.CoreFileKit';

async function uploadFile(filePath: string): Promise<void> {
  const httpRequest = http.createHttp();
  
  try {
    // 构造 multipart/form-data 请求
    const formData = new FormData();
    formData.append('file', {
      uri: filePath,
      name: 'photo.jpg',
      type: 'image/jpeg'
    });
    formData.append('eventId', '12345');
    
    const response = await httpRequest.request(
      'https://api.example.com/upload',
      {
        method: http.RequestMethod.POST,
        header: {
          'Content-Type': 'multipart/form-data',
          'Authorization': 'Bearer token'
        },
        extraData: formData,
        connectTimeout: 10000,
        readTimeout: 30000  // 上传超时设置较长
      }
    );
    
    if (response.responseCode === 200) {
      console.log('上传成功');
    }
  } catch (err) {
    console.error(`上传失败: ${err.message}`);
  } finally {
    httpRequest.destroy();
  }
}

方案	适用场景	注意事项
方案一	简单场景	实现简单，易于维护
方案二	复杂场景	灵活性高，需注意性能
方案三	特殊场景	针对特定需求优化

二、批量上传

2.1 批量上传

typescript 复制代码

// 批量上传照片
async function batchUploadPhotos(photoPaths: string[]): Promise<void> {
  for (const path of photoPaths) {
    try {
      await uploadFile(path);
      console.log(`照片上传完成: ${path}`);
    } catch (err) {
      console.error(`照片上传失败: ${path}`);
    }
  }
}

三、上传进度

3.1 进度监听

typescript 复制代码

// 上传进度监听
// 目前 @ohos.net.http 不直接支持进度回调
// 建议使用分片上传或通过响应时间估算进度

四、常见问题

4.1 上传超时

问题：大文件上传时超时。

解决方案 ：增加 readTimeout 时间，或使用分片上传。

五、

typescript 复制代码

// 错误处理示例
import { BusinessError } from "@kit.BasicServicesKit";

try {
  const data = await getData("https://api.example.com");
} catch (err) {
  console.error(`请求失败: ${(err as BusinessError).message}`);
}

最佳实践

策略	说明	效果
超时配置	上传超时设置为 30s+	大文件上传
压缩图片	上传前压缩	减少体积
批量上传	逐个上传	避免失败

八、拓展阅读

本节汇总了与本文主题相关的扩展阅读材料，帮助读者深入理解相关技术细节。

8.1 官方文档

开发者指南：HarmonyOS 应用开发概述
API 参考：ArkTS API 参考

8.2 相关技术文章

性能优化最佳实践
常见问题排查指南

8.3 社区资源

开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

十、最佳实践与优化建议

在实际开发中，合理运用上述技术可以显著提升应用的性能和用户体验。以下是几个关键的最佳实践建议：

10.1 性能优化要点

优化方向	具体措施	预期效果
渲染性能	减少不必要的组件重建	提升帧率
内存管理	及时释放不再使用的资源	降低内存占用
响应速度	避免在主线程执行耗时操作	提升交互流畅度

10.2 推荐实践步骤

按照以下步骤进行优化：

使用 DevEco Studio 的 Profiler 工具分析当前性能瓶颈
针对识别出的热点进行针对性优化
通过单元测试和集成测试验证优化效果
在真机环境下进行回归测试

10.3 代码示例

typescript 复制代码

// 推荐的最佳实践示例
@Component
export struct OptimizedComponent {
  // 使用 @State 管理最小粒度的状态
  @State private isActive: boolean = false;

  build() {
    Column() {
      Text(this.isActive ? '激活' : '未激活')
        .fontSize(16)
    }
    .onClick(() => {
      // 使用 animateTo 实现平滑过渡
      animateTo({ duration: 300 }, () => {
        this.isActive = !this.isActive;
      });
    });
  }
}

最佳实践提示：在编写代码时，始终遵循 ArkUI 的性能优化原则，避免在 build() 方法中执行复杂计算或频繁的状态更新。

十、进一步学习与拓展

掌握以上内容后，可以进一步探索以下相关主题，深化对 HarmonyOS 开发的理解：

10.1 推荐学习路径

学习阶段	主题	预期目标
基础阶段	掌握核心概念和 API 用法	能够独立完成基本功能开发
进阶阶段	理解底层原理和最佳实践	能够优化应用性能和用户体验
高级阶段	掌握架构设计和性能调优	能够主导复杂项目的技术方案

10.2 实践项目建议

建议通过以下实践项目巩固所学知识：

基于小事记项目，尝试独立实现一个类似的功能模块
阅读 HarmonyOS 官方 Sample 代码，学习最佳实践
参与开源社区，贡献代码或文档

10.3 相关资源

HarmonyOS 官方文档：提供完整的 API 参考和开发指南
DevEco Studio 文档：包含 IDE 使用技巧和调试方法
开源社区：获取项目源码和开发经验

学习建议：理论与实践相结合，在阅读文档的同时动手编写代码，才能更好地掌握 HarmonyOS 应用开发技能。

10.4 拓展阅读

以下资源可以加深对本文内容的理解：

HarmonyOS 官方开发者文档提供了最权威的 API 参考和最佳实践指南
开源社区的项目源码是学习实际应用开发的宝贵资源
DevEco Studio 的代码示例模板可以帮助快速上手

资源类型	推荐指数	适用人群
官方文档	⭐⭐⭐⭐⭐	所有开发者
开源项目	⭐⭐⭐⭐	中级开发者
技术博客	⭐⭐⭐	入门开发者

学习路径：建议按照"官方文档 → 开源项目 → 实践项目"的路径循序渐进地学习。

十、完整示例：网络请求封装

将网络请求逻辑封装为统一的请求工具，可以简化网络层调用。

10.1 请求工具封装

typescript 复制代码

// HttpClient.ets --- 网络请求工具
import { http } from '@kit.NetworkKit';

export class HttpClient {
  static async get<T>(url: string, headers?: Record<string, string>): Promise<T> {
    const req = http.createHttp();
    try {
      const resp = await req.request(url, {
        method: http.RequestMethod.GET,
        header: headers,
        connectTimeout: 5000,
        readTimeout: 10000,
        expectDataType: http.HttpDataType.OBJECT
      });
      return resp.result as T;
    } finally {
      req.destroy();
    }
  }

  static async post<T>(url: string, data: Object, headers?: Record<string, string>): Promise<T> {
    const req = http.createHttp();
    try {
      const resp = await req.request(url, {
        method: http.RequestMethod.POST,
        header: { 'Content-Type': 'application/json', ...headers },
        extraData: JSON.stringify(data),
        connectTimeout: 5000,
        readTimeout: 10000
      });
      return resp.result as T;
    } finally {
      req.destroy();
    }
  }
}

10.2 使用示例

typescript 复制代码

// 定义接口类型
interface ApiResponse {
  code: number;
  message: string;
  data: Record<string, Object>;
}

// 发起 GET 请求
try {
  const result = await HttpClient.get<ApiResponse>('https://api.example.com/events');
  if (result.code === 200) {
    console.log(`获取数据成功: ${JSON.stringify(result.data)}`);
  }
} catch (err) {
  console.error(`请求失败: ${err.message}`);
}

10.3 请求配置参数

参数	类型	默认值	说明
connectTimeout	number	5000	连接超时(ms)
readTimeout	number	10000	读取超时(ms)
expectDataType	enum	OBJECT	期望返回数据类型
usingCache	boolean	false	是否使用缓存
usingProtocol	enum	HTTP1_1	HTTP 协议版本

网络优化：建议在应用启动时预创建 HTTP 连接池，避免频繁创建和销毁连接带来的性能开销。

总结

typescript 复制代码

// 网络请求示例
import { http } from "@kit.NetworkKit";

async function getData(url: string): Promise<Object> {
  const httpRequest = http.createHttp();
  const response = await httpRequest.request(url);
  httpRequest.destroy();
  return response.result;
}

本文深入解析了多媒体文件上传的实现。核心要点如下：

multipart/form-data：构造文件上传请求
FormData：组装表单数据
超时配置：上传超时设置较长
批量上传：逐个上传文件

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

typescript 复制代码

// 数据绑定示例
@Entry
@Component
struct DataBinding {
  @State message: string = "Hello HarmonyOS";

  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .fontColor("#7B68EE")
    }
    .width("100%")
    .height("100%")
    .justifyContent(FlexAlign.Center)
  }
}

typescript 复制代码

// 条件渲染示例
@State isVisible: boolean = false;

build() {
  Column() {
    if (this.isVisible) {
      Text("内容可见")
        .fontSize(16)
    }
    Button("切换")
      .onClick(() => {
        this.isVisible = !this.isVisible;
      })
  }
}

九、完整示例代码

9.1 完整组件实现

以下是一个完整的组件实现示例，展示了本文介绍的各个技术点的综合运用：

typescript 复制代码

import { Component, State, Prop } from '@kit.ArkUI';

@Component
export struct DemoComponent {
  @Prop title: string = '';
  @State count: number = 0;

  build() {
    Column({ space: 12 }) {
      // 标题区域
      Text(this.title)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .fontColor('#1A1A2E')
        .width('100%')

      // 内容区域
      Text(`当前计数: ${this.count}`)
        .fontSize(14)
        .fontColor('#6B7280')

      // 交互按钮
      Button('点击增加')
        .width(120)
        .height(40)
        .backgroundColor('#7B68EE')
        .borderRadius(20)
        .fontColor(Color.White)
        .onClick(() => {
          this.count++;
        })
    }
    .width('100%')
    .padding(16)
    .backgroundColor(Color.White)
    .borderRadius(12)
    .shadow({ radius: 4, color: '#00000008', offsetX: 0, offsetY: 2 })
  }
}

9.2 使用方式

在页面中引入并使用该组件：

typescript 复制代码

@Entry
@Component
struct Index {
  build() {
    Column() {
      DemoComponent({ title: '示例组件' })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F8F9FA')
  }
}

9.3 代码说明

组件封装 ：使用 @Component 装饰器定义可复用的组件
状态管理 ：使用 @State 管理组件内部状态
参数传递 ：使用 @Prop 接收外部传入的参数
事件处理 ：使用 onClick 处理用户交互
样式优化 ：使用 borderRadius、shadow 等属性美化 UI

相关资源：

官方文档 - 开发者指南：HarmonyOS 应用开发
官方文档 - ArkUI 组件参考：ArkUI 组件
官方文档 - API 参考：API 参考
官方文档 - 状态管理：状态管理概述
官方文档 - 动画：动画概述
官方文档 - 网络管理：网络管理
官方文档 - 数据管理：数据管理
开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net