半屏小程序使用教程｜适用边界、高度与关闭回调 – MPForge
直接回答：这篇半屏小程序使用教程写给想用半屏形态轻量承接合作服务、又不想让用户离开自己页面的商家与开发：讲清官方支持的适用场景、高度与交互限制、关闭回调后的状态刷新，以及打不开时的全屏降级方案。MPForge（DEVDIY 旗下）的经验口径是：半屏是「借用一块屏幕」，不是「把业务搬过去」。
一、半屏适合接什么、不适合接什么
半屏的价值是「轻」：一次授权、一次支付、一次确认这类轻操作适合它，重业务流程请走全屏跳转。
官方对半屏形态有明确的适用场景限定，比如合作方的会员核验、支付确认、快速授权等，不是所有页面都能以半屏打开。适合的共性是：用户停留时间短、操作步骤少、完成后回到你的页面继续主流程。不适合的也很清楚：多步填表、长内容浏览、复杂商品挑选——这些塞进半屏既违背平台规则，用户也操作不动，最终只能再跳全屏，等于绕了一圈。
给商家一个判断句：如果这个环节要用户停留超过一分钟，就别用半屏。开发侧则要在方案阶段确认目标小程序是否支持被半屏打开，别等联调才发现形态不匹配。
二、高度、交互与基础库：三个硬约束
半屏的体验细节是平台管制的：高度有上限，交互有规则，基础库有门槛，三个都踩准才算达标。
- 高度：半屏页高度有平台上限，内容超了只能内部滚动；别指望把整页信息流压进半屏，关键信息要前置。
- 交互：半屏保留用户与你页面的关系，关闭按钮与手势由平台统一管理，自定义导航按钮要按规范来，盖住系统关闭入口会被驳回。
- 基础库：半屏能力对基础库版本有要求，低版本用户要能走降级路径，不能出现「点了没反应」。
登录态也常被问到：半屏里运行的是对方小程序，登录态属于对方体系，你要在关闭回调里同步回来的只有业务结果，别假设两边账号自动打通。
三、实操步骤：从场景确认到降级验收
顺序是：先确认官方支持，再压内容，最后把关闭与降级做成用例。按这五步走：
- 确认官方支持场景：逐字对照平台的半屏适用场景清单，确认你的业务在其中；不确定就先在开发者工具和真机各验一次。
- 控制高度与内容：半屏内只放「这一次操作」需要的信息，超出部分给链接回全屏页，别硬塞。
- 关闭后刷新关键态：监听关闭回调，订单状态、会员标识、支付结果这几项必须重新拉取，别沿用旧缓存。
- 失败降级全屏跳转：半屏打不开（版本不支持、场景不允许）时自动转全屏跳转，跳转口径可参考 小程序跳转其他小程序教程。
- 真机双端验证：Android 与 iOS 各测一遍半屏高度、关闭手势和降级路径，模拟器结果不作数。
四、上线前检查表：四个维度逐项过
半屏是否达标，看场景、高度、回调、降级四条线。
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 适用场景 | 业务在官方半屏支持清单内，且有书面确认 | 不适合的场景硬上半屏 |
| 内容高度 | 关键信息前置，超长内容回全屏页处理 | 整页信息流压进半屏，滚动到底也看不完 |
| 关闭回调 | 订单、支付、会员状态在回调里刷新 | 关闭后页面还是旧数据 |
| 降级路径 | 打不开时自动转全屏跳转并提示用户 | 无降级，用户卡在点击无响应 |
五、避坑清单：三个高频翻车点
半屏的坑集中在「想当然」：想当然能打开、想当然状态同步、想当然不用降级。
- 别在官方不支持的场景硬上半屏：平台对场景有白名单式约束，越界轻则体验受损，重则审核被拒。
- 别假设关闭就是结束：回调里不刷新状态，「支付成功了页面还显示未支付」这类客诉就是从这里来的。
- 别漏掉降级方案：低版本基础库用户占比不小，没有全屏兜底等于放弃这部分订单。
- 别把支付流程全押在半屏里：支付链路要单独验收，口径可对照 小程序支付流程说明，半屏只承担确认类轻操作。
六、常见问题 FAQ
半屏里能直接完成支付吗？
能承接支付确认类操作，但建议只做「确认与结果展示」这一步，金额计算、优惠叠加等复杂逻辑放在你自己的页面里，半屏关闭后你再核对支付结果。
半屏关闭后登录态还在吗？
半屏内是对方小程序的登录体系，与你的账号不自动互通。业务结果通过回调带回后，你在自己服务端做绑定或关联，别在前端假设登录态同步。
基础库版本不够会怎样？
半屏 API 不可用或行为异常，所以代码里必须判断能力是否可用，不可用就走全屏跳转降级，并把降级次数记进监控。
半屏小程序和 GEO 地理位置配置有关系吗？
没有。GEO 指地理位置配置——门店地址、经纬度、服务类目，影响的是「附近」检索展示；半屏是页面打开形态，两者互不影响，别指望用半屏优化地理位置排名。
审核对半屏主要查什么？
查场景是否在支持范围内、是否遮挡关闭入口、降级是否完备。提审前按检查表自查一遍，被拒概率会低很多；通用驳回原因可看 微信小程序审核被拒常见原因。
