zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
zhangyan
2026-03-27 21:03:55 +08:00
parent 0e0a724025
commit 0703fd47a2
21 changed files with 903 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
doc/config-option-dictionary.md
View File

@@ -195,6 +195,18 @@
- 类型：`string`
- 说明：打点完成后自动弹出的标题
#### `template`
- 类型：`string`
- 说明：原生内容卡模板
- 当前支持：
- `minimal`
- `story`
- `focus`
- 建议默认值：
- 起点/终点：`focus`
- 普通点：`story`
#### `body`
- 类型：`string`
@@ -233,11 +245,86 @@
- 普通点：`1`
- 终点：`2`
#### `contentExperience`
- 类型：`object`
- 说明：打点完成后使用的体验承载配置
- 当前支持：
- `native`
- `h5`
#### `contentExperience.type`
- 类型：`string`
- 说明：自动弹出内容的承载方式
- 当前支持：
- `native`
- `h5`
#### `contentExperience.url`
- 类型：`string`
- 说明：当 `type = "h5"` 时对应的 H5 页面地址
#### `contentExperience.bridge`
- 类型：`string`
- 说明：H5 bridge 版本
- 建议默认值：`"content-v1"`
#### `contentExperience.presentation`
- 类型：`string`
- 说明：H5 内容的展示形态
- 当前支持：
- `sheet`
- `dialog`
- `fullscreen`
- 建议默认值：`sheet`
#### `clickExperience`
- 类型：`object`
- 说明：点击控制点时使用的体验承载配置
- 当前支持：
- `native`
- `h5`
#### `clickExperience.type`
- 类型：`string`
- 说明：点击内容的承载方式
- 当前支持：
- `native`
- `h5`
#### `clickExperience.url`
- 类型：`string`
- 说明：当 `type = "h5"` 时对应的 H5 页面地址
#### `clickExperience.bridge`
- 类型：`string`
- 说明：H5 bridge 版本
- 建议默认值：`"content-v1"`
#### `clickExperience.presentation`
- 类型：`string`
- 说明：点击内容的展示形态
- 当前支持：
- `sheet`
- `dialog`
- `fullscreen`
- 建议默认值：`sheet`
### 6.3 示例
```json
"controlOverrides": {
"start-1": {
"template": "focus",
"title": "比赛开始",
"body": "从这里出发，先熟悉地图方向。",
"autoPopup": true,
@@ -247,6 +334,7 @@
"clickBody": "点击起点可再次查看起跑说明。"
},
"control-2": {
"template": "minimal",
"score": 20,
"title": "教学楼南侧",
"body": "这里是重要转折点。",
@@ -254,9 +342,22 @@
"once": true,
"priority": 1,
"clickTitle": "教学楼南侧",
"clickBody": "这个点配置成点击查看。"
"clickBody": "这个点配置成点击查看。",
"contentExperience": {
"type": "h5",
"url": "https://example.com/content/control-2",
"bridge": "content-v1",
"presentation": "sheet"
},
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/control-2-click",
"bridge": "content-v1",
"presentation": "dialog"
}
},
"finish-1": {
"template": "focus",
"title": "比赛结束",
"body": "恭喜完成本次路线。",
"autoPopup": true,

232
doc/experience-shell-proposal.md Normal file
View File

@@ -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` 三种体验形态。**

37
doc/h5-experience-integration-proposal.md
View File

@@ -29,7 +29,7 @@
当前最适合 H5 承接的是：
- 结算页
- 打点后的定制内容页
- 打点后的定制**详情页/互动页**
- 文创详情页
- 活动品牌页
- 富图文任务页
@@ -45,6 +45,7 @@
- HUD
- GPS / 心率等实时能力主链
- 需要强实时状态同步的高频游戏弹层
- 游戏中的即时原生内容弹窗
一句话：
@@ -52,6 +53,28 @@
---
## 2.1 当前阶段的定案
经过真机验证，当前项目已经明确：
- 小程序 `web-view` 在企业主体环境下可以正常打开
- 但它不适合作为“原生弹窗里的局部 H5 内容区”使用
- 真机上更接近整页原生容器，局部裁切、壳子覆盖、原生关闭按钮都不稳定
因此当前正式定案为：
- **打点后的即时内容：原生内容卡**
- **H5：只作为详情页 / 互动任务页 / 全屏结果页**
也就是说：
- `content popup` 继续原生
- 原生内容卡上提供 `查看详情`
- 点 `查看详情` 后再进入 H5
- H5 打不开时，原生内容卡继续兜底
---
## 3. 总体架构
推荐分成三层：
@@ -93,12 +116,12 @@
### 4.1 Content Experience Page
用于游戏中途的内容体验页。
用于游戏中途的**详情体验页**或**互动任务页**。
典型场景：
- 控制点打卡后弹文创详情
- 控制点点击后查看图文内容
- 控制点打卡后点击 `查看详情`
- 控制点点击后进入图文详情页
- 拍照上传任务
- 语音留言任务
- 小游戏互动页
@@ -129,6 +152,7 @@
- 打点成功必须先由原生确认
- 比赛结束必须先由原生确认
- H5 只是附加体验，不拥有核心状态
- 原生内容卡必须先可独立工作
### 原则 2：H5 打不开时回退原生
@@ -185,6 +209,11 @@ H5 可以展示、收集信息、提交任务结果。
}
```
这个字段当前应理解为：
- `contentExperience` = 原生内容卡上的 H5 **详情/互动扩展**
- 不是直接顶替原生内容弹窗
或：
```json

32
doc/hybrid-experience-architecture.md
View File

@@ -10,6 +10,12 @@
- 原生有限 DSL
- H5 扩展页
当前阶段已经进一步定案：
- **即时内容弹窗：原生**
- **详情页 / 互动任务页：H5**
- **结算页：原生兜底 + H5 全屏增强**
---
## 1. 为什么需要混合方案
@@ -134,6 +140,7 @@
- 品牌化结算页
- 长图文故事页
- 原生内容卡上的“查看详情”页
- 拍照上传任务
- 语音留言页
- 小游戏互动页
@@ -180,6 +187,19 @@ H5 只负责：
- 结束后至少能看到原生结果页
- H5 打不开时，主流程不受影响
## 4.4 不再尝试 H5 弹窗本体
真机验证后，当前项目已经明确：
- 小程序 `web-view` 不适合作为“原生弹窗里的局部 H5 内容区”
- 它更适合作为整页/全屏体验容器来使用
因此这条边界正式定为：
- 原生内容卡负责即时弹窗体验
- H5 不直接顶替原生弹窗
- H5 只通过原生 CTA 进入详情页/任务页
---
## 5. 推荐的数据流
@@ -205,6 +225,18 @@ H5 只负责：
**先稳定 ViewModel，再让模板与承载方式变化。**
当前内容体验链已经调整成：
```text
控制点触发
↓
原生内容卡（template）
↓
CTA: 查看详情（可选）
↓
H5 详情页 / 互动任务页
```
---
## 6. ViewModel 的作用