Skip to content

Commit 8c88abd

Browse files
syf20020816syf20020816
committed
router config
1 parent 7158acd commit 8c88abd

File tree

9 files changed

+530
-8
lines changed

9 files changed

+530
-8
lines changed

‎docs/v0.1.0/en/doc/config/_meta.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
"env",
44
"ract_toml",
55
"gen_ui_toml",
6+
"router_toml",
67
"types"
78
]

‎docs/v0.1.0/en/doc/config/gen_ui_toml.mdx

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,9 @@ makepad-widgets = { path = "/Users/shengyifei/projects/makepad/makepad/widgets"
6262
|`entry`|`Option<String>`|Entry file name|
6363
|`root`|`RootConf`|Entry configuration, including UI entry address and window properties|
6464
|`dependencies`|`Option<Vec<RustDependence>>`|Rust dependencies|
65+
|`router`|`Option<PathBuf>`|Path of the router.toml|
6566
|`wasm`|`Option<WasmConf>`|wasm related configuration (compilation synchronization mode, not supported yet)|
6667

67-
#### `entry`
68-
69-
- `Option<String>`
70-
7168
#### `[makepad.root]`
7269

7370
|key|value type|description|

‎docs/v0.1.0/en/doc/config/router_toml.mdx

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Router configuration
2+
3+
Starting from GenUI v0.1.2, the framework has introduced the routing configuration function. However, it should be noted that GenUI's routing mechanism is different from the "front-end routing" in traditional Web front-ends. There is no real URL routing in GUI applications. GenUI's routing is essentially a page switching mechanism for state management and navigation between multiple UI interfaces.
4+
5+
GenUI's routing mechanism is based on a dedicated component and is enabled through the project configuration file. You can declare the routing structure in `router.toml`, enable the configuration in `gen_ui.toml`, and then introduce it to a specific page through the `route!` macro.
6+
7+
For more examples, see:
8+
9+
- [Route component example](https://github.com/Privoce/made_with_GenUI/tree/main/tests/router)
10+
- [Root route example](https://github.com/Privoce/made_with_GenUI/tree/main/tests/router_tabbar)
11+
12+
## Configuration and usage process
13+
14+
### Step 1: Configure `router.toml`
15+
16+
You can define a complete route configuration through `router.toml`, including route mode, default activation page, whether to enable Tabbar, page path, etc.:
17+
18+
```toml title="router.toml"
19+
name = "MyRouter"
20+
id = "app_router"
21+
mode = "History" # Optional value: History / Switch
22+
active = "login" # Default page ID
23+
24+
[tabbar]
25+
theme = "Dark"
26+
active = false
27+
28+
[tabbar.bars]
29+
login = { icon = "crate://self/resources/login.svg", text = "Login Page" }
30+
register = { icon = "crate://self/resources/register.svg", text = "Register Page" }
31+
32+
[bar_pages]
33+
login = { path = "crate::views::login::*", component = "Login" }
34+
register = "crate::views::register::Register"
35+
36+
[nav_pages]
37+
nav_about = { path = "crate::views::about::*", component = "About" }
38+
```
39+
40+
### Step 2: Enable routing configuration in `gen_ui.toml`
41+
42+
```toml title="gen_ui.toml"
43+
44+
[compiler]
45+
#...
46+
47+
[makepad]
48+
router = "./router.toml"
49+
50+
[plugins]
51+
#...
52+
```
53+
54+
### Step 3: Import routing in components
55+
56+
In the `.gen` file where routing is needed, use the `route!` macro to import the declared routing component:
57+
58+
```rust
59+
<script>
60+
route!(app_router);
61+
</script>
62+
```
63+
64+
> [!WARNING]
65+
> If the `route!` macro is used, the `.gen` file cannot contain other elements and must be used only for routing.
66+
67+
### Step 4: Use the Router component in other components
68+
69+
You can embed the Router component in other pages just like using a normal component:
70+
71+
```html
72+
<template>
73+
<component name="Home">
74+
<view>
75+
<button @clicked="to_page('login')"></button>
76+
</view>
77+
<MyRouter id="my_router"></MyRouter>
78+
</component>
79+
</template>
80+
```
81+
82+
## Use the Router as the root component
83+
84+
If you want to use the Router component as the root component of your application, use the `route!` macro in the `root.gen` file.
85+
86+
> At this time, `name` in `router.toml` must be set to `"UiRoot"` to ensure that the compiler recognizes it as the main entry.
87+
88+
## Page jump operation
89+
90+
### Control jump in parent component
91+
92+
You can get the router instance through the `c_ref!` macro and call the method it provides:
93+
94+
```rust
95+
fn to_page(&mut self, page: &str) {
96+
let mut my_router = c_ref!(my_router);
97+
98+
match page {
99+
"login" => my_router.nav_to(id!(login)),
100+
"register" => my_router.nav_to(id!(register)),
101+
"about" => my_router.nav_to(id!(nav_about)),
102+
"back" => my_router.nav_back(),
103+
_ => {}
104+
}
105+
}
106+
```
107+
108+
### Jump in child component
109+
110+
For child components, GenUI provides convenient macros `nav_to!` and `nav_back!` to handle jumps:
111+
112+
```rust
113+
pub fn to_register(&mut self) {
114+
nav_to!(register);
115+
}
116+
117+
pub fn back(&mut self) {
118+
nav_back!();
119+
}
120+
```
121+
122+
## Routing configuration structure description
123+
124+
### Data structure definition in Rust:
125+
126+
```rust
127+
pub struct RouterBuilder {
128+
pub name: String,
129+
pub id: String,
130+
pub mode: NavMode,
131+
pub active: Option<String>,
132+
pub tabbar: Option<TabbarBuilder>,
133+
pub bar_pages: Vec<(String, Page)>,
134+
pub nav_pages: HashMap<String, Page>,
135+
}
136+
137+
pub struct TabbarBuilder {
138+
pub theme: Option<Themes>,
139+
pub active: bool,
140+
pub bars: HashMap<String, TabbarItem>,
141+
}
142+
143+
pub struct TabbarItem {
144+
pub icon: Option<LiveDependency>,
145+
pub text: Option<String>,
146+
}
147+
148+
pub enum Page {
149+
Path(Import),
150+
Component { path: Import, component: String },
151+
}
152+
153+
pub enum NavMode {
154+
History,
155+
Switch,
156+
}
157+
```
158+
159+
### Field description table:
160+
161+
| Key | Type | Description |
162+
| ----------------- | ------------------------ | --------------------------------------------------------------------------- |
163+
| `name` | `String` | Routing component name |
164+
| `id` | `String` | Routing component unique identifier |
165+
| `mode` | `NavMode` | Routing mode, supports `History` (history stack) and `Switch` (switch mode) |
166+
| `active` | `Option<String>` | Default activated page ID |
167+
| `tabbar` | `Option<TabbarBuilder>` | Tabbar configuration items (optional) |
168+
| `bar_pages` | `Vec<(String, Page)>` | Primary page configuration, supports component specification |
169+
| `nav_pages` | `HashMap<String, Page>` | Secondary page configuration, not displayed in Tabbar |
170+
| `TabbarItem.icon` | `Option<LiveDependency>` | Icon resource path |
171+
| `TabbarItem.text` | `Option<String>` | Tabbar display text |

‎docs/v0.1.0/en/doc/config/types.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ pub struct CompilerConf {
6666
pub logo: bool,
6767
pub log_level: LogLevel,
6868
pub excludes: Excludes,
69+
pub router: Option<PathBuf>,
6970
}
7071
```
7172

‎docs/v0.1.0/zh/doc/config/_meta.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
"env",
44
"ract_toml",
55
"gen_ui_toml",
6+
"router_toml",
67
"types"
78
]

‎docs/v0.1.0/zh/doc/config/gen_ui_toml.mdx

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,9 @@ makepad-widgets = { path = "/Users/shengyifei/projects/makepad/makepad/widgets"
6262
|`entry`|`Option<String>`|入口文件名|
6363
|`root`|`RootConf`|入口配置，包含UI入口地址和窗口属性|
6464
|`dependencies`|`Option<Vec<RustDependence>>`|Rust依赖项|
65+
|`router`|`Option<PathBuf>`|路由相关配置的路径|
6566
|`wasm`|`Option<WasmConf>`|wasm相关配置(编译同步模式, 暂不支持)|
6667

67-
#### `entry`
68-
69-
- `Option<String>`
70-
7168
#### `[makepad.root]`
7269

7370
|key|value type|description|

‎docs/v0.1.0/zh/doc/config/router_toml.mdx

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Router 配置
2+
3+
从 GenUI v0.1.2 开始，框架引入了路由配置功能。但需要注意的是，GenUI 的路由机制与传统 Web 前端中的“前端路由”是不同的概念。在 GUI 应用中并没有真正的 URL 路由，GenUI 的路由本质上是一种页面切换机制，用于在多个 UI 界面间进行状态管理和导航。
4+
5+
GenUI 的路由机制基于一个专用组件，并通过项目配置文件进行启用。你可以通过在 `router.toml` 中声明路由结构，并在 `gen_ui.toml` 中启用配置，再通过 `route!` 宏将其引入具体页面。
6+
7+
示例详见：
8+
9+
- [路由组件示例](https://github.com/Privoce/made_with_GenUI/tree/main/tests/router)
10+
- [根路由示例](https://github.com/Privoce/made_with_GenUI/tree/main/tests/router_tabbar)
11+
12+
## 配置与使用流程
13+
14+
### Step 1: 配置 `router.toml`
15+
16+
你可以通过 `router.toml` 定义一个完整的路由配置，包括路由模式、默认激活页面、是否启用 Tabbar、页面路径等：
17+
18+
```toml title="router.toml"
19+
name = "MyRouter"
20+
id = "app_router"
21+
mode = "History" # 可选值: History / Switch
22+
active = "login" # 默认页面 ID
23+
24+
[tabbar]
25+
theme = "Dark"
26+
active = false
27+
28+
[tabbar.bars]
29+
login = { icon = "crate://self/resources/login.svg", text = "Login Page" }
30+
register = { icon = "crate://self/resources/register.svg", text = "Register Page" }
31+
32+
[bar_pages]
33+
login = { path = "crate::views::login::*", component = "Login" }
34+
register = "crate::views::register::Register"
35+
36+
[nav_pages]
37+
nav_about = { path = "crate::views::about::*", component = "About" }
38+
```
39+
40+
### Step 2: 在 `gen_ui.toml` 中启用路由配置
41+
42+
```toml title="gen_ui.toml"
43+
[compiler]
44+
#...
45+
46+
[makepad]
47+
router = "./router.toml"
48+
49+
[plugins]
50+
#...
51+
```
52+
53+
### Step 3: 在组件中引入路由
54+
55+
在需要使用路由的 `.gen` 文件中，使用 `route!` 宏引入已声明的路由组件：
56+
57+
```rust
58+
<script>
59+
route!(app_router);
60+
</script>
61+
```
62+
63+
> [!WARNING]
64+
> 如果使用了 `route!` 宏，则该 `.gen` 文件不能包含其他元素，必须仅用于路由承载。
65+
66+
### Step 4: 在其他组件中使用路由组件
67+
68+
你可以像使用普通组件一样，将路由组件嵌入到其他页面中：
69+
70+
```html
71+
<template>
72+
<component name="Home">
73+
<view>
74+
<button @clicked="to_page('login')"></button>
75+
</view>
76+
<MyRouter id="my_router"></MyRouter>
77+
</component>
78+
</template>
79+
```
80+
81+
## 使用路由作为根组件
82+
83+
如果希望以路由组件作为应用根组件，请在 `root.gen` 文件中使用 `route!` 宏。
84+
85+
> 此时 `router.toml` 中的 `name` 必须设置为 `"UiRoot"`，以保证编译器识别为主入口。
86+
87+
88+
## 页面跳转操作
89+
90+
### 在父组件中控制跳转
91+
92+
你可以通过 `c_ref!` 宏获取路由实例，并调用其提供的方法：
93+
94+
```rust
95+
fn to_page(&mut self, page: &str) {
96+
let mut my_router = c_ref!(my_router);
97+
98+
match page {
99+
"login" => my_router.nav_to(id!(login)),
100+
"register" => my_router.nav_to(id!(register)),
101+
"about" => my_router.nav_to(id!(nav_about)),
102+
"back" => my_router.nav_back(),
103+
_ => {}
104+
}
105+
}
106+
```
107+
108+
### 在子组件中跳转
109+
110+
对于子组件，GenUI 提供了便捷的宏 `nav_to!` 和 `nav_back!` 用于处理跳转：
111+
112+
```rust
113+
pub fn to_register(&mut self) {
114+
nav_to!(register);
115+
}
116+
117+
pub fn back(&mut self) {
118+
nav_back!();
119+
}
120+
```
121+
122+
123+
## 路由配置结构说明
124+
125+
### Rust 中的数据结构定义：
126+
127+
```rust
128+
pub struct RouterBuilder {
129+
pub name: String,
130+
pub id: String,
131+
pub mode: NavMode,
132+
pub active: Option<String>,
133+
pub tabbar: Option<TabbarBuilder>,
134+
pub bar_pages: Vec<(String, Page)>,
135+
pub nav_pages: HashMap<String, Page>,
136+
}
137+
138+
pub struct TabbarBuilder {
139+
pub theme: Option<Themes>,
140+
pub active: bool,
141+
pub bars: HashMap<String, TabbarItem>,
142+
}
143+
144+
pub struct TabbarItem {
145+
pub icon: Option<LiveDependency>,
146+
pub text: Option<String>,
147+
}
148+
149+
pub enum Page {
150+
Path(Import),
151+
Component { path: Import, component: String },
152+
}
153+
154+
pub enum NavMode {
155+
History,
156+
Switch,
157+
}
158+
```
159+
160+
### 字段说明表：
161+
162+
| Key | 类型 | 描述 |
163+
| ----------------- | ------------------------ | --------------------------------------------------------- |
164+
| `name` | `String` | 路由组件名称 |
165+
| `id` | `String` | 路由组件唯一标识 |
166+
| `mode` | `NavMode` | 路由模式，支持 `History`（历史栈）与 `Switch`（切换模式） |
167+
| `active` | `Option<String>` | 默认激活的页面 ID |
168+
| `tabbar` | `Option<TabbarBuilder>` | Tabbar 配置项（可选） |
169+
| `bar_pages` | `Vec<(String, Page)>` | 主要页面配置，支持组件指定 |
170+
| `nav_pages` | `HashMap<String, Page>` | 次要页面配置，不显示在 Tabbar 中 |
171+
| `TabbarItem.icon` | `Option<LiveDependency>` | 图标资源路径 |
172+
| `TabbarItem.text` | `Option<String>` | Tabbar 显示文本 |

0 commit comments

Comments
 (0)