为了便于理解uni小程序API的使用，需要知道两种uni-app项目，一种是uni-app宿主App项目（简称“宿主App”），一种是uni-app小程序App项目（简称“uni小程序”），以下将分别从这两种项目作为调用者的角度来介绍相关API。

宿主App使用的API

宿主App是通过uniMP模块管理uni小程序，云端打包时需要在宿主App项目的manifest.json中配置使用uni小程序模块。 在"app-plus"->"modules"节点下添加"UniMP"模块，示例如下：

  "app-plus" : {
    "modules" : {
        "UniMP": {
          "description": "uni小程序"
        }
    },
    //...
  }

HBuilderX中自带的标准基座已经包含uni小程序模块，可以直接调用uni小程序相关API
配置后需提交云端打包后才能生效，真机运行时推荐使用自定义调试基座

加载uniMP模块

在调用uni小程序API时需先调用uni.requireNativePlugin方法加载uni小程序管理模块。
示例如下：

const mp = uni.requireNativePlugin('uniMP');
//通过mp可调用方法操作uni小程序
mp.openUniMP({
  appid:'小程序的appid'
});

注：如果返回的mp为undefined，说明当前环境不支持uni小程序

installUniMP(options,callback)

通过wgt安装uni小程序到宿主App中，示例如下：

mp.installUniMP({
  appid: 'uni小程序的appid',
  wgtFile: 'uni小程序的wgt文件路径'
}, (ret)=>{
  console.log('installUniMP: '+JSON.stringify(ret));
});
options参数说明

JSON Object类型

|属性|类型 |默认值|必填|说明|
|:--|:--|:--|:--|:--|
appid|String|无|是|uni小程序的appid|
wgtFile|String|无|是|wgt资源文件路径|
password|String|无|否|wgt解压密码|

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|type|String|"success" 表示成功， "fail" 表示失败|
|code|Number| 成功返回 0，失败返回相应 code 码|
|message|String|失败描述|

openUniMP(options,callback)

打开uni小程序，示例如下：

mp.openUniMP({
  appid: 'uni小程序的appid'
}, (ret)=>{
  console.log('openUniMP: '+JSON.stringify(ret));
});
options参数说明

JSON Object类型

|属性|类型 |默认值|必填|说明|
|:--|:--|:--|:--|:--|
|appid|String|无|是|uni小程序的appid|
|icon|String|无|否|启动小程序 splash 页面显示的图片，默认显示 app logo|
|path|String|无|否|HBuilderX3.3.1+版本新增
打开的页面路径，如果为空则打开首页。path 中 ? 后面的部分会成为 query，注意：传入此参数后应用会重启|
|extraData|Object|无|否|HBuilderX3.3.1+版本新增
需要传递给目标小程序的数据。小程序接收参考uni小程序中获取启动参数|
|fromAppid|String|无|否|HBuilderX3.3.1+版本新增
打开uni小程序的来源appid|
|scene| Number|无|否|HBuilderX3.3.1+版本新增
启动小程序的场景值，由宿主自定义| |openMode|String|present|否|HBuilderX3.5.1+版本新增
启动小程序的动画方式
present : 从当前页面下面打开小程序
push : 从当前页面右侧打开小程序 (仅ios支持) |enableGestureClose| Boolean |true|否|HBuilderX3.5.1+版本新增
是否开启手势关闭小程序 默认开启 (仅ios支持) |enableShowAnimated| Boolean |true|否|HBuilderX3.5.1+版本新增
是否开启打开小程序时的动画 默认开启 (仅ios支持) |enableHideAnimated| Boolean |true|否|HBuilderX3.5.1+版本新增
是否开启关闭小程序时的动画 默认开启 (仅ios支持) |enableBackground| Boolean |true|否|HBuilderX3.5.1+版本新增
是否开启小程序后台运行的能力 默认开启 如果设置为 false 退出小程序后小程序立即会被释放，下次打开后会重新加载

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|type|String|"success" 表示成功， "fail" 表示失败|
|code|Number| 成功返回 0,失败返回相应 code 码|
|message|String|失败描述|

closeUniMP(appid,callback)

HBuilderX3.4.3+版本新增支持

关闭已经运行的uni小程序，示例如下：

mp.closeUniMP('uni小程序的appid', (ret)=>{
  console.log('closeUniMP: '+JSON.stringify(ret));
});
参数说明

|属性|类型 |默认值|必填|说明|
|:--|:--|:--|:--|:--|
|appid|String|无|是|uni小程序的appid|
|callback|Function|无|是|关闭操作结果回调函数|

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|type|String|"success" 表示成功， "fail" 表示失败|
|code|Number| 成功返回 0,失败返回相应 code 码|
|message|String|失败描述|

hideUniMP(appid,callback)

HBuilderX3.4.3+版本新增支持

隐藏运行在前台的uni小程序，示例如下：

mp.hideUniMP('uni小程序的appid', (ret)=>{
  console.log('hideUniMP: '+JSON.stringify(ret));
});
参数说明

|属性|类型 |默认值|必填|说明|
|:--|:--|:--|:--|:--|
|appid|String|无|是|uni小程序的appid|
|callback|Function|无|是|隐藏操作结果回调函数|

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|type|String|"success" 表示成功， "fail" 表示失败|
|code|Number| 成功返回 0,失败返回相应 code 码|
|message|String|失败描述|

showUniMP(appid,callback)

HBuilderX3.4.3+版本新增支持

将运行在后台的uni小程序切换到前台显示，示例如下：

mp.showUniMP('uni小程序的appid', (ret)=>{
  console.log('showUniMP: '+JSON.stringify(ret));
});
参数说明

|属性|类型 |默认值|必填|说明|
|:--|:--|:--|:--|:--|
|appid|String|无|是|uni小程序的appid|
|callback|Function|无|是|显示操作结果回调函数|

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|type|String|"success" 表示成功， "fail" 表示失败|
|code|Number| 成功返回 0,失败返回相应 code 码|
|message|String|失败描述|

getUniMPVersion(appid,callback)

获取安装的uni小程序版本信息，示例如下：

mp.getUniMPVersion('uni小程序的appid', (ret)=>{
  console.log('getUniMPVersion: '+JSON.stringify(ret));
});
参数说明

|属性|类型 |默认值|必填|说明|
|:--|:--|:--|:--|:--|
|appid|String|无|是|uni小程序的appid|
|callback|Function|无|是|获取版本信息回调函数|

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|type|String|"success" 表示成功， "fail" 表示失败|
|code|Number| 成功返回 0,失败返回相应 code 码|
|message|String|失败描述|
|versionInfo|Object|uni小程序的版本信息，参考versionInfo参数说明|

versionInfo参数说明

|属性|类型 |说明|
|:--|:--|:--|
|name|String|应用版本名称 (对应 manifest.json 中的 versionName)|
|code|String|应用版本号 (对应 manifest.json 中的 versionCode)|

onUniMPEventReceive(callback)

监听uni小程序发送的event事件，建议在宿主App的应用生命周期onLaunch中进行监听。在uni小程序中调用uni.sendHostEvent发送event事件后触发。

示例如下：

export default {
  onLaunch: function() {
    console.log('Host App Launch');
    
    //监听uni小程序发送的事件
    mp.onUniMPEventReceive(ret=>{
			console.log('Receive event from MP: '+JSON.stringify(ret));
    });
  },
  //...
}
callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|fromAppid|String|发送事件的uni小程序的appid|
| event |String|事件名称，uni小程序中调用sendHostEvent传入的event参数|
| data |String 或 Object|传递的数据，小程序中调用sendHostEvent传入的data参数|

sendUniMPEvent(appid,event,data,callback)

HBuilderX3.3.9+版本新增支持：宿主在小程序运行期间向其发送数据进行通讯
注：uni小程序必须处于运行状态，否则会发送失败

宿主App向uni小程序发送event事件，在uni小程序中调用uni.onHostEventReceive监听。

示例如下：

mp.sendUniMPEvent('uni小程序的appid', 'event事件名称', '要传递的数据', (ret) => {
  //发送消息成功回调
  console.log('Send event to MP: '+JSON.stringify(ret));
});
参数说明

|参数|类型 |说明|
|:--|:--|:--|
| appid |String|目标小程序appid|
| event |String|事件名称|
| data |String 或 Object|传递的数据|

setDefaultMenuItems(options,callback)

HBuilderX3.4.3+版本新增支持

设置胶囊按钮菜单 ActionSheet 项

示例如下：

mp.setDefaultMenuItems({
	items: [{
		title: "关于",
		id: "about"
	}, {
		title: "分享",
		id: "share"
	}]
}, ret => {
	if (ret.id == "about") {
		console.log("点击了 关于")
	}
})
参数说明

|属性|类型 |默认值|必填|说明|
|:--|:--|:--|:--|:--|
|options|object|无|是|uni小程序的appid|
|callback|Function|无|是|获取版本信息回调函数|

options 参数说明
属性 类型 说明
items Array.<actionSheetItem> ActionSheet 项
actionSheetItem 参数说明

|属性|类型|说明|
|:--|:--|:--|
|title|String|ActionSheet 按钮的标题|
|id|String|点击 ActionSheet 按钮返回的标识|

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
appid|String|目标小程序的appid|
id|String|成功时存在，返回被点击 ActionSheet 按钮对应的标识|

uni小程序使用的API

获取启动参数

HBuilderX3.3.1+版本新增支持

宿主App启动uni小程序传入的extraData参数可在小程序项目App.vue的应用生命周期onLaunch、onShow中获取，

示例如下：

//首次启动
onLaunch: function(info) {
	console.log('App Launch:',info);
}
//从后台切换到前台
onShow: function(info) {
	console.log('App Launch:',info);
}
info参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|path |String|打开的页面路径|
|query |Object| 页面参数|
|scene | Number |启动小程序的场景值|
|referrerInfo| Object |启动小程序时传递的数据，参考ReferrerInfo |

ReferrerInfo参数说明

|属性|类型 |说明|
|:--|:--|:--|
|appId |String| 打开uni小程序时的来源应用appid|
|extraData |Object| 启动时传递的数据|

uni.sendHostEvent(event,data,ret,callback)

uni小程序向宿主App发送event事件，在宿主App中可调用onUniMPEventReceive监听接收event事件。

示例如下：

uni.sendHostEvent(event, data, (ret) => {
  //发送消息成功回调
  console.log('Send event to Host: '+JSON.stringify(ret));
});

参数说明

|参数|类型 |说明|
|:--|:--|:--|
| event |String|事件名称|
| data |String 或 Object|传递的数据|
| callback | Function(ret) | 操作回调函数，ret参数为SendHostEventRet类型 |

callback回调参数说明

JSON Object类型

|属性|类型 |说明|
|:--|:--|:--|
|type|String|"success" 表示成功， "fail" 表示失败|
|code|Number| 成功返回 0,失败返回相应 code 码|

uni.onHostEventReceive(callback)

uni小程序监听宿主App发送的event事件，建议在uni小程序应用生命周期onLaunch中监听。在uni宿主App中调用sendUniMPEvent发送event事件后触发。

示例如下：

export default {
  onLaunch: function() {
    console.log('App Launch');
    
    //监听宿主App通讯数据
    uni.onHostEventReceive((event,data)=>{
			console.log('Receive event('+event+') from HOST: '+JSON.stringify(data));
    });
  },
  //...
}

callback回调参数说明

|参数|类型 |说明|
|:--|:--|:--|
| event |String|事件名称，宿主调用sendUniMPEvent传入的event参数|
| data |String 或 Object|传递的数据，宿主调用sendUniMPEvent传入的data参数|