maple

一个无 VDOM 的细粒度响应式网页库。

入门指南

推荐使用构建工具 Trunk。首先，将 maple-core 添加到您的 Cargo.toml 文件中。

maple-core = "0.4.3"

将以下内容添加到您的 src/main.rs 文件中

use maple_core::prelude::*;

fn main() {
    let root = template! {
        p {
            "Hello World!"
        }
    };

    render(|| root);
}

这样就完成了！这是使用 maple 编写的“Hello World”程序。要运行应用程序，只需运行 trunk serve --open 并在您的网页浏览器中查看结果。

template! 宏

maple 使用 template! 宏作为创建复杂用户界面的便捷方式。

// You can create nested elements.
template! {
    div {
        p {
            span { "Hello " }
            strong { "World!" }
        }
    }
};

// Attributes (including classes and ids) can also be specified.
template! {
    p(class="my-class", id="my-paragraph", aria-label="My paragraph")
};

template! {
    button(disabled="true") {
        "My button"
    }
}

// Events are attached using the `on:*` directive.
template! {
    button(on:click=|_| { /* do something */ }) {
        "Click me"
    }
}

响应式

与依赖于虚拟 DOM (VDOM) 不同，maple 使用细粒度响应式来保持 DOM 和状态同步。实际上，maple 的响应式部分可以单独使用，而无需 DOM 渲染部分。

响应式基于响应式原语。以下是一个示例

use maple_core::prelude::*;
let state = Signal::new(0); // create an atom with an initial value of 0

如果您熟悉 React 钩子，这会立即让您感到熟悉。

现在，要访问状态，我们像这样在 state 上调用 .get() 方法

println!("The state is: {}", state.get()); // prints "The state is: 0"

要更新状态，我们像这样在 state 上调用 .set(...) 方法

state.set(1);
println!("The state is: {}", state.get()); // should now print "The state is: 1"

这有什么用？这很有用，因为它提供了一种轻松通知任何状态变化的方法。例如，假设我们想要打印出每个状态变化。这可以轻松地按照以下方式完成

let state = Signal::new(0);

create_effect(cloned!((state) => move || {
    println!("The state changed. New value: {}", state.get());
}));  // prints "The state changed. New value: 0" (note that the effect is always executed at least 1 regardless of state changes)

state.set(1); // prints "The state changed. New value: 1"
state.set(2); // prints "The state changed. New value: 2"
state.set(3); // prints "The state changed. New value: 3"

函数create_effect(...)是如何知道每次状态变化时都要执行闭包的？调用create_effect会创建一个新的“响应式作用域”，在这个作用域内部调用state.get()会将自身添加为一个依赖。现在，当调用state.set(...)时，它会自动调用所有的依赖，在这种情况下，是state，因为它是在闭包内部被调用的。

那个cloned!宏是什么做的？

cloned!宏是一个克隆变量到后续表达式的实用宏。之前的create_effect函数调用完全可以写成

create_effect({
    let state = state.clone();
    move || {
        println!("The state changed. New value: {}", state.get());
    }
}));

这最终只是一个直到Rust RFC #2407中发生某些事情之前的权宜之计。

我们还可以很容易地使用create_memo(...)创建派生状态，它实际上是create_effect的一个便于使用的包装器

let state = Signal::new(0);
let double = create_memo(cloned!((state) => move || *state.get() * 2));

assert_eq!(*double.get(), 0);

state.set(1);
assert_eq!(*double.get(), 2);

create_memo(...)会在其任何依赖发生变化时自动重新计算派生值。

现在您已经了解了maple的响应式系统，我们可以看看如何使用它来更新DOM。

使用响应式进行DOM更新

响应式自动内置到template!宏中。假设我们有以下代码

use maple_core::prelude::*;

let state = Signal::new(0);

let root = template! {
    p {
        (state.get())
    }
}

这将展开成类似于以下的内容

use maple_core::prelude::*;
use maple_core::internal;

let state = Signal::new(0);

let root = {
    let element = internal::element(p);
    let text = internal::text(String::new() /* placeholder */);
    create_effect(move || {
        // update text when state changes
        text.set_text_content(Some(&state.get()));
    });

    internal::append(&element, &text);

    element
}

如果我们代码中的其他地方调用了state.set(...)，文本内容将自动更新！

组件

maple中的组件仅仅是返回HtmlElement的函数。它们通过函数参数接收它们的属性。

为了使组件能够自动响应属性变化，它们应该接受一个类型为StateHandle<T>的属性，并在template!中调用函数以订阅状态。

为Signal<T>获取StateHandle<T>非常简单。只需调用.handle()方法。

// This is temporary and will later be removed.
// Currently, the template! macro assumes that all components start with an uppercase character.
#![allow(non_snake_case)]

use maple_core::prelude::*;

fn Component(value: StateHandle<i32>) -> TemplateResult {
    template! {
        div(class="my-component") {
            "Value: " (value.get())
        }
    }
}

// ...
let state = Signal::new(0);

template! {
    Component(state.handle())
}

state.set(1); // automatically updates value in Component