diff --git a/docs/white-book/11-DApp-Guide/01-Runtime-Env/01-Container-Architecture.md b/docs/white-book/11-DApp-Guide/01-Runtime-Env/01-Container-Architecture.md new file mode 100644 index 000000000..00c380d6f --- /dev/null +++ b/docs/white-book/11-DApp-Guide/01-Runtime-Env/01-Container-Architecture.md @@ -0,0 +1,170 @@ +# 01. Container 架构 (Container Architecture) + +> Code: `src/services/miniapp-runtime/container/` + +KeyApp 的 Miniapp 运行时采用 **Container 抽象层** 设计,支持多种沙箱隔离技术。 + +## 设计目标 + +1. **统一接口**: 无论底层使用 iframe 还是 Wujie,上层代码通过统一的 `ContainerHandle` 操作 +2. **可扩展性**: 未来可轻松添加新的容器实现(如 Web Worker、Shadow DOM) +3. **平滑迁移**: 从 iframe 模式迁移到 Wujie 模式无需修改 UI 层代码 + +## 容器类型 + +| 类型 | 实现文件 | 特点 | 适用场景 | +| -------- | --------------------- | ------------------ | ------------- | +| `iframe` | `iframe-container.ts` | 原生浏览器隔离 | 简单 H5 应用 | +| `wujie` | `wujie-container.ts` | JS 沙箱 + CSS 隔离 | 复杂 SPA 应用 | + +## 核心接口 + +### ContainerCreateOptions + +创建容器时的配置选项: + +```typescript +interface ContainerCreateOptions { + type: 'iframe' | 'wujie'; + appId: string; + url: string; + mountTarget: HTMLElement; // 容器挂载的目标元素 +} +``` + +### ContainerHandle + +容器操作句柄: + +```typescript +interface ContainerHandle { + element: HTMLElement; // 容器的 DOM 元素 + destroy: () => void; // 销毁容器 + moveToForeground: () => void; // 移到前台 + moveToBackground: () => void; // 移到后台 + getIframe: () => HTMLIFrameElement | null; // 获取 iframe(用于通讯) +} +``` + +## 工作原理 + +### 1. iframe 模式 + +直接创建 `