客户端Web的标准库

此包的目的是提供对Web API的Rust绑定，并允许Rust和JavaScript之间实现高度的互操作性。

捐赠

赞助者

这些可爱的人们带来了这款软件

• Embark Studios
• Joe Narvaez
• Eduard Knyshov
• Anselm Eickhoff
• Johan Andersson
• Stephen Sugden
• is8ac

谢谢！

示例

您可以直接将JavaScript代码嵌入Rust

let message = "Hello, 世界!";
let result = js! {
    alert( @{message} );
    return 2 + 2 * 2;
};

println!( "2 + 2 * 2 = {:?}", result );

闭包也得到支持

let print_hello = |name: String| {
    println!( "Hello, {}!", name );
};

js! {
    var print_hello = @{print_hello};
    print_hello( "Bob" );
    print_hello.drop(); // Necessary to clean up the closure on Rust's side.
}

您还可以通过serde传递任意结构

#[derive(Serialize)]
struct Person {
    name: String,
    age: i32
}

js_serializable!( Person );

js! {
    var person = @{person};
    console.log( person.name + " is " + person.age + " years old." );
};

此包还公开了多个Web API，例如

let button = document().query_selector( "#hide-button" ).unwrap().unwrap();
button.add_event_listener( move |_: ClickEvent| {
    for anchor in document().query_selector_all( "#main a" ) {
        js!( @{anchor}.style = "display: none;"; );
    }
});

支持将Rust函数暴露给JavaScript

#[js_export]
fn hash( string: String ) -> String {
    let mut hasher = Sha1::new();
    hasher.update( string.as_bytes() );
    hasher.digest().to_string()
}

然后您可以从Node.js这样做

var hasher = require( "hasher.js" ); // Where `hasher.js` is generated from Rust code.
console.log( hasher.hash( "Hello world!" ) );

或者您可以将相同的.js文件用于Web浏览器

<script src="hasher.js"></script>
<script>
    Rust.hasher.then( function( hasher ) {
        console.log( hasher.hash( "Hello world!" ) );
    });
</script>

如果您使用Parcel，您还可以使用我们的实验性Parcel插件；首先在现有的Parcel项目中这样做

$ npm install --save parcel-plugin-cargo-web

然后只需这样

import hasher from "./hasher/Cargo.toml";
console.log( hasher.hash( "Hello world!" ) );

设计目标

• 公开浏览器公开的全套Web API。
• 尽可能地遵循原始的JavaScript约定和结构，除非这样做会产生明显更好的设计。
• 成为构建块，从它可以构建高级框架和库。
• 使其方便且易于将JavaScript代码直接嵌入Rust，并在两者之间进行数据序列化。
• 与更广泛的Rust生态系统集成，例如支持实现serde的Serializable的结构体的序列化。
• 让Rust成为驾驶席，在没有触及JavaScript的情况下编写非平凡Web应用程序。
• 允许Rust参与即将到来的WebAssembly（重新）革命。
• 使其能够轻松创建独立的库，这些库可以从JavaScript中轻松调用。

入门指南

查看一些示例

• examples/minimal - 一个完全简化的示例，调用 alert
• examples/todomvc - 一个简单实现的 TodoMVC 应用程序；展示了如何调用DOM
• examples/hasher - 展示了如何将Rust函数导出到JavaScript，以及如何在纯Web浏览器环境或Nodejs中调用它们
• examples/hasher-parcel - 展示了如何在 Parcel 项目中导入和调用导出的Rust函数
• pinky-web - 一个NES模拟器；你可以在这里尝试预编译版本 （点击此处）

API文档 也可以供你查看。

运行示例

1. 安装 cargo-web

   $ cargo install -f cargo-web
   

2. 进入 examples/todomvc 并使用以下命令之一启动示例

   • 使用Rust的本地WebAssembly后端将代码编译为 WebAssembly

     $ cargo web start --target=wasm32-unknown-unknown
     

   • 使用 Emscripten 将代码编译为 asm.js

     $ cargo web start --target=asmjs-unknown-emscripten
     

   • 使用 Emscripten 将代码编译为 WebAssembly

     $ cargo web start --target=wasm32-unknown-emscripten
     

3. 使用你的浏览器访问 https://:8000

对于 *-emscripten 目标，不需要 cargo-web，但是需要 cargo-web 才能使本地 wasm32-unknown-unknown（不需要Emscripten）工作！

变更日志

• stdweb0.4.20

  • 与最新版本的 wasm-bindgen 兼容
  • 新事件
    • FullscreenChangeEvent

• stdweb0.4.19

  • 新方法
    • Document::fullscreen_enabled
    • Document::fullscreen_element
    • InputElement::selection_start
    • InputElement::selection_end
    • InputElement::set_selection_start
    • InputElement::set_selection_end
    • Object::to_iter
    • Window::confirm
  • &Array 现在可以通过 TryFrom 转换为 Vec
  • 运行时现在应与新版本的 Emscripten 兼容
  • 不稳定的与 futures 相关的API已更新，以与最新的nightlies兼容
  • syn 依赖项已更新到版本1

• stdweb0.4.18

  • js! 宏现在可以通过 use 导入
  • 新事件
    • BeforeUnloadEvent
    • UnloadEvent
  • 新方法
    • IBlob::slice
    • IBlob::slice_with_content_type
    • IWindowOrWorker::set_clearable_timeout

• stdweb0.4.17

  • 不稳定的与 futures 相关的API已更新，以与最新的nightlies兼容

• stdweb0.4.16

  • 初始 wasm-bindgen 兼容性；你现在可以在使用 wasm-bindgen 的项目中使用 stdweb
  • 最低支持的 Rust 版本是 1.33.0
  • 最低要求的 cargo-web 版本是 0.6.24

• stdweb0.4.15

  • 不稳定的与 futures 相关的API已更新，以与最新的nightlies兼容
  • 新类型
    • FormData
    • FormDataEntry
    • MouseButtonsState
  • 新方法
    • Blob::new

• stdweb0.4.14

  • js! 宏现在在您从JS代码片段中不返回任何内容时生成更高效的代码。这使得在大多数情况下添加 @(no_return) 注释变得不必要。
  • 新类型
    • 文件

• stdweb0.4.13

  • 修复了 js! 宏的空白处理
  • 新类型
    • ITouchEvent
    • 触摸
    • 触摸类型
  • 新事件
    • 触摸事件
    • 触摸移动
    • 触摸离开
    • 触摸进入
    • 触摸结束
    • 触摸取消
    • 触摸开始
  • 新方法
    • XmlHttpRequest::set_response_type

• stdweb0.4.12

  • 在没有 cargo-web 的情况下尝试编译为 wasm32-unknown-unknown 目标时的诊断得到了改进

• stdweb0.4.11

  • 现在所需的最低Rust版本是1.30.1
  • 现在所需的最低 cargo-web 版本是0.6.22
  • wasm32-unknown-unknown 现在官方支持稳定版Rust
  • 现在支持在 wasm32-unknown-unknown 上的调试构建
  • js! 宏现在部分使用过程宏实现
  • 由于使用了本地编解码器API，字符串解码/编码现在要快得多
  • 新方法
    • Document::import_node
    • IElement::slot
    • IElement::attach_shadow
    • IElement::shadow_root
  • 新类型
    • ISlotable
    • ShadowRoot
    • ShadowRootMode
    • TemplateElement
    • SlotElement
  • 新事件
    • SlotChangeEvent
  • IParentNode::query_selector 和 IParentNode::query_selector_all 现在返回一个合适的错误类型

• stdweb 0.4.10，stdweb-derive 0.5.1

  • 新方法
    • IElement::insert_adjacent_html
    • IElement::insert_html_before
    • IElement::insert_html_after
    • IElement::prepend_html
    • IElement::append_html
    • IElement::namespace_uri
    • IElement::closest
    • Document::create_element_ns
    • Window::get_selection
  • 新类型
    • AbortError
    • SelectionType
    • Selection
    • Range
  • 失败的类型转换的错误消息现在得到了改进
  • 失败转换的错误类型（当使用 .try_into()/.try_from()）现在可以转换为 TypeError
  • 聚合错误类型（例如 DrawImageError）现在可以通过 js! 宏进行序列化
  • TypeError 现在已修复（它被错误地处理为 DOMException）
  • Number 现在可以用 .into()/.from() 转换为 f64
  • 添加了 Mut，这是一个新的包装类型，用于安全地将 FnMut 闭包传递到 js! 宏；目前这是可选的，但将来使用此包装类型 将是强制性的！
  • FnMut 闭包不能再递归调用
  • #[derive(ReferenceType)] 现在支持有限的一组泛型类型
  • 现在支持异步单元测试，通过新的 #[async_test] 属性宏（仅限夜间构建）。
  • 更新到 futures 0.3（仅限夜间构建）

• stdweb 0.4.9，stdweb-derive 0.5.0

  • 性能改进；通过 serde 进行序列化现在快了两倍
  • 新事件
    • ScrollEvent
    • DragRelatedEvent
    • DragEvent
    • DragStartEvent
    • DragEndEvent
    • DragEnterEvent
    • DragLeaveEvent
    • DragOverEvent
    • DragExitEvent
    • DragDropEvent
  • 新类型
    • DataTransfer
    • EffectAllowed
    • DropEffect
    • DataTransferItemList
    • DataTransferItem
    • DataTransferItemKind
    • IDragEvent
  • 现在可以使用 try_into 将 Value 转换为 Option< Serde< T > >
  • 现在在大多数情况下，通过 serde 进行数字反序列化现在可以工作，允许使用除 i32 和 f64 之外的类型
  • 现在所有的事件都具有更强的类型
    • 之前可以反序列化例如 keyup 事件为 KeyDownEvent，因为只检查了事件的 JS 类型，而 keyup 和 keydown 共享相同的 JS 类型（KeyboardEvent）。从现在起，还会检查事件的 type 字段，因此不再允许此类转换。

• 0.4.8

  • 在针对 wasm32-unknown-unknown 进行目标编译时，修复了最新的夜间构建时的编译问题
  • 新事件
    • PointerLockChangeEvent
    • PointerLockErrorEvent
    • MouseWheelEvent
  • 新类型
    • MouseWheelDeltaMode
    • XhrResponseType
  • 新方法
    • XmlHttpRequest::raw_response
    • Window::device_pixel_ratio
    • Document::pointer_lock_element
    • Document::exit_pointer_lock

• 0.4.7

  • 新事件
    • AuxClickEvent
    • MouseEnterEvent
    • MouseLeaveEvent
    • ContextMenuEvent
    • SelectionChangeEvent
  • 新类型
    • FileList
    • FileReaderReadyState
  • 实现游戏手柄 API
    • Gamepad
    • GamepadButton
    • GamepadButtonMapping
    • GamepadEvent
  • 修复了 CanvasRenderingContext2d::clear_rect
  • 修复了从 Vec 和 ArrayBuffer 创建 TypedArray 时的内存泄漏问题。

• 0.4.6

  • 再次修复 docs.rs
  • 新类型
    • SubmitEvent
    • IChildNode
  • 修复了 CanvasElement::to_data_url

• 0.4.5

  • 新类型
    • DocumentFragment
    • SelectElement
    • OptionElement
    • HtmlCollection
  • 新方法
    • Node::from_html
    • Value::is_null
  • 公开枚举
    • SocketMessageData
    • NodeType
  • 更新到 futures 0.2

• 0.4.4

  • 希望修复 docs.rs
  • 新方法
    • Location::origin
    • Location::protocol
    • Location::host
    • Location::hostname
    • Location::port
    • Location::pathname
    • Location::search
  • 这些现在在错误情况下返回 SecurityError
    • Location::hash
    • Location::href

• 0.4.3

  • 现在应该支持不能用作 WeakMap 键的对象（例如，Firefox 下的一些 WebGL 相关对象）
  • 新方法
    • Element::get_bounding_client_rect
    • Element::滚动顶部
    • Element::滚动左侧
    • Window::页面X偏移量
    • Window::页面Y偏移量
    • NodeList::项目
    • Document::主体
    • Document::头部
    • Document::标题
    • Document::设置标题
    • IMouseEvent::偏移X
    • IMouseEvent::偏移Y
  • 公开更多与画布相关的类型
    • 合成操作
    • 线条端点
    • 线条连接
    • 重复
    • 文本对齐
    • 文本基线
  • 公开与画布相关的错误类型：AddColorStopError、DrawImageError、GetImageDataError
  • 新事件
    • 鼠标悬停事件
    • 鼠标移出事件
    • 指针悬停事件
    • 指针进入事件
    • 指针按下事件
    • 指针移动事件
    • 指针抬起事件
    • 指针取消事件
    • 指针移出事件
    • 指针离开事件
    • 捕获指针事件
    • 失去指针捕获事件
  • 为指针事件提供新的接口：IPointerEvent

• 0.4.2

  • 修复了解析引用时的泄漏问题
  • 修复了 CanvasRenderingContext2d::get_canvas
  • 公开了 FillRule 和 SocketReadyState
  • 为 IElement 添加了相关的新方法
  • 添加了新的 Date 绑定

• 0.4.1

  • 支持最新的 nightly Rust，在 wasm32-unknown-unknown 上
  • 公开了 SocketBinaryType 枚举
  • 新的画布API
    • 为 CanvasRenderingContext2d 添加了许多新方法
    • 新类型：CanvasGradient、CanvasPattern、CanvasStyle、ImageData、TextMetrics
  • 新的错误类型：IndexSizeError、NotSupportedError、TypeError

• 0.4

  • (破坏性更改) 从 Value 中移除了 Array 和 Object 变体；现在它们被视为 Reference
  • (破坏性更改) Value 添加了一个额外的变体：Symbol
  • (破坏性更改) 移除了
    • InputElement::设置类型
    • InputElement::文件
  • (破坏性更改) 重命名
    • KeydownEvent -> KeyDownEvent
    • KeyupEvent -> KeyUpEvent
    • KeypressEvent -> KeyPressEvent
    • ReadyState -> FileReaderReadyState
    • InputElement::value -> InputElement::raw_value
    • InputElement::set_value -> InputElement::set_raw_value
  • (破坏性更改) ArrayBuffer::new 现在需要 u64 参数
  • (破坏性更改) InputElement::set_raw_value 现在需要 &str 而不是 Into< Value >
  • (破坏性更改) 修改了返回类型
    • 所有返回 usize 的方法现在返回 u32
    • INode::remove_child 现在在 Ok 情况下返回 Node
    • 以下现在返回 u64
      • ArrayBuffer::长度
    • 以下现在返回 i32 而不是 f64
      • IMouseEvent::client_x
      • IMouseEvent::client_y
      • IMouseEvent::movement_x
      • IMouseEvent::movement_y
      • IMouseEvent::screen_x
      • IMouseEvent::screen_y
    • 以下现在返回 Result
      • INode::insert_before
      • INode::replace_child
      • INode::clone_node
      • StringMap::insert
      • TokenList::add
      • TokenList::remove
      • Document::create_element
      • IEventTarget::dispatch_event
      • FileReader::read_as_text
      • FileReader::read_as_array_buffer
      • FileReader::read_as_text
      • History::replace_state
      • History::go
      • History::back
      • History::forward
      • Location::href
      • Location::hash
      • CanvasElement::to_data_url
      • CanvasElement::to_blob
      • ArrayBuffer::new
    • INode::base_uri 现在返回 String 而不是 Option< String >
    • InputElement::raw_value 现在返回 String 而不是 Value
  • (破坏性更改) INode::inner_text 已移动到 IHtmlElement::inner_text
  • (破坏性更改) Document::query_selector 和 Document::query_selector_all 已移动到 IParentNode
  • (破坏性更改) IElement::query_selector 和 IElement::query_selector_all 已移动到 IParentNode
  • (破坏性更改) Document::get_element_by_id 已移动到 INonElementParentNode
  • (破坏性更改) 移除了使用 TryFrom/TryInto 在任意引用类型对象之间转换的泛型实现
  • 当使用最近的 cargo-web 构建时，不再需要调用 stdweb::initialize 或 stdweb::event_loop
  • 支持 cdylib 在 wasm32-unknown-unknown 上的包
  • 新增绑定
    • XmlHttpRequest
    • WebSocket
    • MutationObserver
    • History
    • TextAreaElement
    • CanvasElement
  • 新增事件类型
    • MouseDownEvent
    • MouseUpEvent
    • MouseMoveEvent
    • PopStateEvent
    • ResizeEvent
    • ReadyStateChange
    • SocketCloseEvent
    • SocketErrorEvent
    • SocketOpenEvent
    • SocketMessageEvent
  • 对 Canvas APIs 的初始支持
  • 新增特性：ReferenceType 和 InstanceOf
  • 在 stdweb-derive 包中添加 #[derive(ReferenceType)] 注解；现在可以在 stdweb 之外定义自定义 API 绑定
  • 添加 #[js_export] 程序化属性（仅限 wasm32-unknown-unknown）
  • 添加 DomException 和子类型，以便传递 JavaScript 异常
  • IElement 现在继承自 INode
  • 每个接口现在都继承自 ReferenceType
  • 将 stdweb::traits 模块添加为 use 所有接口特质的预处理器
  • 添加 console! 宏
  • 现在大多数类型都实现了 PartialEq 和 Eq

• 0.3

  • (破坏性更改) 删除了 ErrorEvent 方法
  • (破坏性更改) 重命名
    • LoadEvent -> ResourceLoadEvent
    • AbortEvent -> ResourceAbortEvent
    • ErrorEvent -> ResourceErrorEvent
  • 为传递给 js! 的切片提供零成本，添加了 UnsafeTypedArray
  • 为将 FnOnce 闭包传递给 js! 添加了 Once