企业官网建设流程全解析

• 示例工程
• 前端
• 移动开发
• 跨平台

本文以官方文档《UTS中使用uni api》为核心，结合本仓库（uni-app 跨平台框架开源仓库）中的 uts 插件示例与源码，系统讲解在 uts 插件代码中调用 uni API 的用法、类型注意事项、支持范围以及 Android / iOS 平台差异。适合正在使用 HBuilderX 3.8.0 及以上版本、通过 UTS 编写原生插件并希望复用 uni 封装能力的开发者阅读。

为什么要在 UTS 插件中调用 uni API

UTS（uni type script）是 uni-app 提供的统一强类型脚本语言，可按平台编译为不同语言：Web 平台编译为 JavaScript、Android 平台编译为 Kotlin、iOS 平台编译为 Swift、HarmonyOS 平台编译为 ArkTS（详见 uts 插件介绍 与 uts for Android）。

当 UTS 开发者需要调用 iOS 和 Android 的原生能力时，直接操作原生 API 往往需要处理大量平台差异。而 uni 已经对常用能力做了跨平台封装，因此在uni API 的覆盖范围内，开发者可以直接在 uts 插件代码中调用uni.xxx，用一套代码完成对 iOS、Android 原生能力的调用，无需再分别面向 Kotlin 与 Swift 编写两套实现。

版本前提：此能力需要HBuilderX 3.8.0 及以上版本。目前 uts 插件代码中可直接调用部分 uni API（如uni.request、uni.showModal），官方计划在未来陆续实现所有 uni API 在 uts 中的完整调用。

快速上手：在 uts 插件中弹出 Toast

在 uts 插件（如 uni_modules 插件内的utssdk目录下的.uts文件）中，直接调用uni.showToast即可，与在页面脚本中调用方式完全一致：

export function myToast() { uni.showToast({ title: 'This is toast in uts with uni API!', success: function(){ console.log('uni.showToast success!'); }, fail: (err) => { console.log('uni.showToast success: ', err); } }); }

这段代码体现了 uts 中调用 uni API 的三个要点：

• uni.showToast在 uts 插件中可直接调用，无需额外 import；
• 支持success/fail回调分别处理成功与失败分支，回调参数具备对应类型，可用.访问属性；
• 可同时使用箭头函数与普通函数两种回调写法。

在本仓库的示例工程中也能看到类似的调用实践。例如 Toast.vue 页面中，先通过import { showToast } from '@/uni_modules/uts-toast'调用 uts 插件封装的 Toast 能力，当插件返回失败（如未在自定义基座中运行）时，再回退调用uni.showToast提示用户：

testToastShow(){ let ret = showToast(); if(!ret){ uni.showToast({ icon:'none', title:'需要在自定义基座中运行' }) } }

这展示了一个常见模式：uts 插件封装原生能力，页面侧再用 uni API 做兜底交互反馈，二者互补。

重点注意：complete 回调参数是 any 类型

这是 uts 中调用异步 uni API 最容易踩的坑，官方文档特别提示：

uts 不支持联合类型，因此异步 API 中complete回调函数的参数会被当作any类型处理。

其影响与对策如下：

• complete 回调中不能使用.访问属性：any类型对象无法直接点出属性，目前可先用JSON.stringify()转为字符串处理，或改用success/fail分别处理成功与失败数据；
• success 与 fail 不受影响：这两个回调的参数是具体类型，可以正常使用.访问属性；
• 该问题仅存在于 complete 回调。

正确写法示例（uni.request）：

export function myTest() { uni.request({ url: 'https://www.invalidserviceaddress.com/', success: (ret) => { //ret为RequestSuccess类型，可以使用.访问其属性 let data = ret.data; console.log('uni.request successed: ', data); }, fail: (err) => { //err为RequestFail类型，可以使用.访问其属性 let code = err.errCode; console.log('uni.request failed: ', code); }, complete: (res) => { //res为any类型，转换为字符串处理 let ret = JSON.stringify(res); console.log(ret); } }); }

错误写法示例——在 complete 回调中直接点属性：

uni.request({ url: 'https://www.invalidserviceaddress.com/', complete: (res) => { console.log(res.errCode); } });

编译时会报错：

error: Unresolved reference: errCode

请务必养成习惯：success/fail 中读取结构化数据，complete 中只做收尾处理（日志、统一清理等），避免在 complete 中解析业务字段。

当前支持的 uni API 清单

截至本文档版本，uts 插件中支持以下 uni API（完整清单，按能力分类）：

网络

• uni.request(OBJECT)—— 发起网络请求，详见 request 文档

数据缓存

• uni.setStorage(OBJECT)—— 异步写入缓存
• uni.setStorageSync(KEY, DATA)—— 同步写入缓存
• uni.getStorage(OBJECT)—— 异步读取缓存
• uni.getStorageSync(KEY)—— 同步读取缓存
• uni.getStorageInfo(OBJECT)—— 异步获取缓存信息
• uni.getStorageInfoSync()—— 同步获取缓存信息
• uni.removeStorage(OBJECT)—— 异步移除指定缓存
• uni.removeStorageSync(KEY)—— 同步移除指定缓存
• uni.clearStorage()—— 清空缓存
• uni.clearStorageSync()—— 同步清空缓存

以上 API 的详细参数（key、data、success/fail/complete 回调等）可参见 storage 文档。

设备（系统信息）

• uni.getAppBaseInfo()—— 获取应用基础信息，详见 getAppBaseInfo 文档
• uni.getDeviceInfo()—— 获取设备信息，详见 getDeviceInfo 文档
• uni.getSystemSetting()—— 获取系统设置，详见 getSystemSetting 文档

界面（交互反馈）

• uni.showToast(OBJECT)/uni.hideToast()—— 显示/隐藏提示框，详见 showToast 文档
• uni.showLoading(OBJECT)/uni.hideLoading()—— 显示/隐藏加载框，详见 showLoading 文档
• uni.showModal(OBJECT)—— 显示模态弹窗，详见 showModal 文档
• uni.showActionSheet(OBJECT)—— 显示操作菜单，详见 showActionSheet 文档

媒体

HBuilderX 4.52 起新增支持

• uni.chooseMedia—— 拍摄或从相册中选择图片或视频，详见 chooseMedia 文档

使用边界

目前仅支持以上列出的部分 uni API 调用。由 uni ext api 机制实现的扩展 API（例如基于扩展插件实现的uni.getBatteryInfo等）暂时还不支持在 uts 插件中调用。若确实需要这类能力，可考虑将其封装为 uts 插件本身——本仓库 hello-uts 示例 中就提供了uts-getbatteryinfo这样的 uts 插件实现，可作为替代思路的参考。

平台差异：为什么 iOS 与 Android 支持范围不同

在uni-app x项目中使用的 uts 插件，在 App 平台存在明显差异，理解编译模型是正确使用的前提：

Android 平台：可调用全部 uni API

uvue 页面和 uts 插件在 Android 平台都编译为原生 Kotlin 代码，二者处于同一原生环境，因此 uts 插件可以调用所有uni API，不受限制。

iOS 平台：仅支持特殊封装过的 uni API

iOS 平台的架构不同：

• uvue 页面编译为 JS 代码，运行在 JSCore 环境中，所有 uni API 都被封装为JS 层接口；
• uts 插件则编译为原生 Swift 代码，在 Swift 代码中无法直接调用 JS 层接口，因此不能调用全部 uni API；
• 上文清单中列出的那些 uni API，在实现时做了特殊处理，额外封装了对应的 Swift 层接口，从而支持在 uts 插件中调用。

这就是为什么官方提供的支持清单在 iOS 上是"白名单制"——只有完成 Swift 层桥接的 API 才可用。可以结合 uts for iOS 中关于 uts 编译为 Swift 的描述进一步理解该约束。

关于 HarmonyOS

对于 HarmonyOS 平台，uts 会编译为 ArkTS（HBuilderX 4.22+ 支持），且 ArkTS 与 JS 在同一环境下执行，不涉及跨语言通讯问题（参见 uts 插件介绍），平台差异相对更小。

实操建议与注意事项小结

综合官方文档与本仓库示例，在 uts 插件中调用 uni API 时建议遵循以下实践：

1. 确认版本与平台：使用 HBuilderX 3.8.0+；iOS 上只依赖官方支持清单内的 API，Android 上则无此限制；
2. 区分回调职责：success/fail中读取结构化字段，complete中不要用.访问属性，必要时用JSON.stringify输出日志；
3. 优先 uni API 再退原生：uni API 覆盖范围内的能力直接用 uni 封装，覆盖不到（如 ext api）的需求再考虑用 uts 写原生实现（可参考 uts-platform-api 示例 中直接操作 Android 原生 API 的写法）；
4. 关注版本演进：支持的 API 列表会随 HBuilderX 版本持续扩充（如 chooseMedia 在 HBuilderX 4.52 新增），开发时留意当前版本的发布说明。

在编写 uts 插件代码时，也可对照 uts 语言文档、uni_modules 插件规范 与 uts 组件开发 等资料，从语法与工程结构两个层面完善你的插件。

• 示例工程
• 前端
• 移动开发
• 跨平台