Use of static
to Access JS Objects
JavaScript modules will often export arbitrary static objects for use with
their provided interfaces. These objects can be accessed from Rust by declaring
a named static
in the extern
block with an
#[wasm_bindgen(thread_local_v2)]
attribute. wasm-bindgen
will bind a
JsThreadLocal
for these objects, which can be cloned into a JsValue
.
These values are cached in a thread-local and are meant to bind static values or objects only. For getters which can change their return value or throw see how to import getters.
For example, given the following JavaScript:
let COLORS = {
red: 'rgb(255, 0, 0)',
green: 'rgb(0, 255, 0)',
blue: 'rgb(0, 0, 255)',
};
static
can aid in the access of this object from Rust:
# #![allow(unused_variables)] #fn main() { #[wasm_bindgen] extern "C" { #[wasm_bindgen(thread_local_v2)] static COLORS; } fn get_colors() -> JsValue { COLORS.with(JsValue::clone) } #}
Since COLORS
is effectively a JavaScript namespace, we can use the same
mechanism to refer directly to namespaces exported from JavaScript modules, and
even to exported classes:
let namespace = {
// Members of namespace...
};
class SomeType {
// Definition of SomeType...
};
export { SomeType, namespace };
The binding for this module:
# #![allow(unused_variables)] #fn main() { #[wasm_bindgen(module = "/js/some-rollup.js")] extern "C" { // Likewise with the namespace--this refers to the object directly. #[wasm_bindgen(thread_local_v2, js_name = namespace)] static NAMESPACE: JsValue; // Refer to SomeType's class #[wasm_bindgen(thread_local_v2, js_name = SomeType)] static SOME_TYPE: JsValue; // Other bindings for SomeType type SomeType; #[wasm_bindgen(constructor)] fn new() -> SomeType; } #}
Optional statics
If you expect the JavaScript value you're trying to access to not always be
available you can use Option<T>
to handle this:
# #![allow(unused_variables)] #fn main() { extern "C" { type Crypto; #[wasm_bindgen(thread_local_v2, js_name = crypto)] static CRYPTO: Option<Crypto>; } #}
If crypto
is not declared or nullish (null
or undefined
) in JavaScript,
it will simply return None
in Rust. This will also account for namespaces: it
will return Some(T)
only if all parts are declared and not nullish.
Static strings
Strings can be imported to avoid going through TextDecoder/Encoder
when requiring just a JsString
. This can be useful when dealing with environments where TextDecoder/Encoder
is not available, like in audio worklets.
# #![allow(unused_variables)] #fn main() { #[wasm_bindgen] extern "C" { #[wasm_bindgen(thread_local_v2, static_string)] static STRING: JsString = "a string literal"; } #}