# 运行环境

Web 应用运行在独立 iframe 内。宿主提供主题、JavaScript Bridge 和应用包加载器，应用只负责自己的界面与逻辑。

## 沙箱边界

iframe 使用 `sandbox="allow-scripts"`，不开放同源权限。应用不能获取宿主的登录 Cookie 或直接访问父页面 DOM。

所有数据与系统能力通过 `platform.*` 调用，宿主代为处理。不要直接使用 `fetch`、`XMLHttpRequest`、`localStorage`、Cookie 或自定义 `window.parent` 通信；不要从 CDN 引入脚本、CSS、字体，也不要加载未知代码。

应用不能直接联网，数据访问必须通过 `platform.*`。Web 采用可信外层容器与独立的 sandbox srcdoc：外层禁止 iframe 导航到 URL，两份 CSP 同时约束脚本执行和资源来源，阻断 fetch/XHR、外部资源、表单、跳转及嵌套页面脚本。包内 JS/CSS 和现有 DOM 界面保持支持。当前没有应用网络请求白名单 API；不要使用 iframe、外部 CDN、WebRTC 或直接跳转实现功能。

## 可用的编程环境

- 原生 JavaScript、DOM、事件和 Promise。
- 应用包中的 `.js` 模块、`.css` 文件和基础 `app.json`。
- `platform.ui`、`platform.data` 和[能力一览](/doc/api)中的宿主接口。

没有 Node.js、npm 包安装、React、Vue、TypeScript 或 JSX 编译步骤。若使用开发期编译工具，提交的结果仍然必须符合应用包格式。

表单默认提交会被拦截。请通过按钮事件或自己的 `submit` 处理逻辑执行操作，不要依赖页面刷新。

## 启动和生命周期

打开应用后加载文件包，执行入口函数；入口成功返回后，宿主认为应用准备完成。20 秒内没有准备完成会显示打开超时，因此不要在入口等待无限循环或长时间后台任务。

切换标签、切换对话不会销毁应用 iframe。关闭标签或刷新浏览器会销毁内存状态，再次打开时重新执行入口。未提交的输入仅保留在应用内存中；需要跨刷新恢复的草稿必须通过 `platform.data` 保存到准备好的数据集，不能使用浏览器 localStorage。

当前没有内置 `onShow`、`onHide`、页面栈或后台任务回调。多页面切换由应用自己组织，参考[多文件待办](/doc/examples/multi-file)。

## 跨端设计

`platform.host` 返回实际宿主：Web 为 `"web"`，Apple 与 Android 容器分别为 `"ios"`、`"macos"`、`"android"`。公共运行时 v1 已冻结；仓库提供 iOS 产品源码及三端测试宿主，iOS 真机验收与公开分发尚未完成，macOS/Android 完整产品和 Windows 仍为后续目标。应用只通过 JSB 使用宿主能力，用 `platform.can` 检查当前实例的真实能力；测试宿主存在不代表对应产品已经发布。

使用 `platform.can(name)` 检查能力，并为缺失能力提供说明或替代操作。布局应适应窄屏、触控与不同安全区域，不能仅依赖鼠标 hover。