mirror of
https://github.com/DioxusLabs/dioxus
synced 2024-11-27 06:30:20 +00:00
Fix: Remove play button from guide example (#1118)
* fix: Remove play button from guide example * Update index.md * update other examples
This commit is contained in:
parent
90f80e4dc2
commit
98fc153152
74 changed files with 503 additions and 503 deletions
|
@ -2,7 +2,7 @@
|
|||
|
||||
Yew subscriptions are used to schedule update for components into the future. The `Context` object can create subscriptions:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Component(cx: Component) -> DomTree {
|
||||
let update = cx.schedule();
|
||||
|
||||
|
@ -19,7 +19,7 @@ The subscription API exposes this functionality allowing hooks and state managem
|
|||
some state or event occurs outside of the component. For instance, the `use_context` hook uses this to subscribe components that use a
|
||||
particular context.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn use_context<I>(cx: Scope<T>) -> I {
|
||||
|
||||
}
|
||||
|
|
|
@ -4,7 +4,7 @@ Concurrent mode provides a mechanism for building efficient asynchronous compone
|
|||
|
||||
To make a component asynchronous, simply change its function signature to async.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Example(cx: Scope) -> Vnode {
|
||||
rsx!{ <div> "Hello world!" </div> }
|
||||
}
|
||||
|
@ -12,7 +12,7 @@ fn Example(cx: Scope) -> Vnode {
|
|||
|
||||
becomes
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
async fn Example(cx: Scope) -> Vnode {
|
||||
rsx!{ <div> "Hello world!" </div> }
|
||||
}
|
||||
|
@ -20,7 +20,7 @@ async fn Example(cx: Scope) -> Vnode {
|
|||
|
||||
Now, logic in components can be awaited to delay updates of the component and its children. Like so:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
async fn Example(cx: Scope) -> Vnode {
|
||||
let name = fetch_name().await;
|
||||
rsx!{ <div> "Hello {name}" </div> }
|
||||
|
@ -39,7 +39,7 @@ Instead, we suggest using hooks and future combinators that can safely utilize t
|
|||
|
||||
As part of our Dioxus hooks crate, we provide a data loader hook which pauses a component until its async dependencies are ready. This caches requests, reruns the fetch if dependencies have changed, and provides the option to render something else while the component is loading.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
async fn ExampleLoader(cx: Scope) -> Vnode {
|
||||
/*
|
||||
Fetch, pause the component from rendering at all.
|
||||
|
@ -61,7 +61,7 @@ async fn ExampleLoader(cx: Scope) -> Vnode {
|
|||
}
|
||||
```
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
async fn Example(cx: Scope) -> DomTree {
|
||||
// Diff this set between the last set
|
||||
// Check if we have any outstanding tasks?
|
||||
|
|
|
@ -10,7 +10,7 @@ https://dmitripavlutin.com/use-react-memo-wisely/
|
|||
|
||||
This behavior is defined as an attribute implicit to user components. When in React land you might wrap a component with `react.memo`, Dioxus components are automatically memoized via an implicit attribute. You can manually configure this behavior on any component with "nomemo" to disable memoization.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn test() -> DomTree {
|
||||
html! {
|
||||
<>
|
||||
|
@ -42,7 +42,7 @@ fn test_component(cx: Scope, name: String) -> Element {
|
|||
|
||||
Take a component like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn test(cx: Scope) -> DomTree {
|
||||
let Bundle { alpha, beta, gamma } = use_context::<SomeContext>(cx);
|
||||
html! {
|
||||
|
|
|
@ -10,7 +10,7 @@ By default, Dioxus will only try to diff subtrees of components with dynamic con
|
|||
|
||||
Your component today might look something like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Comp(cx: Scope) -> DomTree {
|
||||
let (title, set_title) = use_state(cx, || "Title".to_string());
|
||||
cx.render(rsx!{
|
||||
|
@ -24,7 +24,7 @@ fn Comp(cx: Scope) -> DomTree {
|
|||
|
||||
This component is fairly straightforward – the input updates its own value on every change. However, every call to set_title will re-render the component. If we add a large list, then every time we update the title input, Dioxus will need to diff the entire list, over, and over, and over. This is **a lot** of wasted clock-cycles!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Comp(cx: Scope) -> DomTree {
|
||||
let (title, set_title) = use_state(cx, || "Title".to_string());
|
||||
cx.render(rsx!{
|
||||
|
@ -47,7 +47,7 @@ Many experienced React developers will just say "this is bad design" – but we
|
|||
|
||||
We can use signals to generate a two-way binding between data and the input box. Our text input is now just a two-line component!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Comp(cx: Scope) -> DomTree {
|
||||
let mut title = use_signal(cx, || String::from("Title"));
|
||||
cx.render(rsx!(input { value: title }))
|
||||
|
@ -56,7 +56,7 @@ fn Comp(cx: Scope) -> DomTree {
|
|||
|
||||
For a slightly more interesting example, this component calculates the sum between two numbers, but totally skips the diffing process.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Calculator(cx: Scope) -> DomTree {
|
||||
let mut a = use_signal(cx, || 0);
|
||||
let mut b = use_signal(cx, || 0);
|
||||
|
@ -71,7 +71,7 @@ fn Calculator(cx: Scope) -> DomTree {
|
|||
|
||||
Do you notice how we can use built-in operations on signals? Under the hood, we actually create a new derived signal that depends on `a` and `b`. Whenever `a` or `b` update, then `c` will update. If we need to create a new derived signal that's more complex than a basic operation (`std::ops`) we can either chain signals together or combine them:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let mut a = use_signal(cx, || 0);
|
||||
let mut b = use_signal(cx, || 0);
|
||||
|
||||
|
@ -83,7 +83,7 @@ let c = a.with(b).map(|(a, b)| *a + *b);
|
|||
|
||||
If we ever need to get the value out of a signal, we can simply `deref` it.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let mut a = use_signal(cx, || 0);
|
||||
let c = *a + *b;
|
||||
```
|
||||
|
@ -94,7 +94,7 @@ Calling `deref` or `deref_mut` is actually more complex than it seems. When a va
|
|||
|
||||
Sometimes you want a signal to propagate across your app, either through far-away siblings or through deeply-nested components. In these cases, we use Dirac: Dioxus's first-class state management toolkit. Dirac atoms automatically implement the Signal API. This component will bind the input element to the `TITLE` atom.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
const TITLE: Atom<String> = || "".to_string();
|
||||
const Provider: Component = |cx|{
|
||||
let title = use_signal(cx, &TITLE);
|
||||
|
@ -104,7 +104,7 @@ const Provider: Component = |cx|{
|
|||
|
||||
If we use the `TITLE` atom in another component, we can cause updates to flow between components without calling render or diffing either component trees:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
const Receiver: Component = |cx|{
|
||||
let title = use_signal(cx, &TITLE);
|
||||
log::info!("This will only be called once!");
|
||||
|
@ -130,7 +130,7 @@ By default, Dioxus is limited when you use iter/map. With the `For` component, y
|
|||
|
||||
Dioxus automatically understands how to use your signals when mixed with iterators through `Deref`/`DerefMut`. This lets you efficiently map collections while avoiding the re-rendering of lists. In essence, signals act as a hint to Dioxus on how to avoid un-necessary checks and renders, making your app faster.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
const DICT: AtomFamily<String, String> = |_| {};
|
||||
const List: Component = |cx|{
|
||||
let dict = use_signal(cx, &DICT);
|
||||
|
@ -146,7 +146,7 @@ const List: Component = |cx|{
|
|||
|
||||
Apps that use signals will enjoy a pleasant hybrid of server-side and client-side rendering.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
|
||||
```
|
||||
|
||||
|
|
|
@ -22,13 +22,11 @@ The desktop renderer comes pre-loaded with the window and notification subtree p
|
|||
|
||||
Subtrees also solve the "bridging" issues in React where two different renderers need two different VirtualDoms to work properly. In Dioxus, you only ever need one VirtualDom and the right renderer plugins.
|
||||
|
||||
|
||||
## API
|
||||
|
||||
Due to their importance in the hierarchy, Components – not nodes – are treated as subtree roots.
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
|
||||
fn Subtree<P>(cx: Scope<P>) -> DomTree {
|
||||
|
||||
|
|
|
@ -22,7 +22,7 @@ For reference, check out the WebSys renderer as a starting point for your custom
|
|||
|
||||
The current `RealDom` trait lives in `dioxus-core/diff`. A version of it is provided here (but might not be up-to-date):
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
pub trait RealDom<'a> {
|
||||
fn handle_edit(&mut self, edit: DomEdit);
|
||||
fn request_available_node(&mut self) -> ElementId;
|
||||
|
@ -32,7 +32,7 @@ pub trait RealDom<'a> {
|
|||
|
||||
For reference, the "DomEdit" type is a serialized enum that represents an atomic operation occurring on the RealDom. The variants roughly follow this set:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum DomEdit {
|
||||
PushRoot,
|
||||
AppendChildren,
|
||||
|
@ -51,12 +51,11 @@ enum DomEdit {
|
|||
|
||||
The Dioxus diffing mechanism operates as a [stack machine](https://en.wikipedia.org/wiki/Stack_machine) where the "push_root" method pushes a new "real" DOM node onto the stack and "append_child" and "replace_with" both remove nodes from the stack.
|
||||
|
||||
|
||||
### An example
|
||||
|
||||
For the sake of understanding, lets consider this example – a very simple UI declaration:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!( h1 {"hello world"} )
|
||||
```
|
||||
|
||||
|
@ -64,7 +63,7 @@ To get things started, Dioxus must first navigate to the container of this h1 ta
|
|||
|
||||
When the renderer receives this instruction, it pushes the actual Node onto its own stack. The real renderer's stack will look like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container)
|
||||
]
|
||||
|
@ -75,7 +74,7 @@ stack: [
|
|||
|
||||
Next, Dioxus will encounter the h1 node. The diff algorithm decides that this node needs to be created, so Dioxus will generate the DomEdit `CreateElement`. When the renderer receives this instruction, it will create an unmounted node and push into its own stack:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -85,8 +84,10 @@ stack: [
|
|||
h1,
|
||||
]
|
||||
```
|
||||
|
||||
Next, Dioxus sees the text node, and generates the `CreateTextNode` DomEdit:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -98,9 +99,10 @@ stack: [
|
|||
"hello world"
|
||||
]
|
||||
```
|
||||
|
||||
Remember, the text node is not attached to anything (it is unmounted) so Dioxus needs to generate an Edit that connects the text node to the h1 element. It depends on the situation, but in this case we use `AppendChildren`. This pops the text node off the stack, leaving the h1 element as the next element in line.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -112,8 +114,10 @@ stack: [
|
|||
h1
|
||||
]
|
||||
```
|
||||
|
||||
We call `AppendChildren` again, popping off the h1 node and attaching it to the parent:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -125,8 +129,10 @@ stack: [
|
|||
ContainerNode,
|
||||
]
|
||||
```
|
||||
|
||||
Finally, the container is popped since we don't need it anymore.
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -137,8 +143,10 @@ instructions: [
|
|||
]
|
||||
stack: []
|
||||
```
|
||||
|
||||
Over time, our stack looked like this:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
[]
|
||||
[Container]
|
||||
[Container, h1]
|
||||
|
@ -164,7 +172,7 @@ Like most GUIs, Dioxus relies on an event loop to progress the VirtualDOM. The V
|
|||
|
||||
The code for the WebSys implementation is straightforward, so we'll add it here to demonstrate how simple an event loop is:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
||||
// Push the body element onto the WebsysDom's stack machine
|
||||
let mut websys_dom = crate::new::WebsysDom::new(prepare_websys_dom());
|
||||
|
@ -194,7 +202,7 @@ pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
|||
|
||||
It's important that you decode the real events from your event system into Dioxus' synthetic event system (synthetic meaning abstracted). This simply means matching your event type and creating a Dioxus `VirtualEvent` type. Your custom event must implement the corresponding event trait. Right now, the VirtualEvent system is modeled almost entirely around the HTML spec, but we are interested in slimming it down.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn virtual_event_from_websys_event(event: &web_sys::Event) -> VirtualEvent {
|
||||
match event.type_().as_str() {
|
||||
"keydown" | "keypress" | "keyup" => {
|
||||
|
@ -224,7 +232,7 @@ These custom elements are defined as unit structs with trait implementations.
|
|||
|
||||
For example, the `div` element is (approximately!) defined as such:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
struct div;
|
||||
impl div {
|
||||
/// Some glorious documentation about the class property.
|
||||
|
@ -235,8 +243,8 @@ impl div {
|
|||
// more attributes
|
||||
}
|
||||
```
|
||||
You've probably noticed that many elements in the `rsx!` and `html!` macros support on-hover documentation. The approach we take to custom elements means that the unit struct is created immediately where the element is used in the macro. When the macro is expanded, the doc comments still apply to the unit struct, giving tons of in-editor feedback, even inside a proc macro.
|
||||
|
||||
You've probably noticed that many elements in the `rsx!` and `html!` macros support on-hover documentation. The approach we take to custom elements means that the unit struct is created immediately where the element is used in the macro. When the macro is expanded, the doc comments still apply to the unit struct, giving tons of in-editor feedback, even inside a proc macro.
|
||||
|
||||
## Compatibility
|
||||
|
||||
|
@ -252,7 +260,7 @@ The best hooks will properly detect the target platform and still provide functi
|
|||
|
||||
This particular code _will panic_ due to the unwrap on downcast_ref. Try to avoid these types of patterns.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let div_ref = use_node_ref(cx);
|
||||
|
||||
cx.render(rsx!{
|
||||
|
|
|
@ -5,11 +5,14 @@ Many modern frameworks provide a domain-specific-language for declaring user-int
|
|||
With Dioxus, we actually ship two different macros – a macro that mimics JSX (the `html!` macro) and a macro that mimics Rust's native nested-struct syntax (the `rsx!` macro). These macros simply transform their inputs into NodeFactory calls.
|
||||
|
||||
For instance, this html! call:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
html!(<div> "hello world" </div>)
|
||||
```
|
||||
|
||||
becomes this NodeFactory call:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
|f| f.element(
|
||||
dioxus_elements::div, // tag
|
||||
[], // listeners
|
||||
|
@ -18,6 +21,7 @@ becomes this NodeFactory call:
|
|||
None // key
|
||||
)
|
||||
```
|
||||
|
||||
The NodeFactory API is fairly ergonomic, making it a viable option to use directly. The NodeFactory API is also compile-time correct and has incredible syntax highlighting support. We use what Rust calls a "unit type" – the `dioxus_elements::div` and associated methods to ensure that a `div` can only have attributes associated with `div`s. This lets us tack on relevant documentation, autocomplete support, and jump-to-definition for methods and attributes.
|
||||
|
||||
![Compile time correct syntax](../images/compiletimecorrect.png)
|
||||
|
@ -28,7 +32,7 @@ The html! macro supports a limited subset of the html standard. Rust's macro par
|
|||
|
||||
However, writing HTML by hand is a bit tedious – IDE tools for Rust don't support linting/autocomplete/syntax highlighting. We suggest using RSX – it's more natural for Rust programs and _does_ integrate well with Rust IDE tools.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let name = "jane";
|
||||
let pending = false;
|
||||
let count = 10;
|
||||
|
@ -50,7 +54,7 @@ When helpful, the Dioxus VSCode extension provides a way of converting a selecti
|
|||
|
||||
It's also a bit easier on the eyes than HTML.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
dioxus::ssr::render_lazy(rsx! {
|
||||
div {
|
||||
p {"Hello, {name}!"}
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
To test your Rust code, you can annotate any function with the `#[test]` block. In VSCode with RA, this will provide a lens to click and run the test.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[test]
|
||||
fn component_runs() {
|
||||
assert!(true)
|
||||
|
@ -11,7 +11,7 @@ fn component_runs() {
|
|||
|
||||
This will test your Rust code _without_ going through the browser. This is ideal for squashing logic bugs and ensuring components render appropriately when the browsers's DOM is not needed. If you need to run tests in the browser, you can annotate your blocks with the `#[dioxus::test]` block.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[dioxus::test]
|
||||
fn runs_in_browser() {
|
||||
// ...
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
In the cases where you need to pass arbitrary element properties into a component – say to add more functionality to the `<a>` tag, Dioxus will accept any quoted fields. This is similar to adding arbitrary fields to regular elements using quotes.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
|
||||
rsx!(
|
||||
Clickable {
|
||||
|
@ -13,7 +13,7 @@ rsx!(
|
|||
|
||||
For a component to accept these attributes, you must add an `attributes` field to your component's properties. We can use the spread syntax to add these attributes to whatever nodes are in our component.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[derive(Props)]
|
||||
struct ClickableProps<'a> {
|
||||
attributes: Attributes<'a>
|
||||
|
@ -27,3 +27,4 @@ fn clickable(cx: Scope<ClickableProps<'a>>) -> Element {
|
|||
}
|
||||
))
|
||||
}
|
||||
```
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
# Thinking in Reactively
|
||||
|
||||
We've finally reached the point in our tutorial where we can talk about the theory of Reactivity. We've talked about defining a declarative view, but not about the aspects that make our code *reactive*.
|
||||
We've finally reached the point in our tutorial where we can talk about the theory of Reactivity. We've talked about defining a declarative view, but not about the aspects that make our code _reactive_.
|
||||
|
||||
Understanding the theory of reactive programming is essential to making sense of Dioxus and writing effective, performant UIs.
|
||||
|
||||
|
@ -15,7 +15,7 @@ This section is a bit long, but worth the read. We recommend coffee, tea, and/or
|
|||
|
||||
## Reactive Programming
|
||||
|
||||
Dioxus is one of a handful of Rust libraries that provide a "Reactive Programming Model". The term "Reactive programming" is a classification of programming paradigm – much like functional or imperative programming. This is a very important distinction since it affects how we *think* about our code.
|
||||
Dioxus is one of a handful of Rust libraries that provide a "Reactive Programming Model". The term "Reactive programming" is a classification of programming paradigm – much like functional or imperative programming. This is a very important distinction since it affects how we _think_ about our code.
|
||||
|
||||
Reactive programming is a programming model concerned with deriving computations from asynchronous data flow. Most reactive programs are comprised of datasources, intermediate computations, and a final result.
|
||||
|
||||
|
@ -33,7 +33,7 @@ In Reactive Programming, we don't think about whether or not we should reevaluat
|
|||
|
||||
In Rust, our reactive app would look something like:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn compute_g(t: i32, seconds: i32) -> bool {
|
||||
t > seconds
|
||||
}
|
||||
|
@ -55,7 +55,7 @@ The Dioxus VirtualDom provides us a framework for reactive programming. When we
|
|||
|
||||
If we represented the reactive graph presented above in Dioxus, it would look very similar:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// Declare a component that holds our datasources and calculates `g`
|
||||
fn RenderGraph(cx: Scope) -> Element {
|
||||
let seconds = use_datasource(SECONDS);
|
||||
|
@ -83,11 +83,11 @@ fn RenderT(cx: Scope, seconds: i32, constant: i32) -> Element {
|
|||
|
||||
With this app, we've defined three components. Our top-level component provides our datasources (the hooks), computation nodes (child components), and a final value (what's "rendered").
|
||||
|
||||
Now, whenever the `constant` changes, our `RenderT` component will be re-rendered. However, if `seconds` doesn't change, then we don't need to re-render `RenderG` because the input is the same. If `seconds` *does* change, then both RenderG and RenderT will be reevaluated.
|
||||
Now, whenever the `constant` changes, our `RenderT` component will be re-rendered. However, if `seconds` doesn't change, then we don't need to re-render `RenderG` because the input is the same. If `seconds` _does_ change, then both RenderG and RenderT will be reevaluated.
|
||||
|
||||
Dioxus is "Reactive" because it provides this framework for us. All we need to do is write our own tiny units of computation and Dioxus figures out which components need to be reevaluated automatically.
|
||||
|
||||
These extra checks and algorithms add some overhead, which is why you see projects like [Sycamore](http://sycamore-rs.netlify.app) and [SolidJS](http://solidjs.com) eliminating them altogether. Dioxus is *really* fast, so we're willing to exchange the added overhead for improved developer experience.
|
||||
These extra checks and algorithms add some overhead, which is why you see projects like [Sycamore](http://sycamore-rs.netlify.app) and [SolidJS](http://solidjs.com) eliminating them altogether. Dioxus is _really_ fast, so we're willing to exchange the added overhead for improved developer experience.
|
||||
|
||||
## How do we update values in our dataflow graph?
|
||||
|
||||
|
@ -104,7 +104,7 @@ Technically, the root props of the VirtualDom are a third datasource, but since
|
|||
|
||||
For local state in hooks, Dioxus gives us the `use_hook` method which returns an `&mut T` without any requirements. This means raw hook values are not tracked by Dioxus. In fact, we could write a component that modifies a hook value directly:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let mut count = cx.use_hook(|_| 0);
|
||||
cx.render(rsx!{
|
||||
|
@ -118,7 +118,7 @@ fn app(cx: Scope) -> Element {
|
|||
|
||||
However, when this value is written to, the component does not know to be reevaluated. We must explicitly tell Dioxus that this component is "dirty" and needs to be re-rendered. This is done through the `cx.needs_update` method:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
button {
|
||||
onclick: move |_| {
|
||||
*count += 1;
|
||||
|
@ -130,7 +130,7 @@ button {
|
|||
|
||||
Now, whenever we click the button, the value will change and the component will be re-rendered.
|
||||
|
||||
> Re-rendering is when Dioxus calls your function component *again*. Component functions will be called over and over throughout their lifetime, so they should be mostly side-effect free.
|
||||
> Re-rendering is when Dioxus calls your function component _again_. Component functions will be called over and over throughout their lifetime, so they should be mostly side-effect free.
|
||||
|
||||
### Understand this!
|
||||
|
||||
|
@ -146,9 +146,9 @@ To make app-global state easier to reason about, Dioxus makes all values provide
|
|||
|
||||
In these cases, App-Global state needs to manually track which components need to be re-generated.
|
||||
|
||||
To regenerate *any* component in your app, you can get a handle to the Dioxus' internal scheduler through `schedule_update_any`:
|
||||
To regenerate _any_ component in your app, you can get a handle to the Dioxus' internal scheduler through `schedule_update_any`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let force_render = cx.schedule_update_any();
|
||||
|
||||
// force a render of the root component
|
||||
|
@ -179,9 +179,9 @@ From here, Dioxus computes the difference between these trees and updates the Re
|
|||
|
||||
## Suppressing Renders
|
||||
|
||||
So, we know how to make Dioxus render, but how do we *stop* it? What if we *know* that our state didn't change and we shouldn't render and diff new nodes because they'll be exactly the same as the last time?
|
||||
So, we know how to make Dioxus render, but how do we _stop_ it? What if we _know_ that our state didn't change and we shouldn't render and diff new nodes because they'll be exactly the same as the last time?
|
||||
|
||||
In these cases, you want to reach for *memoization*. In Dioxus, memoization involves preventing a component from rendering again if its props didn't change since the last time it attempted to render.
|
||||
In these cases, you want to reach for _memoization_. In Dioxus, memoization involves preventing a component from rendering again if its props didn't change since the last time it attempted to render.
|
||||
|
||||
Visually, you can tell that a component will only re-render if the new value is sufficiently different than the old one.
|
||||
|
||||
|
@ -196,7 +196,7 @@ Visually, you can tell that a component will only re-render if the new value is
|
|||
|
||||
This is why when you `derive(Props)`, you must also implement the `PartialEq` trait. To override the memoization strategy for a component, you can simply implement your own PartialEq.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
struct CustomProps {
|
||||
val: i32,
|
||||
}
|
||||
|
@ -215,7 +215,7 @@ However, for components that borrow data, it doesn't make sense to implement Par
|
|||
|
||||
You can technically override this behavior by implementing the `Props` trait manually, though it's unsafe and easy to mess up:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
unsafe impl Properties for CustomProps {
|
||||
fn memoize(&self, other &Self) -> bool {
|
||||
self != other
|
||||
|
@ -224,6 +224,7 @@ unsafe impl Properties for CustomProps {
|
|||
```
|
||||
|
||||
TLDR:
|
||||
|
||||
- Dioxus checks if props changed between renders
|
||||
- If props changed according to PartialEq, Dioxus re-renders the component
|
||||
- Props that have a lifetime (ie `<'a>`) will always be re-rendered
|
||||
|
|
|
@ -6,7 +6,7 @@ One of the most reliable state management patterns in large Dioxus apps is `fan-
|
|||
|
||||
With `fan-out`, our individual components at "leaf" position of our VirtualDom are "pure", making them easily reusable, testable, and deterministic. For instance, the "title" bar of our app might be a fairly complicated component.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[derive(Props, PartialEq)]
|
||||
struct TitlebarProps {
|
||||
title: String,
|
||||
|
@ -26,7 +26,7 @@ fn Titlebar(cx: Scope<TitlebarProps>) -> Element {
|
|||
|
||||
If we used global state like use_context or fermi, we might be tempted to inject our `use_read` directly into the component.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Titlebar(cx: Scope<TitlebarProps>) -> Element {
|
||||
let title = use_read(cx, TITLE);
|
||||
let subtitle = use_read(cx, SUBTITLE);
|
||||
|
@ -41,7 +41,7 @@ For many apps – this is a fine pattern, especially if the component is a one-o
|
|||
|
||||
To enable our titlebar component to be used across apps, we want to lift our atoms upwards and out of the Titlebar component. We would organize a bunch of other components in this section of the app to share some of the same state.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn DocsiteTitlesection(cx: Scope) {
|
||||
let title = use_read(cx, TITLE);
|
||||
let subtitle = use_read(cx, SUBTITLE);
|
||||
|
|
|
@ -4,16 +4,15 @@ Every app you'll build with Dioxus will have some sort of state that needs to be
|
|||
|
||||
In this chapter, we'll cover the various ways to manage state, the appropriate terminology, various patterns, and some problems you might run into.
|
||||
|
||||
|
||||
## The Problem
|
||||
|
||||
Why do people say state management is so difficult? What does it mean?
|
||||
|
||||
Generally, state management is the code you need to write to ensure that your app renders the *correct* content. If the user inputs a name, then you need to display the appropriate response – like alerts, validation, and disable/enable various elements on the page. Things can quickly become tricky if you need loading screens and cancellable tasks.
|
||||
Generally, state management is the code you need to write to ensure that your app renders the _correct_ content. If the user inputs a name, then you need to display the appropriate response – like alerts, validation, and disable/enable various elements on the page. Things can quickly become tricky if you need loading screens and cancellable tasks.
|
||||
|
||||
For the simplest of apps, all of your state can enter the app from the root props. This is common in server-side rendering – we can collect all of the required state *before* rendering the content.
|
||||
For the simplest of apps, all of your state can enter the app from the root props. This is common in server-side rendering – we can collect all of the required state _before_ rendering the content.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let all_content = get_all_content().await;
|
||||
|
||||
let output = dioxus::ssr::render_lazy(rsx!{
|
||||
|
@ -27,7 +26,6 @@ With this incredibly simple setup, it is highly unlikely that you'll have render
|
|||
|
||||
However, most of your apps will store state inside of the Dioxus VirtualDom – either through local state or global state.
|
||||
|
||||
|
||||
## Your options
|
||||
|
||||
To deal with complexity, you have a couple of options:
|
||||
|
|
|
@ -6,7 +6,7 @@ The first step to dealing with complexity in your app is to refactor your state
|
|||
|
||||
Let's say we're managing the state for a list of Todos. Whenever we edit the todo, we want the list to update. We might've started building our app but putting everything into a single `use_ref`.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
struct Todo {
|
||||
contents: String,
|
||||
is_hovered: bool,
|
||||
|
@ -29,7 +29,7 @@ cx.render(rsx!{
|
|||
|
||||
As shown above, whenever the todo is hovered, we want to set its state:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
todos.write()[0].is_hovered = true;
|
||||
```
|
||||
|
||||
|
@ -37,7 +37,7 @@ As the amount of interactions goes up, so does the complexity of our state. Shou
|
|||
|
||||
Instead, let's refactor our Todo component to handle its own state:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[inline_props]
|
||||
fn Todo<'a>(cx: Scope, todo: &'a Todo) -> Element {
|
||||
let is_hovered = use_state(cx, || false);
|
||||
|
@ -53,16 +53,15 @@ fn Todo<'a>(cx: Scope, todo: &'a Todo) -> Element {
|
|||
|
||||
Now, we can simplify our Todo data model to get rid of local UI state:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
struct Todo {
|
||||
contents: String,
|
||||
}
|
||||
```
|
||||
|
||||
This is not only better for encapsulation and abstraction, but it's only more performant! Whenever a Todo is hovered, we won't need to re-render *every* Todo again – only the Todo that's currently being hovered.
|
||||
This is not only better for encapsulation and abstraction, but it's only more performant! Whenever a Todo is hovered, we won't need to re-render _every_ Todo again – only the Todo that's currently being hovered.
|
||||
|
||||
|
||||
Wherever possible, you should try to refactor the "view" layer *out* of your data model.
|
||||
Wherever possible, you should try to refactor the "view" layer _out_ of your data model.
|
||||
|
||||
## Immutability
|
||||
|
||||
|
@ -72,7 +71,7 @@ In these scenarios consider breaking your `use_ref` into individual `use_state`s
|
|||
|
||||
You might've started modeling your component with a struct and use_ref
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
struct State {
|
||||
count: i32,
|
||||
color: &'static str,
|
||||
|
@ -85,17 +84,17 @@ let state = use_ref(cx, State::new)
|
|||
|
||||
The "better" approach for this particular component would be to break the state apart into different values:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let count = use_state(cx, || 0);
|
||||
let color = use_state(cx, || "red");
|
||||
let names = use_state(cx, HashMap::new);
|
||||
```
|
||||
|
||||
You might recognize that our "names" value is a HashMap – which is not terribly cheap to clone every time we update its value. To solve this issue, we *highly* suggest using a library like [`im`](https://crates.io/crates/im) which will take advantage of structural sharing to make clones and mutations much cheaper.
|
||||
You might recognize that our "names" value is a HashMap – which is not terribly cheap to clone every time we update its value. To solve this issue, we _highly_ suggest using a library like [`im`](https://crates.io/crates/im) which will take advantage of structural sharing to make clones and mutations much cheaper.
|
||||
|
||||
When combined with the `make_mut` method on `use_state`, you can get really succinct updates to collections:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let todos = use_state(cx, im_rc::HashMap::default);
|
||||
|
||||
todos.make_mut().insert("new todo", Todo {
|
||||
|
@ -106,5 +105,3 @@ todos.make_mut().insert("new todo", Todo {
|
|||
## Moving on
|
||||
|
||||
This particular local patterns are powerful but is not a cure-all for state management problems. Sometimes your state problems are much larger than just staying local to a component.
|
||||
|
||||
|
||||
|
|
|
@ -1,11 +1,10 @@
|
|||
|
||||
## Memoization
|
||||
|
||||
Dioxus uses Memoization for a more efficient user interface. Memoization is the process in which we check if a component actually needs to be re-rendered when its props change. If a component's properties change but they wouldn't affect the output, then we don't need to re-render the component, saving time!
|
||||
|
||||
For example, let's say we have a component that has two children:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Demo(cx: Scope) -> Element {
|
||||
// don't worry about these 2, we'll cover them later
|
||||
let name = use_state(cx, || String::from("bob"));
|
||||
|
@ -25,4 +24,3 @@ Dioxus memoizes owned components. It uses `PartialEq` to determine if a componen
|
|||
> This means you can always rely on props with `PartialEq` or no props at all to act as barriers in your app. This can be extremely useful when building larger apps where properties frequently change. By moving our state into a global state management solution, we can achieve precise, surgical re-renders, improving the performance of our app.
|
||||
|
||||
Borrowed Props cannot be safely memoized. However, this is not a problem – Dioxus relies on the memoization of their parents to determine if they need to be rerendered.
|
||||
|
||||
|
|
|
@ -1,12 +1,10 @@
|
|||
|
||||
|
||||
## Using UseRef with "models"
|
||||
|
||||
One option for state management that UseRef enables is the development of a "model" for your components. This particular pattern enables you to model your state with regular structs.
|
||||
|
||||
For instance, our calculator example uses a struct to model the state.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
|
||||
struct Calculator {
|
||||
display_value: String,
|
||||
|
@ -18,7 +16,7 @@ struct Calculator {
|
|||
|
||||
Our component is really simple – we just call `use_ref` to get an initial calculator state.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let state = use_ref(cx, Calculator::new);
|
||||
|
||||
|
@ -30,7 +28,7 @@ fn app(cx: Scope) -> Element {
|
|||
|
||||
In our UI, we can then use `read` and a helper method to get data out of the model.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// Our accessor method
|
||||
impl Calculator {
|
||||
fn formatted_display(&self) -> String {
|
||||
|
@ -49,7 +47,7 @@ cx.render(rsx!{
|
|||
|
||||
To modify the state, we can setup a helper method and then attach it to a callback.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// our helper
|
||||
impl Calculator {
|
||||
fn clear_display(&mut self) {
|
||||
|
@ -64,4 +62,3 @@ cx.render(rsx!{
|
|||
}
|
||||
})
|
||||
```
|
||||
|
||||
|
|
|
@ -2,11 +2,11 @@
|
|||
|
||||
The `use_future` and `use_coroutine` hooks are useful if you want to unconditionally spawn the future. Sometimes, though, you'll want to only spawn a future in response to an event, such as a mouse click. For example, suppose you need to send a request when the user clicks a "log in" button. For this, you can use `cx.spawn`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/spawn.rs:spawn}}
|
||||
```
|
||||
|
||||
> Note: `spawn` will always spawn a *new* future. You most likely don't want to call it on every render.
|
||||
> Note: `spawn` will always spawn a _new_ future. You most likely don't want to call it on every render.
|
||||
|
||||
Calling `spawn` will give you a `JoinHandle` which lets you cancel or pause the future.
|
||||
|
||||
|
@ -14,6 +14,6 @@ Calling `spawn` will give you a `JoinHandle` which lets you cancel or pause the
|
|||
|
||||
Sometimes, you might want to spawn a background task that needs multiple threads or talk to hardware that might block your app code. In these cases, we can directly spawn a Tokio task from our future. For Dioxus-Desktop, your task will be spawned onto Tokio's Multithreaded runtime:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/spawn.rs:tokio}}
|
||||
```
|
||||
|
|
|
@ -8,7 +8,7 @@ Like regular futures, code in a coroutine will run until the next `await` point
|
|||
|
||||
The `use_coroutine` hook allows you to create a coroutine. Most coroutines we write will be polling loops using async/await.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let ws: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {
|
||||
// Connect to some sort of service
|
||||
|
@ -26,7 +26,7 @@ For many services, a simple async loop will handle the majority of use cases.
|
|||
|
||||
However, if we want to temporarily disable the coroutine, we can "pause" it using the `pause` method, and "resume" it using the `resume` method:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let sync: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {
|
||||
// code for syncing
|
||||
});
|
||||
|
@ -58,7 +58,7 @@ The future must be `'static` – so any values captured by the task cannot carry
|
|||
|
||||
You can use [to_owned](https://doc.rust-lang.org/std/borrow/trait.ToOwned.html#tymethod.to_owned) to create a clone of the hook handle which can be moved into the async closure.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let sync_status = use_state(cx, || Status::Launching);
|
||||
let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
|
||||
let sync_status = sync_status.to_owned();
|
||||
|
@ -73,7 +73,7 @@ let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
|
|||
|
||||
To make this a bit less verbose, Dioxus exports the `to_owned!` macro which will create a binding as shown above, which can be quite helpful when dealing with many values.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let sync_status = use_state(cx, || Status::Launching);
|
||||
let load_status = use_state(cx, || Status::Launching);
|
||||
let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
|
||||
|
@ -88,10 +88,9 @@ let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
|
|||
|
||||
You might've noticed the `use_coroutine` closure takes an argument called `rx`. What is that? Well, a common pattern in complex apps is to handle a bunch of async code at once. With libraries like Redux Toolkit, managing multiple promises at once can be challenging and a common source of bugs.
|
||||
|
||||
With Coroutines, we can centralize our async logic. The `rx` parameter is an Channel that allows code external to the coroutine to send data *into* the coroutine. Instead of looping on an external service, we can loop on the channel itself, processing messages from within our app without needing to spawn a new future. To send data into the coroutine, we would call "send" on the handle.
|
||||
With Coroutines, we can centralize our async logic. The `rx` parameter is an Channel that allows code external to the coroutine to send data _into_ the coroutine. Instead of looping on an external service, we can loop on the channel itself, processing messages from within our app without needing to spawn a new future. To send data into the coroutine, we would call "send" on the handle.
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use futures_util::stream::StreamExt;
|
||||
|
||||
enum ProfileUpdate {
|
||||
|
@ -119,13 +118,11 @@ cx.render(rsx!{
|
|||
})
|
||||
```
|
||||
|
||||
|
||||
> Note: In order to use/run the `rx.next().await` statement you will need to extend the [`Stream`] trait (used by [`UnboundedReceiver`]) by adding 'futures_util' as a dependency to your project and adding the `use futures_util::stream::StreamExt;`.
|
||||
|
||||
|
||||
For sufficiently complex apps, we could build a bunch of different useful "services" that loop on channels to update the app.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let profile = use_coroutine(cx, profile_service);
|
||||
let editor = use_coroutine(cx, editor_service);
|
||||
let sync = use_coroutine(cx, sync_service);
|
||||
|
@ -143,9 +140,9 @@ async fn editor_service(rx: UnboundedReceiver<EditorCommand>) {
|
|||
}
|
||||
```
|
||||
|
||||
We can combine coroutines with [Fermi](https://docs.rs/fermi/latest/fermi/index.html) to emulate Redux Toolkit's Thunk system with much less headache. This lets us store all of our app's state *within* a task and then simply update the "view" values stored in Atoms. It cannot be understated how powerful this technique is: we get all the perks of native Rust tasks with the optimizations and ergonomics of global state. This means your *actual* state does not need to be tied up in a system like Fermi or Redux – the only Atoms that need to exist are those that are used to drive the display/UI.
|
||||
We can combine coroutines with [Fermi](https://docs.rs/fermi/latest/fermi/index.html) to emulate Redux Toolkit's Thunk system with much less headache. This lets us store all of our app's state _within_ a task and then simply update the "view" values stored in Atoms. It cannot be understated how powerful this technique is: we get all the perks of native Rust tasks with the optimizations and ergonomics of global state. This means your _actual_ state does not need to be tied up in a system like Fermi or Redux – the only Atoms that need to exist are those that are used to drive the display/UI.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
static USERNAME: Atom<String> = |_| "default".to_string();
|
||||
|
||||
fn app(cx: Scope) -> Element {
|
||||
|
@ -169,7 +166,7 @@ fn Banner(cx: Scope) -> Element {
|
|||
|
||||
Now, in our sync service, we can structure our state however we want. We only need to update the view values when ready.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use futures_util::stream::StreamExt;
|
||||
|
||||
enum SyncAction {
|
||||
|
@ -198,7 +195,7 @@ async fn sync_service(mut rx: UnboundedReceiver<SyncAction>, atoms: AtomRoot) {
|
|||
|
||||
Coroutine handles are automatically injected through the context API. You can use the `use_coroutine_handle` hook with the message type as a generic to fetch a handle.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Child(cx: Scope) -> Element {
|
||||
let sync_task = use_coroutine_handle::<SyncAction>(cx);
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
For example, we can make an API request (using [reqwest](https://docs.rs/reqwest/latest/reqwest/index.html)) inside `use_future`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/use_future.rs:use_future}}
|
||||
```
|
||||
|
||||
|
@ -14,11 +14,10 @@ We can use `.value()` to get the result of the future. On the first run, since t
|
|||
|
||||
We can then render that result:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/use_future.rs:render}}
|
||||
```
|
||||
|
||||
|
||||
## Restarting the Future
|
||||
|
||||
The `UseFuture` handle provides a `restart` method. It can be used to execute the future again, producing a new value.
|
||||
|
@ -27,7 +26,6 @@ The `UseFuture` handle provides a `restart` method. It can be used to execute th
|
|||
|
||||
Often, you will need to run the future again every time some value (e.g. a prop) changes. Rather than calling `restart` manually, you can provide a tuple of "dependencies" to the hook. It will automatically re-run the future when any of those dependencies change. Example:
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/use_future.rs:dependency}}
|
||||
```
|
||||
|
|
|
@ -8,7 +8,7 @@ Fragments don't mount a physical element to the DOM immediately, so Dioxus must
|
|||
|
||||
Only Component and Fragment nodes are susceptible to this issue. Dioxus mitigates this with components by providing an API for registering shared state without the Context Provider pattern.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/anti_patterns.rs:nested_fragments}}
|
||||
```
|
||||
|
||||
|
@ -16,7 +16,7 @@ Only Component and Fragment nodes are susceptible to this issue. Dioxus mitigate
|
|||
|
||||
As described in the [dynamic rendering chapter](../interactivity/dynamic_rendering.md#the-key-attribute), list items must have unique keys that are associated with the same items across renders. This helps Dioxus associate state with the contained components and ensures good diffing performance. Do not omit keys, unless you know that the list will never change.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/anti_patterns.rs:iter_keys}}
|
||||
```
|
||||
|
||||
|
|
|
@ -4,23 +4,21 @@ A selling point of Rust for web development is the reliability of always knowing
|
|||
|
||||
However, we haven't talked about error handling at all in this guide! In this chapter, we'll cover some strategies in handling errors to ensure your app never crashes.
|
||||
|
||||
|
||||
|
||||
## The simplest – returning None
|
||||
|
||||
Astute observers might have noticed that `Element` is actually a type alias for `Option<VNode>`. You don't need to know what a `VNode` is, but it's important to recognize that we could actually return nothing at all:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn App(cx: Scope) -> Element {
|
||||
None
|
||||
}
|
||||
```
|
||||
|
||||
This lets us add in some syntactic sugar for operations we think *shouldn't* fail, but we're still not confident enough to "unwrap" on.
|
||||
This lets us add in some syntactic sugar for operations we think _shouldn't_ fail, but we're still not confident enough to "unwrap" on.
|
||||
|
||||
> The nature of `Option<VNode>` might change in the future as the `try` trait gets upgraded.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn App(cx: Scope) -> Element {
|
||||
// immediately return "None"
|
||||
let name = cx.use_hook(|_| Some("hi"))?;
|
||||
|
@ -31,7 +29,7 @@ fn App(cx: Scope) -> Element {
|
|||
|
||||
Because Rust can't accept both Options and Results with the existing try infrastructure, you'll need to manually handle Results. This can be done by converting them into Options or by explicitly handling them.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn App(cx: Scope) -> Element {
|
||||
// Convert Result to Option
|
||||
let name = cx.use_hook(|_| "1.234").parse().ok()?;
|
||||
|
@ -46,8 +44,7 @@ fn App(cx: Scope) -> Element {
|
|||
}
|
||||
```
|
||||
|
||||
Notice that while hooks in Dioxus do not like being called in conditionals or loops, they *are* okay with early returns. Returning an error state early is a completely valid way of handling errors.
|
||||
|
||||
Notice that while hooks in Dioxus do not like being called in conditionals or loops, they _are_ okay with early returns. Returning an error state early is a completely valid way of handling errors.
|
||||
|
||||
## Match results
|
||||
|
||||
|
@ -55,14 +52,13 @@ The next "best" way of handling errors in Dioxus is to match on the error locall
|
|||
|
||||
To do this, we simply have an error state built into our component:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let err = use_state(cx, || None);
|
||||
```
|
||||
|
||||
Whenever we perform an action that generates an error, we'll set that error state. We can then match on the error in a number of ways (early return, return Element, etc).
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Commandline(cx: Scope) -> Element {
|
||||
let error = use_state(cx, || None);
|
||||
|
||||
|
@ -83,7 +79,7 @@ fn Commandline(cx: Scope) -> Element {
|
|||
|
||||
If you're dealing with a handful of components with minimal nesting, you can just pass the error handle into child components.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Commandline(cx: Scope) -> Element {
|
||||
let error = use_state(cx, || None);
|
||||
|
||||
|
@ -110,8 +106,7 @@ To get started, consider using a built-in hook like `use_context` and `use_conte
|
|||
|
||||
At the "top" of our architecture, we're going to want to explicitly declare a value that could be an error.
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum InputError {
|
||||
None,
|
||||
TooLong,
|
||||
|
@ -123,7 +118,7 @@ static INPUT_ERROR: Atom<InputError> = |_| InputError::None;
|
|||
|
||||
Then, in our top level component, we want to explicitly handle the possible error state for this part of the tree.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn TopLevel(cx: Scope) -> Element {
|
||||
let error = use_read(cx, INPUT_ERROR);
|
||||
|
||||
|
@ -137,7 +132,7 @@ fn TopLevel(cx: Scope) -> Element {
|
|||
|
||||
Now, whenever a downstream component has an error in its actions, it can simply just set its own error state:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Commandline(cx: Scope) -> Element {
|
||||
let set_error = use_set(cx, INPUT_ERROR);
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@ This walkthrough will take you through the internals of the Hello World example
|
|||
|
||||
We start will a hello world program. This program renders a desktop app with the text "Hello World" in a webview.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../../../examples/readme.rs}}
|
||||
```
|
||||
|
||||
|
@ -16,7 +16,7 @@ We start will a hello world program. This program renders a desktop app with the
|
|||
|
||||
Before the Rust compiler runs the program, it will expand all macros. Here is what the hello world example looks like expanded:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/readme_expanded.rs}}
|
||||
```
|
||||
|
||||
|
@ -40,7 +40,7 @@ Before we dive into the initial render in the virtual dom, we need to discuss wh
|
|||
|
||||
The Virtual Dom roughly looks like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
pub struct VirtualDom {
|
||||
// All the templates that have been created or set durring hot reloading
|
||||
pub(crate) templates: FxHashMap<TemplateId, FxHashMap<usize, Template<'static>>>,
|
||||
|
|
|
@ -25,7 +25,7 @@ Dioxus is built around the concept of [Templates](https://docs.rs/dioxus-core/la
|
|||
|
||||
The `Mutation` type is a serialized enum that represents an operation that should be applied to update the UI. The variants roughly follow this set:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum Mutation {
|
||||
AppendChildren,
|
||||
AssignId,
|
||||
|
@ -58,7 +58,7 @@ Whenever a `CreateElement` edit is generated during diffing, Dioxus increments i
|
|||
|
||||
For the sake of understanding, let's consider this example – a very simple UI declaration:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!( h1 {"count: {x}"} )
|
||||
```
|
||||
|
||||
|
@ -68,7 +68,7 @@ The above rsx will create a template that contains one static h1 tag and a place
|
|||
|
||||
The template will look something like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
Template {
|
||||
// Some id that is unique for the entire project
|
||||
name: "main.rs:1:1:0",
|
||||
|
@ -118,7 +118,7 @@ After the renderer has created all of the new templates, it can begin to process
|
|||
|
||||
When the renderer starts, it should contain the Root node on the stack and store the Root node with an id of 0. The Root node is the top-level node of the UI. In HTML, this is the `<div id="main">` element.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: []
|
||||
stack: [
|
||||
RootNode,
|
||||
|
@ -130,7 +130,7 @@ nodes: [
|
|||
|
||||
The first mutation is a `LoadTemplate` mutation. This tells the renderer to load a root from the template with the given id. The renderer will then push the root node of the template onto the stack and store it with an id for later. In this case, the root node is an h1 element.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
LoadTemplate {
|
||||
// the id of the template
|
||||
|
@ -153,7 +153,7 @@ nodes: [
|
|||
|
||||
Next, Dioxus will create the dynamic text node. The diff algorithm decides that this node needs to be created, so Dioxus will generate the Mutation `HydrateText`. When the renderer receives this instruction, it will navigate to the placeholder text node in the template and replace it with the new text.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
LoadTemplate {
|
||||
name: "main.rs:1:1:0",
|
||||
|
@ -180,7 +180,7 @@ nodes: [
|
|||
|
||||
Remember, the h1 node is not attached to anything (it is unmounted) so Dioxus needs to generate an Edit that connects the h1 node to the Root. It depends on the situation, but in this case, we use `AppendChildren`. This pops the text node off the stack, leaving the Root element as the next element on the stack.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
LoadTemplate {
|
||||
name: "main.rs:1:1:0",
|
||||
|
@ -210,7 +210,7 @@ nodes: [
|
|||
|
||||
Over time, our stack looked like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
[Root]
|
||||
[Root, <h1>""</h1>]
|
||||
[Root, <h1>"count: 0"</h1>]
|
||||
|
@ -229,7 +229,7 @@ Like most GUIs, Dioxus relies on an event loop to progress the VirtualDOM. The V
|
|||
|
||||
The code for the WebSys implementation is straightforward, so we'll add it here to demonstrate how simple an event loop is:
|
||||
|
||||
```rust, ignore
|
||||
```rust, no_run, ignore
|
||||
pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
||||
// Push the body element onto the WebsysDom's stack machine
|
||||
let mut websys_dom = crate::new::WebsysDom::new(prepare_websys_dom());
|
||||
|
@ -259,7 +259,7 @@ pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
|||
|
||||
It's important to decode what the real events are for your event system into Dioxus' synthetic event system (synthetic meaning abstracted). This simply means matching your event type and creating a Dioxus `UserEvent` type. Right now, the virtual event system is modeled almost entirely around the HTML spec, but we are interested in slimming it down.
|
||||
|
||||
```rust, ignore
|
||||
```rust, no_run, ignore
|
||||
fn virtual_event_from_websys_event(event: &web_sys::Event) -> VirtualEvent {
|
||||
match event.type_().as_str() {
|
||||
"keydown" => {
|
||||
|
@ -308,7 +308,7 @@ The `RealDom` is a higher-level abstraction over updating the Dom. It uses an en
|
|||
Let's build a toy renderer with borders, size, and text color.
|
||||
Before we start let's take a look at an example element we can render:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
cx.render(rsx!{
|
||||
div{
|
||||
color: "red",
|
||||
|
@ -380,19 +380,19 @@ To help in building a Dom, native-core provides the State trait and a RealDom st
|
|||
|
||||
Native Core cannot create all of the required methods for the State trait, but it can derive some of them. To implement the State trait, you must implement the following methods and let the `#[partial_derive_state]` macro handle the rest:
|
||||
|
||||
```rust, ignore
|
||||
```rust, no_run, ignore
|
||||
{{#include ../../../examples/custom_renderer.rs:derive_state}}
|
||||
```
|
||||
|
||||
Lets take a look at how to implement the State trait for a simple renderer.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/custom_renderer.rs:state_impl}}
|
||||
```
|
||||
|
||||
Now that we have our state, we can put it to use in our RealDom. We can update the RealDom with apply_mutations to update the structure of the dom (adding, removing, and changing properties of nodes) and then update_state to update the States for each of the nodes that changed.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/custom_renderer.rs:rendering}}
|
||||
```
|
||||
|
||||
|
@ -404,7 +404,7 @@ For most platforms, the layout of the Elements will stay the same. The [layout_a
|
|||
|
||||
To make it easier to implement text editing in rust renderers, `native-core` also contains a renderer-agnostic cursor system. The cursor can handle text editing, selection, and movement with common keyboard shortcuts integrated.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/custom_renderer.rs:cursor}}
|
||||
```
|
||||
|
||||
|
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
In some cases, you may wish to create a component that acts as a container for some other content, without the component needing to know what that content is. To achieve this, create a prop of type `Element`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_element_props.rs:Clickable}}
|
||||
```
|
||||
|
||||
Then, when rendering the component, you can pass in the output of `cx.render(rsx!(...))`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_element_props.rs:Clickable_usage}}
|
||||
```
|
||||
|
||||
|
@ -20,12 +20,12 @@ Then, when rendering the component, you can pass in the output of `cx.render(rsx
|
|||
|
||||
Rather than passing the RSX through a regular prop, you may wish to accept children similarly to how elements can have children. The "magic" `children` prop lets you achieve this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_children.rs:Clickable}}
|
||||
```
|
||||
|
||||
This makes using the component much simpler: simply put the RSX inside the `{}` brackets – and there is no need for a `render` call or another macro!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_children.rs:Clickable_usage}}
|
||||
```
|
||||
|
|
|
@ -7,6 +7,7 @@ Just like you can pass arguments to a function, you can pass props to a componen
|
|||
Component props are a single struct annotated with `#[derive(Props)]`. For a component to accept props, the type of its argument must be `Scope<YourPropsStruct>`. Then, you can access the value of the props using `cx.props`.
|
||||
|
||||
There are 2 flavors of Props structs:
|
||||
|
||||
- Owned props:
|
||||
- Don't have an associated lifetime
|
||||
- Implement `PartialEq`, allow for memoization (if the props don't change, Dioxus won't re-render the component)
|
||||
|
@ -14,17 +15,17 @@ There are 2 flavors of Props structs:
|
|||
- [Borrow](https://doc.rust-lang.org/beta/rust-by-example/scope/borrow.html) from a parent component
|
||||
- Cannot be memoized due to lifetime constraints
|
||||
|
||||
|
||||
### Owned Props
|
||||
|
||||
Owned Props are very simple – they don't borrow anything. Example:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_owned_props.rs:Likes}}
|
||||
```
|
||||
|
||||
You can then pass prop values to the component the same way you would pass attributes to an element:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_owned_props.rs:App}}
|
||||
```
|
||||
|
||||
|
@ -36,18 +37,19 @@ Owned props work well if your props are easy to copy around – like a single nu
|
|||
|
||||
Rust allows for something more efficient – borrowing the String as a `&str` – this is what Borrowed Props are for!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_borrowed_props.rs:TitleCard}}
|
||||
```
|
||||
|
||||
We can then use the component like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_borrowed_props.rs:App}}
|
||||
```
|
||||
|
||||
![Screenshot: TitleCard component](./images/component_borrowed_props_screenshot.png)
|
||||
|
||||
Borrowed props can be very useful, but they do not allow for memorization so they will *always* rerun when the parent scope is rerendered. Because of this Borrowed Props should be reserved for components that are cheap to rerun or places where cloning data is an issue. Using Borrowed Props everywhere will result in large parts of your app rerunning every interaction.
|
||||
Borrowed props can be very useful, but they do not allow for memorization so they will _always_ rerun when the parent scope is rerendered. Because of this Borrowed Props should be reserved for components that are cheap to rerun or places where cloning data is an issue. Using Borrowed Props everywhere will result in large parts of your app rerunning every interaction.
|
||||
|
||||
## Prop Options
|
||||
|
||||
|
@ -57,13 +59,13 @@ The `#[derive(Props)]` macro has some features that let you customize the behavi
|
|||
|
||||
You can create optional fields by using the `Option<…>` type for a field:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:OptionalProps}}
|
||||
```
|
||||
|
||||
Then, you can choose to either provide them or not:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:OptionalProps_usage}}
|
||||
```
|
||||
|
||||
|
@ -71,13 +73,13 @@ Then, you can choose to either provide them or not:
|
|||
|
||||
If you want to explicitly require an `Option`, and not an optional prop, you can annotate it with `#[props(!optional)]`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:ExplicitOption}}
|
||||
```
|
||||
|
||||
Then, you have to explicitly pass either `Some("str")` or `None`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:ExplicitOption_usage}}
|
||||
```
|
||||
|
||||
|
@ -85,13 +87,13 @@ Then, you have to explicitly pass either `Some("str")` or `None`:
|
|||
|
||||
You can use `#[props(default = 42)]` to make a field optional and specify its default value:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:DefaultComponent}}
|
||||
```
|
||||
|
||||
Then, similarly to optional props, you don't have to provide it:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:DefaultComponent_usage}}
|
||||
```
|
||||
|
||||
|
@ -99,13 +101,13 @@ Then, similarly to optional props, you don't have to provide it:
|
|||
|
||||
It is common for Rust functions to accept `impl Into<SomeType>` rather than just `SomeType` to support a wider range of parameters. If you want similar functionality with props, you can use `#[props(into)]`. For example, you could add it on a `String` prop – and `&str` will also be automatically accepted, as it can be converted into `String`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:IntoComponent}}
|
||||
```
|
||||
|
||||
Then, you can use it so:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:IntoComponent_usage}}
|
||||
```
|
||||
|
||||
|
@ -115,7 +117,7 @@ So far, every Component function we've seen had a corresponding ComponentProps s
|
|||
|
||||
`inline_props` allows you to do just that. Instead of typing the "full" version:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[derive(Props, PartialEq)]
|
||||
struct TitleCardProps {
|
||||
title: String,
|
||||
|
@ -130,7 +132,7 @@ fn TitleCard(cx: Scope<TitleCardProps>) -> Element {
|
|||
|
||||
...you can define a function that accepts props as arguments. Then, just annotate it with `#[inline_props]`, and the macro will turn it into a regular Component for you:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[inline_props]
|
||||
fn TitleCard(cx: Scope, title: String) -> Element {
|
||||
cx.render(rsx!{
|
||||
|
|
|
@ -4,7 +4,7 @@ Just like you wouldn't want to write a complex program in a single, long, `main`
|
|||
|
||||
A component is a Rust function, named in UpperCammelCase, that takes a `Scope` parameter and returns an `Element` describing the UI it wants to render. In fact, our `App` function is a component!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_desktop.rs:component}}
|
||||
```
|
||||
|
||||
|
@ -12,13 +12,13 @@ A component is a Rust function, named in UpperCammelCase, that takes a `Scope` p
|
|||
|
||||
A Component is responsible for some rendering task – typically, rendering an isolated part of the user interface. For example, you could have an `About` component that renders a short description of Dioxus Labs:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/components.rs:About}}
|
||||
```
|
||||
|
||||
Then, you can render your component in another component, similarly to how elements are rendered:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/components.rs:App}}
|
||||
```
|
||||
|
||||
|
|
|
@ -1,35 +1,42 @@
|
|||
# Describing the UI
|
||||
|
||||
Dioxus is a *declarative* framework. This means that instead of telling Dioxus what to do (e.g. to "create an element" or "set the color to red") we simply *declare* what we want the UI to look like using RSX.
|
||||
Dioxus is a _declarative_ framework. This means that instead of telling Dioxus what to do (e.g. to "create an element" or "set the color to red") we simply _declare_ what we want the UI to look like using RSX.
|
||||
|
||||
You have already seen a simple example of RSX syntax in the "hello world" application:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_desktop.rs:component}}
|
||||
```
|
||||
|
||||
Here, we use the `rsx!` macro to *declare* that we want a `div` element, containing the text `"Hello, world!"`. Dioxus takes the RSX and constructs a UI from it.
|
||||
Here, we use the `rsx!` macro to _declare_ that we want a `div` element, containing the text `"Hello, world!"`. Dioxus takes the RSX and constructs a UI from it.
|
||||
|
||||
## RSX Features
|
||||
|
||||
RSX is very similar to HTML in that it describes elements with attributes and children. Here's an empty `div` element in RSX, as well as the resulting HTML:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:empty}}
|
||||
```
|
||||
|
||||
```html
|
||||
<div></div>
|
||||
```
|
||||
|
||||
|
||||
### Attributes
|
||||
|
||||
Attributes (and [listeners](../interactivity/index.md)) modify the behavior or appearance of the element they are attached to. They are specified inside the `{}` brackets, using the `name: value` syntax. You can provide the value as a literal in the RSX:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:attributes}}
|
||||
```
|
||||
|
||||
```html
|
||||
<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" class="primary_button" autofocus="true" style="color: red"></a>
|
||||
<a
|
||||
href="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
|
||||
class="primary_button"
|
||||
autofocus="true"
|
||||
style="color: red"
|
||||
></a>
|
||||
```
|
||||
|
||||
> Note: All attributes defined in `dioxus-html` follow the snake_case naming convention. They transform their `snake_case` names to HTML's `camelCase` attributes.
|
||||
|
@ -40,21 +47,22 @@ Attributes (and [listeners](../interactivity/index.md)) modify the behavior or a
|
|||
|
||||
Dioxus has a pre-configured set of attributes that you can use. RSX is validated at compile time to make sure you didn't specify an invalid attribute. If you want to override this behavior with a custom attribute name, specify the attribute in quotes:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:custom_attributes}}
|
||||
```
|
||||
|
||||
```html
|
||||
<b customAttribute="value">
|
||||
</b>
|
||||
<b customAttribute="value"> </b>
|
||||
```
|
||||
|
||||
### Interpolation
|
||||
|
||||
Similarly to how you can [format](https://doc.rust-lang.org/rust-by-example/hello/print/fmt.html) Rust strings, you can also interpolate in RSX text. Use `{variable}` to Display the value of a variable in a string, or `{variable:?}` to use the Debug representation:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:formatting}}
|
||||
```
|
||||
|
||||
```html
|
||||
<div class="country-es" position="(42, 0)">
|
||||
<div>ES</div>
|
||||
|
@ -67,9 +75,10 @@ Similarly to how you can [format](https://doc.rust-lang.org/rust-by-example/hell
|
|||
|
||||
To add children to an element, put them inside the `{}` brackets after all attributes and listeners in the element. They can be other elements, text, or [components](components.md). For example, you could have an `ol` (ordered list) element, containing 3 `li` (list item) elements, each of which contains some text:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:children}}
|
||||
```
|
||||
|
||||
```html
|
||||
<ol>
|
||||
<li>First Item</li>
|
||||
|
@ -82,7 +91,7 @@ To add children to an element, put them inside the `{}` brackets after all attri
|
|||
|
||||
You can render multiple elements at the top level of `rsx!` and they will be automatically grouped.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:manyroots}}
|
||||
```
|
||||
|
||||
|
@ -95,9 +104,10 @@ You can render multiple elements at the top level of `rsx!` and they will be aut
|
|||
|
||||
You can include arbitrary Rust expressions as children within RSX that implements [IntoDynNode](https://docs.rs/dioxus-core/0.3/dioxus_core/trait.IntoDynNode.html). This is useful for displaying data from an [iterator](https://doc.rust-lang.org/stable/book/ch13-02-iterators.html#processing-a-series-of-items-with-iterators):
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:expression}}
|
||||
```
|
||||
|
||||
```html
|
||||
<span>DIOXUS0123456789</span>
|
||||
```
|
||||
|
@ -106,9 +116,10 @@ You can include arbitrary Rust expressions as children within RSX that implement
|
|||
|
||||
In addition to iterators you can also use for loops directly within RSX:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:loops}}
|
||||
```
|
||||
|
||||
```html
|
||||
<div>0</div>
|
||||
<div>1</div>
|
||||
|
@ -122,9 +133,10 @@ In addition to iterators you can also use for loops directly within RSX:
|
|||
|
||||
You can also use if statements without an else branch within RSX:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:ifstatements}}
|
||||
```
|
||||
|
||||
```html
|
||||
<div>true</div>
|
||||
```
|
|
@ -8,8 +8,7 @@ If you're working with pre-rendered assets, output from templates, or output fro
|
|||
|
||||
For example, shipping a markdown-to-Dioxus converter might significantly bloat your final application size. Instead, you'll want to pre-render your markdown to HTML and then include the HTML directly in your output. We use this approach for the [Dioxus homepage](https://dioxuslabs.com):
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/dangerous_inner_html.rs:dangerous_inner_html}}
|
||||
```
|
||||
|
||||
|
@ -17,21 +16,21 @@ For example, shipping a markdown-to-Dioxus converter might significantly bloat y
|
|||
>
|
||||
> If you're handling untrusted input, make sure to sanitize your HTML before passing it into `dangerous_inner_html` – or just pass it to a Text Element to escape any HTML tags.
|
||||
|
||||
|
||||
## Boolean Attributes
|
||||
|
||||
Most attributes, when rendered, will be rendered exactly as the input you provided. However, some attributes are considered "boolean" attributes and just their presence determines whether they affect the output. For these attributes, a provided value of `"false"` will cause them to be removed from the target element.
|
||||
|
||||
So this RSX wouldn't actually render the `hidden` attribute:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/boolean_attribute.rs:boolean_attribute}}
|
||||
```
|
||||
|
||||
```html
|
||||
<div>hello</div>
|
||||
```
|
||||
|
||||
Not all attributes work like this however. *Only the following attributes* have this behavior:
|
||||
Not all attributes work like this however. _Only the following attributes_ have this behavior:
|
||||
|
||||
- `allowfullscreen`
|
||||
- `allowpaymentrequest`
|
||||
|
|
|
@ -39,7 +39,7 @@ tokio = { version = "*", features = ["full"] }
|
|||
|
||||
Now, set up your Axum app to serve the Dioxus app.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/server_basic.rs}}
|
||||
```
|
||||
|
||||
|
@ -72,7 +72,7 @@ web = ["dioxus-web"]
|
|||
|
||||
Next, we need to modify our `main.rs` to use either hydrate on the client or render on the server depending on the active features.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hydration.rs}}
|
||||
```
|
||||
|
||||
|
@ -95,7 +95,7 @@ To do this, we must remove the serve_dioxus_application and replace it with a cu
|
|||
|
||||
The only thing we need to change on the client is the props. `dioxus-fullstack` will automatically serialize the props it uses to server render the app and send them to the client. In the client section of `main.rs`, we need to add `get_root_props_from_document` to deserialize the props before we hydrate the app.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hydration_props.rs}}
|
||||
```
|
||||
|
||||
|
|
|
@ -20,7 +20,7 @@ cargo add serde
|
|||
|
||||
Next, add the server function to your `main.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/server_function.rs}}
|
||||
```
|
||||
|
||||
|
|
|
@ -72,6 +72,6 @@ cargo add dioxus-desktop
|
|||
|
||||
Edit your `main.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_desktop.rs:all}}
|
||||
```
|
||||
|
|
|
@ -36,7 +36,7 @@ For more information about hot reloading on native platforms and configuration o
|
|||
|
||||
Add the following to your main function:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn main() {
|
||||
hot_reload_init!();
|
||||
// launch your application
|
||||
|
|
|
@ -1,18 +1,17 @@
|
|||
# Liveview
|
||||
|
||||
Liveview allows apps to *run* on the server and *render* in the browser. It uses WebSockets to communicate between the server and the browser.
|
||||
Liveview allows apps to _run_ on the server and _render_ in the browser. It uses WebSockets to communicate between the server and the browser.
|
||||
|
||||
Examples:
|
||||
|
||||
- [Axum Example](https://github.com/DioxusLabs/dioxus/tree/master/packages/liveview/examples/axum.rs)
|
||||
- [Salvo Example](https://github.com/DioxusLabs/dioxus/tree/master/packages/liveview/examples/salvo.rs)
|
||||
- [Warp Example](https://github.com/DioxusLabs/dioxus/tree/master/packages/liveview/examples/warp.rs)
|
||||
|
||||
|
||||
## Support
|
||||
|
||||
Liveview is currently limited in capability when compared to the Web platform. Liveview apps run on the server in a native thread. This means that browser APIs are not available, so rendering WebGL, Canvas, etc is not as easy as the Web. However, native system APIs are accessible, so streaming, WebSockets, filesystem, etc are all viable APIs.
|
||||
|
||||
|
||||
## Setup
|
||||
|
||||
For this guide, we're going to show how to use Dioxus Liveview with [Axum](https://docs.rs/axum/latest/axum/).
|
||||
|
@ -50,17 +49,14 @@ tokio = { version = "1.15.0", features = ["full"] }
|
|||
|
||||
Now, set up your Axum app to respond on an endpoint.
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_liveview.rs:glue}}
|
||||
```
|
||||
|
||||
|
||||
And then add our app component:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_liveview.rs:app}}
|
||||
```
|
||||
|
||||
And that's it!
|
||||
|
||||
|
|
|
@ -5,8 +5,8 @@ Build a mobile app with Dioxus!
|
|||
Example: [Todo App](https://github.com/DioxusLabs/example-projects/blob/master/ios_demo)
|
||||
|
||||
## Support
|
||||
Mobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with either the platform's WebView or experimentally through [WGPU](https://github.com/DioxusLabs/blitz). WebView doesn't support animations, transparency, and native widgets.
|
||||
|
||||
Mobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with either the platform's WebView or experimentally through [WGPU](https://github.com/DioxusLabs/blitz). WebView doesn't support animations, transparency, and native widgets.
|
||||
|
||||
Mobile support is currently best suited for CRUD-style apps, ideally for internal teams who need to develop quickly but don't care much about animations or native widgets.
|
||||
|
||||
|
@ -59,7 +59,7 @@ simple_logger = "*"
|
|||
|
||||
Edit your `lib.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use dioxus::prelude::*;
|
||||
|
||||
fn main() {
|
||||
|
|
|
@ -39,19 +39,19 @@ tokio = { version = "1.15.0", features = ["full"] }
|
|||
|
||||
Now, set up your Axum app to respond on an endpoint.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_ssr.rs:main}}
|
||||
```
|
||||
|
||||
And then add our endpoint. We can either render `rsx!` directly:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_ssr.rs:endpoint}}
|
||||
```
|
||||
|
||||
Or we can render VirtualDoms.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_ssr.rs:second_endpoint}}
|
||||
```
|
||||
|
||||
|
|
|
@ -29,7 +29,7 @@ cargo add dioxus-tui
|
|||
|
||||
Then, edit your `main.rs` with the basic template.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_tui.rs}}
|
||||
```
|
||||
|
||||
|
@ -41,6 +41,6 @@ cargo run
|
|||
|
||||
Press "ctrl-c" to close the app. To switch from "ctrl-c" to just "q" to quit you can launch the app with a configuration to disable the default quit and use the root TuiContext to quit on your own.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_tui_no_ctrl_c.rs}}
|
||||
```
|
||||
|
|
|
@ -52,7 +52,7 @@ cargo add dioxus-web
|
|||
|
||||
Edit your `main.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_web.rs}}
|
||||
```
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Dioxus is a portable, performant, and ergonomic framework for building cross-platform user interfaces in Rust. This guide will help you get started with writing Dioxus apps for the Web, Desktop, Mobile, and more.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let mut count = use_state(cx, || 0);
|
||||
|
||||
|
@ -18,7 +18,7 @@ fn app(cx: Scope) -> Element {
|
|||
|
||||
Dioxus is heavily inspired by React. If you know React, getting started with Dioxus will be a breeze.
|
||||
|
||||
> This guide assumes you already know some [Rust](https://www.rust-lang.org/)! If not, we recommend reading [*the book*](https://doc.rust-lang.org/book/ch01-00-getting-started.html) to learn Rust first.
|
||||
> This guide assumes you already know some [Rust](https://www.rust-lang.org/)! If not, we recommend reading [_the book_](https://doc.rust-lang.org/book/ch01-00-getting-started.html) to learn Rust first.
|
||||
|
||||
## Features
|
||||
|
||||
|
@ -31,9 +31,10 @@ Dioxus is heavily inspired by React. If you know React, getting started with Dio
|
|||
|
||||
### Multiplatform
|
||||
|
||||
Dioxus is a *portable* toolkit, meaning the Core implementation can run anywhere with no platform-dependent linking. Unlike many other Rust frontend toolkits, Dioxus is not intrinsically linked to WebSys. In fact, every element and event listener can be swapped out at compile time. By default, Dioxus ships with the `html` feature enabled, but this can be disabled depending on your target renderer.
|
||||
Dioxus is a _portable_ toolkit, meaning the Core implementation can run anywhere with no platform-dependent linking. Unlike many other Rust frontend toolkits, Dioxus is not intrinsically linked to WebSys. In fact, every element and event listener can be swapped out at compile time. By default, Dioxus ships with the `html` feature enabled, but this can be disabled depending on your target renderer.
|
||||
|
||||
Right now, we have several 1st-party renderers:
|
||||
|
||||
- WebSys (for WASM): Great support
|
||||
- Tao/Tokio (for Desktop apps): Good support
|
||||
- Tao/Tokio (for Mobile apps): Poor support
|
||||
|
|
|
@ -10,13 +10,13 @@ To avoid repetition, you can encapsulate business logic based on existing hooks
|
|||
|
||||
For example, if many components need to access an `AppSettings` struct, you can create a "shortcut" hook:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_composed.rs:wrap_context}}
|
||||
```
|
||||
|
||||
Or if you want to wrap a hook that persists reloads with the storage API, you can build on top of the use_ref hook to work with mutable state:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_composed.rs:use_storage}}
|
||||
```
|
||||
|
||||
|
@ -34,7 +34,7 @@ Inside the initialization closure, you will typically make calls to other `cx` m
|
|||
|
||||
Here is a simplified implementation of the `use_state` hook:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_custom_logic.rs:use_state}}
|
||||
```
|
||||
|
||||
|
@ -42,7 +42,7 @@ Here is a simplified implementation of the `use_state` hook:
|
|||
|
||||
Here is an implementation of the `use_context` and `use_context_provider` hooks:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_custom_logic.rs:use_context}}
|
||||
```
|
||||
|
||||
|
@ -54,13 +54,13 @@ When writing a custom hook, you should avoid the following anti-patterns:
|
|||
|
||||
This version of use_state may seem more efficient, but it is not cloneable:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_anti_patterns.rs:non_clone_state}}
|
||||
```
|
||||
|
||||
If we try to use this hook in an async block, we will get a compile error:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn FutureComponent(cx: &ScopeState) -> Element {
|
||||
let my_state = my_use_state(cx, || 0);
|
||||
cx.spawn({
|
||||
|
@ -76,7 +76,7 @@ fn FutureComponent(cx: &ScopeState) -> Element {
|
|||
|
||||
But with the original version, we can use it in an async block:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn FutureComponent(cx: &ScopeState) -> Element {
|
||||
let my_state = use_state(cx, || 0);
|
||||
cx.spawn({
|
||||
|
|
|
@ -6,7 +6,7 @@ Sometimes you want to render different things depending on the state/props. With
|
|||
|
||||
To render different elements based on a condition, you could use an `if-else` statement:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/conditional_rendering.rs:if_else}}
|
||||
```
|
||||
|
||||
|
@ -18,7 +18,7 @@ You may have noticed some repeated code in the `if-else` example above. Repeatin
|
|||
|
||||
We can improve this example by splitting up the dynamic parts and inserting them where they are needed.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/conditional_rendering.rs:if_else_improved}}
|
||||
```
|
||||
|
||||
|
@ -26,18 +26,17 @@ We can improve this example by splitting up the dynamic parts and inserting them
|
|||
|
||||
Since `Element` is a `Option<VNode>`, components accepting `Element` as a prop can inspect its contents, and render different things based on that. Example:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_children_inspect.rs:Clickable}}
|
||||
```
|
||||
|
||||
You can't mutate the `Element`, but if you need a modified version of it, you can construct a new one based on its attributes/children/etc.
|
||||
|
||||
|
||||
## Rendering Nothing
|
||||
|
||||
To render nothing, you can return `None` from a component. This is useful if you want to conditionally hide something:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/conditional_rendering.rs:conditional_none}}
|
||||
```
|
||||
|
||||
|
@ -58,7 +57,7 @@ For this, Dioxus accepts iterators that produce `Element`s. So we need to:
|
|||
|
||||
Example: suppose you have a list of comments you want to render. Then, you can render them like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rendering_lists.rs:render_list}}
|
||||
```
|
||||
|
||||
|
@ -66,7 +65,7 @@ Example: suppose you have a list of comments you want to render. Then, you can r
|
|||
|
||||
Because of how common it is to render a list of items, Dioxus provides a shorthand for this. Instead of using `.iter`, `.map`, and `rsx`, you can use a `for` loop with a body of rsx code:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rendering_lists.rs:render_list_for_loop}}
|
||||
```
|
||||
|
||||
|
|
|
@ -8,7 +8,7 @@ Event handlers are similar to regular attributes, but their name usually starts
|
|||
|
||||
For example, to handle clicks on an element, we can specify an `onclick` handler:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_click.rs:rsx}}
|
||||
```
|
||||
|
||||
|
@ -33,7 +33,7 @@ Some events will trigger first on the element the event originated at upward. Fo
|
|||
|
||||
If you want to prevent this behavior, you can call `stop_propagation()` on the event:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_nested.rs:rsx}}
|
||||
```
|
||||
|
||||
|
@ -43,25 +43,25 @@ Some events have a default behavior. For keyboard events, this might be entering
|
|||
|
||||
In some instances, might want to avoid this default behavior. For this, you can add the `prevent_default` attribute with the name of the handler whose default behavior you want to stop. This attribute can be used for multiple handlers using their name separated by spaces:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_prevent_default.rs:prevent_default}}
|
||||
```
|
||||
|
||||
Any event handlers will still be called.
|
||||
|
||||
> Normally, in React or JavaScript, you'd call "preventDefault" on the event in the callback. Dioxus does *not* currently support this behavior. Note: this means you cannot conditionally prevent default behavior based on the data in the event.
|
||||
> Normally, in React or JavaScript, you'd call "preventDefault" on the event in the callback. Dioxus does _not_ currently support this behavior. Note: this means you cannot conditionally prevent default behavior based on the data in the event.
|
||||
|
||||
## Handler Props
|
||||
|
||||
Sometimes, you might want to make a component that accepts an event handler. A simple example would be a `FancyButton` component, which accepts an `on_click` handler:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_handler_prop.rs:component_with_handler}}
|
||||
```
|
||||
|
||||
Then, you can use it like any other handler:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_handler_prop.rs:usage}}
|
||||
```
|
||||
|
||||
|
|
|
@ -14,9 +14,10 @@ Hooks allow us to create state in our components. Hooks are Rust functions that
|
|||
|
||||
For example, you might have seen the counter example, in which state (a number) is tracked using the `use_state` hook:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_counter.rs:component}}
|
||||
```
|
||||
|
||||
![Screenshot: counter app](./images/counter.png)
|
||||
|
||||
Every time the component's state changes, it re-renders, and the component function is called, so you can describe what you want the new UI to look like. You don't have to worry about "changing" anything – just describe what you want in terms of the state, and Dioxus will take care of the rest!
|
||||
|
@ -25,9 +26,10 @@ Every time the component's state changes, it re-renders, and the component funct
|
|||
|
||||
You can use multiple hooks in the same component if you want:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_counter_two_state.rs:component}}
|
||||
```
|
||||
|
||||
![Screenshot: app with two counters](./images/counter_two_state.png)
|
||||
|
||||
## Rules of Hooks
|
||||
|
@ -36,7 +38,7 @@ The above example might seem a bit magic, since Rust functions are typically not
|
|||
|
||||
But how can Dioxus differentiate between multiple hooks in the same component? As you saw in the second example, both `use_state` functions were called with the same parameters, so how come they can return different things when the counters are different?
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_counter_two_state.rs:use_state_calls}}
|
||||
```
|
||||
|
||||
|
@ -51,17 +53,20 @@ This is only possible because the two hooks are always called in the same order,
|
|||
These rules mean that there are certain things you can't do with hooks:
|
||||
|
||||
### No Hooks in Conditionals
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_bad.rs:conditional}}
|
||||
```
|
||||
|
||||
### No Hooks in Closures
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_bad.rs:closure}}
|
||||
```
|
||||
|
||||
### No Hooks in Loops
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_bad.rs:loop}}
|
||||
```
|
||||
|
||||
|
@ -75,9 +80,8 @@ Thankfully, there is another hook for that, `use_ref`! It is similar to `use_sta
|
|||
|
||||
Here's a simple example that keeps a list of events in a `use_ref`. We can acquire write access to the state with `.with_mut()`, and then just `.push` a new value to the state:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_use_ref.rs:component}}
|
||||
```
|
||||
|
||||
> The return values of `use_state` and `use_ref` (`UseState` and `UseRef`, respectively) are in some ways similar to [`Cell`](https://doc.rust-lang.org/std/cell/) and [`RefCell`](https://doc.rust-lang.org/std/cell/struct.RefCell.html) – they provide interior mutability. However, these Dioxus wrappers also ensure that the component gets re-rendered whenever you change the state.
|
||||
|
||||
|
|
|
@ -4,7 +4,6 @@ In many of your apps, you'll want to have different "scenes". For a webpage, the
|
|||
|
||||
To unify these platforms, Dioxus provides a first-party solution for scene management called Dioxus Router.
|
||||
|
||||
|
||||
## What is it?
|
||||
|
||||
For an app like the Dioxus landing page (https://dioxuslabs.com), we want to have several different scenes:
|
||||
|
@ -20,12 +19,11 @@ The Dioxus router makes it easy to create these scenes. To make sure we're using
|
|||
cargo add dioxus-router
|
||||
```
|
||||
|
||||
|
||||
## Using the router
|
||||
|
||||
Unlike other routers in the Rust ecosystem, our router is built declaratively. This makes it possible to compose our app layout simply by arranging components.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
// All of our routes will be rendered inside this Router component
|
||||
Router {
|
||||
|
@ -43,7 +41,7 @@ We can fix this one of two ways:
|
|||
|
||||
- A fallback 404 page
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
Router {
|
||||
Route { to: "/home", Home {} }
|
||||
|
@ -54,10 +52,9 @@ rsx!{
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
- Redirect 404 to home
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
Router {
|
||||
Route { to: "/home", Home {} }
|
||||
|
@ -72,8 +69,7 @@ rsx!{
|
|||
|
||||
For our app to navigate these routes, we can provide clickable elements called Links. These simply wrap `<a>` elements that, when clicked, navigate the app to the given location.
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
Link {
|
||||
to: "/home",
|
||||
|
|
|
@ -11,7 +11,8 @@ Suppose we want to build a meme editor. We want to have an input to edit the mem
|
|||
> Of course, in this simple example, we could write everything in one component – but it is better to split everything out in smaller components to make the code more reusable, maintainable, and performant (this is even more important for larger, complex apps).
|
||||
|
||||
We start with a `Meme` component, responsible for rendering a meme with a given caption:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor.rs:meme_component}}
|
||||
```
|
||||
|
||||
|
@ -19,14 +20,16 @@ We start with a `Meme` component, responsible for rendering a meme with a given
|
|||
|
||||
We also create a caption editor, completely decoupled from the meme. The caption editor must not store the caption itself – otherwise, how will we provide it to the `Meme` component? Instead, it should accept the current caption as a prop, as well as an event handler to delegate input events to:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor.rs:caption_editor}}
|
||||
```
|
||||
|
||||
Finally, a third component will render the other two as children. It will be responsible for keeping the state and passing down the relevant props.
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor.rs:meme_editor}}
|
||||
```
|
||||
|
||||
![Meme Editor Screenshot: An old plastic skeleton sitting on a park bench. Caption: "me waiting for a language feature"](./images/meme_editor_screenshot.png)
|
||||
|
||||
## Using Context
|
||||
|
@ -43,24 +46,26 @@ Dioxus offers a better solution than this "prop drilling" – providing context.
|
|||
|
||||
First, we have to create a struct for our dark mode configuration:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:DarkMode_struct}}
|
||||
```
|
||||
|
||||
Now, in a top-level component (like `App`), we can provide the `DarkMode` context to all children components:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:context_provider}}
|
||||
```
|
||||
|
||||
As a result, any child component of `App` (direct or not), can access the `DarkMode` context.
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:use_context}}
|
||||
```
|
||||
|
||||
> `use_context` returns `Option<UseSharedState<DarkMode>>` here. If the context has been provided, the value is `Some(UseSharedState<DarkMode>)`, which you can call `.read` or `.write` on, similarly to `UseRef`. Otherwise, the value is `None`.
|
||||
|
||||
For example, here's how we would implement the dark mode toggle, which both reads the context (to determine what color it should render) and writes to it (to toggle dark mode):
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:toggle}}
|
||||
```
|
||||
|
||||
|
|
|
@ -6,11 +6,12 @@ Interfaces often need to provide a way to input data: e.g. text, numbers, checkb
|
|||
|
||||
With controlled inputs, you are directly in charge of the state of the input. This gives you a lot of flexibility, and makes it easy to keep things in sync. For example, this is how you would create a controlled text input:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/input_controlled.rs:component}}
|
||||
```
|
||||
|
||||
Notice the flexibility – you can:
|
||||
|
||||
- Also display the same contents in another element, and they will be in sync
|
||||
- Transform the input every time it is modified (e.g. to make sure it is upper case)
|
||||
- Validate the input every time it changes
|
||||
|
@ -23,9 +24,10 @@ As an alternative to controlled inputs, you can simply let the platform keep tra
|
|||
|
||||
Since you don't necessarily have the current value of the uncontrolled input in state, you can access it either by listening to `oninput` events (similarly to controlled components), or, if the input is part of a form, you can access the form data in the form events (e.g. `oninput` or `onsubmit`):
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/input_uncontrolled.rs:component}}
|
||||
```
|
||||
|
||||
```
|
||||
Submitted! UiEvent { data: FormData { value: "", values: {"age": "very old", "date": "1966", "name": "Fred"} } }
|
||||
```
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Os **"hooks"** `use_future` e `use_coroutine` são úteis se você quiser gerar incondicionalmente o `Future`. Às vezes, porém, você desejará apenas gerar um `Future` em resposta a um evento, como um clique do mouse. Por exemplo, suponha que você precise enviar uma solicitação quando o usuário clicar em um botão "log in". Para isso, você pode usar `cx.spawn`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/spawn.rs:spawn}}
|
||||
```
|
||||
|
||||
|
@ -14,7 +14,7 @@ No entanto, como você normalmente precisa de uma maneira de atualizar o valor d
|
|||
|
||||
Para tornar isso um pouco menos detalhado, o Dioxus exporta a macro `to_owned!` que criará uma ligação como mostrado acima, o que pode ser bastante útil ao lidar com muitos valores.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/spawn.rs:to_owned_macro}}
|
||||
```
|
||||
|
||||
|
@ -24,6 +24,6 @@ Calling `spawn` will give you a `JoinHandle` which lets you cancel or pause the
|
|||
|
||||
Às vezes, você pode querer gerar uma tarefa em segundo plano que precise de vários _threads_ ou conversar com o hardware que pode bloquear o código do seu aplicativo. Nesses casos, podemos gerar diretamente uma tarefa Tokio do nosso `Future`. Para Dioxus-Desktop, sua tarefa será gerada no tempo de execução Multi-Tarefado do Tokio:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/spawn.rs:tokio}}
|
||||
```
|
||||
|
|
|
@ -8,7 +8,7 @@ Assim como os `Futures` regulares, o código em uma corrotina Dioxus será execu
|
|||
|
||||
A configuração básica para corrotinas é o _hook_ `use_coroutine`. A maioria das corrotinas que escrevemos serão _loops_ de pesquisa usando `async`/`await`.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let ws: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {
|
||||
// Connect to some sort of service
|
||||
|
@ -26,7 +26,7 @@ Para muitos serviços, um _loop_ assíncrono simples lidará com a maioria dos c
|
|||
|
||||
No entanto, se quisermos desabilitar temporariamente a corrotina, podemos "pausá-la" usando o método `pause` e "retomá-la" usando o método `resume`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let sync: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {
|
||||
// code for syncing
|
||||
});
|
||||
|
@ -56,7 +56,7 @@ Você deve ter notado que o encerramento `use_coroutine` recebe um argumento cha
|
|||
|
||||
Usando corrotinas, temos a oportunidade de centralizar nossa lógica assíncrona. O parâmetro `rx` é um canal ilimitado para código externo à corrotina para enviar dados _para_ a corrotina. Em vez de fazer um _loop_ em um serviço externo, podemos fazer um _loop_ no próprio canal, processando mensagens de dentro de nosso aplicativo sem precisar gerar um novo `Future`. Para enviar dados para a corrotina, chamaríamos "send" no _handle_.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum ProfileUpdate {
|
||||
SetUsername(String),
|
||||
SetAge(i32)
|
||||
|
@ -84,7 +84,7 @@ cx.render(rsx!{
|
|||
|
||||
Para aplicativos suficientemente complexos, poderíamos criar vários "serviços" úteis diferentes que fazem um _loop_ nos canais para atualizar o aplicativo.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let profile = use_coroutine(cx, profile_service);
|
||||
let editor = use_coroutine(cx, editor_service);
|
||||
let sync = use_coroutine(cx, sync_service);
|
||||
|
@ -104,7 +104,7 @@ async fn editor_service(rx: UnboundedReceiver<EditorCommand>) {
|
|||
|
||||
Podemos combinar corrotinas com `Fermi` para emular o sistema `Thunk` do **Redux Toolkit** com muito menos dor de cabeça. Isso nos permite armazenar todo o estado do nosso aplicativo _dentro_ de uma tarefa e, em seguida, simplesmente atualizar os valores de "visualização" armazenados em `Atoms`. Não pode ser subestimado o quão poderosa é essa técnica: temos todas as vantagens das tarefas nativas do Rust com as otimizações e ergonomia do estado global. Isso significa que seu estado _real_ não precisa estar vinculado a um sistema como `Fermi` ou `Redux` – os únicos `Atoms` que precisam existir são aqueles que são usados para controlar a interface.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
static USERNAME: Atom<String> = |_| "default".to_string();
|
||||
|
||||
fn app(cx: Scope) -> Element {
|
||||
|
@ -128,7 +128,7 @@ fn Banner(cx: Scope) -> Element {
|
|||
|
||||
Agora, em nosso serviço de sincronização, podemos estruturar nosso estado como quisermos. Só precisamos atualizar os valores da _view_ quando estiver pronto.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum SyncAction {
|
||||
SetUsername(String),
|
||||
}
|
||||
|
@ -155,7 +155,7 @@ async fn sync_service(mut rx: UnboundedReceiver<SyncAction>, atoms: AtomRoot) {
|
|||
|
||||
Para obter valores de uma corrotina, basta usar um identificador `UseState` e definir o valor sempre que sua corrotina concluir seu trabalho.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let sync_status = use_state(cx, || Status::Launching);
|
||||
let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
|
||||
to_owned![sync_status];
|
||||
|
@ -172,7 +172,7 @@ let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
|
|||
|
||||
Os identificadores de corrotina são injetados automaticamente por meio da API de contexto. `use_coroutine_handle` com o tipo de mensagem como genérico pode ser usado para buscar um _handle_.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Child(cx: Scope) -> Element {
|
||||
let sync_task = use_coroutine_handle::<SyncAction>(cx);
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Por exemplo, podemos fazer uma solicitação de API dentro de `use_future`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/use_future.rs:use_future}}
|
||||
```
|
||||
|
||||
|
@ -14,7 +14,7 @@ Podemos usar `.value()` para obter o resultado do `Future`. Na primeira execuç
|
|||
|
||||
Podemos então renderizar esse resultado:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/use_future.rs:render}}
|
||||
```
|
||||
|
||||
|
@ -26,6 +26,6 @@ O identificador `UseFuture` fornece um método `restart`. Ele pode ser usado par
|
|||
|
||||
Muitas vezes, você precisará executar o `Future` novamente toda vez que algum valor (por exemplo, uma prop) mudar. Ao invés de `.restart` manualmente, você pode fornecer uma tupla de "dependências" para o gancho. Ele executará automaticamente o `Future` quando qualquer uma dessas dependências for alterada. Exemplo:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/use_future.rs:dependency}}
|
||||
```
|
||||
|
|
|
@ -8,7 +8,7 @@ Os fragmentos não montam um elemento físico no DOM imediatamente, então o Dio
|
|||
|
||||
Apenas os nós Componente e Fragmento são suscetíveis a esse problema. O Dioxus atenua isso com componentes fornecendo uma API para registrar o estado compartilhado sem o padrão _Context Provider_.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/anti_patterns.rs:nested_fragments}}
|
||||
```
|
||||
|
||||
|
@ -16,7 +16,7 @@ Apenas os nós Componente e Fragmento são suscetíveis a esse problema. O Dioxu
|
|||
|
||||
Conforme descrito no capítulo de renderização condicional, os itens da lista devem ter _keys_ exclusivas associadas aos mesmos itens nas renderizações. Isso ajuda o Dioxus a associar o estado aos componentes contidos e garante um bom desempenho de diferenciação. Não omita as _keys_, a menos que você saiba que a lista é estática e nunca será alterada.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/anti_patterns.rs:iter_keys}}
|
||||
```
|
||||
|
||||
|
|
|
@ -8,7 +8,7 @@ No entanto, não falamos sobre tratamento de erros neste guia! Neste capítulo,
|
|||
|
||||
Observadores astutos podem ter notado que `Element` é na verdade um alias de tipo para `Option<VNode>`. Você não precisa saber o que é um `VNode`, mas é importante reconhecer que não poderíamos retornar nada:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn App(cx: Scope) -> Element {
|
||||
None
|
||||
}
|
||||
|
@ -18,7 +18,7 @@ Isso nos permite adicionar um pouco de açúcar sintático para operações que
|
|||
|
||||
> A natureza de `Option<VNode>` pode mudar no futuro à medida que a característica `try` for atualizada.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn App(cx: Scope) -> Element {
|
||||
// immediately return "None"
|
||||
let name = cx.use_hook(|_| Some("hi"))?;
|
||||
|
@ -29,7 +29,7 @@ fn App(cx: Scope) -> Element {
|
|||
|
||||
Como o Rust não pode aceitar opções e resultados com a infraestrutura _try_ existente, você precisará manipular os resultados manualmente. Isso pode ser feito convertendo-os em `Option` ou manipulando-os explicitamente.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn App(cx: Scope) -> Element {
|
||||
// Convert Result to Option
|
||||
let name = cx.use_hook(|_| "1.234").parse().ok()?;
|
||||
|
@ -52,13 +52,13 @@ A próxima "melhor" maneira de lidar com erros no Dioxus é combinar (`match`) o
|
|||
|
||||
Para fazer isso, simplesmente temos um estado de erro embutido em nosso componente:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let err = use_state(cx, || None);
|
||||
```
|
||||
|
||||
Sempre que realizarmos uma ação que gere um erro, definiremos esse estado de erro. Podemos então combinar o erro de várias maneiras (retorno antecipado, elemento de retorno etc.).
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Commandline(cx: Scope) -> Element {
|
||||
let error = use_state(cx, || None);
|
||||
|
||||
|
@ -79,7 +79,7 @@ fn Commandline(cx: Scope) -> Element {
|
|||
|
||||
Se você estiver lidando com alguns componentes com um mínimo de aninhamento, basta passar o identificador de erro para componentes filhos.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Commandline(cx: Scope) -> Element {
|
||||
let error = use_state(cx, || None);
|
||||
|
||||
|
@ -106,7 +106,7 @@ Para começar, considere usar um _hook_ embutido como `use_context` e `use_conte
|
|||
|
||||
No "topo" de nossa arquitetura, queremos declarar explicitamente um valor que pode ser um erro.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum InputError {
|
||||
None,
|
||||
TooLong,
|
||||
|
@ -118,7 +118,7 @@ static INPUT_ERROR: Atom<InputError> = |_| InputError::None;
|
|||
|
||||
Então, em nosso componente de nível superior, queremos tratar explicitamente o possível estado de erro para esta parte da árvore.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn TopLevel(cx: Scope) -> Element {
|
||||
let error = use_read(cx, INPUT_ERROR);
|
||||
|
||||
|
@ -132,7 +132,7 @@ fn TopLevel(cx: Scope) -> Element {
|
|||
|
||||
Agora, sempre que um componente _downstream_ tiver um erro em suas ações, ele pode simplesmente definir seu próprio estado de erro:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn Commandline(cx: Scope) -> Element {
|
||||
let set_error = use_set(cx, INPUT_ERROR);
|
||||
|
||||
|
|
|
@ -21,7 +21,7 @@ Como referência, confira o interpretador `javascript` ou o renderizador `tui` c
|
|||
|
||||
O tipo "DomEdit" é uma `enum` serializada que representa uma operação atômica que ocorre no `RealDom`. As variantes seguem aproximadamente este conjunto:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum DomEdit {
|
||||
PushRoot,
|
||||
AppendChildren,
|
||||
|
@ -48,7 +48,7 @@ O mecanismo de diferenciação Dioxus opera como uma [máquina de pilha] (https:
|
|||
|
||||
Para fins de compreensão, vamos considerar este exemplo – uma declaração de interface do usuário muito simples:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!( h1 {"hello world"} )
|
||||
```
|
||||
|
||||
|
@ -56,7 +56,7 @@ Para começar, o Dioxus deve primeiro navegar até o contêiner dessa tag h1. Pa
|
|||
|
||||
Quando o renderizador recebe essa instrução, ele empurra o `Node` real para sua própria pilha. A pilha do renderizador real ficará assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container)
|
||||
]
|
||||
|
@ -67,7 +67,7 @@ stack: [
|
|||
|
||||
Em seguida, o Dioxus encontrará o nó `h1`. O algoritmo `diff` decide que este nó precisa ser criado, então o Dioxus irá gerar o DomEdit `CreateElement`. Quando o renderizador receber esta instrução, ele criará um nó desmontado e o enviará para sua própria pilha (_stack_):
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -80,7 +80,7 @@ stack: [
|
|||
|
||||
Em seguida, Dioxus vê o nó de texto e gera o DomEdit `CreateTextNode`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -95,7 +95,7 @@ stack: [
|
|||
|
||||
Lembre-se, o nó de texto não está anexado a nada (ele está desmontado), então o Dioxus precisa gerar um _Edit_ que conecte o nó de texto ao elemento `h1`. Depende da situação, mas neste caso usamos `AppendChildren`. Isso remove o nó de texto da _stack_, deixando o elemento `h1` como o próximo elemento na linha.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -110,7 +110,7 @@ stack: [
|
|||
|
||||
Chamamos `AppendChildren` novamente, retirando o nó `h1` e anexando-o ao pai:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -125,7 +125,7 @@ stack: [
|
|||
|
||||
Finalmente, o contêiner é aberto, pois não precisamos mais dele.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -139,7 +139,7 @@ stack: []
|
|||
|
||||
Com o tempo, nossa _stack_ ficou assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
[]
|
||||
[Container]
|
||||
[Container, h1]
|
||||
|
@ -165,7 +165,7 @@ Como a maioria das GUIs, o Dioxus conta com um _loop_ de eventos para progredir
|
|||
|
||||
O código para a implementação do `WebSys` é direto, então vamos adicioná-lo aqui para demonstrar como um `loop` de eventos é simples:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
||||
// Push the body element onto the WebsysDom's stack machine
|
||||
let mut websys_dom = crate::new::WebsysDom::new(prepare_websys_dom());
|
||||
|
@ -195,7 +195,7 @@ pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
|||
|
||||
É importante que você decodifique os eventos reais do seu sistema de eventos no sistema de eventos sintético do Dioxus (entenda sintético como abstraído). Isso significa simplesmente combinar seu tipo de evento e criar um tipo Dioxus `UserEvent`. No momento, o sistema `VirtualEvent` é modelado quase inteiramente em torno da especificação HTML, mas estamos interessados em reduzi-lo.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn virtual_event_from_websys_event(event: &web_sys::Event) -> VirtualEvent {
|
||||
match event.type_().as_str() {
|
||||
"keydown" => {
|
||||
|
@ -233,7 +233,7 @@ Esses elementos personalizados são definidos como estruturas de unidade com imp
|
|||
|
||||
Por exemplo, o elemento `div` é (aproximadamente!) definido assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
struct div;
|
||||
impl div {
|
||||
/// Some glorious documentation about the class property.
|
||||
|
@ -262,7 +262,7 @@ O `RealDom` é uma abstração de nível superior sobre a atualização do Dom.
|
|||
Vamos construir um renderizador de exemplo com bordas, tamanho e cor do texto.
|
||||
Antes de começarmos, vamos dar uma olhada em um elemento de exemplo que podemos renderizar:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
cx.render(rsx!{
|
||||
div{
|
||||
color: "red",
|
||||
|
@ -280,50 +280,50 @@ No diagrama a seguir, as setas representam o fluxo de dados:
|
|||
|
||||
[![](https://mermaid.ink/img/pako:eNqdVNFqgzAU_RXJXizUUZPJmIM-jO0LukdhpCbO0JhIGteW0n9fNK1Oa0brfUnu9VxyzzkXjyCVhIIYZFzu0hwr7X2-JcIzsa3W3wqXuZdKoele22oddfa1Y0Tnfn31muvMfqeCDNq3GmvaNROmaKqZFO1DPTRhP8MOd1fTWYNDvzlmQbBMJZcq9JtjNgY1mLVUhBqQPQeojl3wGCw5PsjqnIe-zXqEL8GZ2Kz0gVMPmoeU3ND4IcuiaLGY2zRouuKncv_qGKv3VodpJe0JVU6QCQ5kgqMyWQVr8hbk4hm1PBcmsuwmnrCVH94rP7xN_ucp8sOB_EPSfz9drYVrkpc_AmH8_yTjJueUc-ntpOJkgt2os9tKjcYlt-DLUiD3UsB2KZCLcwjv3Aq33-g2v0M0xXA0MBy5DUdXi-gcJZriuLmAOSioKjAj5ld8rMsJ0DktaAJicyVYbRKQiJPBVSUx438QpqUCcYb5ls4BrrRcHUTaFizqnWGzR8W5evoFI-bJdw)](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqdVNFqgzAU_RXJXizUUZPJmIM-jO0LukdhpCbO0JhIGteW0n9fNK1Oa0brfUnu9VxyzzkXjyCVhIIYZFzu0hwr7X2-JcIzsa3W3wqXuZdKoele22oddfa1Y0Tnfn31muvMfqeCDNq3GmvaNROmaKqZFO1DPTRhP8MOd1fTWYNDvzlmQbBMJZcq9JtjNgY1mLVUhBqQPQeojl3wGCw5PsjqnIe-zXqEL8GZ2Kz0gVMPmoeU3ND4IcuiaLGY2zRouuKncv_qGKv3VodpJe0JVU6QCQ5kgqMyWQVr8hbk4hm1PBcmsuwmnrCVH94rP7xN_ucp8sOB_EPSfz9drYVrkpc_AmH8_yTjJueUc-ntpOJkgt2os9tKjcYlt-DLUiD3UsB2KZCLcwjv3Aq33-g2v0M0xXA0MBy5DUdXi-gcJZriuLmAOSioKjAj5ld8rMsJ0DktaAJicyVYbRKQiJPBVSUx438QpqUCcYb5ls4BrrRcHUTaFizqnWGzR8W5evoFI-bJdw)
|
||||
|
||||
[//]: # '%% mermaid flow chart'
|
||||
[//]: # 'flowchart TB'
|
||||
[//]: # ' subgraph context'
|
||||
[//]: # ' text_width(text width)'
|
||||
[//]: # ' end'
|
||||
[//]: # ' subgraph state'
|
||||
[//]: # ' direction TB'
|
||||
[//]: # ' subgraph div state'
|
||||
[//]: # ' direction TB'
|
||||
[//]: # ' state1(state)-->color1(color)'
|
||||
[//]: # ' state1-->border1(border)'
|
||||
[//]: # ' text_width-.->layout_width1(layout width)'
|
||||
[//]: # ' linkStyle 2 stroke:#ff5500,stroke-width:4px;'
|
||||
[//]: # ' state1-->layout_width1'
|
||||
[//]: # ' end'
|
||||
[//]: # ' subgraph p state'
|
||||
[//]: # ' direction TB'
|
||||
[//]: # ' state2(state)-->color2(color)'
|
||||
[//]: # ' color1-.->color2'
|
||||
[//]: # ' linkStyle 5 stroke:#0000ff,stroke-width:4px;'
|
||||
[//]: # ' state2-->border2(border)'
|
||||
[//]: # ' text_width-.->layout_width2(layout width)'
|
||||
[//]: # ' linkStyle 7 stroke:#ff5500,stroke-width:4px;'
|
||||
[//]: # ' state2-->layout_width2'
|
||||
[//]: # ' layout_width2-.->layout_width1'
|
||||
[//]: # ' linkStyle 9 stroke:#00aa00,stroke-width:4px;'
|
||||
[//]: # ' end'
|
||||
[//]: # ' subgraph hello world state'
|
||||
[//]: # ' direction TB'
|
||||
[//]: # ' state3(state)-->border3(border)'
|
||||
[//]: # ' state3-->color3(color)'
|
||||
[//]: # ' color2-.->color3'
|
||||
[//]: # ' linkStyle 12 stroke:#0000ff,stroke-width:4px;'
|
||||
[//]: # ' text_width-.->layout_width3(layout width)'
|
||||
[//]: # ' linkStyle 13 stroke:#ff5500,stroke-width:4px;'
|
||||
[//]: # ' state3-->layout_width3'
|
||||
[//]: # ' layout_width3-.->layout_width2'
|
||||
[//]: # ' linkStyle 15 stroke:#00aa00,stroke-width:4px;'
|
||||
[//]: # ' end'
|
||||
[//]: # ' end'
|
||||
[//]: # "%% mermaid flow chart"
|
||||
[//]: # "flowchart TB"
|
||||
[//]: # " subgraph context"
|
||||
[//]: # " text_width(text width)"
|
||||
[//]: # " end"
|
||||
[//]: # " subgraph state"
|
||||
[//]: # " direction TB"
|
||||
[//]: # " subgraph div state"
|
||||
[//]: # " direction TB"
|
||||
[//]: # " state1(state)-->color1(color)"
|
||||
[//]: # " state1-->border1(border)"
|
||||
[//]: # " text_width-.->layout_width1(layout width)"
|
||||
[//]: # " linkStyle 2 stroke:#ff5500,stroke-width:4px;"
|
||||
[//]: # " state1-->layout_width1"
|
||||
[//]: # " end"
|
||||
[//]: # " subgraph p state"
|
||||
[//]: # " direction TB"
|
||||
[//]: # " state2(state)-->color2(color)"
|
||||
[//]: # " color1-.->color2"
|
||||
[//]: # " linkStyle 5 stroke:#0000ff,stroke-width:4px;"
|
||||
[//]: # " state2-->border2(border)"
|
||||
[//]: # " text_width-.->layout_width2(layout width)"
|
||||
[//]: # " linkStyle 7 stroke:#ff5500,stroke-width:4px;"
|
||||
[//]: # " state2-->layout_width2"
|
||||
[//]: # " layout_width2-.->layout_width1"
|
||||
[//]: # " linkStyle 9 stroke:#00aa00,stroke-width:4px;"
|
||||
[//]: # " end"
|
||||
[//]: # " subgraph hello world state"
|
||||
[//]: # " direction TB"
|
||||
[//]: # " state3(state)-->border3(border)"
|
||||
[//]: # " state3-->color3(color)"
|
||||
[//]: # " color2-.->color3"
|
||||
[//]: # " linkStyle 12 stroke:#0000ff,stroke-width:4px;"
|
||||
[//]: # " text_width-.->layout_width3(layout width)"
|
||||
[//]: # " linkStyle 13 stroke:#ff5500,stroke-width:4px;"
|
||||
[//]: # " state3-->layout_width3"
|
||||
[//]: # " layout_width3-.->layout_width2"
|
||||
[//]: # " linkStyle 15 stroke:#00aa00,stroke-width:4px;"
|
||||
[//]: # " end"
|
||||
[//]: # " end"
|
||||
|
||||
Para ajudar na construção de um DOM, o núcleo nativo fornece quatro `traits`: `State`, `ChildDepState`, `ParentDepState` e `NodeDepState` e uma estrutura `RealDom`. O `ChildDepState`, `ParentDepState` e `NodeDepState` fornecem uma maneira de descrever como algumas informações em um nó se relacionam com as de seus parentes. Ao fornecer como construir um único nó a partir de suas relações, o native-core derivará uma maneira de atualizar o estado de todos os nós para você com `#[derive(State)]`. Depois de ter um estado, você pode fornecê-lo como genérico ao `RealDom`. `RealDom` fornece todos os métodos para interagir e atualizar seu novo dom.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use dioxus_native_core::node_ref::*;
|
||||
use dioxus_native_core::state::{ChildDepState, NodeDepState, ParentDepState, State};
|
||||
use dioxus_native_core_macro::{sorted_str_slice, State};
|
||||
|
@ -455,7 +455,7 @@ struct ToyState {
|
|||
|
||||
Agora que temos nosso estado, podemos colocá-lo em uso em nosso DOM. Você pode atualizar o DOM com `update_state` para atualizar a estrutura do dom (adicionando, removendo e alterando as propriedades dos nós) e então `apply_mutations` para atualizar o `ToyState` para cada um dos nós que foram alterados.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn main(){
|
||||
fn app(cx: Scope) -> Element {
|
||||
cx.render(rsx!{
|
||||
|
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
Em alguns casos, você pode desejar criar um componente que atue como um contêiner para algum outro conteúdo, sem que o componente precise saber qual é esse conteúdo. Para conseguir isso, crie uma _prop_ do tipo `Element`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_element_props.rs:Clickable}}
|
||||
```
|
||||
|
||||
Então, ao renderizar o componente, você pode passar a saída de `cx.render(rsx!(...))`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_element_props.rs:Clickable_usage}}
|
||||
```
|
||||
|
||||
|
@ -20,12 +20,12 @@ Então, ao renderizar o componente, você pode passar a saída de `cx.render(rsx
|
|||
|
||||
Em vez de passar o `RSX` através de uma _prop_ regular, você pode querer aceitar filhos da mesma forma que os elementos podem ter filhos. O prop "mágico" `children` permite que você consiga isso:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_children.rs:Clickable}}
|
||||
```
|
||||
|
||||
Isso torna o uso do componente muito mais simples: basta colocar o `RSX` dentro dos colchetes `{}` – e não há necessidade de uma chamada `render` ou outra macro!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_children.rs:Clickable_usage}}
|
||||
```
|
||||
|
|
|
@ -19,13 +19,13 @@ Existem 2 tipos de estruturas Props:
|
|||
|
||||
_Props_ próprios são muito simples – eles não emprestam nada. Exemplo:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_owned_props.rs:Likes}}
|
||||
```
|
||||
|
||||
Você pode então passar valores de _prop_ para o componente da mesma forma que você passaria atributos para um elemento:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_owned_props.rs:App}}
|
||||
```
|
||||
|
||||
|
@ -37,13 +37,13 @@ Possuir _props_ funciona bem se seus _props_ forem fáceis de copiar – como um
|
|||
|
||||
Rust permite algo mais eficiente – emprestar a `String` como um `&str` – é para isso que servem as _props emprestadas_!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_borrowed_props.rs:TitleCard}}
|
||||
```
|
||||
|
||||
Podemos então usar o componente assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_borrowed_props.rs:App}}
|
||||
```
|
||||
|
||||
|
@ -57,13 +57,13 @@ A macro `#[derive(Props)]` tem alguns recursos que permitem personalizar o compo
|
|||
|
||||
Você pode criar campos opcionais usando o tipo `Option<…>` para um campo:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:OptionalProps}}
|
||||
```
|
||||
|
||||
Em seguida, você pode optar por fornecê-los ou não:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:OptionalProps_usage}}
|
||||
```
|
||||
|
||||
|
@ -71,13 +71,13 @@ Em seguida, você pode optar por fornecê-los ou não:
|
|||
|
||||
Se você quiser exigir explicitamente uma `Option`, e não uma _prop_ opcional, você pode anotá-la com `#[props(!optional)]`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:ExplicitOption}}
|
||||
```
|
||||
|
||||
Então, você tem que passar explicitamente `Some("str")` ou `None`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:ExplicitOption_usage}}
|
||||
```
|
||||
|
||||
|
@ -85,13 +85,13 @@ Então, você tem que passar explicitamente `Some("str")` ou `None`:
|
|||
|
||||
Você pode usar `#[props(default = 42)]` para tornar um campo opcional e especificar seu valor padrão:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:DefaultComponent}}
|
||||
```
|
||||
|
||||
Então, da mesma forma que _props_ opcionais, você não precisa fornecê-lo:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:DefaultComponent_usage}}
|
||||
```
|
||||
|
||||
|
@ -99,13 +99,13 @@ Então, da mesma forma que _props_ opcionais, você não precisa fornecê-lo:
|
|||
|
||||
É comum que as funções Rust aceitem `impl Into<SomeType>` em vez de apenas `SomeType` para suportar uma ampla gama de parâmetros. Se você quiser uma funcionalidade semelhante com _props_, você pode usar `#[props(into)]`. Por exemplo, você pode adicioná-lo em uma prop `String` – e `&str` também será aceito automaticamente, pois pode ser convertido em `String`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:IntoComponent}}
|
||||
```
|
||||
|
||||
Então, você pode usá-lo assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_props_options.rs:IntoComponent_usage}}
|
||||
```
|
||||
|
||||
|
@ -115,7 +115,7 @@ Até agora, todas as funções `Component` que vimos tinham uma _struct_ `Compon
|
|||
|
||||
`inline_props` permite que você faça exatamente isso. Em vez de digitar a versão "completa":
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[derive(Props, PartialEq)]
|
||||
struct TitleCardProps {
|
||||
title: String,
|
||||
|
@ -130,7 +130,7 @@ fn TitleCard(cx: Scope<TitleCardProps>) -> Element {
|
|||
|
||||
...você pode definir uma função que aceita _props_ como argumentos. Então, basta anotá-lo com `#[inline_props]`, e a macro irá transformá-lo em um componente regular para você:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[inline_props]
|
||||
fn TitleCard(cx: Scope, title: String) -> Element {
|
||||
cx.render(rsx!{
|
||||
|
|
|
@ -4,7 +4,7 @@ Assim como você não gostaria de escrever um programa complexo em uma única e
|
|||
|
||||
Um componente é uma função Rust, nomeada em _UpperCammelCase_, que recebe um parâmetro `Scope` e retorna um `Element` descrevendo a interface do usuário que deseja renderizar. Na verdade, nossa função `App` é um componente!
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_desktop.rs:component}}
|
||||
```
|
||||
|
||||
|
@ -12,13 +12,13 @@ Um componente é uma função Rust, nomeada em _UpperCammelCase_, que recebe um
|
|||
|
||||
Um Componente é responsável por alguma tarefa de renderização – normalmente, renderizando uma parte isolada da interface do usuário. Por exemplo, você pode ter um componente `About` que renderiza uma breve descrição do Dioxus Labs:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/components.rs:About}}
|
||||
```
|
||||
|
||||
Em seguida, você pode renderizar seu componente em outro componente, da mesma forma que os elementos são renderizados:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/components.rs:App}}
|
||||
```
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@ Dioxus é uma estrutura _declarativa_. Isso significa que, em vez de dizer ao Di
|
|||
|
||||
Você já viu um exemplo simples ou sintaxe `RSX` no aplicativo "hello world":
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_desktop.rs:component}}
|
||||
```
|
||||
|
||||
|
@ -14,7 +14,7 @@ Aqui, usamos a macro `rsx!` para _declarar_ que queremos um elemento `div`, cont
|
|||
|
||||
O RSX é muito semelhante ao HTML, pois descreve elementos com atributos e filhos. Aqui está um elemento `div` vazio no RSX, bem como o HTML resultante:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:empty}}
|
||||
```
|
||||
|
||||
|
@ -26,7 +26,7 @@ O RSX é muito semelhante ao HTML, pois descreve elementos com atributos e filho
|
|||
|
||||
Para adicionar filhos a um elemento, coloque-os dentro dos colchetes `{}`. Eles podem ser outros elementos ou texto. Por exemplo, você pode ter um elemento `ol` (lista ordenada), contendo 3 elementos `li` (item da lista), cada um dos quais contém algum texto:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:children}}
|
||||
```
|
||||
|
||||
|
@ -44,7 +44,7 @@ Você também pode "agrupar" elementos envolvendo-os em `Fragment {}`. Isso não
|
|||
|
||||
> Nota: você também pode renderizar vários elementos no nível superior de `rsx!` e eles serão agrupados automaticamente – não há necessidade de um `Fragment {}` explícito lá.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:fragments}}
|
||||
```
|
||||
|
||||
|
@ -60,7 +60,7 @@ Você também pode "agrupar" elementos envolvendo-os em `Fragment {}`. Isso não
|
|||
|
||||
Os atributos também são especificados dentro dos colchetes `{}`, usando a sintaxe `name: value`. Você pode fornecer o valor como um literal no RSX:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:attributes}}
|
||||
```
|
||||
|
||||
|
@ -79,7 +79,7 @@ Os atributos também são especificados dentro dos colchetes `{}`, usando a sint
|
|||
|
||||
Dioxus tem um conjunto pré-configurado de atributos que você pode usar. O RSX é validado em tempo de compilação para garantir que você não especificou um atributo inválido. Se você quiser substituir esse comportamento por um nome de atributo personalizado, especifique o atributo entre aspas:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:custom_attributes}}
|
||||
```
|
||||
|
||||
|
@ -91,7 +91,7 @@ Dioxus tem um conjunto pré-configurado de atributos que você pode usar. O RSX
|
|||
|
||||
Da mesma forma que você pode [formatar](https://doc.rust-lang.org/rust-by-example/hello/print/fmt.html) Rust _strings_, você também pode interpolar no texto RSX. Use `{variable}` para exibir o valor de uma variável em uma _string_, ou `{variable:?}` para usar a representação `Debug`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:formatting}}
|
||||
```
|
||||
|
||||
|
@ -107,7 +107,7 @@ Da mesma forma que você pode [formatar](https://doc.rust-lang.org/rust-by-examp
|
|||
|
||||
Você pode incluir expressões Rust arbitrárias dentro do RSX, mas deve escapá-las entre colchetes `[]`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rsx_overview.rs:expression}}
|
||||
```
|
||||
|
||||
|
|
|
@ -8,7 +8,7 @@ Se você estiver trabalhando com itens pré-renderizados, modelos ou uma bibliot
|
|||
|
||||
Por exemplo, enviar um conversor de markdown para Dioxus pode aumentar significativamente o tamanho final do aplicativo. Em vez disso, você desejará pré-renderizar sua remarcação para HTML e, em seguida, incluir o HTML diretamente em sua saída. Usamos essa abordagem para a [página inicial do Dioxus](https://dioxuslabs.com):
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/dangerous_inner_html.rs:dangerous_inner_html}}
|
||||
```
|
||||
|
||||
|
@ -22,7 +22,7 @@ A maioria dos atributos, quando renderizados, serão renderizados exatamente com
|
|||
|
||||
Portanto, este RSX não renderizaria o atributo `hidden`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/boolean_attribute.rs:boolean_attribute}}
|
||||
```
|
||||
|
||||
|
|
|
@ -35,6 +35,6 @@ cargo add dioxus-desktop
|
|||
|
||||
Edite seu `main.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_desktop.rs:all}}
|
||||
```
|
||||
|
|
|
@ -59,7 +59,7 @@ simple_logger = "*"
|
|||
|
||||
Edite seu `lib.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use dioxus::prelude::*;
|
||||
|
||||
fn main() {
|
||||
|
|
|
@ -16,7 +16,7 @@ Ao trabalhar com frameworks web que requerem `Send`, é possível renderizar um
|
|||
|
||||
Se você quer apenas renderizar `rsx!` ou um VirtualDom para HTML, confira os documentos da API. É bem simples:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// We can render VirtualDoms
|
||||
let mut vdom = VirtualDom::new(app);
|
||||
let _ = vdom.rebuild();
|
||||
|
@ -61,7 +61,7 @@ tokio = { version = "1.15.0", features = ["full"] }
|
|||
|
||||
Agora, configure seu aplicativo Axum para responder em um _endpoint_.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use axum::{response::Html, routing::get, Router};
|
||||
use dioxus::prelude::*;
|
||||
|
||||
|
@ -83,7 +83,7 @@ async fn main() {
|
|||
|
||||
E, em seguida, adicione nosso _endpoint_. Podemos renderizar `rsx!` diretamente:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
async fn app_endpoint() -> Html<String> {
|
||||
Html(dioxus_ssr::render_lazy(rsx! {
|
||||
h1 { "hello world!" }
|
||||
|
@ -93,7 +93,7 @@ async fn app_endpoint() -> Html<String> {
|
|||
|
||||
Ou podemos renderizar `VirtualDoms`.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
async fn app_endpoint() -> Html<String> {
|
||||
fn app(cx: Scope) -> Element {
|
||||
cx.render(rsx!(h1 { "hello world" }))
|
||||
|
|
|
@ -23,7 +23,7 @@ cargo add dioxus-tui
|
|||
|
||||
Em seguida, edite seu `main.rs` com o modelo básico.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_tui.rs}}
|
||||
```
|
||||
|
||||
|
@ -35,7 +35,7 @@ cargo run
|
|||
|
||||
Pressione "ctrl-c" para fechar o aplicativo. Para mudar de "ctrl-c" para apenas "q" para sair, você pode iniciar o aplicativo com uma configuração para desativar o sair padrão e usar a raiz TuiContext para sair por conta própria.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_tui_no_ctrl_c.rs}}
|
||||
```
|
||||
|
||||
|
|
|
@ -64,7 +64,7 @@ Adicione um `index.html` para o `Trunk` usar. Certifique-se de que seu elemento
|
|||
|
||||
Edite seu `main.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hello_world_web.rs}}
|
||||
```
|
||||
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Dioxus é uma estrutura portátil, de alto desempenho e ergonômica para a construção de interfaces de usuário multiplataforma no Rust. Este guia irá ajudá-lo a começar a escrever aplicativos Dioxus para a Web, Desktop, Mobile e muito mais.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let mut count = use_state(cx, || 0);
|
||||
|
||||
|
|
|
@ -8,7 +8,7 @@ Para evitar a repetição, você pode encapsular a lógica de negócios com base
|
|||
|
||||
Por exemplo, se muitos componentes precisam acessar uma _struct_ `AppSettings`, você pode criar um gancho de "atalho":
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_composed.rs:wrap_context}}
|
||||
```
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
Para renderizar diferentes elementos com base em uma condição, você pode usar uma instrução `if-else`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/conditional_rendering.rs:if_else}}
|
||||
```
|
||||
|
||||
|
@ -16,7 +16,7 @@ Para renderizar diferentes elementos com base em uma condição, você pode usar
|
|||
|
||||
Como `Element` é uma `Option<VNode>`, os componentes que aceitam `Element` como _prop_ podem realmente inspecionar seu conteúdo e renderizar coisas diferentes com base nisso. Exemplo:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/component_children_inspect.rs:Clickable}}
|
||||
```
|
||||
|
||||
|
@ -26,7 +26,7 @@ Você não pode modificar o `Element`, mas se precisar de uma versão modificada
|
|||
|
||||
Para renderizar nada, você pode retornar `None` de um componente. Isso é útil se você deseja ocultar algo condicionalmente:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/conditional_rendering.rs:conditional_none}}
|
||||
```
|
||||
|
||||
|
@ -47,7 +47,7 @@ Para isso, o Dioxus aceita iteradores que produzem `Element`s. Então precisamos
|
|||
|
||||
Exemplo: suponha que você tenha uma lista de comentários que deseja renderizar. Então, você pode renderizá-los assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/rendering_lists.rs:render_list}}
|
||||
```
|
||||
|
||||
|
|
|
@ -8,7 +8,7 @@ Os manipuladores de eventos são semelhantes aos atributos regulares, mas seus n
|
|||
|
||||
Por exemplo, para manipular cliques em um elemento, podemos especificar um manipulador `onclick`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_click.rs:rsx}}
|
||||
```
|
||||
|
||||
|
@ -29,7 +29,7 @@ Para saber o que os diferentes tipos de eventos fornecem, leia os [documentos do
|
|||
|
||||
Quando você tem, por exemplo um `button` dentro de um `div`, qualquer clique no `button` também é um clique no `div`. Por esta razão, Dioxus propaga o evento click: primeiro, ele é acionado no elemento alvo, depois nos elementos pai. Se você quiser evitar esse comportamento, você pode chamar `cancel_bubble()` no evento:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_click.rs:rsx}}
|
||||
```
|
||||
|
||||
|
@ -39,7 +39,7 @@ Alguns eventos têm um comportamento padrão. Para eventos de teclado, isso pode
|
|||
|
||||
Em alguns casos, você pode querer evitar esse comportamento padrão. Para isso, você pode adicionar o atributo `prevent_default` com o nome do manipulador cujo comportamento padrão você deseja interromper. Este atributo é especial: você pode anexá-lo várias vezes para vários atributos:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_prevent_default.rs:prevent_default}}
|
||||
```
|
||||
|
||||
|
@ -51,13 +51,13 @@ Quaisquer manipuladores de eventos ainda serão chamados.
|
|||
|
||||
Às vezes, você pode querer criar um componente que aceite um manipulador de eventos. Um exemplo simples seria um componente `FancyButton`, que aceita um manipulador `on_click`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_handler_prop.rs:component_with_handler}}
|
||||
```
|
||||
|
||||
Então, você pode usá-lo como qualquer outro manipulador:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/event_handler_prop.rs:usage}}
|
||||
```
|
||||
|
||||
|
|
|
@ -14,7 +14,7 @@ Para lógica com estado, você pode usar _hooks_. _Hooks_ são funções Rust qu
|
|||
|
||||
Por exemplo, você pode ter visto o exemplo do contador, no qual o estado (um número) é rastreado usando o _hook_ `use_state`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_counter.rs:component}}
|
||||
```
|
||||
|
||||
|
@ -26,7 +26,7 @@ Toda vez que o estado do componente muda, ele é renderizado novamente e a funç
|
|||
|
||||
Você pode usar vários _hooks_ no mesmo componente se quiser:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_counter_two_state.rs:component}}
|
||||
```
|
||||
|
||||
|
@ -38,7 +38,7 @@ O exemplo acima pode parecer um pouco mágico, já que as funções Rust normalm
|
|||
|
||||
Mas como Dioxus pode diferenciar entre vários _hooks_ no mesmo componente? Como você viu no segundo exemplo, ambas as funções `use_state` foram chamadas com os mesmos parâmetros, então como elas podem retornar coisas diferentes quando os contadores são diferentes?
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_counter_two_state.rs:use_state_calls}}
|
||||
```
|
||||
|
||||
|
@ -54,19 +54,19 @@ Essas regras significam que há certas coisas que você não pode fazer com _hoo
|
|||
|
||||
### Sem Hooks em Condicionais
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_bad.rs:conditional}}
|
||||
```
|
||||
|
||||
### Sem Hooks em Closures
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_bad.rs:closure}}
|
||||
```
|
||||
|
||||
### Sem Hooks em Loops
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_bad.rs:loop}}
|
||||
```
|
||||
|
||||
|
@ -80,7 +80,7 @@ Felizmente, existe outro _hook_ para isso, `use_ref`! É semelhante ao `use_stat
|
|||
|
||||
Aqui está um exemplo simples que mantém uma lista de eventos em um `use_ref`. Podemos adquirir acesso de escrita ao estado com `.write()`, e então apenas `.push` um novo valor para o estado:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/hooks_use_ref.rs:component}}
|
||||
```
|
||||
|
||||
|
|
|
@ -26,7 +26,7 @@ dioxus-router = { version = "*" }
|
|||
|
||||
Ao contrário de outros roteadores no ecossistema Rust, nosso roteador é construído de forma declarativa. Isso torna possível compor o layout do nosso aplicativo simplesmente organizando os componentes.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
Router {
|
||||
Route { to: "/home", Home {} }
|
||||
|
@ -41,7 +41,7 @@ Podemos corrigir isso de duas maneiras:
|
|||
|
||||
- Uma página 404 de _fallback_
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
Router {
|
||||
Route { to: "/home", Home {} }
|
||||
|
@ -53,7 +53,7 @@ rsx!{
|
|||
|
||||
- Redirecionar 404 para _Home_
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
Router {
|
||||
Route { to: "/home", Home {} }
|
||||
|
@ -67,7 +67,7 @@ rsx!{
|
|||
|
||||
Para que nosso aplicativo navegue nessas rotas, podemos fornecer elementos clicáveis chamados Links. Eles simplesmente envolvem elementos `<a>` que, quando clicados, navegam no aplicativo para o local determinado.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!{
|
||||
Link {
|
||||
to: "/home",
|
||||
|
|
|
@ -12,7 +12,7 @@ Por exemplo, suponha que queremos construir um editor de memes. Queremos ter uma
|
|||
|
||||
Começamos com um componente `Meme`, responsável por renderizar um meme com uma determinada legenda:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor.rs:meme_component}}
|
||||
```
|
||||
|
||||
|
@ -20,13 +20,13 @@ Começamos com um componente `Meme`, responsável por renderizar um meme com uma
|
|||
|
||||
Também criamos um editor de legendas, totalmente desacoplado do meme. O editor de legendas não deve armazenar a legenda em si – caso contrário, como iremos fornecê-la ao componente `Meme`? Em vez disso, ele deve aceitar a legenda atual como um suporte, bem como um manipulador de eventos para delegar eventos de entrada para:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor.rs:caption_editor}}
|
||||
```
|
||||
|
||||
Finalmente, um terceiro componente renderizará os outros dois como filhos. Ele será responsável por manter o estado e passar os _props_ relevantes.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor.rs:meme_editor}}
|
||||
```
|
||||
|
||||
|
@ -46,19 +46,19 @@ A Dioxus oferece uma solução melhor do que esta "perfuração com hélice" –
|
|||
|
||||
Primeiro, temos que criar um _struct_ para nossa configuração de modo escuro:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:DarkMode_struct}}
|
||||
```
|
||||
|
||||
Agora, em um componente de nível superior (como `App`), podemos fornecer o contexto `DarkMode` para todos os componentes filhos:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:context_provider}}
|
||||
```
|
||||
|
||||
Como resultado, qualquer componente filho de `App` (direto ou não), pode acessar o contexto `DarkMode`.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:use_context}}
|
||||
```
|
||||
|
||||
|
@ -66,6 +66,6 @@ Como resultado, qualquer componente filho de `App` (direto ou não), pode acessa
|
|||
|
||||
Por exemplo, aqui está como implementaríamos a alternância do modo escuro, que lê o contexto (para determinar a cor que deve renderizar) e grava nele (para alternar o modo escuro):
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/meme_editor_dark_mode.rs:toggle}}
|
||||
```
|
||||
|
|
|
@ -6,7 +6,7 @@ As interfaces geralmente precisam fornecer uma maneira de inserir dados: por exe
|
|||
|
||||
Com entradas controladas, você fica diretamente responsável pelo estado da entrada. Isso lhe dá muita flexibilidade e facilita manter as coisas em sincronia. Por exemplo, é assim que você criaria uma entrada de texto controlada:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/input_controlled.rs:component}}
|
||||
```
|
||||
|
||||
|
@ -24,7 +24,7 @@ Como alternativa às entradas controladas, você pode simplesmente deixar a plat
|
|||
|
||||
Como você não tem necessariamente o valor atual da entrada não controlada no estado, você pode acessá-lo ouvindo os eventos `oninput` (de maneira semelhante aos componentes controlados) ou, se a entrada for parte de um formulário, você pode acessar os dados do formulário nos eventos do formulário (por exemplo, `oninput` ou `onsubmit`):
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
{{#include ../../../examples/input_uncontrolled.rs:component}}
|
||||
```
|
||||
|
||||
|
|
|
@ -20,12 +20,11 @@ Thanks to these amazing folks for their code contributions:
|
|||
- [@oovm](https://github.com/oovm)
|
||||
- [@6asaaki](https://github.com/6asaaki)
|
||||
|
||||
|
||||
Just over two months in, and we already a ton of awesome changes to Dioxus!
|
||||
|
||||
Dioxus is a recently-released library for building interactive user interfaces (GUI) with Rust. It is built around a Virtual DOM, making it portable for the web, desktop, server, mobile, and more. Dioxus looks and feels just like React, so if you know React, then you'll feel right at home.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let mut count = use_state(cx, || 0);
|
||||
|
||||
|
@ -39,7 +38,7 @@ fn app(cx: Scope) -> Element {
|
|||
|
||||
# What's new?
|
||||
|
||||
A *ton* of stuff happened in this release; 550+ commits, 23 contributors, 2 minor releases, and 6 backers on Open Collective.
|
||||
A _ton_ of stuff happened in this release; 550+ commits, 23 contributors, 2 minor releases, and 6 backers on Open Collective.
|
||||
|
||||
Some of the major new features include:
|
||||
|
||||
|
@ -52,12 +51,10 @@ Some of the major new features include:
|
|||
|
||||
We also fixed and improved a bunch of stuff - check out the full list down below.
|
||||
|
||||
|
||||
## A New Renderer: Your terminal!
|
||||
|
||||
When Dioxus was initially released, we had very simple support for logging Dioxus elements out as TUI elements. In the past month or so, [@Demonthos](https://github.com/Demonthos) really stepped up and made the new crate a reality.
|
||||
|
||||
|
||||
![Imgur](https://i.imgur.com/GL7uu3r.png)
|
||||
|
||||
The new TUI renderer even supports mouse movements, keyboard input, async tasks, borders, and a ton more.
|
||||
|
@ -66,15 +63,13 @@ The new TUI renderer even supports mouse movements, keyboard input, async tasks,
|
|||
<source src="https://i.imgur.com/q25tZST.mp4" type="video/mp4">
|
||||
</vido>
|
||||
|
||||
|
||||
|
||||
## New Router
|
||||
|
||||
We totally revamped the router, switching away from the old yew-router approach to the more familiar [React-Router](http://reactrouter.com). It's less type-safe but provides more flexibility and support for beautiful URLs.
|
||||
|
||||
Apps with routers are *really* simple now. It's easy to compose the "Router", a "Route", and "Links" to define how your app is laid out:
|
||||
Apps with routers are _really_ simple now. It's easy to compose the "Router", a "Route", and "Links" to define how your app is laid out:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
cx.render(rsx! {
|
||||
Router {
|
||||
|
@ -97,7 +92,7 @@ fn app(cx: Scope) -> Element {
|
|||
|
||||
We're also using hooks to parse the URL parameters and segments so you can interact with the router from anywhere deeply nested in your app.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[derive(Deserialize)]
|
||||
struct Query { name: String }
|
||||
|
||||
|
@ -122,7 +117,7 @@ Managing state in your app can be challenging. Building global state management
|
|||
|
||||
Fermi uses the concept of "Atoms" for global state. These individual values can be get/set from anywhere in your app. Using state with Fermi is basically as simple as `use_state`.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// Create a single value in an "Atom"
|
||||
static TITLE: Atom<&str> = |_| "Hello";
|
||||
|
||||
|
@ -152,7 +147,8 @@ fn Child(cx: Scope) -> Element {
|
|||
For internal components, explicitly declaring props structs can become tedious. That's why we've built the new `inline_props` macro. This macro lets you inline your props definition right into your component function arguments.
|
||||
|
||||
Simply add the `inline_props` macro to your component:
|
||||
```rust
|
||||
|
||||
```rust, no_run
|
||||
#[inline_props]
|
||||
fn Child<'a>(
|
||||
cx: Scope,
|
||||
|
@ -174,9 +170,9 @@ You won't be able to document each field or attach attributes so you should refr
|
|||
|
||||
## Props optional fields
|
||||
|
||||
Sometimes you don't want to specify *every* value in a component's props, since there might a lot. That's why the `Props` macro now supports optional fields. You can use a combination of `default`, `strip_option`, and `optional` to tune the exact behavior of properties fields.
|
||||
Sometimes you don't want to specify _every_ value in a component's props, since there might a lot. That's why the `Props` macro now supports optional fields. You can use a combination of `default`, `strip_option`, and `optional` to tune the exact behavior of properties fields.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[derive(Props, PartialEq)]
|
||||
struct ChildProps {
|
||||
#[props(default = "client")]
|
||||
|
@ -207,16 +203,15 @@ Under the hood, we have a new string interning engine to cache commonly used tag
|
|||
|
||||
Overall, Dioxus apps are even more snappy than before.
|
||||
|
||||
|
||||
Before and after:
|
||||
![Before and After](https://imgur.com/byTBGlO.png)
|
||||
|
||||
|
||||
## Dioxus Desktop Window Context
|
||||
|
||||
A very welcome change, thanks AGAIN to [@mrxiaozhuox](https://github.com/mrxiaozhuox) is support for imperatively controlling the desktop window from your Dioxus code.
|
||||
|
||||
A bunch of new methods were added:
|
||||
|
||||
- Minimize and maximize window
|
||||
- Close window
|
||||
- Focus window
|
||||
|
@ -240,10 +235,9 @@ Unlike its counterpart, `Trunk.rs`, the dioxus-cli supports running examples and
|
|||
|
||||
Working with async isn't the easiest part of Rust. To help improve things, we've upgraded async support across the board in Dioxus.
|
||||
|
||||
|
||||
First, we upgraded the `use_future` hook. It now supports dependencies, which let you regenerate a future on the fly as its computed values change. It's never been easier to add datafetching to your Rust Web Apps:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn RenderDog(cx: Scope, breed: String) -> Element {
|
||||
let dog_request = use_future(cx, (breed,), |(breed,)| async move {
|
||||
reqwest::get(format!("https://dog.ceo/api/breed/{}/images/random", breed))
|
||||
|
@ -263,7 +257,7 @@ fn RenderDog(cx: Scope, breed: String) -> Element {
|
|||
|
||||
Additionally, we added better support for coroutines. You can now start, stop, resume, and message with asynchronous tasks. The coroutine is automatically exposed to the rest of your app via the Context API. For the vast majority of apps, Coroutines can satisfy all of your state management needs:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn App(cx: Scope) -> Element {
|
||||
let sync_task = use_coroutine(cx, |rx| async move {
|
||||
connect_to_server().await;
|
||||
|
@ -313,6 +307,7 @@ We've covered the major headlining features, but there were so many more!
|
|||
- Right-click menus are now disabled by default
|
||||
|
||||
## Fixes
|
||||
|
||||
- Windows support improved across the board
|
||||
- Linux support improved across the board
|
||||
- Bug in Calculator example
|
||||
|
@ -329,6 +324,7 @@ A ton more! Dioxus is now much more stable than it was at release!
|
|||
- The ContextAPI no longer uses RC to share state - anything that is `Clone` can be shared
|
||||
|
||||
## Community Additions
|
||||
|
||||
- [Styled Components macro](https://github.com/Zomatree/Revolt-Client/blob/master/src/utils.rs#14-27) [@Zomatree](https://github.com/Zomatree)
|
||||
- [Dioxus-Websocket hook](https://github.com/FruitieX/dioxus-websocket-hooks) [@FruitieX](https://github.com/FruitieX)
|
||||
- [Home automation server app](https://github.com/FruitieX/homectl) [@FruitieX](https://github.com/FruitieX)
|
||||
|
@ -363,5 +359,3 @@ If you're interested in building an app with Dioxus, make sure to check us out o
|
|||
- [Reddit](http://reddit.com/r/dioxus/)
|
||||
- [Discord](https://discord.gg/XgGxMSkvUM)
|
||||
- [Twitter](http://twitter.com/dioxuslabs)
|
||||
|
||||
|
||||
|
|
|
@ -20,7 +20,7 @@ Dioxus is designed to be familiar for developers already comfortable with React
|
|||
|
||||
To give you an idea of what Dioxus looks like, here's a simple counter app:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use dioxus::prelude::*;
|
||||
|
||||
fn main() {
|
||||
|
@ -112,8 +112,8 @@ Semantically, TypeScript-React and Rust-Dioxus are very similar. In TypeScript,
|
|||
|
||||
```tsx
|
||||
type CardProps = {
|
||||
title: string,
|
||||
paragraph: string,
|
||||
title: string;
|
||||
paragraph: string;
|
||||
};
|
||||
|
||||
const Card: FunctionComponent<CardProps> = (props) => {
|
||||
|
@ -130,7 +130,7 @@ const Card: FunctionComponent<CardProps> = (props) => {
|
|||
|
||||
In Dioxus, we would define the same component in a similar fashion:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
#[derive(Props, PartialEq)]
|
||||
struct CardProps {
|
||||
title: String,
|
||||
|
@ -176,14 +176,14 @@ $ cd dioxus_example
|
|||
|
||||
We then add a dependency on Dioxus to the `Cargo.toml` file, with the "desktop" feature enabled:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
[dependencies]
|
||||
dioxus = { version = "*", features = ["desktop"] }
|
||||
```
|
||||
|
||||
We can add our counter from above.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use dioxus::prelude::*;
|
||||
|
||||
fn main() {
|
||||
|
@ -203,14 +203,13 @@ fn app(cx: Scope) -> Element {
|
|||
|
||||
And voilà! We can `cargo run` our app
|
||||
|
||||
|
||||
![Simple Counter Desktop App](/static/counter.png)
|
||||
|
||||
## Support for JSX-style templating
|
||||
|
||||
Dioxus ships with a templating macro called RSX, a spin on React's JSX. RSX is very similar to regular struct syntax for Rust so it integrates well with your IDE. If used with [Rust-Analyzer](https://github.com/rust-analyzer/rust-analyzer) (not tested anywhere else) RSX supports code-folding, block selection, bracket pair colorizing, autocompletion, symbol renaming — pretty much anything you would expect from writing regular struct-style code.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx! {
|
||||
div { "Hello world" }
|
||||
button {
|
||||
|
@ -222,7 +221,7 @@ rsx! {
|
|||
|
||||
If macros aren't your style, you can always drop down to the factory API:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
LazyNodes::new(|f| {
|
||||
f.fragment([
|
||||
f.element(div, [f.text("hello world")], [], None, None)
|
||||
|
@ -245,9 +244,9 @@ To make it easier to work with RSX, we've built a small [VSCode extension](https
|
|||
|
||||
Many of the Rust UI frameworks are particularly difficult to work with. Even the ones branded as "ergonomic" are quite challenging to in comparison to TSX/JSX. With Dioxus, we've innovated on a number of Rust patterns to deliver a framework that is actually enjoyable to develop in.
|
||||
|
||||
For example, many Rust frameworks require you to clone your data in for *every* closure and handler you use. This can get really clumsy for large apps.
|
||||
For example, many Rust frameworks require you to clone your data in for _every_ closure and handler you use. This can get really clumsy for large apps.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
div()
|
||||
.children([
|
||||
button().onclick(cloned!(name, date, age, description => move |evt| { /* */ })
|
||||
|
@ -258,8 +257,7 @@ div()
|
|||
|
||||
Dioxus understands the lifetimes of data borrowed from `Scope`, so you can safely return any borrowed data without declaring explicit captures. Hook handles all implement `Copy` so they can be shared between listeners without any ceremony.
|
||||
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let name = use_state(cx, || "asd");
|
||||
rsx! {
|
||||
div {
|
||||
|
@ -272,7 +270,7 @@ rsx! {
|
|||
|
||||
Because we know the lifetime of your handlers, we can also expose this to children. No other Rust frameworks let us share borrowed state through the tree, forcing use of Rc/Arc everywhere. With Dioxus, all the Rc/Arc magic is tucked away in hooks, and just beautiful borrowed interfaces are exposed to your code. You don't need to know how Rc/RefCell work to build a competent Dioxus app.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn app(cx: Scope) -> Element {
|
||||
let name = use_state(cx, || "asd");
|
||||
cx.render(rsx!{
|
||||
|
@ -294,8 +292,7 @@ fn Button<'a>(cx: Scope<'a, Childprops<'a>>) -> Element {
|
|||
}
|
||||
```
|
||||
|
||||
There's *way* more to this story, but hopefully we've convinced you that Dioxus' DX somewhat approximates JSX/React.
|
||||
|
||||
There's _way_ more to this story, but hopefully we've convinced you that Dioxus' DX somewhat approximates JSX/React.
|
||||
|
||||
## Dioxus is perfected for the IDE
|
||||
|
||||
|
@ -335,9 +332,10 @@ We take the performance of Dioxus seriously. Instead of resolving to "good enoug
|
|||
|
||||
Dioxus is humbly built off the work done by [Dodrio](https://github.com/fitzgen/dodrio), a now-archived research project by fitzgen exploring the use of bump allocators in UI frameworks.
|
||||
|
||||
Dioxus is *substantially* more performant than many of the other Rust DOM-based UI libraries (Yew/Percy) and is *significantly* more performant than React - roughly competitive with InfernoJS. While not as performant as libraries like SolidJS/Sycamore, Dioxus imposes roughly a ~3% overhead over DOM patching, so it's *plenty* fast.
|
||||
Dioxus is _substantially_ more performant than many of the other Rust DOM-based UI libraries (Yew/Percy) and is _significantly_ more performant than React - roughly competitive with InfernoJS. While not as performant as libraries like SolidJS/Sycamore, Dioxus imposes roughly a ~3% overhead over DOM patching, so it's _plenty_ fast.
|
||||
|
||||
## Works on Desktop and Mobile
|
||||
|
||||
We’ve mentioned before that Dioxus works practically anywhere that Rust does. When running natively as a desktop or mobile app, your Dioxus code will run on its own thread, not inside of a web runtime. This means you can access hardware, file system, and platform APIs directly without needing to go through a shim layer. In our examples, we feature a [file explorer app](https://github.com/DioxusLabs/example-projects/tree/master/file-explorer) and [WiFi scanner app](https://github.com/DioxusLabs/example-projects/tree/master/wifi-scanner) where platform access occurs inside an asynchronous multithreaded coroutine. This solves the problem faced by React Native and other cross-platform toolkits where JavaScript apps incur a massive performance penalty with substantial maintenance overhead associated with platform API shims.
|
||||
|
||||
A desktop app:
|
||||
|
|
|
@ -21,7 +21,7 @@ Para referência, confira o interpretador JavaScript ou o renderizador TUI como
|
|||
|
||||
O tipo "DomEdit" é uma enumeração serializada que representa uma operação atômica que ocorre no `RealDom`. As variantes seguem aproximadamente este conjunto:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
enum DomEdit {
|
||||
PushRoot,
|
||||
AppendChildren,
|
||||
|
@ -48,7 +48,7 @@ O mecanismo de diferenciação do Dioxus opera como uma [máquina de pilha] (htt
|
|||
|
||||
Por uma questão de compreensão, vamos considerar este exemplo - uma declaração de interface do usuário muito simples:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!( h1 {"hello world"} )
|
||||
```
|
||||
|
||||
|
@ -56,7 +56,7 @@ To get things started, Dioxus must first navigate to the container of this h1 ta
|
|||
|
||||
When the renderer receives this instruction, it pushes the actual Node onto its own stack. The real renderer's stack will look like this:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container)
|
||||
]
|
||||
|
@ -67,7 +67,7 @@ stack: [
|
|||
|
||||
Em seguida, o Dioxus encontrará o nó `h1`. O algoritmo `diff` decide que este nó precisa ser criado, então o Dioxus irá gerar o DomEdit `CreateElement`. Quando o renderizador receber esta instrução, ele criará um nó desmontado e o enviará para sua própria pilha:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -80,7 +80,7 @@ stack: [
|
|||
|
||||
Em seguida, Dioxus vê o nó de texto e gera o DomEdit `CreateTextNode`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -95,7 +95,7 @@ stack: [
|
|||
|
||||
Lembre-se, o nó de texto não está anexado a nada (ele está desmontado), então o Dioxus precisa gerar um `Edit` que conecte o nó de texto ao elemento `h1`. Depende da situação, mas neste caso usamos `AppendChildren`. Isso remove o nó de texto da pilha, deixando o elemento `h1` como o próximo elemento na linha.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -110,7 +110,7 @@ stack: [
|
|||
|
||||
Chamamos `AppendChildren` novamente, retirando o nó `h1` e anexando-o ao pai:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -125,7 +125,7 @@ stack: [
|
|||
|
||||
Finalmente, o contêiner é aberto, pois não precisamos mais dele.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
instructions: [
|
||||
PushRoot(Container),
|
||||
CreateElement(h1),
|
||||
|
@ -139,7 +139,7 @@ stack: []
|
|||
|
||||
Com o tempo, nossa pilha ficou assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
[]
|
||||
[Container]
|
||||
[Container, h1]
|
||||
|
@ -165,7 +165,7 @@ Como a maioria das GUIs, o Dioxus conta com um `loop` de eventos para progredir
|
|||
|
||||
O código para a implementação do `WebSys` é direto, então vamos adicioná-lo aqui para demonstrar como um `loop` de eventos é simples:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
||||
// Push the body element onto the WebsysDom's stack machine
|
||||
let mut websys_dom = crate::new::WebsysDom::new(prepare_websys_dom());
|
||||
|
@ -195,7 +195,7 @@ pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
|
|||
|
||||
É importante que você decodifique os eventos reais do seu sistema de eventos no sistema de eventos sintético do Dioxus (significado sintético abstraído). Isso significa simplesmente combinar seu tipo de evento e criar um tipo Dioxus `UserEvent`. No momento, o sistema `VirtualEvent` é modelado quase inteiramente em torno da especificação HTML, mas estamos interessados em reduzi-lo.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn virtual_event_from_websys_event(event: &web_sys::Event) -> VirtualEvent {
|
||||
match event.type_().as_str() {
|
||||
"keydown" => {
|
||||
|
@ -234,7 +234,7 @@ Esses elementos personalizados são definidos como `unit struct` com implementa
|
|||
|
||||
Por exemplo, o elemento `div` é (aproximadamente!) definido assim:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
struct div;
|
||||
impl div {
|
||||
/// Some glorious documentation about the class property.
|
||||
|
@ -263,7 +263,7 @@ O `RealDom` é uma abstração de nível superior sobre a atualização do DOM.
|
|||
Vamos construir um renderizador de brinquedo com bordas, tamanho e cor do texto.
|
||||
Antes de começarmos, vamos dar uma olhada em um elemento de exemplo que podemos renderizar:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
cx.render(rsx!{
|
||||
div{
|
||||
color: "red",
|
||||
|
@ -315,7 +315,7 @@ flowchart TB
|
|||
|
||||
Para ajudar na construção de um Dom, o núcleo nativo fornece quatro características: `State`, `ChildDepState`, `ParentDepState` e `NodeDepState` e uma estrutura `RealDom`.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
use dioxus_native_core::node_ref::*;
|
||||
use dioxus_native_core::state::{ChildDepState, NodeDepState, ParentDepState, State};
|
||||
use dioxus_native_core_macro::{sorted_str_slice, State};
|
||||
|
@ -447,7 +447,7 @@ struct ToyState {
|
|||
|
||||
Agora que temos nosso estado, podemos colocá-lo em uso em nosso DOM. Nós podemos atualizar o DOM com `update_state` para atualizar a estrutura do `DOM` (adicionando, removendo e alterando as propriedades dos nós) e então `apply_mutations` para atualizar o `ToyState` para cada um dos nós que foram alterados.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn main(){
|
||||
fn app(cx: Scope) -> Element {
|
||||
cx.render(rsx!{
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
The RSX macro makes it very easy to assemble complex UIs with a very natural Rust syntax:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!(
|
||||
div {
|
||||
button {
|
||||
|
@ -30,7 +30,7 @@ In this section, we'll cover the `rsx!` macro in depth. If you prefer to learn t
|
|||
|
||||
Attributes must come before child elements
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
div {
|
||||
hidden: "false",
|
||||
"some text"
|
||||
|
@ -57,7 +57,7 @@ The `render` function provides an **extremely efficient** allocator for VNodes a
|
|||
|
||||
Sometimes, writing `cx.render` is a hassle. The `rsx! macro will accept any token followed by a comma as the target to call "render" on:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
cx.render(rsx!( div {} ))
|
||||
// becomes
|
||||
render!(div {})
|
||||
|
@ -67,7 +67,7 @@ render!(div {})
|
|||
|
||||
Sometimes, you might not want to render an element given a condition. The rsx! macro will accept any tokens directly contained with curly braces, provided they resolve to a type that implements `IntoIterator<VNode>`. This lets us write any Rust expression that resolves to a VNode:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!({
|
||||
if enabled {
|
||||
render!(div {"enabled"})
|
||||
|
@ -79,7 +79,7 @@ rsx!({
|
|||
|
||||
A convenient way of hiding/showing an element is returning an `Option<VNode>`. When combined with `and_then`, we can succinctly control the display state given some boolean:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!({
|
||||
a.and_then(rsx!(div {"enabled"}))
|
||||
})
|
||||
|
@ -87,7 +87,7 @@ rsx!({
|
|||
|
||||
It's important to note that the expression `rsx!()` is typically lazy - this expression must be _rendered_ to produce a VNode. When using match statements, we must render every arm as to avoid the `no two closures are identical` rule that Rust imposes:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// this will not compile!
|
||||
match case {
|
||||
true => rsx!(div {}),
|
||||
|
@ -105,7 +105,7 @@ match case {
|
|||
|
||||
Again, because anything that implements `IntoIterator<VNode>` is valid, we can use lists directly in our `rsx!`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let items = vec!["a", "b", "c"];
|
||||
|
||||
cx.render(rsx!{
|
||||
|
@ -117,7 +117,7 @@ cx.render(rsx!{
|
|||
|
||||
Sometimes, it makes sense to render VNodes into a list:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let mut items = vec![];
|
||||
|
||||
for _ in 0..5 {
|
||||
|
@ -135,7 +135,7 @@ However, with lists, Dioxus does not exactly know how to determine which element
|
|||
|
||||
In these cases, it is vitally important to specify a "key" alongside the element. Keys should be persistent between renders.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn render_list(cx: Scope, items: HashMap<String, Todo>) -> DomTree {
|
||||
render!(ul {
|
||||
{items.iter().map(|key, item| {
|
||||
|
@ -156,7 +156,7 @@ There have been many guides made for keys in React, so we recommend reading up t
|
|||
|
||||
### Complete Reference
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let text = "example";
|
||||
|
||||
cx.render(rsx!{
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
A macro RSX facilita muito a montagem de interfaces de usuário complexas com uma sintaxe Rust muito natural:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!(
|
||||
div {
|
||||
button {
|
||||
|
@ -30,7 +30,7 @@ Nesta seção, abordaremos a macro `rsx!` em profundidade. Se você preferir apr
|
|||
|
||||
Os atributos devem vir antes dos elementos filhos
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
div {
|
||||
hidden: "false",
|
||||
"some text"
|
||||
|
@ -57,7 +57,7 @@ A função `render` fornece um alocador **extremamente eficiente** para `VNodes`
|
|||
|
||||
Às vezes, escrever `cx.render` é um aborrecimento. O `rsx!` macro aceitará qualquer token seguido por uma vírgula como destino para chamar "render" em:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
cx.render(rsx!( div {} ))
|
||||
// becomes
|
||||
render!(div {})
|
||||
|
@ -67,7 +67,7 @@ render!(div {})
|
|||
|
||||
Às vezes, você pode não querer renderizar um elemento dada uma condição. O `rsx!` macro aceitará quaisquer tokens contidos diretamente com chaves, desde que resolvam para um tipo que implemente `IntoIterator<VNode>`. Isso nos permite escrever qualquer expressão Rust que resolva para um `VNode`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!({
|
||||
if enabled {
|
||||
render!(div {"enabled"})
|
||||
|
@ -79,7 +79,7 @@ rsx!({
|
|||
|
||||
Uma maneira conveniente de ocultar/mostrar um elemento é retornar um `Option<VNode>`. Quando combinado com `and_then`, podemos controlar sucintamente o estado de exibição dado alguns booleanos:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
rsx!({
|
||||
a.and_then(rsx!(div {"enabled"}))
|
||||
})
|
||||
|
@ -87,7 +87,7 @@ rsx!({
|
|||
|
||||
É importante notar que a expressão `rsx!()` é tipicamente tardia - esta expressão deve ser _renderizada_ para produzir um `VNode`. Ao usar declarações de `match`, devemos renderizar todos os braços para evitar a regra 'não há dois fechamentos idênticos' que o Rust impõe:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// this will not compile!
|
||||
match case {
|
||||
true => rsx!(div {}),
|
||||
|
@ -105,7 +105,7 @@ match case {
|
|||
|
||||
Novamente, porque qualquer coisa que implemente `IntoIterator<VNode>` é válida, podemos usar listas diretamente em nosso `rsx!`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let items = vec!["a", "b", "c"];
|
||||
|
||||
cx.render(rsx!{
|
||||
|
@ -117,7 +117,7 @@ cx.render(rsx!{
|
|||
|
||||
Às vezes, faz sentido renderizar `VNodes` em uma lista:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let mut items = vec![];
|
||||
|
||||
for _ in 0..5 {
|
||||
|
@ -135,7 +135,7 @@ No entanto, com listas, Dioxus não sabe exatamente como determinar quais elemen
|
|||
|
||||
Nesses casos, é de vital importância especificar uma "chave" ao lado do elemento. As chaves devem ser persistentes entre as renderizações.
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
fn render_list(cx: Scope, items: HashMap<String, Todo>) -> DomTree {
|
||||
render!(ul {
|
||||
{items.iter().map(|key, item| {
|
||||
|
@ -156,7 +156,7 @@ Existem muitos guias feitos para chaves no React, então recomendamos a leitura
|
|||
|
||||
### Referência Completa
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
let text = "example";
|
||||
|
||||
cx.render(rsx!{
|
||||
|
|
|
@ -21,7 +21,7 @@ $ cargo add dioxus --features desktop
|
|||
|
||||
Edit your `main.rs`:
|
||||
|
||||
```rust
|
||||
```rust, no_run
|
||||
// main.rs
|
||||
use dioxus::prelude::*;
|
||||
|
||||
|
|
Loading…
Reference in a new issue