# tiny-nexus

**Repository Path**: Jumping99/tiny-nexus

## Basic Information

- **Project Name**: tiny-nexus
- **Description**: 一个轻量级的通用 UI 页面导航管理框架。
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tiny-nexus

## 介绍

一个轻量级的通用 UI 页面导航管理框架，提供页面注册、导航拦截、页面栈管理等核心功能。
此框架是一个完全独立且通用的中间件，将页面的操作抽象出来，方便工程的搭建和后期维护扩展。

## 功能特性

- **页面注册机制**：支持运行时动态注册页面创建器
- **导航拦截器**：支持在导航过程中进行拦截和处理
- **页面栈管理**：提供页面的进栈、出栈、替换等操作
- **页面生命周期**：完整的页面生命周期回调（create、enter、exit、destroy）
- **结果返回机制**：支持页面间的结果(参数)传递

## 快速开始

### 1. 继承 `nexus::i_page` 实现具体的页面类

`nexus::i_page`是一个抽象类，在应用层定义每一个页面时，需要继承它并实现相应的虚函数，
以便接入框架管理。

```cpp
class my_page : public nexus::i_page
{
public:
    void on_create() override;    // 页面创建时调用
    void on_destroy() override;   // 页面销毁时调用
    void on_enter(any_t arg) override;  // 进入页面时调用
    void on_exit(nexus::exit_reason reason) override;      // 退出页面时调用
    void on_result(result_id id, any_t arg) override;  // 接收其他页面返回结果时调用
};
```

### 2. 继承 `nexus::nav::interceptor` 实现具体的拦截器类(可选)

`nexus::nav::interceptor`也是一个抽象类，在应用层定义一个拦截器时，需要继承它并实现相应
的虚函数，以便接入框架管理。拦截器用于在发生页面跳转(**导航**，**返回**，**替换**)时进行
判断拦截，用于解耦功能和页面。  
如：

1. 某个页面返回时设置了数据，拦截不让其返回，进行弹窗提示用户是否保存。
2. 某个页面进入时需要输入密码，输入后一段时间不需要再输入，在拦截器中添加判断是否需要进行密码输入。

```cpp
class my_interceptor : public nexus::nav::interceptor
{
public:
    nexus::page_id get_target_page_id() override { 
        return target_page_id;  // 返回要拦截的页面ID
    }
    
    nexus::intercept_result on_intercept(nexus::nav::request &req) override {
        // 根据条件决定是否拦截
        if (should_intercept(req)) {
            return nexus::intercept_result::intercepted;
        }
        return nexus::intercept_result::no_intercepted;
    }
};
```

### 3. 注册页面创建器(函数)

此处使用了工厂模式设计，在导航系统启动时，会实例化所有具体的页面对象进行管理。
因此需要在启动导航系统前，注册所有会用到的具体页面实例化方法。

```cpp
// 注册页面创建器
nexus::register_page_creator(1, "page1", []() -> nexus::i_page* { 
    return new page1(); 
});
nexus::register_page_creator(2, "page2", []() -> nexus::i_page* { 
    return new page2(); 
});
```

### 4. 注册拦截器（可选）

拦截器对象的生命周期必须是全局有效的，导航系统内部仅保存其地址。

```cpp
static page2_interceptor interceptor_page2;
nexus::nav::add_interceptor(&interceptor_page2);
```

### 5. 初始化并启动

```cpp
// 启动导航系统
nexus::start();
```

### 6. 进行页面导航操作

1. 创建一个请求`request`并设定**目标页面ID**、**目标页面参数**和**期望目标页面返回的结果ID**，
**目标页面参数**会在目标页面触发`on_enter()`时传入，没有参数或不需要目标页面返回结果只需要设置目标页面ID即可。
2. 调用`navigate()`或`replace()`函数进行导航、替换操作。

```cpp
// 导航到页面
auto req = nexus::nav::make_request(Page1);     // 不带参数的导航
auto req = nexus::nav::make_request(Page1, std::string_view("hello world"));     // 带参数的导航
auto req = nexus::nav::make_request(Page1, std::string_view("hello world"), 123);     // 带参数且期望结果(id 123)的导航

nexus::nav::navigate(req);
```

### 7. 页面返回

1. 无参数返回，直接调用`back()`函数。
2. 带参数返回，在调用`back()`时传入和上个页面约定好的**结果ID**和参数即可，当前页面返回后，
等待结果的页面如果检测到**返回的结果ID**和**期望的结果ID**相等时，会调用`on_result()`函数接收返回值。
3. 一键返回根页面，调用`back_all()`函数即可。该函数不进行任何拦截器检查。

```cpp

// Page2
void page2::on_result(nexus::result_id id, any_t arg)
{
    if (id == 123 && arg.has_value())
        // 使用arg参数设置时间
}

auto req = nexus::nav::make_request(Page3, current_time, 123);     // 模拟时间设置页面，传入当前时间,当前是page2页面
nexus::nav::navigate(req);  // 导航到page3

// Page3
nexus::nav::back(123, setting_time);    // page3返回,并附带设置的时间参数

```

### 8. 关闭导航系统

关闭导航系统后会，所有页面的析构函数会被调用，确保所有页面的资源被释放。  
在嵌入式中，通常不会执行到这一步。

```cpp
// 销毁导航系统
nexus::stop();
```

## API 文档

### 核心函数

| 函数 | 说明 |
|------|------|
| `nexus::start()` | 初始化导航系统 |
| `nexus::stop()` | 销毁导航系统 |
| `nexus::register_page_creator()` | 注册页面创建器 |

### 导航 API

| 函数 | 说明 |
|------|------|
| `nexus::nav::make_request()` | 创建导航请求 |
| `nexus::nav::navigate()` | 导航到目标页面 |
| `nexus::nav::back()` | 返回上一页 |
| `nexus::nav::replace()` | 替换当前页面 |
| `nexus::nav::add_interceptor()` | 添加导航拦截器 |
| `nexus::nav::back_all()` | 一键返回根页面 |

## 项目结构

tiny-nexus/  
├── src/ # 源代码目录  
│ ├── core/ # 核心模块  
│ │ ├── nx_ipage.h # 页面接口定义  
│ │ ├── nx_types.h # 类型定义  
│ │ └── nx_page_registry.cpp/h # 页面注册管理  
│ ├── nav/ # 导航模块  
│ │ ├── nx_nav.cpp/h # 导航核心实现  
│ │ └── nx_page_stack.cpp/h # 页面栈管理  
│ ├── utils/ # 工具模块  
│ │ └── any.h # 任意类型封装  
│ └── nexus.h # 框架入口头文件  
├── tests/ # 测试代码  
│ ├── page1.cpp/h # 测试页面1  
│ ├── page2.cpp/h # 测试页面2  
│ ├── page3.cpp/h # 测试页面3  
│ ├── page_id.h # 页面ID定义  
│ └── test.cpp # 测试主入口  


## 编译说明

使用 CMake 进行构建：

```bash
mkdir build 
cd build 
cmake .. 
make
```

## 扩展

1. 与本框架对接的业务代码使用抽象接口定义页面行为进行软件分层，避免直接依赖具体业务代码。
2. 结合*发布订阅*框架，实现一对多的通知机制，如wifi连接状态变化通知所有关心此事件的页面。

## 许可证

MIT License