# Web (TeaVM/WebGL) 及其真实的限制

> 通过 TeaVM 编译为 JS、在 WebGL canvas 上运行的应用——以及哪些功能无法工作。

Source: https://crossfly.dev/zh/docs/platforms/web-teavm — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Web (TeaVM/WebGL) 🌐

**本节最诚实的一页。** web 目标平台（`web` 模块，`WebLauncher`）将应用**通过 TeaVM 编译为
JavaScript**，并在一个 WebGL2 `<canvas>` 上运行（后端为 `gdx-teavm`）。**它不是 GWT**，也
**不是**内嵌的 webview：它是运行在浏览器中的**应用本身**。

## 构建与服务
```bash
gradlew :web:webBundle       # (别名: dist)
```
生成 `web/build/webapp/`，包含 `index.html`、`web.js`、`scripts/howler.js`、`gdx.wasm.js`，以及
`assets/` + `assets.txt`。在本地提供服务：
```bash
cd web/build/webapp && python -m http.server 8080
# 打开 http://127.0.0.1:8080/index.html
```
`WebLauncher` 执行 `new TeaApplication(new Main(true, cmdline), config)`。

## ⚠️ 哪些功能无法工作（是 *stub*）
在 web 上，`PlatformUtilsWeb` 将大多数功能实现为 *stub*——调用存在，但**不执行任何有用操作**：
| 功能 | web 上的行为 |
|---|---|
| `WebContainer` | `createWebView()` 返回 **`null`** |
| GPS / 定位 | *stub*（无定位结果） |
| Bluetooth / 无线电 | *stub*（`WirelessState.UNSUPPORTED`） |
| 生物识别 | `AuthResult.ERROR` "Not supported" |
| 语音 (TTS/STT) | `voiceToText` → `onError` |
| 原生地图 | 不支持 |
| 振动 / 电池 | *stub* |
| **文件持久化** | `Device.homeFolder = null` |

> 由于 `crossfly-lib` (JNI) **在 WebGL 上不会被加载**（`Main.create()` 在 WebGL 目标平台上跳过
> `SharedLibraryLoader`），所有依赖原生的功能都会退回到上述 *stub*。

## 哪些功能可以工作
- **完整渲染 UI**（它是运行在 WebGL2 canvas 上的真实应用）。
- **打开外部 URL / 拨号**：`PlatformUtils.instance.view(url)` / `dial(numero)`（通过
  `Gdx.net.openURI`）。
- 带**限制**的 HTTP（CORS；`Utils.getRemoteFile` 在失败时返回 `null`）。

## 强制模式：检测并退回到 fallback
```java
if (PlatformUtils.instance.createWebView() != null) {
   // Android/iOS/Desktop：内嵌 webview
} else {
   PlatformUtils.instance.view(url);   // Web：在新标签页打开
}
```
并在尝试于 web 上持久化文件之前先检查 `Device.homeFolder == null`。

## 最佳实践
- 在 web 上**禁用/适配**设备功能（不要留下不做任何事的按钮）。
- web 上的持久化：使用你的构建中可用的方案（不要依赖 `homeFolder`）。
- 在托管之前先在本地提供静态 bundle 服务进行测试。

## 常见错误
- 在 web 上假设 `WebContainer`/GPS/生物识别可用（它们是 *stub*）。
- 在 web 上尝试 `Device.homeFolder + "arquivo"`（`homeFolder` 为 `null` → NPE）。

## 另请参阅
- [原生集成](/docs/platforms/native-integration) · [平台矩阵](/docs/platforms/overview)