# 沉浸内容承载与控制组件 PRD

版本：v0.5
状态：待原型与实现验证

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- |
| 2026-08-03 | v0.1 | 初始创建 | 抽取 3D、360、WALK、VR 等体验共用的帮助、复位、退出与状态控制。 |
| 2026-08-04 | v0.2 | 重大：iframe 承载职责补充 | 统一承载空间体验 iframe 及其加载、失败、重试和退出；明确 WALK / VR 类型由 Widget 决定，组件不提供类型切换；补充不可判定失败原因的统一反馈。 |
| 2026-08-06 | v0.3 | 重大：WALK / VR 组件化 | 删除空间体验 Widget；组件由共有部、样板间、住户展示等内容对象直接调用。 |
| 2026-08-06 | v0.4 | 重大：恢复业务 Widget 边界 | WALK、VR 分别恢复为独立 Widget；本组件只提供二者共用的 iframe 承载、状态与控制。 |
| 2026-08-11 | v0.5 | 重大：WALK / VR 内容组件化 | WALK、VR 退出 Widget 范围；共有部、样板间、住户展示等调用方直接传入对应内容并调用本组件。 |

## 定义

唯一标识：`immersive-embed-controls`。由共有部、样板间、住户展示等调用方传入 WALK 或 VR 内容，提供统一 iframe 承载，以及可理解的加载、失败、重试、帮助、复位、暂停（如外部内容支持）和退出反馈；不定义具体空间内容、数据来源或关联对象。

## 内容与配置

体验名称、iframe 地址、体验类型标识和退出动作为必需；帮助、复位、暂停、进度、设备提示按调用方和外部内容实际能力可选。体验类型标识只用于显示与反馈，组件不得把 WALK 改成 VR、把 VR 改成 WALK，也不得提供顾客侧类型切换。不可用动作必须隐藏，不显示不可点击的装饰控件。

## 交互、状态与验收

顾客从调用方的 WALK 或 VR 体验入口启动后，组件加载该内容的 iframe；加载中可取消，地址无效、禁止嵌入、超时或运行失败时不显示空白画面，并可重试或退出。浏览器无法可靠区分禁止嵌入与网络失败时，统一反馈“体验暂时无法加载”，不向顾客展示未经确认的技术原因。顾客可执行外部内容实际支持的控制并始终退出；退出后回到调用方原区块。移动端控制区不遮挡核心画布。

验收：同一组件可分别承载调用方传入的 WALK 或 VR 内容 iframe；组件显示类型与传入内容一致；不提供类型切换；失败不自动降级为另一种内容；控件与实际能力一致；无返回死路；状态文字可理解。iframe 允许来源、安全属性、全屏权限和跨域通信规则属于实现约束，需在开发前补齐，不改变产品边界。