版本：v0.1.0
⚠️ 项目状态：本项目仍在积极开发中，部分功能可能不完善。
PhotoWall 是一款基于 Tauri + React + TypeScript + Vite 的 Windows 桌面照片管理软件，专注于本地照片的浏览、索引与整理体验。
- 操作系统：Windows 10 或更高版本
- 运行环境：需要安装 WebView2 运行时（Windows 11 已内置）
- 硬盘空间：至少 100 MB 可用空间（用于程序和缩略图缓存）
- 内存：建议 4 GB 以上
环境要求（Windows）：
- Node.js 18+（仓库使用
package-lock.json，推荐使用 npm） - Rust stable（建议使用 MSVC 工具链）
- WebView2 Runtime（Windows 11 已内置）
构建步骤：
# 克隆仓库
git clone https://github.com/gy212/PhotoWall.git
cd PhotoWall
# 安装依赖
npm install
# 开发模式运行（桌面端：自动启动 Vite + Tauri）
npm run tauri dev
# 构建生产版本（桌面端）
npm run tauri build构建完成后，安装包位于 src-tauri/target/release/bundle/
| 命令 | 说明 |
|---|---|
npm run dev |
启动 Web UI（Vite） |
npm run build |
TypeScript 类型检查 + 构建 Web UI 到 dist/ |
npm run tauri dev |
启动桌面端开发（Tauri） |
npm run tauri build |
构建桌面端安装包/可执行文件 |
npm run test |
运行 Vitest |
npm run test:coverage |
运行测试并生成覆盖率（输出到 coverage/） |
npm run lint |
ESLint 检查 |
npm run lint:fix |
ESLint 自动修复 |
npm run format |
Prettier 格式化 src/ |
- 前端类型：
src/types/ - 后端（Rust）数据结构：
src-tauri/src/**
当 Rust 命令/结构体对前端暴露 payload 时，建议同步更新对应的 TypeScript 类型，避免运行时字段不一致。
-
启动程序：运行构建后的应用或使用
npm run tauri dev开发模式 -
添加照片文件夹：
- 进入「设置」页面
- 在「文件夹同步」中，点击「添加文件夹」
- 选择您存放照片的文件夹
- 程序会自动扫描并索引照片
-
开始浏览：
- 点击顶部导航栏的「照片」
- 您的照片将以网格形式展示
PhotoWall 支持两种方式导入照片：
自动扫描
- 在设置中添加监控文件夹后，程序会自动扫描并索引其中的照片
- 支持增量更新，只处理新增或修改的文件
- 文件夹内的变化会被实时监控
手动导入
- 点击右下角的「快速导入」浮动按钮（
+） - 选择包含照片的文件夹
- 等待导入完成
PhotoWall 提供三种浏览模式：
- 以缩略图网格形式展示所有照片
- 使用工具栏中的滑块可调整缩略图大小
- 支持流畅滚动，可快速浏览大量照片
- 按拍摄日期自动分组
- 日期标题清晰显示
- 方便按时间回顾照片
- 点击顶部导航栏的「文件夹」
- 显示文件夹树形结构
- 每个文件夹显示照片数量
- 点击文件夹可查看其中的照片
双击任意照片可进入全屏查看模式：
基本操作
- 使用左右箭头键或点击屏幕两侧切换照片
- 鼠标滚轮或 +/- 键缩放照片
- 拖拽照片可平移查看
- 按
0键重置缩放
幻灯片播放
- 按空格键开始/暂停自动播放
- 默认每 3 秒切换一张照片
信息面板
- 按
I键显示/隐藏照片详细信息 - 包括文件名、尺寸、拍摄参数等
标签可以帮助您更好地分类和查找照片：
创建/添加标签
- 在「照片」页面选中一张或多张照片
- 在出现的操作工具栏中点击「标签」
- 在弹出的面板中搜索已有标签，或直接输入名称创建并添加
按标签/收藏筛选
- 在「照片」页面的「快速筛选」中点击标签或「收藏」即可筛选
相册功能仍在完善中，部分交互/入口可能会在后续版本调整。
点击右上角搜索按钮或按 Ctrl + K 打开搜索面板，可快速查找照片：
搜索方式
- 按文件名搜索
- 按标签名称搜索
- 支持模糊匹配
高级筛选 程序支持按以下条件筛选：
- 日期范围
- 相机型号
- 镜头型号
- 评分
- 收藏状态
- 左侧：应用 Logo 与名称（桌面端可拖拽区域）
- 中间：主导航（胶囊式）「照片 / 文件夹 / 废纸篓 / 设置」
- 右侧：全局搜索（
Ctrl + K）与窗口控制按钮（桌面端）
- 仪表盘 + 照片网格：最近添加、标签条、全部照片等
- 选中照片后会出现操作工具栏：批量收藏、批量标签、删除等
- 点击照片进入查看器：支持方向键切换、缩放等操作
按文件夹结构浏览已索引照片，并查看每个文件夹的照片数量等信息。
展示已删除（软删除）的照片，可进行恢复或清空。
- 左侧分区：文件夹同步 / 外观 / 照片扫描 / 缩略图 / 性能
- 支持「保存设置」与「恢复默认设置」
- 文件夹同步中会提示不可访问/不存在的路径（如被移动或权限不足）
| 快捷键 | 功能 |
|---|---|
Ctrl + A |
全选照片 |
Delete |
删除选中的照片 |
Escape |
取消选择/关闭对话框 |
| 快捷键 | 功能 |
|---|---|
← / → |
上一张/下一张 |
+ / - |
放大/缩小 |
0 |
重置缩放 |
空格 |
播放/暂停幻灯片 |
I |
显示/隐藏照片信息 |
Escape |
退出全屏查看 |
进入设置页面可配置以下选项：
- 主题：浅色 / 深色 / 跟随系统
- 监控文件夹：添加或移除自动扫描的文件夹
- 排除文件夹：设置不需要扫描的文件夹
- 缓存位置：缩略图缓存存储位置
- 清理缓存：手动清理缩略图缓存以释放空间
- 并行线程数：调整扫描和缩略图生成的并发数
PhotoWall 支持以下常见图片格式：
常规格式
- JPEG (.jpg, .jpeg)
- PNG (.png)
- GIF (.gif)
- BMP (.bmp)
- WebP (.webp)
- TIFF (.tiff, .tif)
RAW 格式
- Nikon (.nef) ✅ 已测试
- Canon (.cr2, .cr3)
⚠️ 未充分测试 - Sony (.arw)
⚠️ 未充分测试 - Adobe DNG (.dng)
⚠️ 未充分测试 - 其他 RAW 格式
⚠️ 未充分测试
注意：目前 RAW 格式仅对 Nikon NEF 进行了完整测试。其他 RAW 格式可能出现缩略图无法加载、色彩信息丢失或偏绿等问题。如遇此类情况，建议将 RAW 文件转换为 DNG 或 JPEG 格式使用。
A: 首次打开大量照片时，程序需要生成缩略图，这可能需要一些时间。生成完成后，缩略图会被缓存，后续加载会非常快速。
A: 删除的照片会移动到废纸篓。点击顶部导航栏的「废纸篓」，选中照片后点击「恢复」即可。
A: 程序会在本地缓存缩略图以提高加载速度。您可以在「设置」→「缓存设置」中清理缓存。
A: 请确保照片所在的文件夹已添加到监控列表中。您也可以点击「刷新」按钮手动触发扫描。
A: 目前仅对 Nikon NEF 格式进行了完整测试。其他品牌（佳能、索尼、富士等）的 RAW 格式支持尚在完善中，可能出现缩略图加载失败或色彩异常的情况。如遇问题，建议将 RAW 文件转换为 DNG 或 JPEG 格式。
A: 这是已知问题，目前部分 RAW 格式的解码尚未完善。临时解决方案是使用 Adobe DNG Converter 或相机厂商软件将 RAW 文件转换为 DNG 或 JPEG 格式。
程序数据存储在以下位置：
%AppData%\PhotoWall\
├── Database\ # 数据库文件
│ └── photowall.db
├── Thumbnails\ # 缩略图缓存
│ ├── small\
│ ├── medium\
│ └── large\
├── Config\ # 配置文件
│ └── settings.json
└── Logs\ # 日志文件
src/：React + TypeScript 前端（@/为src/别名）src/test/：Vitest 测试与公共测试工具public/：Vite 静态资源src-tauri/：Tauri（Rust）后端与打包配置docs/：设计/方案文档
- 提交前建议执行：
npm run test、npm run lint - 避免提交真实用户数据（如
*.db、缓存目录等），也不要在日志中打印敏感的本地路径 - 如需调整 Tauri 文件访问范围，请先评估最小权限并在 PR 中明确说明（配置见
src-tauri/tauri.conf.json）
如遇到问题或有功能建议，欢迎通过以下方式联系：
- 在 GitHub 仓库提交 Issue
- 查看项目文档获取更多帮助
感谢您使用 PhotoWall！