165 lines
3.2 KiB
Markdown
165 lines
3.2 KiB
Markdown
# Renderer 开发指南
|
||
|
||
本文档说明在当前项目里开发 React 渲染层时，推荐的组织方式和常见改动路径。
|
||
|
||
## 1. Renderer 结构
|
||
|
||
```mermaid
|
||
graph TD
|
||
App[App.tsx]
|
||
Pages[pages/]
|
||
Components[components/]
|
||
Hooks[hooks/]
|
||
Stores[stores/]
|
||
Lib[lib/]
|
||
|
||
App --> Pages
|
||
Pages --> Components
|
||
Pages --> Hooks
|
||
Hooks --> Stores
|
||
Hooks --> Lib
|
||
```
|
||
|
||
## 2. 开发原则
|
||
|
||
当前 renderer 层推荐遵循这些边界：
|
||
|
||
- 页面组件优先作为组装层
|
||
- 复杂流程优先下沉到 hook
|
||
- 纯逻辑优先抽到 helper / lib
|
||
- 非首屏重型弹窗优先考虑懒加载
|
||
- bridge 调用优先放在 hook，不直接散落在组件树中
|
||
|
||
## 3. 页面开发路径
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Feature[新增或修改页面功能]
|
||
Page[页面容器]
|
||
Hook[页面 Hook]
|
||
Components[子组件]
|
||
Helpers[helper / lib]
|
||
Preload[window.electron facade]
|
||
|
||
Feature --> Page
|
||
Page --> Hook
|
||
Page --> Components
|
||
Hook --> Helpers
|
||
Hook --> Preload
|
||
```
|
||
|
||
## 4. 当前页面入口
|
||
|
||
主要页面：
|
||
|
||
- `ExtractorPage.tsx`
|
||
- `CleanerPage.tsx`
|
||
- `SettingsPage.tsx`
|
||
|
||
主壳层：
|
||
|
||
- `App.tsx`
|
||
- `AuthenticatedAppShell.tsx`
|
||
- `UnauthenticatedApp.tsx`
|
||
|
||
## 5. Hook 组织建议
|
||
|
||
推荐把 hook 分成几类：
|
||
|
||
- 页面启动/编排 hook
|
||
例如 `useAppBootstrap`
|
||
- 业务流程 hook
|
||
例如 `useCleaner`、`useExtractor`
|
||
- 辅助状态 hook
|
||
例如 `usePersistentTextState`、`useSharedProductionIds`
|
||
|
||
```mermaid
|
||
graph LR
|
||
Page[Page]
|
||
Bootstrap[Bootstrap Hook]
|
||
Domain[Domain Hook]
|
||
Helper[Helper Hook]
|
||
|
||
Page --> Bootstrap
|
||
Page --> Domain
|
||
Domain --> Helper
|
||
```
|
||
|
||
## 6. 当前推荐风格
|
||
|
||
结合近期重构，当前 renderer 更推荐：
|
||
|
||
- `App.tsx` 保持薄入口
|
||
- `CleanerPage` 保持页面布局和弹窗编排
|
||
- 重型局部区域拆成子组件
|
||
- 异步状态收敛到 hook
|
||
|
||
## 7. 状态更新建议
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Input[用户输入]
|
||
Local[局部 state]
|
||
Derived[派生状态]
|
||
Async[异步请求]
|
||
UI[UI 更新]
|
||
|
||
Input --> Local
|
||
Local --> Derived
|
||
Local --> Async
|
||
Derived --> UI
|
||
Async --> UI
|
||
```
|
||
|
||
建议：
|
||
|
||
- 能派生的状态尽量派生，不额外存储
|
||
- 输入态不要直接挂太多高频副作用
|
||
- 非紧急 UI 更新可考虑 `startTransition`
|
||
|
||
## 8. 弹窗开发建议
|
||
|
||
当前项目弹窗较多，建议遵循：
|
||
|
||
- 非首屏关键弹窗优先懒加载
|
||
- 弹窗状态尽量放在页面或页面 hook 中统一管理
|
||
- 弹窗本身专注展示和内部交互
|
||
|
||
## 9. 典型改动路径
|
||
|
||
### 改 Cleaner 页面
|
||
|
||
- `CleanerPage.tsx`
|
||
- `components/cleaner/*`
|
||
- `useCleaner.ts`
|
||
- `hooks/cleaner/*`
|
||
|
||
### 改 Extractor 页面
|
||
|
||
- `ExtractorPage.tsx`
|
||
- `useExtractor.ts`
|
||
- `useSharedProductionIds.ts`
|
||
|
||
### 改更新弹窗
|
||
|
||
- `UpdateDialog.tsx`
|
||
- `useUpdateDialogState.ts`
|
||
- `useAppBootstrap.ts`
|
||
|
||
## 10. 测试建议
|
||
|
||
当前 renderer 测试更适合先从：
|
||
|
||
- 状态 helper
|
||
- hook 决策逻辑
|
||
- 与 preload 调用边界有关的轻量测试
|
||
|
||
开始补，而不是一上来就做全量 UI 集成测试。
|
||
|
||
## 11. 常见反模式
|
||
|
||
- 页面组件同时承载过多副作用
|
||
- 在组件中直接散布大量 `window.electron.xxx`
|
||
- 一个 hook 同时管理初始化、交互、请求、持久化和对话框
|
||
- 非首屏重型组件全部静态导入
|