鸿蒙 uni-app x callFunction 调用指南

鸿蒙专家

在鸿蒙端使用 uni-app x 开发时，登录、数据查询、文件上传、支付回调等需要服务端逻辑的功能，通常交给云函数。uniCloud 是 DCloud 提供的 Serverless 云服务，开发者不用自建服务器、买域名、做运维，写云函数上传后由客户端直接调用，对个人开发者和小团队比较友好。客户端入口是 uniCloud.callFunction，HarmonyOS 4.61 版本开始支持；鸿蒙平台与 Android 端一样，支持阿里云、腾讯云、支付宝云。鸿蒙平台使用前，需要在 HBuilderX 中右键项目目录，关联 uniCloud 服务空间；云服务商可选阿里云、腾讯云、支付宝云，功能差别不大，阿里云文档最全。

API 签名如下：

2. uniCloud.callFunction<T>(options: UniCloudCallFunctionOptions): Promise<UniCloudCallFunctionResult<T>>

复制代码

从 4.13 版本起支持泛型。传入泛型后，res.result 会得到明确类型；不传泛型时，返回类型为 Promise<UniCloudCallFunctionResult<UTSJSONObject>>。options 中常见字段包括 name、data、secretType；secretType 用于加密类型，设置为 'both' 表示请求和响应都加密。这个泛型能力对鸿蒙端类型安全有直接帮助，可以减少手写类型转换。

基础调用：定义 hello 云函数，客户端传 name，云函数返回 message。

2. uniCloud.callFunction({
3.   name: 'hello',
4.   data: { name: 'uni-app x' }
5. } as UniCloudCallFunctionOptions).then((res) => {
6.   console.log('云函数返回:', res.result)
7. }).catch((err) => {
8.   console.error('调用失败:', err)
9. })

复制代码

云函数侧：

2. // cloudfunctions/hello/index.js
3. 'use strict';
4. exports.main = async (event, context) => {
5.   return {
6.     errCode: 0,
7.     errMsg: '',
8.     message: 'Hello ' + event.name
9.   }
10. }

复制代码

如果希望类型更安全，可以定义返回类型并使用泛型：

2. type HelloResult = {
3.   errCode: number
4.   errMsg: string
5.   message: string
6. }
7. uniCloud.callFunction<HelloResult>({
8.   name: 'hello',
9.   data: { name: 'uni-app x' }
10. } as UniCloudCallFunctionOptions).then((res) => {
11.   const result = res.result
12.   console.log(result.message)
13. })

复制代码

这样 result.message 可以直接访问，不需要类型转换。

登录场景可把 token、userId、nickname 放进 LoginResult。调用成功后，用 uni.setStorageSync 保存 token、userId、nickname；失败时用 result.errMsg 提示。查询场景把 list 定义为 Array<UTSJSONObject>，total 为 number；云函数中用 uniCloud.database() 获取 collection('articles')，通过 where 过滤 status，count 统计总数，再用 skip、limit、orderBy 取分页数据。提交场景返回 id，云函数用 collection('articles').add 写入 title、content、createTime 和 status: 'active'。这些模式覆盖了鸿蒙端 uni-app x 常见的云函数交互。

敏感数据调用时设置 secretType: 'both'：

2. uniCloud.callFunction({
3.   name: 'process-sensitive',
4.   data: { data: sensitiveData },
5.   secretType: 'both'
6. } as UniCloudCallFunctionOptions)

复制代码

错误处理建议同时处理业务错误和网络异常。业务错误可依据 errCode 分支：0 成功，10001 参数错误，10002 未登录，10003 无权限，其他走 errMsg 或未知错误；catch 中提示网络错误或云函数异常，并让用户重试。

和鸿蒙原生对接 Cloud 服务相比，uniCloud.callFunction 省去了购买服务器、配置域名和 HTTPS、维护服务端等步骤。鸿蒙原生写法通常要引入 @kit.NetworkKit，自己拼 HTTP 请求并维护服务端；而在 uni-app x 中，写云函数并上传后即可调用。整体取舍是：个人开发者和小团队优先用 uniCloud 降低运维成本；鸿蒙平台适配的重点是确认 HarmonyOS 4.61 以上支持 callFunction、在 HBuilderX 关联服务空间、选择阿里云/腾讯云/支付宝云，并在调用侧用好泛型、加密和错误码分支。