538 lines
15 KiB
Markdown
538 lines
15 KiB
Markdown
# Slint 代理管理应用设计文档
|
||
|
||
**创建日期：** 2026-01-30
|
||
**状态：** 设计完成，待实施
|
||
|
||
## 项目概述
|
||
|
||
将 web 目录下的 Tauri + React 实现的代理管理工具，使用 Slint UI 组件库完整重新实现。应用包含 6 个主要页面，采用模块化架构，通过 Callback 与 Rust 后端交互。
|
||
|
||
## 整体架构
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
ui/
|
||
├── app.slint # 主应用入口（替代 demo.slint）
|
||
├── types.slint # 数据结构定义
|
||
├── components/ # 通用组件（已有 + 新增）
|
||
│ ├── button.slint # ✓ 已有
|
||
│ ├── badge.slint # ✓ 已有
|
||
│ ├── card.slint # ✓ 已有
|
||
│ ├── input.slint # ✓ 已有
|
||
│ ├── item.slint # ✓ 已有
|
||
│ ├── dialog.slint # ✓ 已有
|
||
│ ├── toast.slint # ✓ 已有
|
||
│ ├── sidebar.slint # ✓ 已有
|
||
│ ├── tabs.slint # ✓ 已有
|
||
│ ├── accordion.slint # ✓ 已有
|
||
│ ├── switch.slint # ✓ 已有
|
||
│ ├── select.slint # ✓ 已有
|
||
│ ├── label.slint # ✓ 已有
|
||
│ ├── progress.slint # ✓ 已有
|
||
│ ├── separator.slint # ✓ 已有
|
||
│ ├── tooltip.slint # ✓ 已有
|
||
│ └── empty.slint # ☐ 待实现
|
||
├── layouts/ # 布局组件（新增）
|
||
│ ├── page-layout.slint # ☐ 待实现
|
||
│ └── container.slint # ☐ 待实现
|
||
├── pages/ # 页面模块（新增）
|
||
│ ├── home.slint # ☐ 待实现
|
||
│ ├── proxies.slint # ☐ 待实现
|
||
│ ├── profiles.slint # ☐ 待实现
|
||
│ ├── connections.slint # ☐ 待实现
|
||
│ ├── logs.slint # ☐ 待实现
|
||
│ └── settings.slint # ☐ 待实现
|
||
└── theme/ # 主题系统（已有）
|
||
├── theme.slint # ✓ 已有
|
||
├── colors.slint # ✓ 已有
|
||
├── spacing.slint # ✓ 已有
|
||
└── typography.slint # ✓ 已有
|
||
```
|
||
|
||
### 核心设计原则
|
||
|
||
1. **页面独立性** - 每个页面是独立的 component，通过 `if current-view == "xxx"` 条件渲染
|
||
2. **Callback 驱动** - 所有数据通过 callback 从 Rust 获取，页面只负责展示
|
||
3. **状态提升** - 应用状态（当前页面、数据）在主应用层管理，向下传递
|
||
4. **组件复用** - 最大化复用现有 components，缺失的通用组件补充到 components/
|
||
5. **固定布局** - 桌面应用，不需要响应式布局（800x600 最小尺寸）
|
||
6. **Emoji 图标** - 使用 emoji 作为图标方案（简单且项目已在使用）
|
||
|
||
## 数据结构设计
|
||
|
||
### 核心数据类型（ui/types.slint）
|
||
|
||
```slint
|
||
// 配置文件信息
|
||
export struct Profile {
|
||
id: string,
|
||
name: string,
|
||
url: string,
|
||
type: string, // "remote" | "local"
|
||
updated-at: string,
|
||
usage: string, // "1.26GB / 100GB"
|
||
expire-at: string,
|
||
selected: bool,
|
||
}
|
||
|
||
// 代理节点
|
||
export struct ProxyNode {
|
||
name: string,
|
||
type: string, // "Vmess", "Shadowsocks", etc.
|
||
delay: int, // 延迟 ms，-1 表示未测试
|
||
udp: bool,
|
||
}
|
||
|
||
// 代理组
|
||
export struct ProxyGroup {
|
||
name: string,
|
||
type: string, // "Selector", "URLTest", etc.
|
||
now: string, // 当前选中的节点
|
||
nodes: [ProxyNode],
|
||
}
|
||
|
||
// 连接信息
|
||
export struct Connection {
|
||
id: string,
|
||
host: string,
|
||
process: string,
|
||
rule: string,
|
||
chains: string,
|
||
upload: string,
|
||
download: string,
|
||
tring,
|
||
}
|
||
|
||
// 日志条目
|
||
export struct LogEntry {
|
||
time: string,
|
||
level: string, // "debug", "info", "warn", "error"
|
||
message: string,
|
||
}
|
||
|
||
// 设置项
|
||
export struct SettingItem {
|
||
key: string,
|
||
label: string,
|
||
value: string,
|
||
type: string, // "switch", "select", "button", "text"
|
||
enabled: bool,
|
||
}
|
||
```
|
||
|
||
## 主应用架构
|
||
|
||
### 应用状态与 Callback（ui/app.slint）
|
||
|
||
```slint
|
||
export component App inherits Window {
|
||
// ===== 应用状态 =====
|
||
in-out property <string> current-view: "home";
|
||
in-out property <bool> sidebar-collapsed: false;
|
||
|
||
数据状态 =====
|
||
in-out property <Profile> current-profile;
|
||
in-out property <[Profile]> profiles;
|
||
in-out property <[ProxyGroup]> proxy-groups;
|
||
in-out property <[Connection]> connections;
|
||
in-out property <[LogEntry]> mihomo-logs;
|
||
in-out property <[LogEntry]> app-logs;
|
||
in-out property <[SettingItem]> app-settings;
|
||
in-out property <[SettingItem]> clash-settings;
|
||
|
||
// ===== Callbacks（Rust 实现） =====
|
||
// 数据加载
|
||
callback load-profiles();
|
||
callback load-proxy-groups(string /* mode: rule/global/direct */);
|
||
callback load-connections();
|
||
callback load-logs(string /* type: mihomo/app */);
|
||
callback load-settings();
|
||
|
||
// 用户操作
|
||
callback select-profile(string /* profile-id */);
|
||
callback select-proxy(string /* group-name */, string /* node-name */);
|
||
callback test-proxy-delay(string /* node-name */);
|
||
callback toggle-setting(string /* key */, bool /* value */);
|
||
callback update-profile(string /* profile-id */);
|
||
callback delete-profile(string /* profile-id */);
|
||
callback add-profile(string /* url */);
|
||
|
||
// Toast 通知
|
||
callback show-toast(string /* message */, string /* type */);
|
||
}
|
||
```
|
||
|
||
### Callback 调用流程
|
||
|
||
1. 页面初始化时调用 `load-xxx()` 获取数据
|
||
2. 用户交互触发操作 callback（如 `select-profile`）
|
||
3. Rust 处理后更新对应的 property
|
||
4. Slint 自动重新渲染相关 UI
|
||
|
||
## 布局组件设计
|
||
|
||
### PageLayout（ui/layouts/page-layout.slint）
|
||
|
||
页面布局：包含固定头部 + 可滚动内容区
|
||
|
||
```slint
|
||
export component PageLayout inherits Rectangle {
|
||
in property <string> title;
|
||
in property <bool> show-actions: false;
|
||
|
||
@children // 头部右侧操作区（可选）
|
||
|
||
background: Theme.colors.background;
|
||
|
||
VerticalLayout {
|
||
// 固定头部（48px）
|
||
Rectangle {
|
||
height: 48px;
|
||
HorizontalLayout {
|
||
padding: SpacingSystem.spacing.s4;
|
||
alignment: space-between;
|
||
|
||
Text { text: root.title; }
|
||
// 右侧操作区
|
||
}
|
||
}
|
||
|
||
// 可滚动内容
|
||
Flickable {
|
||
VerticalLayout {
|
||
padding: SpacingSystem.spacing.s4;
|
||
spacing: SpacingSystem.spacing.s4;
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Container（ui/layouts/container.slint）
|
||
|
||
内容容器：带边框和圆角的卡片式容器
|
||
|
||
```slint
|
||
export component Container inherits Rectangle {
|
||
@children
|
||
|
||
background: Theme.colors.card;
|
||
border-radius: SpacingSystem.radius.md;
|
||
border-width: 1px;
|
||
border-color: Theme.colors.border;
|
||
|
||
VerticalLayout {
|
||
padding: SpacingSystem.spacing.s4;
|
||
spacing: SpacingSystem.spacing.s3;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 页面功能说明
|
||
|
||
### 1. Home 页面（ui/pages/home.slint）
|
||
|
||
**功能：** 显示当前配置文件信息、位置信息、快捷设置
|
||
|
||
**布局：**
|
||
- ProfileCard：当前配置文件信息（名称、类型、流量使用、到期时间）
|
||
- LocationCard：当前连接位置信息
|
||
- SettingCard：快捷设置开关
|
||
|
||
**数据依赖：**
|
||
- `current-profile: Profile`
|
||
- 部分 `app-settings` 和 `clash-settings`
|
||
|
||
### 2. Proxies 页面（ui/pages/proxies.slint）
|
||
|
||
**功能：** 代理节点管理，支持 Rule/Global/Direct 三种模式
|
||
|
||
**布局：**
|
||
- Tabs：切换模式（Rule/Global/Direct）
|
||
- 每个模式下：
|
||
- 多个 Accordion（代理组）
|
||
- 每个 Accordion 内：网格ode 卡片
|
||
|
||
**数据依赖：**
|
||
- `proxy-groups: [ProxyGroup]`
|
||
|
||
**交互：**
|
||
- 切换 Tab 时调用 `load-proxy-groups(mode)`
|
||
- 点击节点时调用 `select-proxy(group, node)`
|
||
- 测试延迟调用 `test-proxy-delay(node)`
|
||
|
||
### 3. Profiles 页面（ui/pages/profiles.slint）
|
||
|
||
**功能：** 配置文件管理，网格布局展示所有配置文件
|
||
|
||
**布局：**
|
||
- 头部：标题 + 添加按钮 + 刷新按钮
|
||
- 网格布局：ProfileCard 列表（每行自适应，最小 18rem）
|
||
|
||
**数据依赖：**
|
||
- `profiles: [Profile]`
|
||
|
||
**交互：**
|
||
- 点击配置文件调用 `select-profile(id)`
|
||
- 更新配置文件调用 `update-profile(id)`
|
||
- 删除配置文件调用 `delete-profile(id)`
|
||
- 添加配置文件调用 `add-profile(url)`
|
||
|
||
### 4. Connections 页面（ui/pages/connections.slint）
|
||
|
||
**功能：** 显示当前活动连接列表
|
||
|
||
**布局：**
|
||
- 简单列表，每个连接使用 Item 组件展示
|
||
|
||
**数据依赖：**
|
||
- `connections: [Connection]`
|
||
|
||
**交互：**
|
||
- 定时刷新（每秒调用 `load-connections()`）
|
||
|
||
### 5. Logs 页面（ui/pages/logs.slint）
|
||
|
||
**功能：** 日志查看，支持 Mihomo 日志和 App 日志切换
|
||
|
||
**布局：**
|
||
- Tabs：切换日志类型（Mihomo/App）
|
||
- 每个 Tab：滚动列表展示日志条目
|
||
- 日志条目：时间 + 级别 + 消息（不同级别不同颜色）
|
||
|
||
**数据依赖：**
|
||
- `mihomo-logs: [LogEntry]`
|
||
- `app-logs: [LogEntry]`
|
||
|
||
**交互：**
|
||
- 切换 Tab 时调用 `load-logs(type)`
|
||
- 定时刷新（每秒）
|
||
|
||
### 6. Settings 页面（ui/pages/settings.slint）
|
||
|
||
**功能：** 应用设置和 Clash 设置
|
||
|
||
**布局：**
|
||
- 多个 Container，每个包含一组设置项
|
||
- 设置项使用 Item 组件：图标 + 标题 + Switch/Button
|
||
|
||
**数据依赖：**
|
||
- `app-settings: [SettingItem]`
|
||
- `clash-settings: [SettingItem]`
|
||
|
||
**交互：**
|
||
- 切换开关调用 `tg(key, value)`
|
||
|
||
## 实现计划
|
||
|
||
### Phase 1: 基础设施 ✓
|
||
|
||
**优先级：** 最高
|
||
**预估代码量：** ~150 行
|
||
**完成日期：** 2026-01-30
|
||
|
||
- [x] `ui/types.slint` - 数据结构定义（~50 行）
|
||
- [x] `ui/layouts/container.slint` - 容器组件（~30 行）
|
||
- [x] `ui/layouts/page-layout.slint` - 页面布局（~70 行）
|
||
- [x] `ui/app.slint` - 主应用框架（侧边栏 + 路由）（~200 行）
|
||
- [x] `build.rs` - 修改编译入口为 app.slint（~5 行）
|
||
- [x] `src/main.rs` - 基础 callback 框架（~100 行）
|
||
- [x] 恢复 `ui/theme/` 目录（从 git 历史）
|
||
|
||
### Phase 2: 简单页面 ✓
|
||
|
||
**优先级：** 高
|
||
**预估代码量：** ~180 行
|
||
**完成日期：** 2026-01-30
|
||
|
||
- [x] `ui/components/empty.slint` - 空状态组件（~40 行）
|
||
- [x] `ui/pages/connections.slint` - 连接列表（~60 行）
|
||
- [x] `ui/pages/logs.slint` - 日志查看（~210 行）
|
||
|
||
### Phase 3: 中等复杂页面 ✓
|
||
|
||
**优先级：** 中
|
||
**预估代码量：** ~350 行
|
||
**完成日期：** 2026-01-30
|
||
|
||
- [x] `ui/pages/settings.slint` - 设置页面（~280 行）
|
||
- [x] `ui/pages/profiles.slint` - 配置文件管理（~230 行）
|
||
|
||
### Phase 4: 复杂页面 ✓
|
||
|
||
**优先级：** 中
|
||
**预估代码量：** ~550 行
|
||
**完成日期：** 2026-01-30
|
||
|
||
- [x] `ui/pages/home.slint` - 首页（~380 行）
|
||
- [x] `ui/pages/proxies.slint` - 代理管理（~280 行）
|
||
|
||
### Phase 5: Rust 集成 ✓
|
||
|
||
**优先级：** 低
|
||
**预估代码量：** ~200 行
|
||
**完成日期：** 2026-01-30
|
||
|
||
- [x] `src/main.rs` - 实现所有 callback 的 mock 数据（~450 行）
|
||
- Mock 数据生成函数
|
||
- 用户交互处理
|
||
- 数据状态更新
|
||
|
||
## 项目完成总结
|
||
|
||
### 实现成果
|
||
|
||
**总代码量：** ~2100 行（超出预估的 ~1430 行）
|
||
|
||
**完成时间：** 2026-01-30（单日完成）
|
||
|
||
**实现的文件：**
|
||
|
||
1. **基础设施（7 个文件）**
|
||
- `ui/types.slint` - 数据结构定义
|
||
- `ui/layouts/container.slint` - 容器组件
|
||
- `ui/layouts/page-layout.slint` - 页面布局
|
||
- `ui/app.slint` - 主应用框架
|
||
- `ui/theme/` - 主题系统（从 git 恢复）
|
||
- `build.rs` - 编译配置
|
||
- `src/main.rs` - Rust 集成
|
||
|
||
2. **UI 组件（1 个新增）**
|
||
- `ui/components/empty.slint` - 空状态组件
|
||
|
||
3. **页面模块（6 个页面）**
|
||
- `ui/pages/home.slint` - 首页
|
||
- `ui/pages/proxies.slint` - 代理管理
|
||
- `ui/pages/profiles.slint` - 配置文件管理
|
||
- `ui/pages/connections.slint` - 连接列表
|
||
- `ui/pages/logs.slint` - 日志查看
|
||
- `ui/pages/settings.slint` - 设置页面
|
||
|
||
### 功能特性
|
||
|
||
✅ **完整的 6 页面应用**
|
||
- Home - 配置文件信息、位置、快捷设置
|
||
- Proxies - 代理节点管理（Rule/Global/Direct 模式）
|
||
- Profiles - 配置文件管理（网格布局）
|
||
- Connections - 活动连接列表
|
||
- Logs - 日志查看（Mihomo/App 切换）
|
||
- Settings - 应用和 Clash 设置
|
||
|
||
✅ **主题系统**
|
||
- 亮色/暗色模式切换
|
||
- 响应式主题颜色
|
||
- 统一的设计系统
|
||
|
||
✅ **交互功能**
|
||
- 侧边栏导航
|
||
- 页面路由
|
||
- 数据加载和更新
|
||
- Toast 通知
|
||
- 用户操作反馈
|
||
|
||
✅ **Mock 数据**
|
||
- 3 个配置文件
|
||
- 2 个代理组（多个节点）
|
||
- 3 个活动连接
|
||
- 多条日志记录
|
||
- 完整的设置项
|
||
|
||
### 技术亮点
|
||
|
||
1. **模块化架构** - 清晰的目录结构和职责划分
|
||
2. **Callback 驱动** - 单向数据流，易于维护
|
||
3. **组件复用** - 最大化利用现有 shadcn-slint 组件
|
||
4. **类型安全** - Slint 类型系统保证数据一致性
|
||
5. **Mock 数据完整** - 所有页面都有真实的数据展示
|
||
|
||
### 运行方式
|
||
|
||
```bash
|
||
# 编译并运行
|
||
cargo run
|
||
|
||
# 发布版本
|
||
cargo run --release
|
||
```
|
||
|
||
### 下一步建议
|
||
|
||
1. **后端集成**
|
||
- 替换 mock 数据为真实的 Tauri 命令调用
|
||
- 实现配置文件的增删改查
|
||
- 实现代理节点的延迟测试
|
||
- 实现实时连接监控
|
||
|
||
2. **功能增强**
|
||
- 添加搜索和过滤功能
|
||
- 实现配置导入导出
|
||
- 添加更多设置选项
|
||
- 实现 TUN 模式配置对话框
|
||
|
||
3. **用户体验优化**
|
||
- 添加加载状态指示器
|
||
- 优化动画效果
|
||
- 添加键盘快捷键
|
||
- 实现拖拽排序
|
||
|
||
4. **性能优化**
|
||
- 虚拟滚动（大量数据时）
|
||
- 按需加载数据
|
||
- 优化渲染性能
|
||
|
||
## 总体进度
|
||
|
||
**总预估代码量：** ~1430 行
|
||
|
||
**完成情况：**
|
||
- ✓ Phase 1: 基础设施（7/7）
|
||
- ✓ Phase 2: 简单页面（3/3）
|
||
- ✓ Phase 3: 中等复杂页面（2/2）
|
||
- ✓ Phase 4: 复杂页面（2/2）
|
||
- ✓ Phase 5: Rust 集成（1/1）
|
||
|
||
**总进度：** 15/15 (100%) ✅
|
||
|
||
**项目状态：** 已完成
|
||
|
||
## 技术决策
|
||
|
||
### 图标方案
|
||
**选择：** Emoji
|
||
**理由：** 简单、无需额外资前项目已在使用
|
||
|
||
### 布局方案
|
||
**选择：** 固定桌面布局
|
||
**理由：** 桌面应用，不需要响应式
|
||
|
||
### 数据流方案
|
||
**选择：** Callback + Property
|
||
**理由：** 清晰的单向数据流，便于维护和测试
|
||
|
||
### 模块划分方案
|
||
**选择：** pages/ + layouts/ + components/
|
||
**理由：** 清晰的职责划分，易于维护和扩展
|
||
|
||
## 后续优化方向
|
||
|
||
1. **性能优化**
|
||
- 虚拟滚动（如果列表数据量大）
|
||
- 按需加载页面数据
|
||
|
||
2. **用户体验**
|
||
- 加载状态提示
|
||
- 错误处理和提示
|
||
- 操作确认对话框
|
||
|
||
3. **功能扩展**
|
||
- 搜索和过滤
|
||
- 排序功能
|
||
- 导入导出配置
|
||
|
||
## 参考资料
|
||
|
||
- 原 Tauri 实现：`web/src/` 目录
|
||
- Slint 文档：https://slint.dev/
|
||
- 现有组件库：`ui/components/` 目录
|