mirror of
https://github.com/nyakang/nyaterm.git
synced 2026-11-06 16:07:55 +00:00
Kang
b0a8d66695
- Replaced all instances of `gpui-component` with `gpui-kit` across various files to reflect the new naming convention. - Updated Cargo.toml and documentation to ensure consistency in dependency management and integration boundaries. - Adjusted comments and code references to align with the new structure, enhancing clarity and maintainability.
74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
# GPUI 桌面开发
|
|
|
|
NyaTerm 的原生界面位于 `crates/nyaterm-desktop`，共享控件位于 `crates/nyaterm-ui`。这里的“桌面层”同时包含 GPUI 状态、视图、窗口交互、平台适配和后台任务结果的接入。
|
|
|
|
## 入口与窗口
|
|
|
|
`nyaterm-app` 创建根窗口和 `AppShell`。存储启动完成后，`AppShell` 创建 `NyaTermApp` Entity 并启动工作区恢复。
|
|
|
|
设置、连接编辑、快捷命令、远程文本编辑等独立窗口通过 GPUI `open_window` 创建。窗口之间传递 Entity、typed state 或明确的回调，不使用 URL 路由或消息桥。
|
|
|
|
## 模块结构
|
|
|
|
```text
|
|
crates/nyaterm-desktop/src/
|
|
├── app_shell/ # 根 shell、启动/恢复/退出生命周期和原生菜单
|
|
├── entities/ # 窗口 runtime、启动恢复和 quick switch 的权威 Entity
|
|
├── features/ # focused feature state、运行时适配和视图
|
|
├── i18n/ # locale 加载与翻译
|
|
├── models/ # 桌面呈现模型
|
|
├── http/ # 原生 HTTP 适配
|
|
└── terminal.rs # 终端展示层入口
|
|
```
|
|
|
|
`features/` 按领域组织连接、会话、终端、设置、安全、传输、隧道、同步、AI、远程操作、布局和面板。新增功能应进入拥有该行为的领域目录，不要创建新的通用迁移桶或共享 prelude。
|
|
|
|
## 状态管理
|
|
|
|
`NyaTermApp` 组合各个 focused feature state。只操作一个领域的方法优先放到对应 state 上；需要通知 GPUI、访问窗口或协调多个领域时，再由 `NyaTermApp` 提供薄适配。
|
|
|
|
遵守以下所有权规则：
|
|
|
|
- 每份可变状态只有一个权威 owner。
|
|
- 不在 `NyaTermApp`/feature state 和 Entity store 中维护双写镜像。
|
|
- 由视图直接读取当前状态，不在 render 中发布再读回快照。
|
|
- 跨线程结果通过 typed event 或 typed task result 进入 GPUI update。
|
|
|
|
## 视图与控件
|
|
|
|
构造 GPUI element 的 helper 留在 view 或桌面 feature 中，不要为减少 `impl NyaTermApp` 数量而把视图构造移动到纯状态模型。
|
|
|
|
普通输入、选择、菜单、开关和对话框使用 `nyaterm-ui` 暴露的稳定组件 API。桌面 feature 不直接依赖 `gpui-kit`。普通文本字段使用 `NyaInput`/`NyaInputState` 或 `features/text_inputs.rs` 的 id registry，并为输入框提供明确尺寸。
|
|
|
|
终端输入、粘贴审查和 `RemoteTextEditor` 是完整编辑面，不应替换成普通单行输入。
|
|
|
|
## 输入与原生窗口交互
|
|
|
|
全局快捷键和 pointer 事件从根视图路由到当前 feature。处理事件时应明确何时调用 `cx.stop_propagation()`，并避免父级 click handler 抢回文本字段焦点。
|
|
|
|
平台相关窗口、剪贴板、拖放、PTY 和输入法行为需要在受影响的操作系统上验证。创建子窗口时复用已有窗口生命周期和 modal 协调模式。
|
|
|
|
## 终端展示
|
|
|
|
终端职责分为两层：
|
|
|
|
- `nyaterm-terminal` 维护终端网格、scrollback、控制序列、搜索和图形协议状态。
|
|
- `nyaterm-terminal-gpui` 负责像素布局、键盘事件转换、选区、高亮、图片和绘制。
|
|
|
|
桌面层把会话输出送入终端状态机，再把 snapshot 和交互状态交给 GPUI terminal element。不要在视图中重新实现控制序列解析或 wire protocol。
|
|
|
|
## 国际化
|
|
|
|
应用语言包位于：
|
|
|
|
- `crates/nyaterm-desktop/src/i18n/locales/zh-CN.json`
|
|
- `crates/nyaterm-desktop/src/i18n/locales/en.json`
|
|
|
|
新增或修改用户可见文本时同步更新两种语言，并复用现有 translation key 命名方式。
|
|
|
|
## 后台任务与测试
|
|
|
|
render 和长时间 GPUI update callback 中不得执行数据库、文件系统、网络、SSH、SFTP、子进程或图片解码工作。使用 GPUI executor、专用 runtime 或已有 job coordinator，并在结果返回时更新权威状态。
|
|
|
|
状态迁移尽量通过纯方法测试；GPUI 交互使用相邻模块中的 `#[gpui::test]` 或现有 test context。涉及窗口、剪贴板、拖放和 IME 的改动还需做平台 smoke test。
|