122 lines
5.4 KiB
Markdown
122 lines
5.4 KiB
Markdown
# 在线工具箱（tool.xpcool.com）
|
||
|
||
纯前端在线工具站：**Vite + Vue3 + Pinia + TypeScript + UnoCSS + TDesign**。15 个常用工具，所有文件处理与计算均在浏览器本地完成，**不上传任何用户数据到服务器**。
|
||
|
||
## 功能特性
|
||
|
||
- 15 个实用工具：图片压缩/裁剪、二维码生成解析、JSON 格式化、时间戳转换、Base64 编解码、JWT 解析、Cron 表达式、进制转换、哈希计算、身份证解析、地址解析、URL 解析、翻译、图片 OCR 识别
|
||
- 左侧固定导航 + 中间内容区；PC Web 与移动端 H5 响应式适配（移动端为抽屉导航）
|
||
- 暗黑 / 浅色主题切换，选择持久化，刷新不丢失
|
||
- 每个工具独立路由、独立本地历史记录（localStorage）
|
||
- 所有文件上传支持点击选择 + 拖拽上传，图片自动缩略图回显；图片压缩支持批量、按质量/限制大小、等比缩放与 ZIP 批量下载
|
||
- 翻译工具参考有道翻译的交互：中/英/韩/日互译、双栏对照、单词释义（拼音 + 词性释义 + 例句）、真人发音朗读、逐句对照与来源标注
|
||
- 通用组件：拖拽上传、复制按钮、下载按钮、错误提示、历史记录面板
|
||
- 全部能力由浏览器原生 API、WebAssembly 与 npm 前端库实现，无任何 mock 后端接口、无 CDN 脚本引入
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 选型 |
|
||
| --- | --- |
|
||
| 构建 | Vite 6 + pnpm |
|
||
| 框架 | Vue 3（`<script setup>` 组合式 API） |
|
||
| 语言 | TypeScript（strict） |
|
||
| 状态 | Pinia |
|
||
| UI | TDesign Vue Next + tdesign-icons-vue-next |
|
||
| 样式 | UnoCSS 原子类 + SCSS（使用 TDesign 设计令牌变量） |
|
||
| 路由 | Vue Router 4（History 模式） |
|
||
|
||
工具依赖：`qrcode`、`jsqr`、`cropperjs`、`browser-image-compression`、`tesseract.js`、`cron-parser`、`spark-md5`、`jszip`、`pinyin-pro`（全部通过 npm 安装）。
|
||
|
||
## 快速开始
|
||
|
||
要求：Node.js ≥ 18，pnpm ≥ 8。
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
pnpm install
|
||
|
||
# 2. 启动开发服务器（默认 http://localhost:5173）
|
||
pnpm dev
|
||
|
||
# 3. 类型检查
|
||
pnpm type-check
|
||
|
||
# 4. 生产构建（输出到 dist/）
|
||
pnpm build
|
||
|
||
# 5. 本地预览构建产物
|
||
pnpm preview
|
||
```
|
||
|
||
## 页面路由
|
||
|
||
| 路由 | 工具 |
|
||
| --- | --- |
|
||
| `/` | 首页（工具卡片导航） |
|
||
| `/image-compress` | 图片压缩 |
|
||
| `/image-cropper` | 图片裁剪 |
|
||
| `/qrcode` | 二维码生成 / 解析 |
|
||
| `/json-format` | JSON 格式化 |
|
||
| `/timestamp` | 时间戳转换 |
|
||
| `/base64` | Base64 编解码 |
|
||
| `/jwt-parse` | JWT 解析 |
|
||
| `/cron` | Cron 表达式工具 |
|
||
| `/radix-convert` | 进制转换 |
|
||
| `/hash` | 哈希计算 |
|
||
| `/idcard` | 身份证解析 |
|
||
| `/address-parse` | 地址解析 |
|
||
| `/url-parse` | URL 解析 |
|
||
| `/translate` | 翻译（中英韩日） |
|
||
| `/ocr` | 图片 OCR 识别 |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
├── index.html # 入口 HTML（含防闪烁主题脚本）
|
||
├── package.json
|
||
├── vite.config.ts # Vite 配置（别名、分包）
|
||
├── unocss.config.ts # UnoCSS 配置（快捷类）
|
||
├── tsconfig.json / tsconfig.node.json
|
||
└── src/
|
||
├── main.ts # 应用入口（TDesign 全量注册、主题初始化）
|
||
├── App.vue
|
||
├── env.d.ts
|
||
├── assets/styles/ # 全局样式（TDesign 令牌变量）
|
||
├── router/
|
||
│ ├── index.ts # 路由表（由注册表生成）
|
||
│ └── tools.ts # ★ 工具注册表（唯一数据源）
|
||
├── stores/theme.ts # 主题状态（Pinia）
|
||
├── composables/
|
||
│ ├── useHistory.ts # 本地历史记录
|
||
│ ├── useClipboard.ts # 剪贴板复制
|
||
│ └── useDownload.ts # 本地文件下载
|
||
├── components/common/ # UploadDrop / CopyButton / DownloadButton / ErrorAlert / HistoryPanel
|
||
├── layout/ # MainLayout（响应式布局）+ SideNav（侧边导航）
|
||
├── utils/index.ts # 通用工具函数
|
||
└── views/ # 首页 + 14 个工具页面（每个工具一个目录）
|
||
```
|
||
|
||
## 部署
|
||
|
||
构建产物为纯静态文件，托管到任意静态服务器或 OSS/CDN 即可。使用 History 路由需配置回退（以 Nginx 为例）：
|
||
|
||
```nginx
|
||
location / {
|
||
root /usr/share/nginx/html;
|
||
index index.html;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
```
|
||
|
||
## 隐私说明
|
||
|
||
所有计算均在浏览器本地完成：图片压缩/裁剪/OCR 使用本地 Canvas/WASM，哈希使用本地 Web Crypto 与 spark-md5，历史记录仅存于本机 localStorage。项目不包含任何后端接口调用，用户文件永远不会离开浏览器。唯一例外是「翻译」工具：待翻译文本会发送至第三方免费翻译接口（有道 / 腾讯），单词释义与发音会请求 Free Dictionary API / Datamuse 与有道词典语音接口，页面已做提示。
|
||
|
||
## OCR 语言包说明
|
||
|
||
OCR 的引擎代码（worker + wasm）已随 npm 依赖打包进产物；语言数据属于运行时资源，默认从官方语言包源加载（首次识别约 20MB，浏览器会缓存）。如需完全离线部署：下载 `chi_sim.traineddata.gz` 与 `eng.traineddata.gz` 放入 `public/traineddata/`，并将 `src/views/ocr/OcrView.vue` 中的 `LANG_PATH` 改为 `${window.location.origin}/traineddata`。
|
||
|
||
## 维护与扩展
|
||
|
||
新增工具、修改架构、排查问题的完整说明见 [agents.md](./agents.md)。
|