docs: synchronize #3555 0.21 changes to Next (#3834)

This commit is contained in:
Siyuan Yan 2025-03-26 23:04:57 +09:00 committed by GitHub
parent 842dc29ddc
commit b0d0656261
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -105,14 +105,14 @@ _[extends section in The `wasm-bindgen` Guide](https://rustwasm.github.io/docs/w
### [`JsValue`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html) ### [`JsValue`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html)
This is a representation of an object owned by JavaScript, this is a root catch-all type for `wasm-bindgen`. This is a representation of an object owned by JavaScript, this is a root catch-all type for `wasm-bindgen`.
Any type that comes from `wasm-bindgen` is a `JsValue` and this is because JavaScript does not have Because JavaScript does not have a strong type system, any type that comes from `wasm-bindgen` is a `JsValue`.
a strong type system so any function that accepts a variable `x` does not define its type so `x` can be Functions in JavaScript do not define the type of any variables they take in or return; variables can be
a valid JavaScript value; hence `JsValue`. If you are working with imported functions or types that any valid JavaScript value, hence `JsValue`. If you are working with imported functions or types that
accept a `JsValue`, then any imported value is _technically_ valid. accept a `JsValue`, then any imported value is _technically_ valid.
`JsValue` can be accepted by a function but that function may still only accept certain types and this Even though `JsValue` may be accepted by a JS function, that function may still only _actually_ accept certain types.
can lead to panics - so when using raw `wasm-bindgen` APIs check the documentation of the JavaScript Passing an incorrect `JsValue` can lead to an exception which triggers a panic - so when using raw `wasm-bindgen` APIs,
being imported as to whether an exception (panic) will be raised if that value is not a certain type. check the your JavaScript's documentation for types of inputs that will cause an exception (and a panic).
_[`JsValue` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html)._ _[`JsValue` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/struct.JsValue.html)._
@ -125,13 +125,13 @@ that if you have one type which you know is another, then you can use the functi
to jump from one type to the other. It is a nice trait to get to know when working with `web-sys`, to jump from one type to the other. It is a nice trait to get to know when working with `web-sys`,
`wasm_bindgen`, `js-sys` - you will notice lots of types will implement `JsCast` from those crates. `wasm_bindgen`, `js-sys` - you will notice lots of types will implement `JsCast` from those crates.
`JsCast` provides both checked and unchecked methods of casting - so that at runtime if you are `JsCast` provides both checked and unchecked methods of casting - so if at runtime if you are
unsure what type a certain object is you can try to cast it which returns possible failure types like unsure what type a certain object is, you can try to cast it, which returns possible failure types like
[`Option`](https://doc.rust-lang.org/std/option/enum.Option.html) and [`Option`](https://doc.rust-lang.org/std/option/enum.Option.html) and
[`Result`](https://doc.rust-lang.org/std/result/enum.Result.html). [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html).
A common example of this in [`web-sys`](./web-sys.mdx) is when you are trying to get the A common example of this in [`web-sys`](./web-sys.mdx) is when you are trying to get the
target of an event. You might know what the target element is but the target of an event. You might know what the target element is, but the
[`web_sys::Event`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Event.html) API will always return an [`Option<web_sys::EventTarget>`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Event.html#method.target). [`web_sys::Event`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Event.html) API will always return an [`Option<web_sys::EventTarget>`](https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Event.html#method.target).
You will need to cast it to the element type so you can call its methods. You will need to cast it to the element type so you can call its methods.
@ -157,7 +157,7 @@ fn handle_event(event: Event) {
``` ```
The [`dyn_ref`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html#method.dyn_ref) The [`dyn_ref`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html#method.dyn_ref)
method is a checked cast that returns an `Option<&T>` which means the original type method is a checked cast that returns an `Option<&T>`, which means the original type
can be used again if the cast failed and thus returned `None`. The can be used again if the cast failed and thus returned `None`. The
[`dyn_into`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html#method.dyn_into) [`dyn_into`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/trait.JsCast.html#method.dyn_into)
method will consume `self`, as per convention for `into` methods in Rust, and the type returned is method will consume `self`, as per convention for `into` methods in Rust, and the type returned is
@ -168,10 +168,10 @@ _[`JsCast` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindg
### [`Closure`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/closure/struct.Closure.html) ### [`Closure`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/closure/struct.Closure.html)
The `Closure` type provides a way to transfer Rust closures to JavaScript, the closures passed to The `Closure` type provides a way to transfer Rust closures to JavaScript. The closures passed to
JavaScript must have a `'static` lifetime for soundness reasons. JavaScript must have a `'static` lifetime for soundness reasons.
This type is a "handle" in the sense that whenever it is dropped it will invalidate the JS This type is a "handle" in the sense that whenever it is dropped, it will invalidate the JS
closure that it refers to. Any usage of the closure in JS after the Closure has been dropped will closure that it refers to. Any usage of the closure in JS after the Closure has been dropped will
raise an exception. raise an exception.
@ -187,7 +187,7 @@ _[`Closure` documentation](https://rustwasm.github.io/wasm-bindgen/api/wasm_bind
The `js-sys` crate provides bindings/imports of JavaScript's standard, built-in objects, including The `js-sys` crate provides bindings/imports of JavaScript's standard, built-in objects, including
their methods and properties. their methods and properties.
This does not include any web APIs as this is what [`web-sys`](./web-sys.mdx) is for! This does not include any web APIs; that's what [`web-sys`](./web-sys.mdx) is for!
_[`js-sys` documentation](https://rustwasm.github.io/wasm-bindgen/api/js_sys/index.html)._ _[`js-sys` documentation](https://rustwasm.github.io/wasm-bindgen/api/js_sys/index.html)._