uniapp 微信半屏小程序跳转配置与使用指南

微信小程序支持通过 uni.openEmbeddedMiniProgram(OBJECT) 接口实现半屏跳转功能。

以下是关于在 uniapp 中实现半屏跳转的具体文档说明。

在 uniapp 开发项目中，开发者需在全局配置 manifest.json 的 mp-weixin 节点下，添加 embeddedAppIdList 字段，并声明允许半屏跳转的小程序 AppID。若未进行此配置，系统将自动切换为普通的全屏小程序跳转模式（半屏功能若不符合条件，将自动降级为全屏跳转以保证兼容性）。配置示例如下：

// manifest.json
{
		"mp-weixin" : {
		   "embeddedAppIdList": ["wxe5f52902cf4de896"]//需要半屏跳转的小程序appid
		}
	}

代码层面的调用示例如下：

uni.openEmbeddedMiniProgram({
	appId: '',
	path: 'pages/index/index?id=123',
	extraData: {
		'data1': 'test'
	},
	success(res) {
    // 打开成功
	}
})

使用限制

半屏跳转存在多项限制，若不符合以下所有条件，系统将自动切换为普通（全屏）小程序跳转模式，但这不会影响用户的正常使用体验：

• 目标半屏小程序必须通过来源小程序的调用申请，开发者可在 小程序管理后台「设置」-「第三方设置」-「半屏小程序管理」板块发起申请，最多可以申请10个小程序；
• 基础库版本低于 3.1 时，被半屏打开的小程序需在 app.json 的 embeddedAppIdList 字段中进行声明；
• 当前小程序必须处于竖屏模式；
• 被半屏跳转的目标小程序必须是非个人主体性质的小程序（不包含小游戏）。

后台配置步骤如下： 点击进入小程序管理后台进行登录操作。

完成上述配置后，即可调用半屏跳转 API。 在此基础上，开发者可封装通用方法以便复用。需注意，若 API 可用但后台配置未完成，调用 openEmbeddedMiniProgram 接口时半屏效果将不生效，系统会自动转换为全屏跳转。

注意：半屏跳转必须绑定在 @tap 或 @click 事件上触发，不能通过模态框（如 uni.showModal的确认/取消事件）的确认或取消事件来调用。若通过模态框事件触发半屏跳转，默认将表现为全屏跳转。

// method.js
export function openEmbeddedMiniProgram(data) {
    let openMiniProgram = wx.navigateToMiniProgram;
     // canIUse检查openEmbeddedMiniProgram在此场景是否可用
    if (uni.canIUse('openEmbeddedMiniProgram')) {
        openMiniProgram = wx.openEmbeddedMiniProgram;
    }
    openMiniProgram(data);
}
// main.js
import Vue from 'vue';
import { openEmbeddedMiniProgram } from './method.js';
Vue.prototype.$openEmbeddedMiniProgram = openEmbeddedMiniProgram;
// 调用的事件
this.$openEmbeddedMiniProgram({
    appId: '需要跳转小程序的appid',
    path: '需要跳转小程序的指定路径/'
});

官方演示效果如下：

至此，关于 uniapp 微信半屏跳转的使用介绍完毕。如需了解更多 uniapp 微信半屏跳转相关内容，请搜索本站往期文章或继续浏览后续文章，感谢大家的支持！