https://github.com/1ureka/taggit
基於 Svelte 5 與 SvelteKit 開發的個人本地圖片管理工具，原生支持雲端同步架構，兼容 OneDrive 等共用目錄
https://github.com/1ureka/taggit
svelte sveltekit web
Last synced: 2 months ago
JSON representation
基於 Svelte 5 與 SvelteKit 開發的個人本地圖片管理工具，原生支持雲端同步架構，兼容 OneDrive 等共用目錄
- Host: GitHub
- URL: https://github.com/1ureka/taggit
- Owner: 1ureka
- Created: 2026-03-03T15:19:16.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-14T05:42:01.000Z (2 months ago)
- Last Synced: 2026-04-14T07:31:07.764Z (2 months ago)
- Topics: svelte, sveltekit, web
- Language: TypeScript
- Homepage:
- Size: 1.36 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Taggit
個人本地圖片管理工具，為本機圖片集提供標籤、評分、瀏覽與播放功能，在設計之初即導入雲端同步友好的架構，確保與 OneDrive 等共用目錄完美兼容
## 特色
| 特色 | 說明 |
| -------------- | ------------------------------------------------------------------------------------------------- |
| 標籤 + 評分 | 為每張圖片加上多個標籤與 0–5 星評分，以交集 / 差集、評分比較、多種排序快速找到目標 |
| 暫存 / 已提交 | 新圖片先進入暫存區，加完標籤與評分後才正式提交，靈感源自 Git |
| 拋棄式環境 | 程式只是殼，所有資料都在本地；隨時可刪除紀錄檔重置，也可手動在資料夾中增刪圖片 |
| 雲端同步友好 | 收藏目錄適合放在 OneDrive、Dropbox 等同步資料夾，運行時只寫入紀錄檔，圖片與檔名從頭到尾不會被更動 |
| 大量圖片也流暢 | 所有畫面都只渲染看得見的部分，無論是簡單的列表還是複雜的瀑布流布局 |
| 圖片播放器 | 不需要生成影片，自製播放器以更快且動態的方式提供進度條拖動、速度調整等操控 |
| 模糊佔位圖 | 圖片載入前先以模糊色塊預覽輪廓與色調，畫面不跳動也不留白 |
## 頁面導覽
| 頁面 | 路徑 | 功能 |
| ------------ | ----------- | -------------------------------------------------------------------------- |
| **Browse** | `/` | 搜尋、篩選、排序，以瀑布流瀏覽已提交圖片；點擊查看詳情 |
| **Tagger** | `/tagger` | 上傳或預覽暫存圖片、匯入紀錄，加標籤與評分後提交，支援批次操作與永久刪除 |
| **Editor** | `/editor` | 編輯已提交圖片的名稱、標籤與評分，支援批次操作與退回至暫存區 |
| **Compare** | `/compare` | 隨機抽兩張圖片並列比較，`Space` 鍵換下一組 |
| **Player** | `/player` | 全螢幕圖片播放器，播放 / 暫停、速度調整、反向播放、進度拖曳 |
| **Settings** | `/settings` | 設定收藏目錄、全域標籤重新命名、快取管理、資料修復、孤立記錄清理、備份下載 |
## 使用流程
1. **放入圖片**: 在 Tagger 上傳，或直接把檔案丟進收藏目錄的 `images/` 資料夾
2. **匯入紀錄**: 可在 Tagger 直接匯入符合格式的 JSON，使工作流程能與其他工具或腳本銜接
3. **整理**: 在 Tagger 為每張圖片加標籤、給評分，然後提交
4. **瀏覽與使用**: 提交後即可在 Browse 搜尋瀏覽、在 Player 播放、在 Compare 比較
5. **隨時修改**: 在 Editor 調整標籤與評分或者退回至暫存區重新整理
## 安裝與執行
需要 [Node.js](https://nodejs.org/)（建議最新 LTS 版本）。
```bash
npm install # 安裝依賴
npm run build # 建置
node build # 啟動，之後可隨時使用 Ctrl + C 停止，停止前會自動保存資料
```
首次啟動後開啟網頁，會自動引導你設定圖片收藏目錄。
## 收藏目錄結構
設定的收藏目錄會自動建立如下結構：
```
<收藏目錄>/
├── images/ # 所有圖片（放入即凍結）
└── db.json # 紀錄檔（唯一會被程式寫入的檔案）
```
## API 概覽
| 端點 | 方法 | 用途 |
| --------------------------- | -------------------- | --------------------------------------------- |
| `/api/committed` | GET / POST | 查詢已提交圖片（篩選 + 分頁）/ 匯入紀錄 |
| `/api/committed/[filename]` | GET / PATCH / DELETE | 取得 / 更新 / 取消提交單張圖片 |
| `/api/staged` | GET / POST | 列出暫存檔案 / 上傳圖片 |
| `/api/staged/[filename]` | POST / DELETE | 提交至資料庫 / 永久刪除 |
| `/api/images/[filename]` | GET | 取得圖片（支援 `?size=sm\|md\|xl`） |
| `/api/tags` | GET / POST / DELETE | 列出所有標籤 / 全域重新命名 / 全域刪除標籤 |
| `/api/settings/*` | 多種 | 備份、快取、metadata 修復、孤立記錄、目錄設定 |
## 進一步了解
本專案在前端架構做了不少與主流框架慣例相反的選擇，不走「一切皆組件」的路線，而是將 HTML 結構與互動邏輯拆成兩個正交的維度。
每個頁面只有一個 `.svelte` 檔案保持完整的 DOM 結構，所有互動邏輯收進獨立的 `.svelte.ts` class。這讓語意標記、無障礙屬性、CSS 能在一處通盤審視，同時互動邏輯沿職責邊界自由拆分，不被組件邊界綁架。
如果你對這套設計的取捨、Svelte 5 runes 的 class-based 用法、進階的 snippet、CSS 選擇器策略（為什麼刻意保持脆弱性而非健壯性）等話題感興趣，請參閱 [docs/frontend/index.md](docs/frontend/index.md)。