#Component API

This document introduces the core API of the component system, including component import, property declaration, event management, etc., to help developers build and manage custom components more efficiently.

#import!

The import! macro is used to import custom components so that they can be used in the current scope.

#Usage

1import! {
2    crate::moudle::to::component;
3}

#Example

Import Rust components into your structure using import!:

1<template>
2    <component name="MyView2">
3        <Header></Header>
4        <MyView1></MyView1>
5    </component>
6</template>
7
8<script>
9import! {
10    crate::views::my_view1::*;
11    crate::components::header::*;
12}
13</script>

##[prop]

The #[prop] macro is used to define the properties (Props) of a component. For custom components, we need to use the #[prop] macro to declare properties so that they can be assigned when the component is instantiated.

#Limitations

Not all types can be used as prop. Only types that implement the Default trait can be used for property declaration.

#Example

1<script>
2#[prop]
3pub struct MyView {
4    name: String,
5}
6</script>

#get|set method

All #[prop] marked properties will automatically generate corresponding get and set methods. It is recommended to use get|set methods to access and modify property values, otherwise two-way binding may fail.

For example, the above MyView structure will automatically generate the following methods:

• fn get_name(&self) -> String;
• fn set_name(&mut self, value: String) -> ();

#default_prop!

The default_prop! macro is used to initialize the property values ​​of a component instance.

#Example

1<script>
2#[prop]
3pub struct MyView {
4    name: String,
5}
6
7let mut prop = default_prop! {
8    MyView {
9        name: "John".to_string(),
10    }
11};
12</script>

In subsequent code, you can use prop to access get|set methods, for example:

1let name = prop.get_name();
2prop.set_name("Alice".to_string());

1println!("name is: {}", prop.get_name());

##[event]

Custom components do not trigger any events by default. To use the event system, you need to use the #[event] macro to declare events.

#Addention

• Events must be marked with #[event].
• Event types must derive from the Debug and Clone traits.

#Example

1#[event]
2#[derive(Debug, Clone)]
3pub enum MyViewEvent {
4    Clicked,
5    Changed(String),
6}

In the above example, we define the MyViewEvent event type, where:

1. Clicked: a click event without parameters.
2. Changed(String): a change event with a String parameter.

#c_ref!

The c_ref! macro is used to obtain a component reference based on the component id, making it easier to directly manipulate the reference of a component instance.

#Example

1<template>
2    <component name="MyView">
3        <label id="my_label" text="'Hello'"></label>
4        <button id="my_btn" @clicked="get_label_text()">
5            <label as_prop="slot" text="'get my label text'"></label>
6        </button>
7    </component>
8</template>
9
10<script>
11fn get_label_text() {
12    let label = c_ref!(my_label);
13    let label_text = label.get_text();
14    println!("label text is: {}", label_text);
15}
16</script>

#active!

The active! macro is used to trigger an event defined inside a component and pass it to an external component for callback processing.

#Example

#MyView Component

1#[event]
2#[derive(Debug, Clone)]
3pub enum MyViewEvent {
4    Clicked,
5    Changed(String),
6}
7
8fn click_view() {
9    let _ = active!(MyViewEvent::Clicked);
10}
11
12fn change_view() {
13    active!(MyViewEvent::Changed, "changed!".to_string());
14}

#FatherView Component

The FatherView component listens to the events of MyView:

1<template>
2    <component name="FatherView">
3        <MyView 
4            @clicked="my_view_clicked()" 
5            @changed="my_view_changed()">
6        </MyView>
7    </component>
8</template>
9
10<script>
11fn my_view_clicked() {
12    dbg!("my_view_clicked!");
13}
14
15fn my_view_changed(param: impl EventParam) {
16    dbg!(param);
17}
18</script>