# Photo Gallery

**Repository Path**: Adnois/photo-gallery

## Basic Information

- **Project Name**: Photo Gallery
- **Description**: 一个专注于照片管理和展示的开源项目，提供丰富的功能和友好的用户界面，帮助用户轻松整理和分享照片。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📷 Photo Gallery · 照片相册

一个基于 **Tauri 2.0 + React + TypeScript + Tailwind CSS + Framer Motion** 的桌面端照片相册应用。

优雅的毛玻璃界面、流畅的动效切换、多主题可自定义、多种浏览视图（网格/瀑布流/轮播），以及相册分组与收藏。

---

## ✨ 功能亮点

- 🖼 **多种视图模式** — 网格布局、瀑布流、沉浸式轮播，一键切换
- 🎨 **5 套主题风格** — 极光梦境 / 极简黑白 / 温暖日落 / 深邃海洋 / 静谧森林
- 🌈 **动画过渡** — 淡入淡出、左右滑动、缩放、旋转、3D 翻转、Ken Burns、幕布、视差 共 8 种
- ⭐ **收藏与相册** — 一键收藏、自定义相册分组、移动照片
- 🔍 **搜索过滤** — 按名称、标签快速筛选
- 🔎 **照片查看器** — 全屏查看、缩放、左右切换、键盘快捷键
- 📁 **本地导入** — 选择文件或扫描整个目录
- 💾 **自动持久化** — 配置自动保存到本地，下次打开恢复如初
- 🖼 **Base64 兼容** — 对 convertFileSrc 无法加载的图片，自动 fallback 为 Base64
- 🌙 **毛玻璃 + 渐变** — 现代感 UI，低 CPU 负载的静态渐变

---

## 🛠 技术栈

| 层级 | 技术 |
|------|------|
| 桌面壳 | Tauri 2.0 (Rust) |
| 前端 | React 18 + TypeScript |
| 样式 | Tailwind CSS 3 + 自定义 CSS 变量 |
| 动效 | Framer Motion 11 |
| 构建 | Vite 5 |
| 类型检查 | TypeScript 5.4 |

---

## 📁 项目结构

```
photo-gallery/
├── src-tauri/              # Tauri Rust 后端
│   ├── src/main.rs         # 核心指令（图片加载、扫描、配置读写）
│   ├── capabilities/       # 权限配置
│   └── tauri.conf.json     # Tauri 配置
├── src/                    # React 前端
│   ├── components/
│   │   ├── Sidebar.tsx        # 左侧栏（相册/快捷入口）
│   │   ├── TopBar.tsx         # 顶栏（搜索/视图/动画/主题切换）
│   │   ├── GridView.tsx       # 网格视图
│   │   ├── MasonryView.tsx    # 瀑布流视图
│   │   ├── CarouselView.tsx   # 轮播视图
│   │   ├── PhotoViewer.tsx    # 全屏照片查看器
│   │   ├── ThemeSwitcher.tsx  # 主题选择弹窗
│   │   ├── InputDialog.tsx    # 自定义输入对话框
│   │   └── WelcomeScreen.tsx  # 空状态欢迎页
│   ├── App.tsx             # 主应用（状态管理/组件编排）
│   ├── types.ts            # 类型定义 + 主题/动画/视图常量
│   ├── index.css           # 全局样式与主题变量
│   └── main.tsx            # 入口
├── package.json
├── vite.config.ts
└── README.md
```

---

## 🚀 快速开始

### 环境要求

- Node.js ≥ 18
- Rust 工具链（安装方法见 [Tauri 文档](https://tauri.app/start/prerequisites/)）
- 操作系统：Windows / macOS / Linux

### 安装依赖

```bash
npm install
```

### 开发模式（带热重载）

```bash
npm run tauri dev
```

### 生产构建（生成可安装包）

```bash
npm run tauri:build
# 构建产物位于 src-tauri/target/release/bundle/
```

### 纯 Web 调试（不带 Tauri 壳）

```bash
npm run dev     # http://localhost:1420
npm run build   # 构建前端到 dist/
npm run preview # 预览生产构建
```

---

## ⌨️ 快捷键

在照片查看器中：

| 按键 | 功能 |
|------|------|
| `←` / `→` | 上一张 / 下一张 |
| `+` / `-` | 放大 / 缩小 |
| `0` | 重置缩放 |
| `F` | 切换收藏 |
| `Esc` | 关闭查看器 |
| `Ctrl + 滚轮` | 缩放（查看器内） |

---

## 🎨 主题对照表

| Key | Label | 风格 |
|-----|-------|------|
| `aurora` | 极光梦境 | 粉紫渐变 |
| `mono` | 极简黑白 | 现代简约 |
| `sunset` | 温暖日落 | 橙红色调 |
| `ocean` | 深邃海洋 | 深蓝夜色 |
| `forest` | 静谧森林 | 绿色自然 |

在应用内点击右上角 🎨 按钮即可切换主题，主题会自动保存。

---

## 🔑 Tauri 指令（Commands）

由 [src-tauri/src/main.rs](file:///Users/hulongguang/trae/photo-gallery/src-tauri/src/main.rs) 提供：

| 指令 | 说明 |
|------|------|
| `save_app_config(config)` | 保存用户配置（照片、相册、主题） |
| `load_app_config()` | 读取用户配置（首次启动时） |
| `read_image_as_data_url(path)` | 以 Base64 形式读取图片（convertFileSrc 失败时 fallback） |
| `scan_images_in_dir(dir)` | 扫描目录下的所有图片文件 |

配置文件路径：
- Windows: `%APPDATA%\photo-gallery\config.json`
- macOS: `~/Library/Application Support/photo-gallery/config.json`
- Linux: `~/.config/photo-gallery/config.json`

---

## 🛡 安全说明

- 应用只在用户显式选择的目录或文件上进行读取
- 图片仅在本地处理，不上传任何服务器
- `dialog:allow-open` 权限仅用于"打开文件"对话框
- `fs:default` 权限用于读取用户选择的图片文件

---

## 📝 开发注意事项

1. **Tauri v2** 使用了新的 API（`@tauri-apps/api/core` 而不是 `@tauri-apps/api`）
2. 原生 `prompt()` / `alert()` 在 Tauri 环境中不工作，已改用 `InputDialog` 组件替代
3. Ken Burns 动画使用了 `useRef` 作为挂载 flag，避免组件卸载后微任务死循环
4. 主题背景走静态渐变 + 低强度 `backdrop-filter(10px)`，避免每帧整页重绘

---

## 📜 License

MIT