微信【跳转】相关API详细整理，含注意事项

1.wx.restartMiniProgram(Object object) | 重启

核心功能及注意点

清空小程序的运行内存和临时数据；
终止当前所有页面的生命周期函数，当前所有页面的 onUnload 生命周期函数会被触发；
从配置页面重新启动；
不会清除本地存储；
类似于手动杀掉小程序重新进入的效果；

应用场景

异常处理：小程序出现页面卡死、逻辑错误时，通过重启实现快速恢复。
多账号切换：用户切换账号后，需要清除当前账号的临时数据并重新加载首页。
版本更新感知：小程序发布新版本后，引导用户重启以加载最新代码。
流程闭环：完成支付、表单提交等流程后，跳转到结果页并重启小程序。
状态重置 + 定向跳转：需要重置小程序状态，同时不希望回到首页，而是跳转到其他页面。
特定入口唤起：通过分享卡片、扫码等方式进入小程序后，希望用户操作后回到特定页面。

使用示例

javascript 复制代码

// 完整调用示例
wx.restartMiniProgram({
  // 指定重启后跳转的页面路径（必填，否则默认首页）
  path: 'pages/result/index',
  
  // 页面参数（可选，类似 URL query 参数）
  query: {
    orderId: '123456',
    status: 'success'
  },
  
  // 重启成功的回调
  success(res) {
    console.log('重启成功', res);
  },
  
  // 重启失败的回调
  fail(err) {
    console.error('重启失败', err);
    // 可添加降级方案，如跳转到首页
    wx.switchTab({ url: '/pages/index/index' });
  },
  
  // 无论成功失败都会执行的回调
  complete() {
    console.log('重启操作完成');
  }
});

2.wx.openOfficialAccountProfile(Object object) | 打开公众号

核心功能及注意点

在小程序内直接打开关联公众号的资料页；
注意：必须满足的前置条件-小程序与公众号已关联，同一主体下的小程序和公众号可直接关联，非同一主体的小程序和公众号需通过授权关联。
调用该接口后，小程序进入后台运行状态（触发 onShow 生命周期函数）。
用户从公众号返回小程序时，小程序恢复前台运行（触发 onShow 生命周期函数）。

应用场景

跳转公众号，引导用户关注公众号参与抽奖、打卡等活动。

使用示例

javascript 复制代码

const openOfficialAccountProfile = () => {
  // 跳转到公众号个人主页
  wx.openOfficialAccountProfile({
    // 公众号的微信号
    username: "yzwdkamsn557",

    // 跳转成功回调
    success(res) {
      console.log("跳转成功", res);
    },

    // 跳转失败回调
    fail(err) {
      console.error("跳转失败", err);
    },

    complete() {
      console.log("跳转操作完成");
    },
  });
};

3.wx.openOfficialAccountArticle(Object object) | 打开任意公众号文章

核心功能及注意点

在小程序内直接打开关联公众号的指定文章；
文章必须是已发布状态（草稿状态无法打开）；
文章必须是公开可见的（不支持私密文章或仅特定用户可见的文章）；
URL 必须是公众号文章的原始链接（以 mp.weixin.qq.com/s/ 开头）；

应用场景

在小程序内引导用户阅读公众号的文章。
如何判断用户是否已阅读文章？该接口本身不提供阅读状态的判断可通过以下方式间接获取：在文章中引导用户返回小程序，并携带特定参数通过微信开放平台的 UnionID 机制，关联用户在小程序和公众号的行为使用公众号的数据分析接口（需认证公众号）获取文章阅读数据

使用示例

javascript 复制代码

const openOfficialAccountArticle = () => {
  wx.openOfficialAccountArticle({
    // 文章链接（必填）
    // 文章必须是已发布状态（草稿状态无法打开）；文章必须是公开可见的（不支持私密文章或仅特定用户可见的文章）； 
    // URL 必须是公众号文章的原始链接（以 https://mp.weixin.qq.com/s/ 开头）；
    url: "https://mp.weixin.qq.com/s/oI95r2qFLl38r2ZmcAueQA",

    // 成功回调
    success(res) {
      console.log("文章打开成功", res);
    },

    // 失败回调
    fail(err) {
      console.error("文章打开失败", err);
      // 可添加降级方案
    },

    // 完成回调
    complete() {
      console.log("打开文章操作完成");
    },
  });
};

4.wx.openEmbeddedMiniProgram(Object object) | 打开半屏小程序

核心功能及注意点

在小程序内直接打开被关联的其他小程序；
支持传递参数到被打开的小程序；
用户可在被打开的小程序内进行操作，完成后可直接返回当前小程序；
调用该接口后，当前小程序的页面会进入后台状态，但不会触发 onUnload 生命周期函数
用户从被嵌入小程序返回时，当前小程序的页面会恢复前台状态，触发 onShow 生命周期函数
被嵌入的小程序必须在 app.json 中配置 embeddedApp 字段，声明支持被嵌入；

javascript 复制代码

// 被嵌入小程序的 app.json
{
  "embeddedApp": {
    "enable": true
  }
}

应用场景

当前小程序的功能无法满足用户全部需求时，嵌入其他专业小程序提供补充服务；
通过互相嵌入，实现小程序之间的流量互通；
必须满足的前置条件-小程序已关联；

使用示例

javascript 复制代码

const openEmbeddedMiniProgram = () => {
  // 完整参数调用示例
  wx.openEmbeddedMiniProgram({
    // 半屏小程序的 AppID（必填）
    appId: "wxb69897679e7aadd6",

    // 被嵌入小程序的页面路径（可选，默认为首页）
    path: "pages/index/index",

    // 传递给被嵌入小程序的参数（可选）
    extraData: {
      fromApp: "当前小程序标识",
      userId: "123456",
      orderId: "ORD7890",
    },

    // 接口调用成功的回调
    success(res) {
      console.log("成功打开嵌入小程序", res);
    },

    // 接口调用失败的回调
    fail(err) {
      console.error("打开嵌入小程序失败", err);
      // 可添加降级方案
    },

    // 接口调用完成的回调（成功或失败都会执行）
    complete() {
      console.log("打开嵌入小程序操作完成");
    },
  });
};

5.wx.onEmbeddedMiniProgramHeightChange(function listener) | 监听半屏小程序可视高度

核心功能及注意点

当一个小程序作为嵌入方打开另一个被嵌入的小程序时，被嵌入小程序的内容可能会动态变化（如加载更多内容、展开折叠面板等），导致其高度发生变化。这个接口允许嵌入方实时获取被嵌入小程序的高度变化，从而调整自身界面布局。
建议在嵌入方小程序的页面加载时（如 onLoad 或 onReady 生命周期函数中）注册监听。
确保在被嵌入小程序打开前已注册监听，避免错过首次高度变化。
可使用 wx.offEmbeddedMiniProgramHeightChange 移除监听。
建议在页面卸载时（如 onUnload 生命周期函数中）移除监听，避免内存泄漏。
注意：
1.接口返回的高度单位为 px（像素），若嵌入方使用其他单位（如 rpx）进行布局，需要进行单位转换。

javascript 复制代码

// px 转 rpx 示例（假设设计稿宽度为 750rpx）
const rpxHeight = res.height * (750 / wx.getSystemInfoSync().windowWidth);
this.setData({
  embeddedHeight: rpxHeight
});

2.同一页面可以注册多个监听函数，当高度变化时，所有注册的监听函数都会被触发，建议避免重复注册监听，可在注册前先移除已有的监听。
3.高度变化频繁时（如滚动、动画过程中），可能会导致频繁触发回调，建议在回调函数中添加节流或防抖处理，避免过度渲染。

javascript 复制代码

// 防抖处理示例
let timer = null;
wx.onEmbeddedMiniProgramHeightChange(function(res) {
  clearTimeout(timer);
  timer = setTimeout(() => {
    this.setData({
      embeddedHeight: res.height
    });
  }, 100);
});

应用场景

内容动态加载：被嵌入小程序加载更多内容或展开折叠面板时，嵌入方需要调整界面高度。
表单交互：被嵌入小程序中的表单展开或收起时，嵌入方需要同步调整界面。
响应式布局：根据不同设备屏幕尺寸或横竖屏切换，被嵌入小程序的高度发生变化动画效果：被嵌入小程序执行动画（如展开 /收起动画）时，嵌入方需要平滑调整界面。
图片加载：被嵌入小程序中的图片加载完成后，高度可能会发生变化。

使用示例

javascript 复制代码

// 基本调用格式
wx.onEmbeddedMiniProgramHeightChange(function(res) {
  // 高度变化时的回调函数
  console.log('被嵌入小程序高度变化', res);
  
  // res 参数包含以下属性：
  // - height: 被嵌入小程序的最新高度（单位：px）
  // - initialHeight: 被嵌入小程序的半屏小程序初始高度
  
  const newHeight = res.height;
  const initialHeight= res.initialHeight;
  
  // 根据新高度调整界面布局
  this.setData({
    embeddedHeight: newHeight
  });
});

6.wx.offEmbeddedMiniProgramHeightChange(function listener)| 移除半屏小程序可视高度变化事件的监听

核心功能及注意点

移除之前注册的被嵌入小程序高度变化事件的监听函数，释放相关资源，避免内存泄漏。
前置：已通过 wx.onEmbeddedMiniProgramHeightChange 注册了监听函数

应用场景

页面卸载：当前页面被关闭或卸载时，移除监听以释放资源。
条件监听：根据业务逻辑，只在特定条件下监听高度变化，条件不满足时移除监听。
资源优化：当不再需要关注被嵌入小程序的高度变化时，主动移除监听以优化性能。
防止重复监听：在重新注册监听前，先移除已有的监听，避免重复触发回调。

使用示例

javascript 复制代码

  //const listener = function (res) { console.log(res) }
  //wx.onEmbeddedMiniProgramHeightChange(listener)
  //wx.offEmbeddedMiniProgramHeightChange(listener) // 需传入与监听时同一个的函数对象

7.wx.navigateToMiniProgram(Object object)| 跳转另一个小程序

核心功能及注意点

在当前小程序内跳转到其他小程序。
目标小程序必须已经在微信公众平台注册并审核通过。
用户必须已授权当前小程序使用该功能（通常在首次调用时会自动请求授权）。
目标小程序必须在 app.json 中配置了允许被跳转的页面。
若目标小程序设置了隐私权限，可能需要用户额外授权。
在微信公众平台的 "开发管理 → 开发设置 → 跳转小程序" 中添加目标小程序的 AppID。
调用该接口后，当前小程序会进入后台状态，触发 onShow 生命周期函数。
用户从目标小程序返回时，当前小程序会恢复前台状态，再次触发 onShow 生命周期函数。
数据传递与接收：通过 extraData 参数传递数据到目标小程序，目标小程序可在 app.js 的 onLaunch 或 onShow 生命周期函数中获取传递的数据。

javascript 复制代码

// 目标小程序的 app.js
onLaunch(options) {
  console.log('接收来自跳转方的数据', options.query);
  // 输出: { fromApp: '当前小程序标识', userId: '123456', orderId: 'ORD7890' }
}

如何获取用户从目标小程序返回的信息？ 当用户从目标小程序返回时，当前小程序的 onShow 生命周期函数会被触发，可通过 options.scene 和 options.referrerInfo 获取返回信息。

javascript 复制代码

// 当前小程序的 app.js
onShow(options) {
  console.log('小程序进入前台', options);
  
  // 判断是否从小程序返回
  if (options.scene === 1038) {
    console.log('从小程序返回', options.referrerInfo);
    // options.referrerInfo.appId: 来源小程序的 AppID
    // options.referrerInfo.extraData: 来源小程序传递的额外数据
  }
}

如何实现从目标小程序自动返回原小程序？ 目标小程序可使用 wx.navigateBackMiniProgram 接口返回原小程序。

javascript 复制代码

// 目标小程序中返回原小程序
wx.navigateBackMiniProgram({
  extraData: {
    result: 'success',
    data: { /* 返回的数据 */ }
  },
  success: function(res) {
    console.log('成功返回原小程序', res);
  }
});

应用场景

功能互补、生态整合、服务闭环

使用示例

javascript 复制代码

// 完整参数调用示例
wx.navigateToMiniProgram({
  // 目标小程序的 AppID（必填）
  appId: 'wx1234567890abcdef',
  
  // 目标小程序的页面路径（可选，默认为首页）
  path: 'pages/index/index',
  
  // 传递给目标小程序的参数（可选）
  extraData: {
    fromApp: '当前小程序标识',
    userId: '123456',
    orderId: 'ORD7890'
  },
  
  // 跳转目标小程序的版本（可选，默认值为 release）
  envVersion: 'release', // 有效值：develop（开发版）、trial（体验版）、release（正式版）
  
  // 接口调用成功的回调
  success(res) {
    console.log('成功跳转到目标小程序', res);
  },
  
  // 接口调用失败的回调
  fail(err) {
    console.error('跳转目标小程序失败', err);
    // 可添加降级方案
  },
  
  // 接口调用完成的回调（成功或失败都会执行）
  complete() {
    console.log('跳转目标小程序操作完成');
  }
});

8.wx.navigateBackMiniProgram(Object object)| 返回到上一个小程序

核心功能及注意点

返回到上一个小程序。只有在当前小程序是被其他小程序打开时可以调用成功。
若当前小程序不是通过跳转进入的（如直接打开），调用该接口会失败

应用场景

服务完成返回：在目标小程序中完成操作后（如支付成功、信息提交等），自动返回原小程序。
数据同步：将目标小程序中的操作结果（如支付状态、表单提交结果等）返回给原小程序。

使用示例

javascript 复制代码

  // 完整参数调用示例
  wx.navigateBackMiniProgram({
    // 传递回原小程序的数据（可选）
    extraData: {
      result: "success",
      payStatus: "paid",
      transactionId: "TXN123456",
    },

    // 接口调用成功的回调
    success(res) {
      console.log("成功返回原小程序", res);
    },

    // 接口调用失败的回调
    fail(err) {
      console.error("返回原小程序失败", err);
      // 可添加降级方案
    },

    // 接口调用完成的回调（成功或失败都会执行）
    complete() {
      console.log("返回原小程序操作完成");
    },
  });

9.wx.exitMiniProgram(Object object)| 退出

核心功能及注意点

调用该接口后，用户会返回到微信聊天界面或其他调用入口。
调用该接口后，小程序会触发 onShow、onHide 和 onUnload 生命周期函数。
小程序的所有页面会被销毁，内存资源被释放。

应用场景

直接退出小程序。

使用示例

javascript 复制代码

// 基本调用格式
wx.exitMiniProgram({
  // 接口调用成功的回调
  success(res) {
    console.log('成功退出小程序', res);
  },
  
  // 接口调用失败的回调
  fail(err) {
    console.error('退出小程序失败', err);
    // 可添加降级方案
  },
  
  // 接口调用完成的回调（成功或失败都会执行）
  complete() {
    console.log('退出小程序操作完成');
  }
});

相关接口对比

接口名称	功能差异	适用场景
wx.restartMiniProgram	完全重启小程序，从指定页面加载，清空运行时数据	状态重置 + 定向跳转
wx.openOfficialAccountProfile	打开公众号资料页，进入后台运行，需关联	跳转公众号主页
wx.openOfficialAccountArticle	打开任意公众号文章，进入后台运行状态	跳转公众号文章
wx.openEmbeddedMiniProgram	打开半屏小程序，需关联	功能互补、生态整合、服务闭环
wx.onEmbeddedMiniProgramHeightChange	监听被嵌入小程序的高度变化事件，获取最新高度	需要根据被嵌入小程序高度动态调整布局
wx.offEmbeddedMiniProgramHeightChange	移除被嵌入小程序的高度变化事件	不再需要监听高度变化时释放资源
wx.navigateToMiniProgram	跳转到其他小程序，当前小程序进入后台，用户需手动返回	小程序之间的普通跳转
wx.navigateToMiniProgram	返回上一个小程序	完成目标小程序操作后返回原小程序
wx.exitMiniProgram	退出当前小程序	任务完成后退出、错误处理退出等