{ "schemaVersion": "0.11.0", "canonical": "https://www.pystone.net/notes/webgl-platform-capability-api/", "atlas": "https://www.pystone.net/?node=webgl-platform-capability-api#knowledge-atlas", "markdown": "https://www.pystone.net/notes/webgl-platform-capability-api.md", "context": "https://www.pystone.net/notes/webgl-platform-capability-api.context.json", "knowledgeVersion": "224c990773de.5fa8af6e39fa", "build": { "siteCommit": "224c990773de166d23a886306577dd90379529ce", "notesCommit": "5fa8af6e39fa3891d1b9b4832bfa6c4e0ecaaf0a", "builtAt": "1970-01-01T00:00:00.000Z", "version": "224c990773de.5fa8af6e39fa" }, "id": "note:webgl-platform-capability-api", "slug": "webgl-platform-capability-api", "title": "WebGL应用平台能力接口", "type": "note", "visibility": "public", "idStability": "rename-stable", "author": { "name": "Perrin Yong", "profile": "https://www.pystone.net/profile/" }, "publisher": { "name": "Perrin Yong", "profile": "https://www.pystone.net/profile/" }, "aliases": [], "summary": "WebGL应用平台能力接口", "contentRole": "unspecified", "isMoc": false, "mocRecognition": "none", "generated": false, "attribution": "unspecified", "domain": "10-计算机、信息技术与工程", "tags": [], "mocs": [], "contentHash": "cff1c5737d322d6b80256e15bdbc0e9eab8a3c5efb8225be5631b1c46d9d808c", "assets": [], "headings": [ { "depth": 1, "text": "WebGL应用平台能力接口", "anchor": "webgl应用平台能力接口", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#webgl%E5%BA%94%E7%94%A8%E5%B9%B3%E5%8F%B0%E8%83%BD%E5%8A%9B%E6%8E%A5%E5%8F%A3" }, { "depth": 2, "text": "引言: Web平台能力接口", "anchor": "引言-web平台能力接口", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E5%BC%95%E8%A8%80-web%E5%B9%B3%E5%8F%B0%E8%83%BD%E5%8A%9B%E6%8E%A5%E5%8F%A3" }, { "depth": 2, "text": "规范定义：Web IDL（Web Interface Definition Language）", "anchor": "规范定义web-idlweb-interface-definition-language", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E8%A7%84%E8%8C%83%E5%AE%9A%E4%B9%89web-idlweb-interface-definition-language" }, { "depth": 2, "text": "API 的生态与标准化现状", "anchor": "api-的生态与标准化现状", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#api-%E7%9A%84%E7%94%9F%E6%80%81%E4%B8%8E%E6%A0%87%E5%87%86%E5%8C%96%E7%8E%B0%E7%8A%B6" }, { "depth": 2, "text": "示例剖析：wx API（MiniApp）", "anchor": "示例剖析wx-apiminiapp", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E7%A4%BA%E4%BE%8B%E5%89%96%E6%9E%90wx-apiminiapp" }, { "depth": 2, "text": "从脚本到系统：底层调用链", "anchor": "从脚本到系统底层调用链", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E4%BB%8E%E8%84%9A%E6%9C%AC%E5%88%B0%E7%B3%BB%E7%BB%9F%E5%BA%95%E5%B1%82%E8%B0%83%E7%94%A8%E9%93%BE" }, { "depth": 3, "text": "在浏览器 (Web) 里的机制", "anchor": "在浏览器-web-里的机制", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E5%9C%A8%E6%B5%8F%E8%A7%88%E5%99%A8-web-%E9%87%8C%E7%9A%84%E6%9C%BA%E5%88%B6" }, { "depth": 4, "text": "例1: window.onerror 发生了什么？", "anchor": "例1-windowonerror-发生了什么", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E4%BE%8B1-windowonerror-%E5%8F%91%E7%94%9F%E4%BA%86%E4%BB%80%E4%B9%88" }, { "depth": 4, "text": "例2: fetch() / XMLHttpRequest", "anchor": "例2-fetch-xmlhttprequest", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E4%BE%8B2-fetch-xmlhttprequest" }, { "depth": 3, "text": "在 小程序 (如微信/支付宝) WebGL Runtime 里的机制", "anchor": "在-小程序-如微信支付宝-webgl-runtime-里的机制", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E5%9C%A8-%E5%B0%8F%E7%A8%8B%E5%BA%8F-%E5%A6%82%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98%E5%AE%9D-webgl-runtime-%E9%87%8C%E7%9A%84%E6%9C%BA%E5%88%B6" }, { "depth": 4, "text": "例1: wx.request() 工作流程", "anchor": "例1-wxrequest-工作流程", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E4%BE%8B1-wxrequest-%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%A8%8B" }, { "depth": 4, "text": "例1: App.onError", "anchor": "例1-apponerror", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E4%BE%8B1-apponerror" }, { "depth": 2, "text": "总结：“JS 运行时 vs 宿主” 责任划分", "anchor": "总结js-运行时-vs-宿主-责任划分", "citation": "https://www.pystone.net/notes/webgl-platform-capability-api/#%E6%80%BB%E7%BB%93js-%E8%BF%90%E8%A1%8C%E6%97%B6-vs-%E5%AE%BF%E4%B8%BB-%E8%B4%A3%E4%BB%BB%E5%88%92%E5%88%86" } ], "claims": [], "outgoing": [], "incoming": [ { "id": "note:game-graphics-and-runtime", "title": "游戏图形与运行时", "url": "https://www.pystone.net/notes/game-graphics-and-runtime/", "atlas": "https://www.pystone.net/?node=game-graphics-and-runtime#knowledge-atlas", "label": "游戏图形与运行时", "origin": "explicit", "humanReviewed": true, "context": "WebGL中的“WebGL应用平台能力接口”导航项", "citation": "https://www.pystone.net/notes/game-graphics-and-runtime/#webgl" } ], "contentMarkdown": "# WebGL应用平台能力接口\n\n# WebGL应用平台能力接口\n\n\n## 引言: Web平台能力接口\n\n```text\n平台能力接口（Browser / MiniApp API）\n ▲\n │ 由规范形式化\n │\nWeb IDL（接口描述语言）\n ▲\n │ 被宿主实现并注入\n │\n宿主（浏览器、微信 App、抖音 App…）\n```\n\nWeb 页面和各类 MiniApp 脚本都不是裸跑在 ECMAScript 引擎里，而是依赖宿主（浏览器、微信 App、抖音 App …）注入的 **“平台能力接口”**。理解它们的**定义方式**、**使用方式**与**底层实现**，是写出跨端、可维护代码的前提。\n\n**平台能力接口**：浏览器或小程序宿主在 **JavaScript 运行环境** 中注入的一组函数 / 对象，向脚本暴露网络、存储、渲染、系统能力等。\n**核心特征**：\n\n1. 入口是 **全局单例对象**；\n2. 业务脚本 **无需 import**；\n3. 真正实现位于 **宿主的原生层（C++/Java/Obj-C/Rust…）**。\n\n| 宿主 | 全局对象 | 运行时何时注入 |\n| ----- | ---------------------------------- | ---------------------------- |\n| 浏览器 | `window`（含 `document`、`fetch()` …） | 浏览器进程初始化 JS 引擎后立即注入 |\n| 微信小程序 | `wx` | 在 WebView 创建脚本上下文前由微信 App 注入 |\n| 抖音小程序 | `tt` | 同上，由抖音 App 注入 |\n| … | … | … |\n\n\n## 规范定义：Web IDL（Web Interface Definition Language）\n\nWeb IDL（Web Interface Definition Language）：一门专门为 _Web 平台_ 设计的 _接口描述语言_ （IDL），由 WHATWG 维护为 _Living Standard_ ，W3C 也有准同步版本。其目标是：用一套与编程语言无关的语法，把浏览器要提供给 JavaScript 的 API 定义得 _精确、可测试、可生成绑定代码_ 。\n\n早期规范用自然语言描述 DOM、XHR 等接口，结果各浏览器对同一属性的类型、可空性、默认值等细节解释不同，导致互操作问题。Web IDL 让这些细节（类型转换、异常、可选参数、Promise 处理等）机器可读，从而：\n1. 规范作者能一致地写 API；\n2. 浏览器实现者可自动生成 C++/Rust ↔ JS 的“胶水”代码；\n3. 文档站（MDN）、类型系统（TypeScript lib.dom.d.ts）和测试框架可以直接解析 IDL。\n\n\n规范到浏览器的路径：\n1. 规范发布 → 浏览器拉取最新 Web IDL 列表；\n2. 工具（如 _Blink’s IDL compiler_、_Gecko’s WebIDLCodegen_）把 IDL 生成 C++/Rust 绑定：创建 JS **interface object**、实现属性 getter/setter、参数校验；\n3. JS 引擎通过绑定层把调用转发给内部实现（网络栈、DOM 等）。\n\n给开发者的影响：\n- **一致的 API 形状**：不同浏览器对 `fetch()`、`AbortSignal` 等接口的签名完全一致；\n- 类型定义可被 TypeScript、Flow、Rust wasm-bindgen 等再利用，实现强类型提示；\n- 测试框架 (WPT) 能自动生成“接口存在性”断言。\n\n## API 的生态与标准化现状\n\n\n问：这些 API 有统一标准吗？\n\n| 生态 | 标准化现状 | 规范出处 | 兼容度现状 |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |\n| **Web（浏览器）** | **完全标准化**：WHATWG/W3C 在 HTML、DOM、Fetch 等规范里通过 **Web IDL** 精确定义每个接口 | 例：Fetch Standard Living Spec ([fetch.spec.whatwg.org](https://fetch.spec.whatwg.org/?utm_source=chatgpt.com \"WHATWG - Fetch Standard\")) | 主要浏览器实现一致 |\n| **MiniApp（微信 / 抖音 / 支付宝 …）** | **各家先行 → W3C 正在收敛**：API 由各平台先各自设计；2019 年起 W3C 成立 **MiniApps WG**，正把共性沉淀成系列规范（Packaging、Manifest、Lifecycle、API Profile 等） | • MiniApp Packaging WD ([W3C](https://www.w3.org/TR/miniapp-packaging/?utm_source=chatgpt.com \"MiniApp Packaging - World Wide Web Consortium (W3C)\")) • MiniApp Specs 一览 (W3C) ([W3C GitHub](https://w3c.github.io/miniapp/specs/?utm_source=chatgpt.com \"MiniApp Specifications \\| miniapp - w3c.github.io\")) | 目前仍以厂商文档为准；同名接口大多“形似、细节不同” |\n\n**厂商官方文档示例**: 抖音 `tt.request()` API 文档 ([developer.open-douyin.com](https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/api/network/http/tt-request/?utm_source=chatgpt.com \"tt.request_小程序_抖音开放平台\"))\n\n## 示例剖析：**`wx` API**（MiniApp）\n\n**`wx` 是什么？**\n * 它是 **WeChat Mini Program 运行时** 在加载脚本前注入的 **全局单例对象**。\n * 其内部保存了一张 *命令→native 调用* 的路由表，并附带常量、枚举、内部缓存等。\n\n**作用**\n * **API 集合入口**：大多数小程序能力（网络、存储、文件、蓝牙、云开发等）都以 `wx.` 形式公开。\n * **事件/钩子注册器**：如 `wx.onError`、`wx.onNetworkStatusChange` 等监听接口同样挂载在 `wx`。\n\n**所有 API 都在 `wx` 上吗？**\n * **绝大多数** 通用能力是的。\n * 但还有三类例外：\n 1. **生命周期构造器**：`App()`, `Page()`, `Component()` —— 用来声明应用/页面/组件本身。\n 2. **增强 API**：插件、云开发 (`wx.cloud` 子命名空间)、小游戏 (`wx.game.*`) 在 `wx` 下再分级。\n 3. **Worker 与 ES 模块**：在独立沙箱脚本中可能无法直接访问主环境的 `wx`，需通过 `self.wx` 或 `importScripts('wx.js')` 暴露的 shim。\n\n\n**注册 `wx.onError(cb)` 时发生的事**\n * 运行时把 `cb` 存入监听表。\n * 当 **JS 引擎** 抛出未捕获异常或 **Native 层** 上报崩溃摘要时，Bridge 会序列化错误信息 → 主 JS 线程 → 依次调用注册的回调。\n * 回调内若希望阻止默认错误提示，可返回 `true` 或调用 `console.error` 后自行上报。\n\n\n## 从脚本到系统：底层调用链\n\n```text\n┌───────────────────────────────┐\n│ JavaScript 代码（前端） │ ► 调用 JS API\n└──────────────┬────────────────┘\n ▼\n┌──────────────┴────────────────┐\n│ JS ↔ Native 绑定/Bridge 层 │ ► 形态取决于宿主\n│ • 浏览器：Web IDL + V8/JSValue│ • 小程序：JSON/二进制消息队列\n└──────────────┬────────────────┘\n ▼\n┌──────────────┴────────────────┐\n│ 宿主 Native 实现层 │ ► 线程池 / 网络栈 / GPU / …\n│ • Blink / Gecko / WebKit │ • 微信 App (OKHttp, NSURLSession…)\n└──────────────┬────────────────┘\n ▼\n┌──────────────┴────────────────┐\n│ OS / 硬件服务 │ ► TCP/IP、文件系统、OpenGL ES…\n└───────────────────────────────┘\n```\n\n| | **Browser API** (`window.fetch`, `window.onerror`, …) | **Mini-Program API** (`wx.request`, `wx.onError`, …) |\n| ----------- | ------------------------------------------------------ | ---------------------------------------------------- |\n| **接口规范** | W3C/WHATWG 定义，使用 **Web IDL** 描述属性与方法 | 腾讯自定义 MDN-style 文档；无统一规范组织 |\n| **JS 宿主对象** | `window`（同时承载 BOM、DOM、Web API） | `wx` **＋** 全局构造器 `App / Page / Component` |\n| **绑定方式** | 编译生成 C++/Rust glue，将 V8 `v8::Object` ↔ native 对象 | 手写或代码生成的 **Bridge**，JS ↔ Native 通过 JSON/二进制消息 |\n| **线程模型** | 主线程负责 JS + DOM；I/O 与 GPU 在独立线程/进程 | JS 运行在单独 V8 线程；网络/GPU/文件在宿主线程池 |\n| **回调返回** | DOM 事件队列 & 微任务；Promise Resolution | Bridge 将结果投递到 JS **Callback 队列** 或 Promise |\n| **错误捕获** | JS 异常 → `window.onerror` / `addEventListener('error')` | JS 异常 → `wx.onError`Native 崩溃 → `App.onError` |\n| **核心思想** | **Web IDL × 单一全局对象** 把平台能力映射到 JS | **小型 SDK** 将平台能力聚合到 `wx`，外加若干生命周期钩子 |\n\n\n* **Browser API**：由浏览器内核实现，借助 **Web IDL** 挂到 `window`；JS 引擎仅负责执行语言本身。\n* **Mini-Program API**：由宿主 App 用 Native 代码实现，通过 **`wx` 全局对象 + Bridge** 向脚本暴露；`wx` 既是命名空间也承担事件总线的角色，但构造器 (`App/Page/Component`) 和部分子域另作补充。这样就把“Web API” 的设计理念迁移到小程序沙盒中，实现了跨端一致的调用体验。\n\n\n### 在**浏览器 (Web)** 里的机制\n\n\n| 层级 | 作用 / 关键点 | 代码/技术栈 | 归属 |\n| -------------- | -------------------------------------------------------------------- | ------------------------------------------ | --------------------------- |\n| ECMAScript 运行时 | `try … catch`、`Promise` 等，只描述语法和执行语义 | V8、SpiderMonkey、JavaScriptCore… | **JS 引擎** |\n| Web IDL 绑定层 | `window.onerror`、`XMLHttpRequest`、`fetch()`、`addEventListener` 等接口签名 | Web IDL ➜ 生成 C++/Rust/Objective-C 绑定代码 | **宿主 (浏览器内核, Bindings子模块)** |\n| 内核模块(浏览器内部实现) | 事件派发、网络栈、线程/进程隔离、沙箱 | Blink / Gecko / WebKit (C++/Rust) + OS 网络库 | **宿主 (浏览器内核)** |\n| JS 回调 | `onerror` 或 Promise `resolve/reject` | 业务 JS | 脚本 |\n\n#### 例1: `window.onerror` 发生了什么？\n\n1. **JavaScript 运行时**在执行脚本或事件回调时抛出未捕获异常。\n2. JS 引擎把异常对象上浮到 **绑定层**：\n\n```cpp\n// 伪码 in V8 bindings\nv8::TryCatch try_catch(isolate);\nRunScript();\nif (try_catch.HasCaught()) {\n DispatchJSEvent(\"error\", try_catch.Exception());\n}\n```\n\n3. 绑定层调用 **DOM 事件系统**（C++）创建一个 `ErrorEvent`，并按 *Web IDL* 定义把 `message / filename / lineno / colno / error` 填进去。\n4. DOM 事件系统按照 **事件流** 规则逐级冒泡；如果在 `window` 对象上发现 `onerror` 属性存在可调用函数，就在主线程回调它。\n5. 若 `onerror` 返回 `true` 或 `event.preventDefault()`，浏览器会阻止默认的错误提示；否则控制台输出 error。\n\n> **关键点**：`window.onerror` 并非 ECMAScript 规范，而是浏览器在 *宿主层* 用 C++/Rust 实现并通过 Web IDL 暴露的 **Web API**。\n\n#### 例2: `fetch()` / `XMLHttpRequest`\n\n* **JS → C++ 边界**：调用时传入 JS 对象；绑定层生成网络请求描述，放入 **NetworkService** 线程/进程。\n* **网络栈**：Blink/Chromium 使用 **net/** 模块，加上 QUIC/HTTP2/TLS 实现；Gecko 使用 Necko。\n* **Promise**：`fetch()` 返回 JS Promise；C++ 网络回包后通过 **microtask queue** 向 JS 线程投递 `resolve`/`reject`，再执行回调。\n\n---\n\n### 在 **小程序 (如微信/支付宝) WebGL Runtime** 里的机制\n\n> 小程序的 JS 运行时（通常是 **V8 (Android)** / **JavaScriptCore (iOS)**）嵌在 App 内；Web API 子集由宿主 App 用 **Native+C++/Obj-C/Java/Kotlin** 实现，并通过 **JS–Native Bridge** 暴露给脚本。Unity WebGL 的“小游戏”运行时亦遵循同思路。\n\n\n| 层级 | 作用 / 关键点 | 代码/技术栈 | 归属 |\n| ---------- | ---------------------------------- | ---------------------------------------- | -------------- |\n| JS 调用 | `wx.request({ … })` | V8 / JSC | **JS 引擎** |\n| Bridge | 参数 JSON 化 → Native | C++, Java/Kotlin, Obj-C | 宿主App(Bridge层) |\n| Native 网络栈 | OKHttp / NSURLSession | Java/Kotlin (Android), Obj-C/Swift (iOS) | 宿主App(Native层) |\n| 回抛 | JSON → JS 线程 → `success`/`fail` 回调 | 业务 JS | JS 脚本 |\n\n\n#### 例1: `wx.request()` 工作流程\n\n1. **前端脚本** 调用 `wx.request({url, success, fail, complete})`.\n2. **JS–Native 桥** 把参数序列化成 JSON，送到 **宿主线程**。\n3. 宿主用 **OKHttp / NSURLSession** 发网络请求。\n4. 回包后，宿主线程把结果再次序列化成 JSON，通过队列抛回 **JS 线程**。\n5. Runtime 把 JSON 解析成 JS 对象并执行 `success` 回调；如果网络/解析异常，执行 `fail` 并触发全局 `App.onError`。\n\n#### 例1: `App.onError`\n\n* 在 iOS/Android 原生侧通过捕获 **Objective-C Exception, Java Exception, Signal** 等，把崩溃信息写入 JS 引擎特定对象并触发 JS 回调。\n* 对于 **JS 代码异常**（类似浏览器的未捕获异常），Runtime 会通过 `V8::MessageListener` / `JSC::exception` 捕获并转调 `onError`（守护线程与宿主线程通信即可）。\n\n\n---\n\n## 总结：**“JS 运行时 vs 宿主” 责任划分**\n\n| 功能 | ECMAScript 引擎 (V8/JSC) | 宿主环境 (Browser / 小程序 App) |\n| ------------------------------ | ---------------------- | ------------------------ |\n| 解析 & 执行 JS 语法 | ✔ | ✘ |\n| 管理事件循环宏/微任务 | ✔ (内部实现) | 提供额外任务源 (I/O, timer) |\n| 全局错误捕获 `onerror`/`App.onError` | 将异常上浮 | 创建 Event / 回调到 JS |\n| 网络 I/O (`fetch`, `wx.request`) | ✘ | ✔ (网络栈 + 结果回调) |\n| Canvas/WebGL 渲染 & DOM | ✘ | ✔ (GPU/Skia/OpenGLES) |\n| 文件、系统能力 | ✘ | ✔ (Native 调用) |\n\n* **JS 引擎** 只负责 *语言*；所有环境能力（DOM、网络、文件、摄像头）都由 **宿主** 提供。\n* 宿主通过 **Web IDL**（浏览器）或 **桥接协议**（小程序）把这些能力映射为 JS 可调用对象。\n* “浏览器 API” 与 “小程序 API” 路径大同小异：**JS → 绑定 → 宿主 native layer → 系统服务 → 回调 → JS**。\n\n希望这张“分层图 + 调用链”能澄清 onerror/request 等接口的 **归属** 与 **底层实现**。若你需要更深入到特定引擎（如 Chromium `blink::V8ErrorHandler` 或 Unity WebGL `JS_LIBRARIES/*.js`）的源码路径，可告诉我再展开。\n" }