微信半屏小程序跳转功能详解

栏目： mina 发布时间：2025-01-10

在微信小程序的开发中，为了满足用户在不同场景下的快捷操作需求，微信官方自基础库2.20.1版本起，推出了打开半屏小程序的功能。这一功能允许一个小程序以半屏的形态跳转至另一个小程序，从而在不完全离开当前小程序的情况下，完成一些特定的快捷操作。下面，我们将对这一功能进行详细的介绍。

一、功能概述

半屏小程序跳转功能主要适用于那些需要频繁调用其他小程序进行某些快捷操作的场景。通过这一功能，用户可以在不中断当前小程序使用的情况下，快速打开另一个小程序进行操作，然后再返回到原小程序。这大大提高了用户的使用效率和体验。

二、调用流程

要实现半屏小程序跳转功能，开发者需要按照以下步骤进行操作：

配置embeddedAppIdList字段（2.23.1以下版本基础库）：在全局配置文件app.json中，开发者需要声明需要半屏跳转的小程序的appId。这些appId需要被添加到embeddedAppIdList字段中。如果不进行配置，系统将默认使用普通的小程序跳转方式。

配置示例如下：

{
  "embeddedAppIdList": ["wxe5f52902cf4de896"]
}

需要注意的是，从2.23.1版本起，这一配置已经不再需要。

调用wx.openEmbeddedMiniProgram方法：开发者可以通过调用wx.openEmbeddedMiniProgram方法来实现半屏跳转小程序的功能。这一方法需要传入目标小程序的appId以及其他相关的参数。

wx.openEmbeddedMiniProgram API用于打开半屏小程序。以下是该API的详细参数说明：

appId（必填）：要打开的小程序的appId。
path（非必填）：打开的页面路径，如果为空则打开首页。path中?后面的部分会成为query，可以在小程序的App.onLaunch、App.onShow和Page.onLoad的回调函数或小游戏的wx.onShow回调函数、wx.getLaunchOptionsSync中获取到query数据。
extraData（非必填）：需要传递给目标小程序的数据，目标小程序可在App.onLaunch、App.onShow中获取到这份数据。
envVersion（非必填）：要打开的小程序版本。仅在当前小程序为开发版或体验版时此参数有效。
shortLink（非必填）：小程序链接，当传递该参数后，可以不传appId和path。链接可以通过【小程序菜单】->【复制链接】获取。
verify（非必填）：校验方式。
noRelaunchIfPathUnchanged（非必填）：不reLaunch目标小程序，直接打开目标跳转的小程序退后台时的页面，需满足目标跳转的小程序生命周期未被销毁，且目标当次启动的path、query与上次启动相同。
allowFullScreen（非必填）：打开的小程序是否支持全屏。
success（非必填）：接口调用成功的回调函数。
fail（非必填）：接口调用失败的回调函数。
complete（非必填）：接口调用结束的回调函数（调用成功、失败都会执行）。

调用wx.openEmbeddedMiniProgram API

在你的小程序代码中，通过调用wx.openEmbeddedMiniProgram API来实现半屏跳转。

wx.openEmbeddedMiniProgram({
  appId: '目标小程序的appId',
  path: '打开的页面路径',
  extraData: {
    // 需要传递给目标小程序的数据
  },
  success: function (res) {
    // 调用成功后的回调
    console.log('调用成功', res);
  },
  fail: function (err) {
    // 调用失败后的回调
    console.error('调用失败', err);
  },
  complete: function () {
    // 调用结束后的回调（无论成功或失败都会执行）
    console.log('调用结束');
  }
});

处理目标小程序的接收逻辑

在目标小程序中，你需要在App.onLaunch或App.onShow中获取传递过来的extraData数据，并根据需要进行处理。

App({
  onLaunch: function (options) {
    if (options.extraData) {
      // 处理传递过来的数据
      console.log('接收到的数据', options.extraData);
    }
  },
  onShow: function (options) {
    // 其他逻辑处理
  }
});

判断小程序是否被半屏打开：被半屏打开的小程序可以通过调用wx.getEnterOptionsSync方法读取apiCategory参数，当该参数的值为embedded时，可以判断此时小程序是被半屏打开的。
返回原小程序：被半屏打开的小程序在完成操作后，可以通过调用wx.navigateBackMiniProgram方法返回到上一个小程序。

三、使用限制

虽然半屏小程序跳转功能为用户带来了极大的便利，但在使用过程中也需要注意以下限制：

申请限制：被半屏跳转的小程序需要通过来源小程序的调用申请。开发者可以在小程序管理后台的「设置」-「第三方设置」-「半屏小程序管理」板块发起申请，最多可以申请10个小程序。
版本限制：对于2.23.1版本以下的基础库，被半屏打开的小程序需要在app.json的embeddedAppIdList字段中声明。而从2.23.1版本起，这一限制已经被取消。
屏幕方向限制：当前小程序需要为竖屏模式才能使用半屏跳转功能。
小程序类型限制：被半屏跳转的小程序需要为非个人主体小程序（不含小游戏）。这一限制确保了半屏跳转功能只适用于那些有正规运营主体和资质的小程序。

四、总结

半屏小程序跳转功能为微信小程序的开发和使用带来了全新的体验。通过这一功能，开发者可以更加灵活地设计小程序的交互流程，提高用户的使用效率和满意度。同时，也需要注意在使用过程中遵守相关的限制和规定，以确保功能的正常运行和用户的良好体验。

本文地址：https://www.tides.cn/p_mina-openEmbeddedMiniProgram

微信半屏小程序跳转功能详解

推荐阅读