# atom-reader

**Repository Path**: blaxey/atom-reader

## Basic Information

- **Project Name**: atom-reader
- **Description**: 原子阅读器，通过rust和tauri开发的一款轻量型电子书阅读器
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Atom Reader

> 一款基于 Tauri 2 + Vue 3 构建的现代跨平台电子书阅读器，支持 TXT、EPUB、PDF 三种格式，体积小巧、界面简洁。

---

## 目录

- [功能特性](#功能特性)
- [界面预览](#界面预览)
- [用户使用说明](#用户使用说明)
- [开发环境搭建](#开发环境搭建)
- [项目结构](#项目结构)
- [技术栈](#技术栈)
- [构建与发布](#构建与发布)
- [扩展开发指南](#扩展开发指南)
- [常见问题](#常见问题)

---

## 功能特性

| 功能 | 说明 |
|------|------|
| 📖 多格式支持 | TXT、EPUB、PDF 三种格式，按需懒加载解析引擎 |
| 🎨 多主题切换 | 日间、夜间、护眼（Sepia）、完全自定义四种主题 |
| 🖋 排版自定义 | 字体大小（12–36px）、行间距（1.0–3.0）、字间距（0–10px）自由调节 |
| 🎨 自定义颜色 | 自由选择背景色与字体色，实时预览 |
| 📚 书库管理 | 书籍列表、搜索过滤、右键删除、拖拽导入 |
| 💾 进度持久化 | 阅读进度、排版设置、主题偏好自动保存到本地 |
| 🔖 书签与批注 | 划词高亮（4 种颜色）、文字批注、批注导出 Markdown |
| 🪟 无边框窗口 | 自定义标题栏，支持最小化/最大化/关闭 |
| ⚡ 体积轻量 | Tauri 架构，安装包 < 10 MB |

---

## 界面预览

**书库页面** — 干净的双栏布局，支持搜索和拖拽导入

**阅读设置面板** — 主题切换 + 排版三联调节 + 实时预览

---

## 用户使用说明

### 导入书籍

有两种方式将书籍加入书库：

1. **点击按钮导入**：点击右上角的「**+ 导入书籍**」按钮，在系统文件选择框中选取 `.txt`、`.epub` 或 `.pdf` 文件（支持多选）。
2. **拖拽导入**：直接将文件从资源管理器拖入书库区域即可自动添加。

### 开始阅读

在书库网格中点击任意书籍封面即可进入阅读器。书籍格式会自动识别：
- **TXT**：自动按章节（"第X章"格式）分段渲染
- **EPUB**：使用 epub.js 渲染，支持目录导航
- **PDF**：使用 pdf.js 逐页渲染，显示页码进度

### 调节阅读体验

点击顶部工具栏右侧的 **⚙️ 设置图标**，打开阅读设置面板：

| 设置项 | 范围 | 说明 |
|--------|------|------|
| 显示主题 | 日间 / 夜间 / 护眼 / 自定义 | 点击切换，即时生效 |
| 背景色 | 任意 HEX 颜色 | 仅在「自定义」主题下可用 |
| 字体色 | 任意 HEX 颜色 | 仅在「自定义」主题下可用 |
| 字体大小 | 12 – 36 px | 拖动滑块，底部有实时预览 |
| 行间距 | 1.0 – 3.0 | 影响段落行与行之间的间隔 |
| 字间距 | 0 – 10 px | 影响每个字符之间的水平间距 |

所有设置会**自动保存**，下次启动时恢复。

### 目录 / 书签 / 批注侧边栏

在阅读器页面，点击顶部工具栏左侧的 **☰ 目录图标** 展开侧边栏，包含三个标签页：

- **目录**：展示当前书籍的章节结构，点击可跳转
- **书签**：查看已添加的书签，点击可跳转；顶部「添加书签」按钮快速标记当前位置
- **批注**：查看所有划词高亮和笔记

### 划词高亮

在阅读区域选中文字后，会弹出操作工具条，可选择：
- 🟡 黄色 / 🟢 绿色 / 🔵 蓝色 / 🩷 粉色 高亮
- 添加笔记（保存到批注列表）
- 复制文字到剪贴板

### 删除书籍

在书库页面对书籍封面**右键单击**，选择「从书库移除」即可删除（仅删除记录，不删除本地文件）。

---

## 开发环境搭建

### 前置要求

在开始之前，请确认以下工具已安装：

| 工具 | 版本要求 | 安装方式 |
|------|----------|---------|
| **Node.js** | ≥ 18.x | https://nodejs.org |
| **Rust** | stable (≥ 1.77) | https://rustup.rs |
| **Cargo** | 随 Rust 自动安装 | — |
| **WebView2** (Windows) | 系统内置或手动安装 | https://developer.microsoft.com/microsoft-edge/webview2/ |

> **macOS 额外要求**：需要安装 Xcode Command Line Tools：`xcode-select --install`
>
> **Linux 额外要求**：需要安装 WebKitGTK 及相关依赖，参见 [Tauri 官方文档](https://v2.tauri.app/start/prerequisites/#linux)

验证环境：

```bash
node -v       # ≥ 18
rustc -V      # stable
cargo -V
```

### 克隆与安装依赖

```bash
# 克隆仓库
git clone <repository-url>
cd atom-reader

# 安装前端依赖
npm install
```

> 首次运行时，Cargo 会自动下载并编译所有 Rust 依赖（约 200+ crates），**耗时 5–15 分钟**，后续增量编译只需数秒。

### 启动开发模式

```bash
npm run tauri dev
```

此命令会同时启动：
1. **Vite 开发服务器**（`http://localhost:1420`）— 前端 HMR 热更新
2. **Rust 后端**（`cargo run`）— 监听 `src-tauri/` 变化自动重编译

修改前端代码（`.vue`、`.ts`、`.css`）会立即热刷新；修改 Rust 代码（`src-tauri/src/`）会触发后端重编译。

### 仅运行前端（不启动 Tauri 窗口）

```bash
npm run dev
```

在浏览器打开 `http://localhost:1420` 预览 UI。注意：Tauri 原生 API（文件系统、对话框等）在此模式下不可用。

---

## 项目结构

```
atom-reader/
├── src/                        # 前端源码（Vue 3 + TypeScript）
│   ├── App.vue                 # 根组件，负责初始化 store
│   ├── main.ts                 # 应用入口
│   ├── router/
│   │   └── index.ts            # 路由配置（/ 书库，/reader 阅读器）
│   ├── stores/                 # Pinia 状态管理
│   │   ├── library.ts          # 书库：书籍列表、导入、删除、进度
│   │   ├── reader.ts           # 阅读器：当前书籍、目录、进度
│   │   ├── settings.ts         # 设置：主题、字体、自定义颜色
│   │   ├── bookmark.ts         # 书签管理
│   │   └── annotation.ts       # 批注管理（高亮、笔记、导出）
│   ├── views/
│   │   ├── LibraryView.vue     # 书库页面
│   │   └── ReaderView.vue      # 阅读器页面（含侧边栏、工具栏）
│   ├── components/
│   │   ├── layout/
│   │   │   ├── TitleBar.vue    # 自定义无边框标题栏
│   │   │   └── Sidebar.vue     # 书库左侧导航栏
│   │   ├── reader/
│   │   │   ├── TxtReader.vue   # TXT 渲染器
│   │   │   ├── EpubReader.vue  # EPUB 渲染器（epubjs）
│   │   │   └── PdfReader.vue   # PDF 渲染器（pdfjs-dist）
│   │   ├── settings/
│   │   │   └── SettingsPanel.vue  # 阅读设置浮层
│   │   ├── bookmark/
│   │   │   └── BookmarkPanel.vue  # 书签列表面板
│   │   └── annotation/
│   │       ├── AnnotationPanel.vue   # 批注列表面板
│   │       └── AnnotationPopup.vue   # 划词弹出工具条
│   └── styles/
│       ├── index.css           # 全局基础样式、滚动条
│       └── themes.css          # CSS 变量主题系统（light/dark/sepia/custom）
│
├── src-tauri/                  # Tauri / Rust 后端
│   ├── src/
│   │   ├── main.rs             # Rust 程序入口
│   │   └── lib.rs              # Tauri 命令实现
│   ├── capabilities/
│   │   └── default.json        # 权限声明（fs、dialog、store 等）
│   ├── Cargo.toml              # Rust 依赖配置
│   ├── tauri.conf.json         # Tauri 应用配置（窗口、打包等）
│   └── icons/                  # 应用图标（各平台格式）
│
├── public/                     # Vite 静态资源
├── index.html                  # HTML 入口模板
├── vite.config.ts              # Vite 配置
├── tsconfig.json               # TypeScript 配置
└── package.json                # npm 依赖与脚本
```

---

## 技术栈

### 前端

| 库 | 版本 | 用途 |
|----|------|------|
| Vue 3 | ^3.5 | UI 框架（Composition API） |
| Vue Router | ^5.0 | 单页路由（书库 ↔ 阅读器） |
| Pinia | ^3.0 | 状态管理（书库、设置、阅读进度） |
| epubjs | ^0.3.93 | EPUB 解析与渲染 |
| pdfjs-dist | ^5.6 | PDF 解析与 Canvas 渲染 |
| Vite | ^6.0 | 构建工具 |
| TypeScript | ~5.6 | 类型安全 |

### Tauri 插件

| 插件 | 用途 |
|------|------|
| `tauri-plugin-dialog` | 原生系统文件选择对话框 |
| `tauri-plugin-fs` | 读取本地文件系统（文件内容） |
| `tauri-plugin-store` | 持久化键值存储（设置、书库） |
| `tauri-plugin-opener` | 用系统默认程序打开文件/链接 |

### Rust 后端命令

| 命令 | 入参 | 返回 | 说明 |
|------|------|------|------|
| `read_text_file` | `path: String` | `Result<String>` | 读取文本文件，自动处理 UTF-8 |
| `get_file_metadata` | `path: String` | `Result<Object>` | 获取文件名、扩展名、大小 |

---

## 构建与发布

### 生产构建

```bash
npm run tauri build
```

构建产物位于 `src-tauri/target/release/bundle/`：

| 平台 | 格式 | 路径 |
|------|------|------|
| Windows | `.msi` / `.exe` | `bundle/msi/` 或 `bundle/nsis/` |
| macOS | `.dmg` / `.app` | `bundle/dmg/` |
| Linux | `.AppImage` / `.deb` | `bundle/appimage/` 或 `bundle/deb/` |

### 修改应用元信息

编辑 `src-tauri/tauri.conf.json`：

```json
{
  "productName": "Atom Reader",
  "version": "0.1.0",
  "identifier": "com.atom.reader",
  "app": {
    "windows": [
      {
        "title": "Atom Reader",
        "width": 1000,
        "height": 700,
        "decorations": false,
        "transparent": true
      }
    ]
  }
}
```

### 替换应用图标

将图标文件放入 `src-tauri/icons/` 并运行：

```bash
npm run tauri icon <path-to-icon.png>
```

该命令会自动生成所有平台所需的尺寸变体。

---

## 扩展开发指南

### 添加新的文件格式支持

1. 在 `src/views/ReaderView.vue` 中注册新的阅读器组件：

```vue
<!-- 示例：添加 MOBI 支持 -->
<MobiReader v-else-if="currentFormat === 'mobi'" />
```

2. 在 `src/stores/reader.ts` 中扩展格式类型：

```ts
const currentFormat = ref<'txt' | 'epub' | 'pdf' | 'mobi' | null>(null);
```

3. 在 `src/stores/library.ts` 的 `importBook` 方法中，将 `'mobi'` 加入允许的扩展名列表，并更新文件过滤器。

4. 新建 `src/components/reader/MobiReader.vue`，参照 `TxtReader.vue` 实现渲染逻辑。

### 添加新的 Tauri 后端命令

在 `src-tauri/src/lib.rs` 中添加函数并注册：

```rust
#[tauri::command]
fn my_command(arg: String) -> Result<String, String> {
    Ok(format!("result: {}", arg))
}

pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![
            read_text_file,
            get_file_metadata,
            my_command,  // 注册新命令
        ])
        // ...
}
```

在前端调用：

```ts
import { invoke } from '@tauri-apps/api/core';
const result = await invoke<string>('my_command', { arg: 'hello' });
```

### 添加新的主题

在 `src/styles/themes.css` 中添加新的 CSS 变量块：

```css
:root[data-theme="solarized"] {
  --bg-color: #fdf6e3;
  --text-primary: #657b83;
  --accent-color: #268bd2;
  /* ... 其余变量 */
}
```

在 `src/stores/settings.ts` 的 `ThemeMode` 类型中添加 `'solarized'`，并在 `SettingsPanel.vue` 的 `themes` 数组中追加对应配置项。

### 新增权限

若需要调用更多 Tauri 插件能力，在 `src-tauri/capabilities/default.json` 中声明：

```json
{
  "permissions": [
    "core:default",
    "fs:allow-write-text-file",
    "dialog:allow-save"
  ]
}
```

完整权限列表参见 [Tauri 官方权限文档](https://v2.tauri.app/plugin/)。

---

## 常见问题

**Q: 首次 `npm run tauri dev` 非常慢？**

A: 正常现象。Rust 需要从头编译所有依赖（约 200+ crates），首次约 5–15 分钟，后续增量编译只需几秒。建议保持良好的网络或配置 crates.io 镜像。

配置国内镜像（在 `%USERPROFILE%\.cargo\config.toml` 或 `~/.cargo/config.toml` 中）：

```toml
[source.crates-io]
replace-with = "ustc"

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"
```

---

**Q: Windows 上提示缺少 WebView2？**

A: 安装 [Microsoft Edge WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/)，Windows 11 系统已内置。

---

**Q: TXT 文件出现乱码？**

A: 当前 Rust 后端优先尝试 UTF-8 解码，GBK/GB2312 编码的文件会 fallback 到逐字节读取。建议先将文件转换为 UTF-8 编码（可用 Notepad++ 等工具），后续版本将增加自动编码检测（`chardet`）。

---

**Q: PDF 文件很大，加载很慢？**

A: 当前实现一次性渲染前 50 页（Canvas 绘制），大文件建议等待完整渲染。后续版本将改为虚拟滚动按需渲染。

---

**Q: 如何重置所有设置？**

A: 删除应用数据目录下的 `settings.json` 和 `library.json`，路径通常为：
- **Windows**: `%APPDATA%\com.atom.reader\`
- **macOS**: `~/Library/Application Support/com.atom.reader/`
- **Linux**: `~/.local/share/com.atom.reader/`

---

## 推荐开发工具

- **[VS Code](https://code.visualstudio.com/)** + 以下扩展：
  - [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) — Vue 3 语法支持
  - [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) — Tauri 项目集成
  - [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) — Rust 智能提示

---

## License

MIT