callArkTSFunction 接口文档

返回主文档

目录

• 一、概述
  • 1.1 简介
  • 1.2 应用场景
• 二、接口定义
  • 2.1 JS端签名
  • 2.2 参数说明
  • 2.3 返回值
  • 2.4 调用示例
• 三、类型值映射表
  • 3.1 参数类型映射表
  • 3.2 返回值类型映射表
• 四、使用示例
  • 4.1 JS端调用示例
  • 4.2 ArkTS端注册回调函数
  • 4.3 参数规范
• 五、注意事项
• 六、注意说明
• 七、Demo

---

一、概述

1.1 简介

在 OpenHarmony Electron 应用场景中，业务层（JS/TS）想要调用 ArkTS 来使用系统底层特有功能。

该接口提供了一种 Electron JS 与 ArkTS 交互通信的机制，并实现了参数类型和返回值类型的双向传递。

systemPreferences.callArkTSFunction()

该接口为 Electron JS 与 ArkTS 的通信提供了异步调用机制，并实现了参数类型和返回值类型的双向传递。

1.2 应用场景

• 该接口属于 systemPreferences
• 通过 AKI 框架注册 ArkTS 函数
• 支持异步调用

---

二、接口定义

2.1 JS端签名

systemPreferences.callArkTSFunction(funcName: string, param: any): Promise<any>

2.2 参数说明

参数名	类型	必填	说明
funcName	string	是	ArkTS端注册的函数名
param	any	否	传递给 ArkTS 函数的参数，可以是基本类型或复杂类型

2.3 返回值

返回 Promise<any> - 异步返回 ArkTS 函数的处理结果。

2.4 调用示例

const result = await systemPreferences.callArkTSFunction('getDeviceName', null);
console.log('Device name:', result);

---

三、类型值映射表

3.1 参数类型映射表

JS类型	ArkTS类型	说明
number	number	数值类型
string	string	字符串类型
boolean	boolean	布尔类型
null	null	空值
undefined	undefined	未定义
Array	Array	数组类型
Object	Object	对象类型
Function	Function	函数类型（用于回调）

3.2 返回值类型映射表

ArkTS类型	JS类型	说明
number	number	数值类型
string	string	字符串类型
boolean	boolean	布尔类型
null	null	空值
undefined	undefined	未定义
Array	Array	数组类型
Object	Object	对象类型

---

四、使用示例

4.1 JS端调用示例

无参调用示例

// 无参调用
const result = await systemPreferences.callArkTSFunction('getDeviceName');
console.log('Result:', result);

带参调用示例

// 基本类型参数
const sum = await systemPreferences.callArkTSFunction('addNumbers', [1, 2, 3]);
console.log('Sum:', sum);

// 复杂对象参数
const userInfo = {
  name: '张三',
  age: 25,
  email: 'zhangsan@example.com'
};
const result = await systemPreferences.callArkTSFunction('processUserInfo', userInfo);

回调函数示例

// 注册回调函数
const callbackId = await systemPreferences.callArkTSFunction('registerCallback', {
  onSuccess: (data) => {
    console.log('Success:', data);
  },
  onError: (error) => {
    console.error('Error:', error);
  }
});

4.2 ArkTS端注册回调函数

步骤 1：在 Adapter 实现业务逻辑

创建 Adapter 层来处理具体的业务逻辑：

// adapter/UserAdapter.ets
import { NativeContext } from '../interface/CommonInterface';

export class UserAdapter {
  private static nativeContext: NativeContext;

  static init(context: NativeContext) {
    UserAdapter.nativeContext = context;
  }

  static getDeviceName(): string {
    // 实现获取设备名称的逻辑
    return 'HarmonyOS Device';
  }

  static addNumbers(numbers: number[]): number {
    return numbers.reduce((sum, num) => sum + num, 0);
  }
}

步骤 2：在 Bind 文件中对函数进行包装和注册

在 Bind 文件中完成函数的包装和注册：

// jsbindings/UserBind.ets
import { JSBindingMethod } from './JsBindingMethod';
import { UserAdapter } from '../adapter/UserAdapter';

export function registerUserFunctions() {
  // 注册获取设备名称函数
  JSBindingMethod.bind('getDeviceName', () => {
    return UserAdapter.getDeviceName();
  });

  // 注册数字相加函数
  JSBindingMethod.bind('addNumbers', (numbers: number[]) => {
    return UserAdapter.addNumbers(numbers);
  });
}

步骤 3：在 JsBindingMethod.ets 确认 bind() 调用

确保在 JsBindingMethod.ets 中正确调用 bind() 方法：

// jsbindings/JsBindingMethod.ets
import { NativeContext } from '../interface/CommonInterface';

export class JSBindingMethod {
  private static nativeContext: NativeContext;

  static init(context: NativeContext) {
    JSBindingMethod.nativeContext = context;
  }

  static bind(funcName: string, func: Function): void {
    if (JSBindingMethod.nativeContext) {
      JSBindingMethod.nativeContext.JSBind.bindFunction(funcName, func);
    }
  }
}

步骤 4：在 JS 端调用

在 Electron JS 端调用注册的函数：

// renderer.js
const { systemPreferences } = require('electron');

async function main() {
  // 获取设备名称
  const deviceName = await systemPreferences.callArkTSFunction('getDeviceName');
  console.log('Device Name:', deviceName);

  // 计算数字和
  const sum = await systemPreferences.callArkTSFunction('addNumbers', [1, 2, 3, 4, 5]);
  console.log('Sum:', sum);
}

main().catch(console.error);

4.3 参数规范

为确保 JS 与 ArkTS 之间的正确通信，请遵循以下参数规范：

1. 基本类型参数：直接传递，类型会自动映射
2. 对象参数：确保对象结构简单，避免循环引用
3. 数组参数：支持基本类型数组，复杂对象数组需谨慎
4. 函数参数：仅用于回调场景，不支持直接传递函数执行

---

五、注意事项

1. 该接口仅支持异步调用，不支持同步调用
2. 函数名必须在 ArkTS 端通过 AKI 框架正确注册
3. 参数和返回值的类型必须符合映射表要求
4. 复杂对象建议扁平化处理，避免嵌套层级过深
5. 大数据传输可能影响性能，建议分批处理

---

六、注意说明

1. 确保在调用前已完成 ArkTS 端的函数注册
2. 函数名必须唯一，避免重复注册
3. 参数类型不匹配会导致调用失败
4. 异步调用需要正确处理 Promise
5. 建议添加错误处理机制

---

七、Demo

• 使用Demo

---

相关文档

• Electron鸿蒙化指导文档（主文档）
• Electron调用ETS指导文档
• Electron加载Addon指导文档