完善原生内容卡与H5详情分工

2026-03-27 21:03:55 +08:00
parent 0e0a724025
commit 0703fd47a2
21 changed files with 903 additions and 83 deletions
--- a/doc/experience-shell-proposal.md
+++ b/doc/experience-shell-proposal.md
@@ -0,0 +1,232 @@
+# 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` 内容区
+
+也就是：
+
+```text
+experience-shell
+  ├─ backdrop
+  ├─ native header
+  └─ web-view body
+```
+
+---
+
+## 3. 支持的展示方式
+
+第一阶段只支持 3 种：
+
+- `sheet`
+- `dialog`
+- `fullscreen`
+
+### 3.1 `sheet`
+
+适合：
+
+- 打点后的文创内容
+- 拍照任务
+- 轻互动内容
+
+视觉：
+
+- 自底部升起
+- 圆角卡片
+- 半透明暗背景
+
+### 3.2 `dialog`
+
+适合：
+
+- 结果页
+- 中短内容
+- 重要说明
+
+视觉：
+
+- 居中大卡片
+- 更聚焦
+
+### 3.3 `fullscreen`
+
+适合：
+
+- 长内容
+- 强定制专题页
+- 复杂表单/小游戏
+
+---
+
+## 4. 配置结构
+
+H5 内容配置建议支持：
+
+```json
+{
+  "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` 三种体验形态。**