WEB版本UI界面重构的建议和思路

建议开发[MulimgViewer](https://github.com/nachifur/MulimgViewer)的web同步版本，web前端技术可以实现我们传统pythonwxformbuilder实现不了的视觉冲击和性能

更新后的图片导入功能 更加美观和现代化
[

<img width="810" height="571" alt="Image" src="https://github.com/user-attachments/assets/7cabfabd-b797-4e0b-9b54-882791b348f8" />

](url)
更新后的主界面更加美观，功能拓展丰富
<img width="1672" height="941" alt="Image" src="https://github.com/user-attachments/assets/0515d4cd-8584-4cb0-9de7-02f882dc8086" />

很容易便实现了繁体中文和简体中文以及English的支持

<img width="225" height="251" alt="Image" src="https://github.com/user-attachments/assets/0c6a1c6d-08d1-497e-aea6-95eb061668c4" />

# MulimgViewer Web 技术文档

Version: `2026.4.23.1`

Last Updated: `2026-04-23`

## 1. 文档目标

本文档用于说明当前 Web 版的：

- 代码结构（请直接跳转下文 8.1 Web 前端目录）
- 技术栈
- 分层架构
- 本地版 / Web 版的区别
- 一键启动方式
- 主要新增功能实现逻辑
- 关键代码位置
- 常见错误与排查方式

---

## 2. 两个版本怎么区分

MulimgViewer 应有两种启动形态。

| 版本 | UI 形态 | 技术形态 | 推荐启动方式 | 入口代码 |
|---|---|---|---|---|
| 原有本地版 | `wxPython` 桌面窗口 | 单机桌面 GUI | `start_local.bat` / `start_local.py` | `src/mulimgviewer/__main__.py` |
| Web 版 | 浏览器页面 | `React + FastAPI` | `start_web.bat` / `start_web.py` | `src/mulimgviewer/web/__main__.py`、`src/mulimgviewer/web/app.py` |

### 最直观的区别

1. 如果启动后弹出的是传统桌面窗口，那是原有本地版。
2. 如果启动后浏览器打开 `http://127.0.0.1:8000`，那是 Web 版。

---

## 3. 为什么以前 `python -m mulimgviewer.web` 容易报错

仓库采用的是 `src/` 布局：

```text
repo/
├─ src/
│  └─ mulimgviewer/
```

这意味着：

- 直接在仓库根目录执行 `python -m mulimgviewer.web`
- 如果没有安装包，或者没有设置 `PYTHONPATH=.\src`

Python 就会找不到 `mulimgviewer`，报：

```text
ModuleNotFoundError: No module named 'mulimgviewer'
```

为了解决这个问题，当前web版本新增了两套启动器：

- `start_local.py` / `start_local.bat`
- `start_web.py` / `start_web.bat`

它们会自动把仓库路径和 `src` 路径处理好，所以后续不再推荐直接手敲 `python -m mulimgviewer.web`。

---

## 4. 一键启动脚本

## 4.1 新增文件

位于仓库根目录：

```text
start_local.py
start_local.bat
start_web.py
start_web.bat
```

## 4.2 脚本职责

### `start_local.py`

职责：

- 自动切回仓库根目录
- 自动把仓库根目录加入 Python 搜索路径
- 启动原有桌面版
- 支持 `--check` 自检

### `start_web.py`

职责：

- 自动切回仓库根目录
- 自动把 `src` 加入 Python 搜索路径
- 检查 Web 依赖
- 如果 `web/dist` 不存在则自动执行一次 `npm run build`
- 启动 FastAPI Web 服务
- 自动打开浏览器
- 支持 `--check`

### `.bat` 包装脚本

职责：

- 方便双击启动
- 固定切回仓库根目录
- 直接调用当前终端 / 当前系统 PATH 下的 `python`

建议：

- 如果你想明确使用 `mulimgviewer` 环境，请先手动执行：

```powershell
conda activate mulimgviewer
```

然后再运行 `.bat` 或 `.py` 启动器。

---

## 5. 推荐启动方式

## 5.1 原有本地版

### 双击方式

直接双击：

```text
start_local.bat
```

### 终端方式

```powershell
.\start_local.bat
```

或：

```powershell
python .\start_local.py
```

### 自检

```powershell
.\start_local.bat --check
```

或：

```powershell
python .\start_local.py --check
```

## 5.2 Web 版

### 双击方式

直接双击：

```text
start_web.bat
```

### 终端方式

```powershell
.\start_web.bat
```

或：

```powershell
python .\start_web.py
```

### 常用参数

```powershell
python .\start_web.py --port 8001
python .\start_web.py --no-browser
python .\start_web.py --reload
python .\start_web.py --check
```

---

## 6. Web 版总体架构

```mermaid
flowchart LR
    A["React + TypeScript + Vite"] --> B["web/src/api.ts"]
    B --> C["FastAPI app.py"]
    C --> D["ImageService"]
    D --> E["本地文件系统"]
    D --> F["Pillow / imageio / 缓存目录"]
    A --> G["Zustand Store"]
    A --> H["TanStack Query"]
    A --> I["WebSocket Events"]
```
### 架构职责

1. 前端负责页面、状态、交互、资源管理器、预览和配置面板。
2. FastAPI 负责暴露 REST / WebSocket 接口，并在生产模式下挂载 `web/dist`。
3. `ImageService` 负责目录扫描、媒体元数据、缓存、渲染、保存和同步刷新。

---

## 7. 技术栈

## 7.1 前端

- `React`
- `TypeScript`
- `Vite`
- `Tailwind CSS`
- `Radix UI`
- `lucide-react`
- `Zustand`
- `TanStack Query`
- `@tanstack/react-virtual`
- `Playwright`

## 7.2 后端

- `FastAPI`
- `Uvicorn`
- `Pydantic`
- `Pillow`
- `imageio`

### 设计选择

- `React + TS`：适合把工具型桌面界面拆成独立模块
- `Zustand`：很适合 viewer 这种本地交互状态多的页面
- `TanStack Query`：适合轮询同步会话状态
- `FastAPI + Pydantic`：接口与模型定义清晰
- `Pillow + imageio`：可以较低成本复用现有 Python 图像处理逻辑，并扩展到视频首帧

---

## 8. 代码结构

## 8.1 Web 前端目录

```text
web/
├─ src/
│  ├─ api.ts
│  ├─ App.tsx
│  ├─ i18n.ts
│  ├─ main.tsx
│  ├─ store.ts
│  ├─ styles.css
│  ├─ types.ts
│  ├─ utils.ts
│  ├─ components/
│  │  ├─ BrowseDialog.tsx
│  │  ├─ FormControls.tsx
│  │  ├─ IconButton.tsx
│  │  ├─ PreviewCanvas.tsx
│  │  ├─ RenderedPreview.tsx
│  │  ├─ SettingsPanel.tsx
│  │  ├─ Sidebar.tsx
│  │  ├─ StatusBar.tsx
│  │  ├─ ThumbnailStrip.tsx
│  │  └─ TopToolbar.tsx
│  └─ hooks/
│     └─ useSessionEvents.ts
├─ e2e/
│  └─ viewer.spec.ts
├─ dist/
├─ README.md
└─ WEBreadme.md
```

## 8.2 Python Web 模块目录

```text
src/mulimgviewer/web/
├─ __init__.py
├─ __main__.py
├─ app.py
├─ image_service.py
└─ models.py
```

## 8.3 根目录新增启动器

```text
start_local.py
start_local.bat
start_web.py
start_web.bat
```

---

## 9. 分层架构

## 9.1 前端分层

### 1) 视图层

文件：

- `web/src/App.tsx`
- `web/src/components/*.tsx`

职责：

- 搭建整体布局
- 接收状态与接口数据
- 组织工具栏、预览区、缩略图、设置面板、资源管理器

### 2) 状态层

文件：

- `web/src/store.ts`

职责：

- 保存当前会话
- 保存媒体顺序、选中项、播放状态、语言、主题、输出配置
- 负责会话同步时保留路径级别的排序和选中状态

### 3) 数据访问层

文件：

- `web/src/api.ts`

职责：

- 封装 API 请求
- 自动探测 API Base
- 生成资源 URL / WebSocket URL
- 为缩略图和预览资源加版本参数，降低旧缓存命中导致的问题

### 4) 通信与同步层

文件：

- `web/src/App.tsx`
- `web/src/hooks/useSessionEvents.ts`

职责：

- 轮询当前会话，监测目录内容变化
- 订阅 WebSocket 事件

## 9.2 后端分层

### 1) API 层

文件：

- `src/mulimgviewer/web/app.py`

职责：

- 路由分发
- 统一异常转 HTTP 状态码
- 挂载构建后的前端静态资源

### 2) 业务服务层

文件：

- `src/mulimgviewer/web/image_service.py`

职责：

- 打开会话
- 扫描图片 / 视频
- 生成缩略图和预览
- 拼接渲染
- 保存结果
- 刷新目录变化

### 3) 模型层

文件：

- `src/mulimgviewer/web/models.py`
- `web/src/types.ts`

职责：

- 统一定义前后端数据结构

---

## 10. 主要功能与代码位置

## 10.1 Explorer 风格资源管理器

主要文件：

- `web/src/components/BrowseDialog.tsx`
- `src/mulimgviewer/web/image_service.py`
- `src/mulimgviewer/web/app.py`

实现内容：

- 左侧快速访问 / 磁盘列表
- 地址栏
- 面包屑
- 搜索
- 双击目录进入
- 双击文件直接打开
- 表格视图

## 10.2 图片 + 视频统一浏览

主要文件：

- `src/mulimgviewer/web/image_service.py`
- `web/src/components/PreviewCanvas.tsx`
- `web/src/components/ThumbnailStrip.tsx`
- `web/src/components/BrowseDialog.tsx`

实现内容：

- 扫描时统一纳入图片和视频
- 视频支持首帧缩略图
- 主预览区视频原生播放
- 视频首帧可参与拼接

## 10.3 排序 / 筛选 / 搜索

主要文件：

- `web/src/components/BrowseDialog.tsx`

实现内容：

- 按名称 / 时间 / 类型 / 大小排序
- 升序 / 降序切换
- 文件夹 / 图像 / 视频筛选
- 当前目录关键字搜索

## 10.4 文件夹增删自动同步

主要文件：

- `src/mulimgviewer/web/image_service.py`
- `web/src/App.tsx`
- `web/src/store.ts`

实现内容：

- 后端 `get_session()` 时调用 `_refresh_state()`
- 前端定时轮询当前 session
- 只在 `updated_at` 真变化时同步状态
- 尽量保留原来的排序和选中

## 10.5 多语言

主要文件：

- `web/src/i18n.ts`
- `web/src/components/Sidebar.tsx`
- `web/src/components/SettingsPanel.tsx`
- `web/src/components/BrowseDialog.tsx`
- `web/src/components/TopToolbar.tsx`

实现内容：

- 简体中文 / English / 繁體中文
- 词典驱动的 UI 文案渲染

## 10.6 拼接与保存

主要文件：

- `src/mulimgviewer/web/image_service.py`
- `src/mulimgviewer/web/app.py`
- `web/src/App.tsx`
- `web/src/components/RenderedPreview.tsx`

实现内容：

- 选中媒体拼接
- 设置背景色、尺寸策略、gap
- 生成缓存图
- 输出保存到指定目录

---

## 11. 启动与运行逻辑

## 11.1 原有本地版启动链路

```mermaid
flowchart LR
    A["start_local.bat"] --> B["start_local.py"]
    B --> C["src/mulimgviewer/__main__.py"]
    C --> D["wxPython Desktop UI"]
```

### 说明

- 本地版不依赖浏览器
- 启动的是 `wxPython` 窗口
- 主要沿用原项目逻辑

## 11.2 Web 版启动链路

```mermaid
flowchart LR
    A["start_web.bat"] --> B["start_web.py"]
    B --> C["检查 Python 依赖"]
    B --> D["检查 web/dist"]
    D --> E["必要时 npm run build"]
    B --> F["FastAPI + Uvicorn"]
    F --> G["浏览器打开 http://127.0.0.1:8000"]
```

### 说明

- Web 版启动后，浏览器是主界面
- `start_web.py` 已经处理 `src` 布局的导入问题
- 不需要再手动设置 `PYTHONPATH`

---

## 12. 常见错误与排查

## 12.1 `ModuleNotFoundError: No module named 'mulimgviewer'`

原因：

- 直接使用了 `python -m mulimgviewer.web`
- 当前环境没有安装包
- 没有设置 `PYTHONPATH`

解决：

优先改用：

```powershell
.\start_web.bat
```

或：

```powershell
python .\start_web.py
```

## 12.2 `favicon.ico 404`报错

原因：

- 浏览器会自动请求标签页图标

当前状态：

- 已在 `app.py` 中处理为非致命响应

## 12.3 缩略图偶发 `416 Requested Range Not Satisfiable`报错

原因：

- 浏览器缓存 / Range 请求与文件变化时机重叠

当前缓解：

- 缩略图与预览 URL 已加版本参数

## 12.4 资源管理器输入了路径，列表又跳回旧目录

原因：

- 异步请求先后返回顺序不同造成旧结果回写

当前修复：

- `BrowseDialog.tsx` 中已限制只有当前请求对应路径才刷新地址栏

---

## 13. 测试与验证

## 13.1 后端测试

```powershell
python -m pytest tests\test_web_api.py -q
```

覆盖：

- 会话打开
- 目录递归扫描
- 缩略图 / 预览 / 渲染 / 保存
- 浏览器接口
- 文件夹自动同步

## 13.2 前端构建

```powershell
cd web
npm run build
```

## 13.3 E2E

```powershell
cd web
npm run test:e2e
```

说明：

- Playwright 使用独立测试端口，避免误复用你本机已启动的旧服务

---

## 14. 当前版本总结

`version2026.4.23.1` 相比初始 Web MVP，已经把“能打开”推进到了“能稳定用”：

- 增加了原有本地版 / Web 版两套一键启动器
- 补齐了 `src` 布局导致的启动痛点
- 明确区分了桌面版与 Web 版入口
- 增强了资源管理器的实际可用性
- 支持视频浏览
- 支持排序、筛选、搜索
- 支持文件夹内容变化自动同步
- 支持三语言切换

后续继续扩展 `Compare / Sequence / Batch` 时，建议继续沿用当前这套：

- 前端组件层
- Zustand 状态层
- FastAPI 路由层
- ImageService 服务层
- 

                                   _这样演进成本最低，也最稳。
                                          -2026/4/23 jingyu_
                                                                                      

版本	UI 形态	技术形态	推荐启动方式	入口代码
原有本地版	`wxPython` 桌面窗口	单机桌面 GUI	`start_local.bat` / `start_local.py`	`src/mulimgviewer/__main__.py`
Web 版	浏览器页面	`React + FastAPI`	`start_web.bat` / `start_web.py`	`src/mulimgviewer/web/__main__.py`、`src/mulimgviewer/web/app.py`

WEB版本UI界面重构的建议和思路 #207

Description

MulimgViewer Web 技术文档

1. 文档目标

2. 两个版本怎么区分

最直观的区别

3. 为什么以前 python -m mulimgviewer.web 容易报错

4. 一键启动脚本

4.1 新增文件

4.2 脚本职责

start_local.py

start_web.py

.bat 包装脚本

5. 推荐启动方式

5.1 原有本地版

双击方式

终端方式

自检

5.2 Web 版

双击方式

终端方式

常用参数

6. Web 版总体架构

架构职责

7. 技术栈

7.1 前端

7.2 后端

设计选择

8. 代码结构

8.1 Web 前端目录

8.2 Python Web 模块目录

8.3 根目录新增启动器

9. 分层架构

9.1 前端分层

1) 视图层

2) 状态层

3) 数据访问层

4) 通信与同步层

9.2 后端分层

1) API 层

2) 业务服务层

3) 模型层

10. 主要功能与代码位置

10.1 Explorer 风格资源管理器

10.2 图片 + 视频统一浏览

10.3 排序 / 筛选 / 搜索

10.4 文件夹增删自动同步

10.5 多语言

10.6 拼接与保存

11. 启动与运行逻辑

11.1 原有本地版启动链路

说明

11.2 Web 版启动链路

说明

12. 常见错误与排查

12.1 ModuleNotFoundError: No module named 'mulimgviewer'

12.2 favicon.ico 404报错

12.3 缩略图偶发 416 Requested Range Not Satisfiable报错

12.4 资源管理器输入了路径，列表又跳回旧目录

13. 测试与验证

13.1 后端测试

13.2 前端构建

13.3 E2E

14. 当前版本总结

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

3. 为什么以前 `python -m mulimgviewer.web` 容易报错

`start_local.py`

`start_web.py`

`.bat` 包装脚本

12.1 `ModuleNotFoundError: No module named 'mulimgviewer'`

12.2 `favicon.ico 404`报错

12.3 缩略图偶发 `416 Requested Range Not Satisfiable`报错