Uni-app原生插件基础开发文档

本文详细指导了如何在Hbuilder和AndroidStudio中搭建Uni-app项目,创建原生插件,包括Module扩展、Component扩展的步骤,以及如何注册、测试、打包和问题解决。重点讲解了插件开发、依赖管理、生命周期管理和不同打包方式的实践。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

Uni-app原生插件基础开发文档

一、软件安装

需要Hbuilder和Android Studio,前往官网下载即可
HBuilderX官网下载
Android Studio 官网下载
uni-app原生开发SDK最新版本下载

二、插件开发与测试

1、创建Uni-app项目

打开Hbuilder,左上角文件->新建->项目,选择项目类型为uni-app,选择合适的项目模板

创建uniapp项目

生成的目录结构如下
uniapp项目结构

2、创建原生项目

打开Android Studio,左上角File->new->new Project,选择设备类型Phone and Tablet,选择初始有一个空的Activity,点击Next,设置应用名称,选择最小SDK,勾选下面的Use legacy…,Finish,项目创建完成
创建AS项目
AS项目设置
有两种目录结构比较常用,Project和Android,平时开发主要使用Android,但是文件显示的不够全面,我们这里拿Project来看一下所生成的Android原生项目的目录结构
AS项目结构
如果gradle版本过高会出问题,所以检查下版本,查看以下两个文件,DCloud推荐gradle-4.6-all版本,tools.build版本为3.2.1
修改gradle版本
之后,我们还需要引入uni-app开发所需要的aar包以及添加依赖
我们已经下载了uni-app原生开发SDK(如果没有下载,可以回到文档最上方,点击链接下载),将我们需要的aar包放在app的libs中,并在build.gradle中添加依赖
添加uniapp依赖
代码块:

aaptOptions {
        additionalParameters '--auto-add-overlay'
        ignoreAssetsPattern "!.svn:!.git:.*:!CVS:!thumbs.db:!picasa.ini:!*.scc:*~"
}

//uni-app添加
    implementation fileTree(include: ['*.aar'], dir: 'libs')
    /*uniapp集成所需库-----------------------开始*/
    implementation 'com.android.support:recyclerview-v7:26.1.0'
    implementation 'com.alibaba:fastjson:1.1.46.android'
    implementation 'com.facebook.fresco:fresco:1.13.0'
    implementation "com.facebook.fresco:animated-gif:1.13.0"
    /*uniapp集成所需库-----------------------结束*/

3、创建插件

uni-app插件目前仅支持Module扩展和Component扩展
我们这里先学习Module扩展

1)扩展Module
① 创建Module

左上角File,new->new Module,选择Android Library,点击Next,设置模块名称Module name,以及包名和最小SDK minimum SDK,注意与创建项目时选择一致,如果不小心选择错误也没事,可以在build.gradle中进行修改,之后Finish
添加module-1
添加module-2

② 引入依赖

我们已经在主项目中添加了aar,在Module中只需要在build.gradle中引入即可,其中uniapp-v8-release.aar是扩展module主要依赖库,必须导入此依赖库!
引入依赖

③ 类继承UniModule
我们需要创建一个继承UNIModule的类,这里我们写与js交互的方法逻辑,需要注意以下两点:

扩展方法必须加上@UniJSMethod (uiThread = false or true) 注解。UniApp 会根据注解来判断当前方法是否要运行在 UI 线程,和当前方法是否是扩展方法。
UniApp是根据反射来进行调用 Module 扩展方法,所以Module中的扩展方法必须是 public 类型。同样因为是通过反射调用,Module 不能被混淆。请在混淆文件中添加代码:
-keep public class * extends io.dcloud.feature.uniapp.common.UniModule{*;}
新建插件类

4、使用插件

1)注册插件

我们在app模块下的src/main下创建assets文件夹,创建dcloud_uniplugins.json文件,注册我们创建的插件

dcloud_uniplugins.json说明

nativePlugins: 插件跟节点 可存放多个插件
hooksClass: 生命周期代理(实现AppHookProxy接口类)格式(完整包名加类名)
plugins: 插件数组
name : 注册名称
class : module 或 component 实体类完整名称
type : module 或 component类型。

可参考下图:
注册插件

2)引入插件

在app下的build.gradle中引入插件
引入插件

5、测试

我们需要修改我们创建的uni-app项目调用插件里的方法,那我们就简单写一个调用来进行测试。

1) uni-app项目修改

我们简单写了一个按钮,调用原生方法,发送参数并返回数据,展示在textArea中
index页面

2) uni-app项目打包

当我们写完代码,可以先运行测试一下代码是否有问题,防止多次修改多次编译
运行测试
确定代码没有问题,就可以编译资源包,点击上方发行->原生APP-本地打包->生成本地打包APP资源,这里需要微信开发者工具,根据提示下载引入即可,编译完成,控制台会打印资源包路径

3) 添加到原生项目

将资源包复制到src/main/assets/apps下,如果没有apps文件夹,则创建,之后从我们下载的原生开发SDK中复制data文件夹到assets下,修改dcloud_control.xml中appid与我们项目的appid一致
添加www
data文件夹
修改了这些还是不够,还需要修改app下AndroidManifest.xml,我们原先是有一个默认的Activity的,删掉,将下面的内容复制进去,然后修改provider标签的authorities,修改为自己的包名

<activity
            android:name="io.dcloud.PandoraEntry"
            android:configChanges="orientation|keyboardHidden|keyboard|navigation"
            android:label="@string/app_name"
            android:launchMode="singleTask"
            android:hardwareAccelerated="true"
            android:theme="@style/TranslucentTheme"
            android:screenOrientation="user"
            android:windowSoftInputMode="adjustResize" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <activity
            android:name="io.dcloud.PandoraEntryActivity"
            android:launchMode="singleTask"
            android:configChanges="orientation|keyboardHidden|screenSize|mcc|mnc|fontScale|keyboard"
            android:hardwareAccelerated="true"
            android:permission="com.miui.securitycenter.permission.AppPermissionsEditor"
            android:screenOrientation="user"
            android:theme="@style/DCloudTheme"
            android:windowSoftInputMode="adjustResize">
            <intent-filter>
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <action android:name="android.intent.action.VIEW" />
                <data android:scheme="h56131bcf" />
            </intent-filter>
        </activity>
        <!--provider节点必须添加-->
        <provider
            android:name="io.dcloud.common.util.DCloud_FileProvider"
            android:authorities="包名.dc.fileprovider"
            android:exported="false"
            android:grantUriPermissions="true">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/dcloud_file_provider" />
        </provider>

4) 插件模块修改
我们只修改VUE代码显然是不够的,还需要在java中实现对应的方法,否则会报错,我们在VUE中调用了getLocation方法,而且有参数和返回值,那么我们就在java中进行对应的实现
添加插件方法
5)运行
点击Android Studio的run 或者 debug来运行APP,点击按钮测试,可以看到已经成功调用
AS运行
运行结果

6、生成插件包

其实上述的方法是以原生开发为主导,如果是以vue开发为主导,需要将我们的插件模块,封装为一个插件包,首先,我们打开gradle,选择插件模块,Tasks->other->assembleRelease,双击执行,生成aar文件
生成插件包

三、使用插件包

1、Uni-app云打包

1)创建插件文件夹

之后,在我们的uni-app项目根目录下,新建nativeplugins文件夹,新建我们的插件文件夹,然后新建android文件夹,将我们的aar文件复制进来,如果有第三方jar包或者so库可以放在libs文件夹,创建package.json,可以查看官网说明
创建插件文件夹

2)引入插件

随后,在manifest.json中引入我们的插件
引入插件

3)打包

HbuilderX,点击上方工具栏,选择发行->原生App-云打包,之后进行部分设置,主要需要注意的部分如下,点击打包即可,我们可以点击发行->原生App-查看云打包状态,查看云打包进度,如果打包完成,在控制台会打印下载链接,下载APK即可
云打包
安装后进行测试,功能正常
运行结果-2

2、Android Studio离线打包

可以参考官方文档 Android平台App本地离线打包
其实最开始,我们是直接运行在真机,但是会出现如下报错TypeError undefined
真机运行报错
这是由于原生插件需要先进行云打包更新基座,所以我们进行了云打包,报错消失,调用插件正常
现在我们尝试第二种方式,本地离线打包

创建原生工程

创建一个包含空Activity的项目。
与之前类似,就不再多说,参考 二-2 创建原生项目。
注意:App离线SDK不支持Kotlin

配置工程
基础库

拿到我们的插件生成的aar,放到libs文件夹

将lib.5plus.base-release.aar、android-gif-drawable-release@1.2.17.aar、uniapp-release.aar和miit_mdid_1.0.10.aar(HBuilderX2.8.1之后更新到msa_mdid_1.0.13.aar)拷贝到libs目录下

注意:自HBuilderX2.8.0开始,JS引擎默认从jscore改为V8,提升运算性能,离线sdk自HBuilderX2.8.1也将默认JS引擎切换到V8,新增uniapp-v8-release.aar(uniapp-v8-release.aar和uniapp-release.aar不能同时使用。)。

在build.gradle中添加资源引用

implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'], exclude: [])
implementation "com.android.support:support-v4:28.0.0"
implementation "com.android.support:appcompat-v7:28.0.0"
implementation 'com.android.support:recyclerview-v7:28.0.0'
implementation 'com.facebook.fresco:fresco:1.13.0'
implementation "com.facebook.fresco:animated-gif:1.13.0"
implementation 'com.github.bumptech.glide:glide:4.9.0'
implementation 'com.alibaba:fastjson:1.1.46.android'

uni-app配置时需要在build.gradle中添加aaptOptions配置

aaptOptions {  
  additionalParameters '--auto-add-overlay'  
  ignoreAssetsPattern "!.svn:!.git:.*:!CVS:!thumbs.db:!picasa.ini:!*.scc:*~"  
}

注意:更新SDK时需要同时更新aar/jar文件和build.gradle配置
引入依赖-3

应用配置

配置应用启动页及provider节点,删除AndroidManifest.xml中初始的Activity标签,将下述内容添加到Androidmanifest.xml的application节点中
注意:${apk.applicationId} 必须替换成当前应用的包名

<activity
      android:name="io.dcloud.PandoraEntry"
      android:configChanges="orientation|keyboardHidden|keyboard|navigation"
      android:label="@string/app_name"
      android:launchMode="singleTask"
      android:hardwareAccelerated="true"
      android:theme="@style/TranslucentTheme"
      android:screenOrientation="user"
      android:windowSoftInputMode="adjustResize" >
      <intent-filter>
          <action android:name="android.intent.action.MAIN" />
          <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
  </activity>
  <activity
      android:name="io.dcloud.PandoraEntryActivity"
      android:launchMode="singleTask"
      android:configChanges="orientation|keyboardHidden|screenSize|mcc|mnc|fontScale|keyboard"
      android:hardwareAccelerated="true"
      android:permission="com.miui.securitycenter.permission.AppPermissionsEditor"
      android:screenOrientation="user"
      android:theme="@style/DCloudTheme"
      android:windowSoftInputMode="adjustResize">
      <intent-filter>
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="h56131bcf" />
      </intent-filter>
  </activity>
  <!--provider节点必须添加-->
  <provider
      android:name="io.dcloud.common.util.DCloud_FileProvider"
      android:authorities="${apk.applicationId}.dc.fileprovider"
      android:exported="false"
      android:grantUriPermissions="true">
      <meta-data
          android:name="android.support.FILE_PROVIDER_PATHS"
          android:resource="@xml/dcloud_file_provider" />
  </provider>

!!!注意:gradle版本不可过高,注意和com.android.tools.build:gradle同步修改

插件配置

插件包都有package.json文件,放在原生项目中就可以将里面的内容复制到assets下的dcloud_uniplugins.json中,前面也提到过这个文件 二-4-1)注册插件

资源配置

Android studio默认项目没有assets文件夹,需手动创建,创建位置与java目录同级,创建data文件夹并将SDK->assets->data文件夹拷贝到刚刚创建的assets文件夹下,将uni-app打成资源包放在assets/apps下,修改dcloud_control.xml中的appid为拷贝过来的APP的id,之前已经有说明,就不再配图
生成自定义基座,需要在根节点下添加debug="true"和syncDebug=“true”,如下图:
自定义基座
运行测试成功。

四、问题

1、页面显示的是原生页面

注意修改AndroidManifest.xml,删除默认的Activity,复制我们需要的内容进去

2、页面空白

看是不是gradle版本过高,DCloud推荐gradle-4.6-all版本,tools.build版本为3.2.1

3、不开Activity怎么获取权限

可以搞一个透明Activity申请权限,申请成功后,调用finish()关闭activity
可以在AndroidManifest.xml中设置activity的android:theme="@android:style/Theme.Translucent"使Activity透明

4、高德地图加载失败,No implementation found for

是由于我们所使用的so库与手机架构不匹配,可以在app下的build.gradle文件中的android标签下的defaultConfig标签中添加如下代码
ndk {
//设置支持的SO库架构(开发者可以根据需要,选择一个或多个平台的so)
abiFilters “armeabi-v7a”
}

5、打包成aar,高德地图黑屏

百度有人说是由于aar打包的时候jar包里的assets没有打进去
没有找到合适的解决方案,只能把jar包和so库提出来放在插件包里,修改插件模块下build.gradle,这样打包成aar的时候就不会把jar和so也打进去,然后在调用插件的项目中引入这些jar和so

6. 添加iOS端插件后云打包超限

注意这个超限不是说打包后的安装包过大,而是资源包以及本地插件等的大小,这是由于我们把第三方framework也放在了插件文件夹中,例如我们项目使用的高德导航SDK,有五百多M。

这种情况有两种解决方案:

① 将插件发布至插件市场,以云端插件的方式引入插件,进行云打包
这种方式的弊端就是别人也可以使用你的插件,如果设置了插件价格,即便是插件作者使用插件也需要收费,当然收益还是给到插件作者,也就是付给DCloud一个分成费。

② 如果没有使用插件市场的其他插件,可以使用XCode本地打包

### 如何在uni-app开发原生插件 #### 1. 插件开发概述 uni-app支持通过原生插件扩展功能,允许开发者封装Android和iOS平台的原生能力,并在uni-app项目中调用。开发原生插件通常涉及以下步骤:环境准备、插件结构设计、插件配置文件编写以及调试与打包[^1]。 #### 2. 环境准备 在开始开发原生插件之前,需要确保开发环境已经正确配置。这包括安装必要的IDE(如Android Studio和Xcode),以及配置相关的SDK工具链。具体可以参考《uni-app原生插件混合开发调试1-环境准备》中的详细说明[^1]。 #### 3. 插件包结构 原生插件的目录结构通常如下所示: ``` |-- 插件id // 插件包是一个以插件id命名的文件夹 |-- android // 存放Android插件所需要的依赖库及资源文件 |-- ios // 存放iOS插件所需要的依赖库及资源文件 |-- package.json // 插件配置文件 ``` `package.json`是插件的核心配置文件,用于描述插件的基本信息、版本号、依赖关系等[^2]。 #### 4. Android原生插件开发Android平台上开发原生插件时,需要在`app/src/main/assets`目录下创建`dcloud_uniplugins.json`文件,并添加插件的相关配置。例如: ```json { "nativePlugins": [ { "plugins": [ { "type": "module", "name": "Test-Module", "class": "com.test.testplugin.TestModule" } ] } ] } ``` 上述配置定义了一个名为`Test-Module`的模块,对应的Java类为`com.test.testplugin.TestModule`[^4]。 #### 5. iOS原生插件开发 对于iOS平台,插件开发主要涉及Objective-C或Swift代码的编写,并将相关依赖库放置在`ios`目录下。具体实现可以参考《iOS uni-app 原生插件开发》中的详细说明[^2]。 #### 6. 调试与打包 开发完成后,可以通过uni-app提供的调试工具进行本地测试。如果遇到签名证书或appid不匹配的问题,需检查应用包名、签名证书以及AppKey是否一致,并按照官方文档逐一排查[^3]。 #### 7. 示例代码 以下是一个简单的Android原生插件示例: ```java package com.test.testplugin; import com.alibaba.fastjson.JSONObject; import io.dcloud.feature.uniapp.annotation.UniJSMethod; import io.dcloud.feature.uniapp.bridge.UniJSCallback; public class TestModule { @UniJSMethod(uiThread = true) public void echo(String message, UniJSCallback callback) { JSONObject result = new JSONObject(); result.put("echo", message); if (callback != null) { callback.invoke(result); } } } ``` ###
评论 4
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值