为 wasm-bindgen 的 js-sys 新增 ECMAScript API 绑定：完整贡献指南

开发工具【免费下载链接】wasm-bindgenFacilitating high-level interactions between Wasm modules and JavaScript项目地址https://gitcode.com/gh_mirrors/wa/wasm-bindgen点击查看免费下载js-sys是 wasm-bindgen 生态中手写的 ECMAScript 标准全局 API 绑定层覆盖所有 JavaScript 环境浏览器、Node.js 等都保证存在的内置对象与全局函数。本文基于仓库内 guide/src/contributing/js-sys/adding-more-apis.md 的贡献流程结合 crates/js-sys/src/lib.rs 中的源码级规范完整讲解当发现缺失 API 或 TC39 新提案进入 Stage 4 时如何为 js-sys 新增绑定读完即可按仓库既定规范独立提交一次高质量的新 API 绑定 PR。js-sys 的定位只绑定 ECMAScript 标准全局 API在动手新增 API 之前必须先明确 js-sys 的边界。根据 crates/js-sys/README.md 与 crates/js-sys/src/lib.rs 顶部文档注释js-sys 是手写的 JS 全局 API 绑定raw bindings不是自动生成目标是在所有 JS 环境浏览器、Node.js 等中可用不包含任何 Web、Node 或其他 JS 环境专属 API只包含 ECMAScript 标准保证存在于全局作用域的东西即 MDN Global Objects 目录 中属于 ECMAScript 标准的那部分。例如Array、Promise、Map、Set、decodeURI属于 js-sys 的职责范围而fetch、XMLHttpRequest、document等 Web API 属于 web-sys 的职责范围。因此新增 API 的第一步是确认它确实属于 ECMAScript 标准而非宿主环境扩展。何时需要新增 API触发条件原文档给出了两个明确触发条件发现缺失的 APIjs-sys 覆盖了 ECMAScript 标准中所有 API但标准在持续演进绑定可能出现遗漏新 API 已到达 TC39 Stage 4TC39 提案流程中Stage 4 表示提案已被 ECMAScript 标准委员会正式接受、即将/已经进入标准此时就值得为它添加绑定。满足上述条件时原文档建议先在 GitHub 上提交 issue 进行登记与讨论再着手实现。新增 API 之前还应当查阅 js-sys 类型参考文档确认该 API 是否已以泛型类型如ArrayT、PromiseT、MapK, V等的形式存在避免重复添加。源码级检查清单lib.rs 中的新增导入规范新增绑定的核心规范并不在单独的文档里而是以注释形式直接内嵌在 crates/js-sys/src/lib.rs 的// When adding new imports:中这也是本贡献流程最权威的依据。规范全文如下When adding new imports: * Keep imports in alphabetical order. * Rename imports with js_name ... according to the note about camelCase and snake_case in the modules documentation above. * Include the one sentence summary of the import from the MDN link in the modules documentation above, and the MDN link itself. * If a function or method can throw an exception, make it catchable by adding #[wasm_bindgen(catch)]. * Add a new #[test] into the appropriate file in the crates/js-sys/tests/wasm/ directory. If the imported function or method can throw an exception, make sure to also add test coverage for that case. * Arguments that are JsValues or imported JavaScript types should be taken by reference. * Name JavaScripts toString() method as to_js_string() to avoid conflict with Rusts ToString trait.下面逐条展开说明每项规范的意图与仓库中的对应实现。1. 导入保持字母序所有extern C块中的绑定按字母顺序排列便于审查与查找。新增绑定时应插入到正确位置而不是追加在文件末尾。2. 用js_name处理 camelCase / snake_case 命名差异JavaScript 的全局对象与方法使用camelCase命名而 Rust 风格是snake_case。绑定对外暴露 Rust 风格的snake_case名字同时用#[wasm_bindgen(js_name ...)]指向真实的 JavaScript 名字。此外方法名中的缩写acronym在 Rust 侧全部小写而在 JavaScript 中通常全大写。例如decodeURI绑定为decode_uricrates/js-sys/src/lib.rs#[wasm_bindgen] extern C { /// The decodeURI() function decodes a Uniform Resource Identifier (URI) /// previously created by encodeURI or by a similar routine. /// /// [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) #[wasm_bindgen(catch, js_name decodeURI)] pub fn decode_uri(encoded: str) - ResultJsString, JsValue; /// The decodeURIComponent() function decodes a Uniform Resource Identifier (URI) component /// previously created by encodeURIComponent or by a similar routine. /// /// [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) #[wasm_bindgen(catch, js_name decodeURIComponent)] pub fn decode_uri_component(encoded: str) - ResultJsString, JsValue; }同理encodeURI绑定为encode_uri、encodeURIComponent绑定为encode_uri_component见 crates/js-sys/src/lib.rs。3. 附带 MDN 单句摘要与链接每个绑定的 doc 注释必须包含来自 MDN 的一句话功能摘要以及对应的MDN 链接。这一点在所有现有绑定中都有体现如上面的decodeURI示例。这条规范保证了 js-sys 的文档质量——每个绑定都有官方语义来源读者无需再翻外部文档。4. 可抛异常的 API 必须加#[wasm_bindgen(catch)]如果一个函数或方法可能抛出异常就必须加上#[wasm_bindgen(catch)]使 Rust 侧签名变成Result_, JsValue从而把 JS 异常转化为 Rust 的错误值而不是 panic 或未定义行为。这在 lib.rs 中大量使用全局函数decode_uri、decode_uri_component返回ResultJsString, JsValue静态方法Array.from、Array.fromAsync等使用#[wasm_bindgen(static_method_of Array, catch, js_name from)]见 crates/js-sys/src/lib.rs实例方法Array.prototype.every/filter/find/map/sort等大量方法使用#[wasm_bindgen(method, js_name ..., catch)]见 crates/js-sys/src/lib.rs。判断是否可抛异常的依据是 ECMAScript 规范与 MDN 文档中该方法是否声明可能抛出如类型错误、范围错误等。5. 参数按引用传递凡是JsValue或导入的 JavaScript 类型的参数都应按引用T传递避免不必要的所有权转移与克隆这也符合 wasm-bindgen 的 ABI 约定。字符串、数字等 Rust 原始类型则按其自身约定传递。6.toString()一律命名为to_js_string()JavaScript 的toString()在 js-sys 中暴露为to_js_string()这是为了避免与 Rust 标准库的ToStringtrait 及其to_string()方法冲突。这样一来类型可以同时实现 Rust 的Displaytrait经由ToString提供to_string()与 JS 侧的toString()功能而不互相干扰。仓库中大量#[wasm_bindgen(method, js_name toString)]即对应此规范见 crates/js-sys/src/lib.rs 等处。同理valueOf()、toLocaleString()等按需绑定。绑定结构速查一个完整绑定长什么样综合上述规范一个完整的新绑定通常包含四部分/// 来自 MDN 的一句话功能摘要 /// /// [MDN documentation](https://developer.mozilla.org/...) #[wasm_bindgen(catch, js_name originalJsName)] // 若可抛异常则加 catch pub fn rust_name(args: JsValue) - ResultJsValue, JsValue; // 参数按引用异常转 Result若绑定的是对象静态方法使用static_method_of TypeName若绑定的是实例方法使用method若绑定的是命名空间下的函数如Atomics使用js_namespace Atomics见 crates/js-sys/src/lib.rs 中大量#[wasm_bindgen(js_namespace Atomics, catch, js_name ...)]。为新 API 添加测试规范要求每个新增绑定都要在crates/js-sys/tests/wasm/目录下对应的文件中添加新的#[wasm_bindgen_test]测试。测试文件按内置对象/主题组织例如 crates/js-sys/tests/wasm/Array.rs、Map.rs、Promise.rs、Number.rs、AggregateError.rs等。如果新绑定可能抛异常还必须同时覆盖异常路径的测试用例。典型测试结构摘自 crates/js-sys/tests/wasm/Array.rs#[wasm_bindgen_test] fn from_iter() { assert_eq!( to_rust( vec![JsValue::from(a), JsValue::from(b), JsValue::from(c),] .into_iter() .collect() ), vec![a, b, c], ); // ... }测试通过#[wasm_bindgen_test]宏标记编译为 Wasm 后在 Node.js 或无头浏览器中执行。js-sys 的完整测试命令来自 guide/src/contributing/testing.mdWASM_BINDGEN_SPLIT_LINKED_MODULES1 cargo test --target wasm32-unknown-unknown如果你只需要验证 js-sys 相关测试可在工作区中聚焦对应 crate 执行。测试运行前提是安装好 Rust 的wasm32-unknown-unknowntarget 与支持 WebAssembly 的 Node.js详见 guide/src/contributing/index.md 的 Prerequisites 部分rustup target add wasm32-unknown-unknown常用泛型类型参考避免重复造轮子新增绑定前务必对照 js-sys 类型参考文档 检查是否已有可复用的泛型绑定。该参考列出了ArrayT、ArrayTupleT1..T8、Functionfn(A) - R、PromiseT、MapK, V、SetT、IteratorT/AsyncIteratorT、GeneratorT、ObjectT、WeakMap/WeakSet/WeakRef、JsOptionTT | undefined与JsNullableTWebIDLT?等泛型类型。所有泛型类型都实现JsGeneric未指定类型参数时默认JsValue。举例来说如果你要绑定一个返回 Promise 的新 API应声明返回PromiseT而非裸Promise从而让调用方直接.await得到类型化的T如果你要绑定一个可能返回undefined的取值函数应使用JsOptionT而不是OptionT因为JsOptionT可以在JsGeneric位置延迟 undefined 检查两者行为对比见参考文档中的表格。提交前的自查清单综合原文档与源码规范提交新增 API 的 PR 前应逐项确认API 属于 ECMAScript 标准全局 API而非 Web/Node 专属 API若为新提案已到 TC39 Stage 4若为缺失绑定已提交 issue 说明绑定按字母序插入js_name正确映射 camelCase 到 snake_casedoc 注释含 MDN 单句摘要与链接可抛异常的 API 已加#[wasm_bindgen(catch)]并返回Result_, JsValueJsValue/导入类型参数按引用传递toString()命名为to_js_string()已在crates/js-sys/tests/wasm/对应文件添加测试含异常路径本地cargo test --target wasm32-unknown-unknown通过。延伸阅读js-sys 类型参考泛型绑定与类型擦除的完整说明js-sys 测试指南js-sys 测试入口贡献总览环境准备与代码格式化要求web-sys 贡献指南Web API 绑定属于 web-sys 而非 js-sysjs-sys 测试集全部现有绑定测试新增测试的样板来源js-sys 源码绑定规范与命名约定的权威出处赞分享开发工具【免费下载链接】wasm-bindgenFacilitating high-level interactions between Wasm modules and JavaScript项目地址https://gitcode.com/gh_mirrors/wa/wasm-bindgen点击查看免费下载相关推荐wasm-bindgen 的 web-sys 指南Web API 原始绑定、Cargo Feature 门控与新增接口的完整流程wasm bindgen 的 web sys 指南Web API 原始绑定、Cargo Feature 门控与新增接口的完整流程 导读 web sys 是 w开发工具为 web-sys 扩展新的 Web API从 WebIDL 到 Rust 绑定的完整贡献指南为 web sys 扩展新的 Web API从 WebIDL 到 Rust 绑定的完整贡献指南 web sys 是 wasm bindgen 生态中面向 We开发工具wasm-bindgen 的 js-sys crateECMAScript 全局 API 绑定与类型化泛型系统深度解析wasm bindgen 的 js sys crateECMAScript 全局 API 绑定与类型化泛型系统深度解析 导读 js sys 是 wasm bi开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考