238 lines
3.6 KiB
Markdown
238 lines
3.6 KiB
Markdown
# Experience Shell 方案
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02
|
||
|
||
|
||
本文档用于定义小程序中 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` 三种体验形态。**
|
||
|
||
|