uni-app总结5-UTS插件开发

我们先贴上官方UTS插件开发的教程地址：UTS插件介绍 | uni-app-x

uni-app本身对于原生的支持有限，当App想要使用原生的部分Api或者原生平台上的第三方SDK时，就需要通过UTS插件的形式来实现。

这篇文章我们就来讲下UTS插件开发的流程以及开发过程中常用的一些写法。

想要得心应手，需要仔细的看一遍官方的UTS插件开发文档，也可在实际开发中遇到问题的时候回头去查阅并记录。

一、开发流程 

uni_modules目录创建

如果之前使用过插件或者创建过插件，项目里已经存在uni_modules目录，则跳过这一步。

否则需要我们在HBuilder左侧的项目目录里选中项目最外层文件夹，右键然后选择“新建uni_modules目录”。

新建插件

选中上一步中的uni_modules目录，右键然后选择“新建uni_modules插件”，然后选择UTS插件-API插件（这里介绍的是API插件）。然后设置插件ID点击完成则会自动生成插件的目录。

插件目录介绍

utssdk是插件代码功能部分，readme是说明文件(发布插件市场时在详情显示)

app-android和app-ios，则分别为安卓端和iOS端的目录

interface.uts，接口声明文件，声明插件对完开放的方法、声明插件内部通用的Type等。

config.json，原生层配置文件，简单理解为设置远程SDK仓库依赖

• Android：

{// 使用NDK时支持的CPU类型，可选（打包时不要复制注释）"abis": ["使用NDK时支持的cpu类型, 可取值armeabi-v7a|arm64-v8a|x86|x86_64"],// 依赖的仓储配置，可选，打包时会合并到原生工程的build.gradle中（打包时不要复制注释）"dependencies": ["androidx.core:core-ktx:1.6.0",{"id": "com.xxx.richtext:richtext","source": "implementation 'com.xxx.richtext:richtext:3.0.7'"}],// Android系统版本要求，最低Android 5.0（打包时不要复制注释）"minSdkVersion": 21,"project": {"plugins": ["com.huawei.agconnect"],"dependencies": ["com.huawei.agconnect:agcp:1.6.0.300"],"repositories": ["maven { url 'https://artifact.bytedance.com/repository/Volcengine/' }"]}
}

• 1、abis： 当插件使用了NDK开发的so库时配置，描述插件支持CPU类型。 可取值：armeabi-v7a、arm64-v8a、x86、x86_64

• 2、dependencies： 配置插件依赖的仓储，云端打包时会合并到Android原生工程的build.gradle的 数组类型，数组中的项可以是字符串类型或JSON对象 对于字符串类型项，将会作为implementation方式依赖添加到build.gradle中，上面示例中"androidx.core:core-ktx:1.6.0"将会添加以下配置。就是添加远程SDK的依赖。

  • 2.1 字符串类型

dependencies {implementation 'androidx.core:core-ktx:1.6.0'
}

                2.2对于JSON类型项，将会把source字段值作为gradle源码添加到build.gradle中，上面示例中"id": "com.xxx.richtext:richtext"项将会添加以下配置

dependencies {implementation 'com.xxx.richtext:richtext:3.0.7'
}

• 3、minSdkVersion 插件支持的Android最低版本，整数类型，取值范围为Android API Level

  • uni-app 项目支持最低版本为19，即Android 4.4.2

  • uni-app x 项目支持最低版本为21，即Android 5.0

• 正常只需要设置这些配置项就可以了，遇到特殊需求需要配置其他东西可参考官方文档。

• iOS：   

{"frameworks": ["可选，依赖的系统库(系统库有.framework和.tbd和.dylib类型)"],"deploymentTarget": "12.0",   // 可选，插件支持的最低 iOS 版本  默认：12.0""validArchitectures": [    // 可选，支持的 CPU 架构类型 默认：arm64"arm64"],"dependencies-pods": [ // 可选, 需要依赖的pod库, HBuilderX 3.8.5+ 版本支持{"name": "WechatOpenSDK","version": "2.0.2"}]
}

正常我们只需要设置 deploymentTarget和dependencies-pods就可以了。

deploymentTarget：iOS支持的最低iOS系统版本

dependencies-pods：第三方SDK的pod库设置

插件功能实现

UTS的语言目前其实还并不完善，对于原生的很多写法没办法直接使用UTS翻译，官方一直在更新中。所以建议插件功能实现的方式采用UTS+原生混编的形式，在app-andriod和app-ios目录中分别创建原生kotlin和swift文件混编。只在interface.uts和index.uts这两个文件中声明方法的时候采用UTS语法，方法实现时通过调用原生文件中的api来完成。

interface.uts文件：

• 声明自定义Type        

export type User = {id: string;name: string;email: string;
};

• 声明插件对外的api       

export declare function testFunction(paramA: string, paramB: User, paramC: (res: UTSJSONObject) => void) : void;

Android端：

• index.uts

        对interface.uts中声明的api做一个实现，但其实也只是调用原生hybrid.kt文件中的一个方法，将参数已经回调传递到原生文件中。

import { User } from "../interface.uts"
export function testFunction(paramA : string, paramB : User, paramC : (res : UTSJSONObject) => void) : void {Hybrid.testFunction()
}

• hybird.kt

        原生的混编kotlin文件，根据第三方SDK的文档实现相关功能。这一步的工作建议是直接在Android Studio中开发好，然后复制过来。因为uni-app对于原生这块没有代码提示，也没有语法支持，会显示很多语法错误。但其实只要在原生中能正常运行，这里报错也是没有关系的。

        这里需要开发人员有一定的Android原生开发能力，起码是IDE使用、项目结构及配置和kotlin语法。

object Hybrid {fun testFunction() {}
}

iOS端

• index.uts

        对interface.uts中声明的api做一个实现，但其实也只是调用原生hybrid.kt文件中的一个方法，将参数已经回调传递到原生文件中。

import { User } from "../interface.uts"
export function testFunction(paramA : string, paramB : User, paramC : (res : UTSJSONObject) => void) : void {Hybrid.testFunction()Hybrid.shared.testFunction2()
}

• hybrid.swift

        原生的混编swift文件，根据第三方SDK的文档实现相关功能。这一步的工作建议是直接在Xcode中开发好，然后复制过来。因为uni-app对于iOS原生这块没有代码提示，也没有语法支持，在原生中开发更方便。

        这里需要开发人员有一定的iOS原生开发能力，起码是IDE使用、项目结构及配置和swift语法。

class Hybrid: NSObject {static let shared = Hybrid()private var str: String!// 声明一个类方法static func testFunction() {}// 声明一个对象方法func testFunction2() {}
}

 打自定义基座以及插件调用

在开发好插件，编译没有错误后。我们就需要在uni中去使用，比如App.vue或者index.vue中。

自定义基座制作

UTS插件只能在自定义基座中运行调试，而且每次修改到config.json文件时需要重新制作。需要通过云打包制作自定义基座，然后再选择基座运行。

引入和调用

import * as HYTest from '@/uni_modules/hy-test'

let user = {id: '1',name: '张三'
}
HYTest.testFunction('a', user, (res) => {console.log('测试回调', res)
})

二、易错点总结

1. 在混编的原生文件中访问uts文件中内容，在swift中需要

   import DCloudUTSFoundation

   在kotlin中需要

   import io.dcloud.uts.*
   import uts.sdk.modules.hyShopify.HYPayResult
   import uts.sdk.modules.hyShopify.HYProductListInfo

2. index.uts调用原生时传参写法，调用kotlin原生方法正常传，调用swift方法时需要加上参数声明，Hybrid.method(a = a)，需要加上 "a="
3. 在原生中创建uts中自定义的Type类型变量，通过UTSJSONObject构建，

   export type HYLoginResult = {code : number,msg : string,data : UTSJSONObject | null
   }

   lHYLoginResult(UTSJSONObject(["code": -1 as NSNumber,"msg": "user cancel","data": nil]))

4. 在UTS插件中拦截应用生命周期。有很多第三方SDK，需要在应用创建时对其进行初始化，此时需要拦截原生应用的生命周期。需要在index.uts中通过协议的方式去实现，Android端：

   export class AppHookProxy implements UTSAndroidHookProxy {override onCreate(application : Application) {OneSignal.initWithContext(application, ONESIGNAL_CONFIG.appId as string)    }
   }

   iOS端：

   export class AppHookProxy implements UTSiOSHookProxy {applicationDidFinishLaunchingWithOptions(application : UIApplication | null, launchOptions : Map<UIApplication.LaunchOptionsKey, any> | null = null) : boolean {let config : HYOneSignalConfig = {appId: ONESIGNAL_CONFIG.appId,fallbackToSettings: ONESIGNAL_CONFIG.fallbackToSettings,}OneSignalKit.getInstance().initialize(config, launchOptions)return true}
   }

5. 第5点
6. 第6点