不稳定的 API

浏览器在编写 Web API 规范时实现 API 的某些部分是很常见的。随着规范的不断开发,API 可能需要频繁更改,因此 WebIDL 相对不稳定。

这给 web-sys 带来了一些挑战,因为这意味着每当 WebIDL 更改时,web-sys 都必须进行破坏性的 API 更改。这也意味着先前发布的 web-sys 版本将无效,因为浏览器 API 可能已被更改以匹配更新的 WebIDL。

为了避免不稳定 API 的频繁重大更改,web-sys 通过类似如下的属性隐藏所有不稳定的 API


# #![allow(unused_variables)]
#fn main() {
#[cfg(web_sys_unstable_apis)]
pub struct Foo;
#}

通过属性隐藏不稳定的 API,crate 必须显式选择加入这些降低的稳定性保证才能使用这些 API。具体来说,这些 API 不遵循语义版本控制,并且可能会在 WebIDL 更改时中断。

Crate 可以通过传递 cfg 标志 web_sys_unstable_apis 在编译时选择加入不稳定的 API。

通常,RUSTFLAGS 环境变量用于执行此操作。例如

RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run

或者,您可以创建一个 cargo 配置文件来设置其 rustflags

./.cargo/config.toml

[build]
rustflags = ["--cfg=web_sys_unstable_apis"]