当前位置：首页 > ai >正文

uniapp- UTS 插件鸿蒙端开发示例虽然我们这个示例简单但是这个是难住很多人的一大步

ai 2025/6/26 6:02:46

UTS 插件鸿蒙端开发示例

以上示例已开源
项目地址请参考示例代码。

前言

虽然这个 UTS 插件鸿蒙端的示例看起来很简单，但说实话，这一步其实难住了不少开发者。很多人第一次做 UTS 插件，尤其是要跑通鸿蒙端，都会在这里卡壳。希望这份文档能帮你少走弯路，顺利迈过这道坎。

基础知识补充

什么是 UTS 插件？

UTS 插件其实就是 uni-app x 扩展 API 的标准插件形式。你可以把它理解成"写一份 TypeScript 风格的代码，编译后在不同平台都能用"。

说个实话，刚接触 uni-app x 的时候，很多人一看到"插件"两个字就头大，觉得一定很复杂。其实 UTS 插件的本质，就是把你想要的原生能力用 TypeScript 包一层，剩下的交给编译器搞定。

UTS 与 ArkTS 的关系

UTS 和 ArkTS 都是基于 TypeScript 的扩展，但有些细节不同。特别注意：鸿蒙端开发时，所有对象字面量都必须定义类型，不能用 any 类型，否则会直接编译报错。

比如 ArkTS 不允许无类型的对象字面量，UTS 会自动帮你加上类型，但你自己写代码时一定要养成良好习惯：

// 错误写法（鸿蒙端会报错）
const obj = { a: 1 };// 正确写法
interface Obj { a: number }
const obj: Obj = { a: 1 };
// 或
const obj = { a: 1 } as Obj;

你只需要记住：UTS 写的代码，最终会被编译成 ArkTS（.ets）文件，然后就能愉快地调用鸿蒙的原生 API 了。

配置鸿蒙依赖

鸿蒙的依赖管理工具叫 ohpm，和 npm 很像。三方 SDK 用 .har 文件（有点像 Android 的 .aar）。

配置依赖时，记得在 utssdk/app-harmony/config.json 里写清楚：

{"dependencies": {"@cashier_alipay/cashiersdk": "15.8.26","local-deps": "./libs/local-deps.har"}
}

注意：config.json 不能有注释，本地依赖路径是相对的。

资源文件与权限配置

插件资源（图片、字体等）放在 utssdk/app-harmony/resources。
权限、模块信息等写在 utssdk/app-harmony/module.json5。

比如你要用定位权限，可以这样写：

{"module": {"requestPermissions": [{"name": "ohos.permission.LOCATION","usedScene": { "when": "inuse" },"reason": "$string:permission_location_reason"}]}
}

context 获取

很多鸿蒙原生 API 需要 context。大多数场景下直接用 getContext() 就行：

import settings from '@ohos.settings';
const context: Context = getContext();
settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => {if (err) {console.error(`Failed to get the setting. ${err.message}`);return;}console.log(`SCREEN_BRIGHTNESS_STATUS: ${JSON.stringify(value)}`)
});

有一次小王同学写插件，死活拿不到 context，结果发现是忘了在页面生命周期里调用，调试了半天才恍然大悟。遇到问题别慌，先查查官方文档和社区经验，很多"坑"其实大家都踩过。

更多细节和常见问题，建议随时查阅官方文档：UTS for HarmonyOS

步骤详解

友情提示：

虽然下面的步骤看起来很基础，但每一步都很关键。尤其是接口定义和鸿蒙端实现，很多人就是在这里卡住的。别嫌简单，能跑通才是王道。

再次强调：鸿蒙端开发时，所有对象字面量都必须定义类型，不能用 any 类型！

第一步：定义插件接口（interface.uts）

目的：

明确插件对外暴露的 API 规范，方便多端实现和 IDE 智能提示。
这是 UTS 插件开发的基础，所有端的实现都要遵循这里定义的接口。

操作：

在 uni_modules/你的插件名/utssdk/ 下新建或编辑 interface.uts 文件。
定义你要暴露的类型、方法签名。例如：

// uni_modules/tt-ost/utssdk/interface.uts
export type MyApiSync1 = (paramA: string) => string;

第二步：鸿蒙端实现接口（app-harmony/index.uts）

目的：

按照接口定义，实现鸿蒙端的具体逻辑。
这是很多开发者卡壳的地方，需注意导入接口类型、调用鸿蒙 API、正确导出方法。
注意：所有对象字面量都要定义类型，不能用 any！

操作：

在 uni_modules/你的插件名/utssdk/app-harmony/ 下新建或编辑 index.uts 文件。
按照接口定义，实现方法。例如：

// uni_modules/tt-ost/utssdk/app-harmony/index.uts
import { MyApiSync1 } from '../interface.uts';
import { promptAction } from '@kit.ArkUI';interface ShowToastOptions {message: string;
}export const myApiSync1: MyApiSync1 = function (paramA: string): string {let ddd: ShowToastOptions = { message: paramA };promptAction.showToast(ddd);return paramA;
}

这里以 Toast 弹窗为例，实际可根据业务需求调用鸿蒙原生能力。

第三步：在页面中调用插件方法

目的：

验证插件功能是否生效。
体验 UTS 跨端调用的便捷性。

操作：

在页面脚本中引入并调用插件方法。例如：

<script>
import { myApiSync1 } from '@/uni_modules/tt-ost';
export default {methods: {showToast() {const msg = 'Hello Harmony!';const result = myApiSync1(msg);console.log(result); // 输出: Hello Harmony!}}
}
</script>