DCloud_App_Array
DCloud_App_Array
  • 发布:2018-12-26 15:10
  • 更新:23 小时前
  • 阅读:5188

uni-app原生插件(native plugin)格式说明

分类:uni-app

uni-app原生插件(native plugin)提交DCloud插件市场需按以下目录格式配置:


上传时压缩为zip格式文件,压缩文件中必须包含目录名称,如下:

package.json

uni-app原生插件描述文件,完整格式如下
注:如果只有一端比如只包含android插件,请把ios节点删除掉,不能直接注释

{  
    "name": "插件名称",  
    "id": "插件标识",  
    "version": "插件版本号",  
    "description": "插件描述信息",  
    "_dp_type":"nativeplugin",  
    "_dp_nativeplugin":{  
        "ios": {  
            "plugins": [  
                {  
                    "type": "必填, module|component, 根据插件类型选择",  
                    "name": "必填, 注册插件的名称, 通常与插件标识一致",  
                    "class": "必填, 注册插件的类名"   
                }  
            ],  
            "integrateType": "必填, 可取值framework|library",  
            "hooksClass": "可选, 事件钩子注册类名",  
            "frameworks": [  
                "可选, 依赖的系统framework库(第三方 .a 库或 framework 直接放到ios根目录即可,不需要配置)"  
            ],  
            "embedFrameworks": [  
                "可选,依赖的framework动态库(同样将动态库framework文件放到 ios 根目录)"  
            ],  
            "capabilities": {    // 配置应用的capabilities数据(根据XCode规范分别配置到entitlements和plist文件中)  
                "entitlements": {    // 合并到工程entitlements文件的数据(json格式)  
                },  
                "plists": {    // 合并到工程Info.plist文件的数据(json格式)  
                }  
            },  
            "plists": {    // 自定义配置工程Info.plist文件的数据(json格式),优先级高于capabilities->plists  
            },  
            "resources": [  
                "可选, 插件要使用的资源文件列表,相对于ios目录的路径"  
            ],  
            "privacies": [  
                "可选, 插件使用到的隐私列表,如NSPhotoLibraryUsageDescription"  
            ],  
            "deploymentTarget": "8.0, 可选,支持的iOS最低版本",  
            "parameters": {  
                "插件需要配置的参数名称, 如appid": {  
                    "des": "参数描述信息",  
                    "key": "参数需要配置到infor.plist中的键名, 嵌套时使用:分割,如getui:appid"  
                }  
            }  
        },  
        "android": {  
            "plugins": [  
                {  
                    "type": "module|component, 必填, 根据插件类型选择"  
                    "name": "必填, 注册插件的名称, 通常与插件标识一致",  
                    "class": "必填, 注册插件的类名"  
                }  
            ],  
            "hooksClass": "可选, 事件钩子注册类名",  
            "integrateType": "必填, 可取值aar|jar",  
            "dependencies": [  
                "可选, 依赖的库名称"  
            ],  
            "abis": [  
                "可选, 支持的abi类型, 可取值armeabi|armeabi-v7a|x86"  
            ],  
            "minSdkVersion": "可选,支持的Android最低版本,如21",  
            "permissions": [  
                "可选, 要使用的Android权限列表"  
            ],  
            "parameters": {  
                "插件需要配置的参数名称, 如appid": {  
                    "des": "参数描述",  
                    "key": "AndroidManifest.xml中添加meta-data节点的android:name属性值, 如GETUI_APPID"  
                }  
            }  
        }  
    }  
}  

dependencies节点特殊说明

android插件中集成的第三方SDK 如果是jar或so放入到libs文件夹中即可,无需要配置到dependencies节点下。
gradle配置的第三方sdk 仓储名称方式的配置信息 需要在dependencies节点下填写。
例如:
app.gradle 配置中dependencies节点信息如下。

dependencies {  
    compileOnly fileTree(dir: 'libs', include: ['*.jar'])  
    compileOnly "com.android.support:recyclerview-v7:25.3.1"  
    compileOnly "com.android.support:support-v4:25.3.1"  
    compileOnly "com.android.support:appcompat-v7:25.3.1"  
    compileOnly "com.alibaba:fastjson:1.1.46.android"  
}  

package.json的dependencies节点就需要配置如下信息

dependencies [  
    "com.android.support:recyclerview-v7:25.3.1",  
    "com.android.support:support-v4:25.3.1",  
    "com.android.support:appcompat-v7:25.3.1",  
    "com.alibaba:fastjson:1.1.46.android"  
]  

!!!注意V7、V4、fastjson都已默认集成 不需要再次配置。这里仅是示例写法!!!

parameters

插件使用时需要配置的参数(每个参数配置一个json项),参数名称为键名,以下定义appid参数为示例:

"parameters": {  
    "appid": {  
        "des": "XXX插件的appid参数",  
        "key": "XXX_APPID",  
        "value": "WX_${appid}"  
   }  
}  
  • des 参数的描述信息
    在HBuilderX中显示,用于提示插件使用者配置此参数的作用。
  • key 云端打包时原生层使用的键名称
    Android平台为AndroidManifest.xml中添加meta-data节点的android:name属性值,推荐使用“插件标识_键名”格式,如"DC-RichAlert_appid";
    iOS平台为info.plist中的键名, 多层级嵌套时使用:分割,推荐使用“插件标识:键名”格式,如"DC-RichAlert:appid"。
  • value 云端打包时格式化的键值
    如果需要对插件使用者配置的参数值做一些格式化处理(如添加固定的前缀或后缀)时才需要配置vlue字段,其中${appid}表示插件使用者配置的appid参数值;不配置此字段则键值为插件使用者配置的参数值。

插件使用时需在manifest.json的"app-plus"->"nativePlugins"->"插件标识"中配置(最新版HBuilderX已支持可视化配置)
以"DC-RichAlert"插件配置appid参数为示例:

"app-plus": {  
    "nativePlugins": {  
        "DC-RichAlert": {  
            "appid": "T1234567890"  
        }  
    }  
}  

按上面的配置规则提交云端打包后appid的键值为"WX_T1234567890"。

android

uni-app原生插件Android平台资源,支持Android平台时必须添加此目录,所有Android平台相关的资源都放到此目录下。

  • aar文件,直接放到android目录下,云端打包会自动引用所有的aar文件
  • android\libs目录,所有需要使用的jar文件放到此目录,如果包含so文件,则放到libs下对应cpu类型目录
  • android\assets目录,Android平台需要assets资源
  • android\res目录,Android平台需要的res资源
    Android平台原生插件开发教程参考:https://ask.dcloud.net.cn/article/35416

ios

uni-app原生插件iOS平台资源,支持iOS平台时必须添加此目录,所有iOS平台相关的资源都放到此目录下。
iOS平台原生插件开发教程参考:https://ask.dcloud.net.cn/article/35415

插件配置完成后请作为本地uni-app原生插件提交云端打包进行测试验证插件是否配置正确

更多uni-app原生插件文档参考:uni-app原生插件开发指南

0 关注 分享

要回复文章请先登录注册

568660803@qq.com

568660803@qq.com

请问下:原生插件里调用了第三方SDK中的activity,这个activity如何在uniapp基座里的AndroidManifest.xml里注册
23 小时前
DCloud_App_Array

DCloud_App_Array (作者)

回复 928073632@qq.com:
参考:https://ask.dcloud.net.cn/article/35427
2019-07-10 13:09
928073632@qq.com

928073632@qq.com

心累 这个怎么回事 [JS Framework] using unregistered weex module "DCloud-RichAlert"
2019-07-09 18:27
fusenwang@163.com

fusenwang@163.com

回复 DCloud_App_Array:
嗯,明白了。感谢楼主耐心的解释
2019-07-05 17:35
DCloud_App_Array

DCloud_App_Array (作者)

回复 fusenwang@163.com:
manifest.json文件m不区分云端和本地,都是一样的。可能是你目录结构不正确。参考:https://ask.dcloud.net.cn/article/35844
2019-07-05 15:18
fusenwang@163.com

fusenwang@163.com

楼主您好,按照您说的“最新版HBuilderX已支持可视化配置“,但是在我这里可视化配置不奏效(在弹出的选择本地插件对话框中仍是一片空白,已经在nativeplugin目录下放置了解压的插件文件)。麻烦提供一份在manifest.json代码中配置本地插件的代码示例呢。本文中提及的在manifest.json代码中配置插件是云端上的插件。万分感激
2019-07-05 13:41
fusenwang@163.com

fusenwang@163.com

回复 指尖上的代码:
目前只能通过离线打包的方式走。期待uni-app官方把文档写得详实些。产品是个好产品
2019-07-05 13:35
指尖上的代码

指尖上的代码

脑阔疼我觉得这个对于 公司选用uniapp是至关重要的,但是这个地方的文档太模糊了...对于我这种不了解的人来说难受啊,我的插件是公司原生开发部门提供的aar的 但是文档里面没有相关描述啊
2019-07-03 17:21
指尖上的代码

指尖上的代码

回复 fusenwang@163.com:
aar的要怎么弄哇,,,
2019-07-03 17:13
fusenwang@163.com

fusenwang@163.com

回复 DCloud_App_Array:
您好,按照你说的将原生插件解压(包含android,ios和package.json)放置在nativeplugin目录下,在manifest.json的App原生插件配置中选择本地插件,在弹出的对话框中仍是空白的。是我hbuilderx版本问题还是什么?最近一直在踩坑,主要是官方文档写得比较粗糙啊,遗漏了一些关键性的细节,对于刚入门的开发者来说门槛很高了。
2019-07-03 10:01
DCloud_App_Array

DCloud_App_Array (作者)

回复 fusenwang@163.com:
nativeplugins目录下发的是解压后的插件目录,参考:https://ask.dcloud.net.cn/article/35844
2019-07-02 17:46
fusenwang@163.com

fusenwang@163.com

楼主您好,按照你的教程。我在项目的nativeplugins目录下放置了插件(文档中未涉及是放置aar文件还是zip文件包,我这里都有试),在manifest.json的App原生插件配置模块点击【选择本地插件】,在弹出的本地插件选择对话框中是一片空白,没有我放置的插件,这是怎么回事呢?
2019-07-02 16:30
2047185642@qq.com

2047185642@qq.com

回复 DCloud_App_Array:
好的,谢谢!
2019-03-26 14:05
DCloud_App_Array

DCloud_App_Array (作者)

回复 2047185642@qq.com:
如果只是在iOS平台使用的插件,可以只包含ios目录。
2019-03-26 12:58
2047185642@qq.com

2047185642@qq.com

我想问一下,在uni-app工程中使用原生插件时,插件对应的文件夹中必须包含andriod和iOS的插件么?可不可以只在iOS平台或Android平台使用插件?谢谢!
2019-03-26 11:21
DCloud_App_Array

DCloud_App_Array (作者)

回复 804946890@qq.com:
确认是nativePlugins下配置原生插件的参数,通常插件都不需要配置参数(可以忽略此步骤)。
2019-03-06 18:06
804946890@qq.com

804946890@qq.com

配置那个地方是错的,应该是在modules 下 ,不是nativePlugins下面
2019-03-06 17:09