Experience Shell 方案

本文档用于定义小程序中 H5 定制内容的承载方式。目标不是把 H5 做成真正的同页弹窗，而是做成：

独立页面路由
原生壳子控制外观
web-view 只负责内容区

这样既保留了 H5 的定制能力，也能让用户感受更接近“弹窗”或“抽屉”。

1. 设计目标

当前 H5 内容页已经能打开，但整页全屏切换比较生硬，用户体验不够好。
新的 experience-shell 目标是：

视觉上像弹窗
保持原生关闭、回退、失败兜底逻辑
不把地图主页面和 web-view 强绑在一起
为后续结果页 H5、文创内容 H5 复用

2. 核心原则

2.1 不做真正同页 H5 弹窗

微信小程序里的 web-view 更适合放在独立页面中承载。
不要尝试把 web-view 直接叠在地图页上方做真弹窗，否则后续很容易遇到：

层级冲突
手势冲突
iOS / Android 表现不一致
遮罩和关闭逻辑变脏

2.2 原生壳子 + H5 内容区

最终结构应该是：

原生遮罩
原生标题栏
原生关闭按钮
web-view 内容区

也就是：

experience-shell
  ├─ backdrop
  ├─ native header
  └─ web-view body

3. 支持的展示方式

第一阶段只支持 3 种：

sheet
dialog
fullscreen

3.1 `sheet`

适合：

打点后的文创内容
拍照任务
轻互动内容

视觉：

自底部升起
圆角卡片
半透明暗背景

3.2 `dialog`

适合：

结果页
中短内容
重要说明

视觉：

居中大卡片
更聚焦

3.3 `fullscreen`

适合：

长内容
强定制专题页
复杂表单/小游戏

4. 配置结构

H5 内容配置建议支持：

{
  "type": "h5",
  "url": "https://example.com/content/control-1",
  "bridge": "content-v1",
  "presentation": "sheet"
}

字段说明：

type 当前支持 native / h5
url H5 页面地址
bridge bridge 版本
presentation 展示方式，支持：
- sheet
- dialog
- fullscreen

默认值建议：

内容体验默认 sheet
结果页默认 dialog

5. 原生壳子职责

原生壳子负责：

遮罩
标题、副标题
关闭按钮
页面进入/退出动画
H5 打开失败回退

原生壳子不负责：

H5 页面内部业务逻辑
H5 具体视觉排版

6. 关闭与回退逻辑

6.1 原生关闭

原生必须始终支持：

右上/头部关闭
返回键关闭
失败时自动关闭并回退

6.2 H5 请求关闭

H5 可以通过 bridge 发：

close

然后由原生统一关闭壳子页。

6.3 H5 失败回退

如果出现：

URL 无效
页面打不开
bridge 初始化失败

统一回退到：

原生内容卡
原生结果页

7. 动画建议

`sheet`

遮罩淡入
面板自下而上出现

`dialog`

遮罩淡入
面板轻微放大进入

`lite`

在低端机或 lite 模式下：

只保留 opacity
降低位移动画强度

8. 推荐接入顺序

第一阶段

先把当前 experience-webview 升级成 shell
先支持 sheet
先接 content-v1

第二阶段

补 dialog
结果页 H5 开始复用壳子

第三阶段

主题样式可配置
过场动画接入

9. 一句话结论

小程序里的 H5 不应该直接作为“生硬全页”使用，也不应该强行做成“地图页上的真弹窗”。
最稳的方案是：

独立页面承载，但由原生壳子把它做成 sheet / dialog / fullscreen 三种体验形态。

experience-shell-proposal.md 3.6 KB تاريخچه خام