HarmonyOS 项目示例

项目配置

安装、初始化和首次配置，请参考 HarmonyOS 接入教程。

概述

本示例展示了如何在鸿蒙 ArkTS 项目中集成 ApiSorcery。ArkTS 是华为用于鸿蒙开发的编程语言，为构建原生鸿蒙应用程序提供现代化的开发体验。

特性

• 鸿蒙原生：针对鸿蒙生态系统和 API 进行优化
• 类型安全：完整的 ArkTS 类型支持，生成接口定义
• @ohos/axios 集成：内置支持鸿蒙适配的 HTTP 客户端
• 分布式能力：支持鸿蒙分布式特性
• 性能优化：针对鸿蒙运行时和内存管理进行优化

功能演示

本示例应用基于真实后端 API，实现了完整的用户管理模块：

• 分页列表 — 支持按 code、姓名、状态条件过滤的分页查询
• 完整 CRUD — 新增、查看、编辑、删除用户记录
• 头像上传 — 通过 POST /file/upload 上传图片，含 10 MB 大小校验
• Excel 导出 — 通过 Blob 响应下载过滤后的结果为 .xlsx 文件
• 字段验证 — 表单提交前异步检查 code 字段是否已存在

代码示例

分页查询

import * as ApiUser from '../apis/auto/demo/ApiUser';
import { UserPageQueryDto, UserInfoDto } from '../api/auto/demo/model';

@Entry
@Component
struct UserPage {
  @State users: UserInfoDto[] = [];
  @State total: number = 0;
  @State loading: boolean = false;
  private page: number = 1;

  async aboutToAppear() {
    await this.loadUsers();
  }

  async loadUsers(code: string = '', name: string = '') {
    this.loading = true;
    try {
      const res = await ApiUser.getUserPaged({
        pagination: { page: this.page, limit: 10 },
        code,
        name,
      } as UserPageQueryDto);
      this.users = (res.results || []) as UserInfoDto[];
      this.total = res.total || 0;
    } catch (error) {
      console.error('获取用户失败:', error);
    } finally {
      this.loading = false;
    }
  }
}

Excel 导出

import * as ApiUser from '../apis/auto/demo/ApiUser';
import { ExportUsersRequest } from '../api/auto/demo/model';
import fs from '@ohos.file.fs';

async function exportUsers(code = '', name = '') {
  const blobRes = await ApiUser.exportUsers({ code, name } as ExportUsersRequest);
  const filePath = `${getContext().filesDir}/${blobRes.name ?? 'users.xlsx'}`;
  const file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY);
  fs.writeSync(file.fd, blobRes.data!.buffer);
  fs.closeSync(file);
}

头像上传

import * as ApiFile from '../apis/auto/demo/ApiFile';
import { UploadFileRequest } from '../api/auto/demo/model';
import picker from '@ohos.file.picker';

async function uploadAvatar(): Promise<string> {
  const photoPicker = new picker.PhotoViewPicker();
  const result = await photoPicker.select({ maxSelectNumber: 1 });
  const filePath = result.photoUris[0];
  const fileId = await ApiFile.uploadFile({ file: filePath } as UploadFileRequest);
  return `${BASE_URL}/file/${fileId}`;
}

鸿蒙特有功能

分布式数据管理

import distributedKVStore from '@ohos.data.distributedKVStore';

class UserService {
  private apiMain = new ApiMain();
  private kvStore?: distributedKVStore.SingleKVStore;

  async syncUserData(userId: string) {
    const userData = await this.apiMain.getUser(userId);
    // 与分布式 KV 存储同步
    if (this.kvStore) {
      await this.kvStore.put(`user_${userId}`, JSON.stringify(userData.data));
    }
  }
}

后台任务集成

import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';

class DataSyncService {
  private apiMain = new ApiMain();

  async startBackgroundSync() {
    const requestInfo: backgroundTaskManager.BackgroundTaskInfo = {
      bgMode: backgroundTaskManager.BackgroundMode.DATA_TRANSFER,
      wantAgent: undefined
    };

    backgroundTaskManager.startBackgroundRunning(getContext(), requestInfo)
      .then(() => {
        this.performDataSync();
      });
  }

  private async performDataSync() {
    try {
      const response = await this.apiMain.syncData();
      console.log('后台同步完成:', response.data);
    } catch (error) {
      console.error('后台同步失败:', error);
    }
  }
}

最佳实践

1. 权限管理：正确请求和处理网络权限
2. 生命周期管理：将 API 调用与鸿蒙组件生命周期集成
3. 错误处理：实现鸿蒙特定的错误处理模式
4. 性能优化：使用鸿蒙性能优化技术
5. 分布式特性：在适用时利用鸿蒙分布式能力