You've already forked SmartisanNote.Remake
优化 增强应用的离线支持功能
This commit is contained in:
yuantao
185
README.md
185
README.md
@@ -1,109 +1,130 @@
|
||||
# 锤子便签(重制版)
|
||||
# Smartisan Note 离线支持说明
|
||||
|
||||
这是一个基于 Vue 3、Vite 和 Pinia 的移动端现代化 Web 应用，旨在重现并改进经典的锤子便签应用体验。该项目采用 PWA（渐进式 Web 应用）技术，支持离线使用和安装到主屏幕。
|
||||
## 离线功能特性
|
||||
|
||||
## 主要特性
|
||||
Smartisan Note 应用支持完整的离线工作模式，确保用户在没有网络连接的情况下也能正常使用所有功能。
|
||||
|
||||
- **便签管理**: 创建、编辑、删除、置顶、加星便签
|
||||
- **文件夹管理**: 将便签分类到不同的文件夹中
|
||||
- **搜索功能**: 按标题或内容搜索便签
|
||||
- **回收站**: 临时存储已删除的便签，支持彻底删除
|
||||
- **多种排序方式**: 按更新时间、标题、星标状态排序
|
||||
- **PWA 支持**: 可安装为独立应用，支持离线使用
|
||||
- **本地存储**: 所有数据存储在浏览器的 IndexedDB 中
|
||||
- **富文本编辑**: 支持标题、待办事项、列表、加粗、引用、图片等多种格式
|
||||
- **动画效果**: 使用 Oku Motion 实现流畅的动画效果
|
||||
- **拖拽排序**: 支持图片拖拽排序
|
||||
### 核心离线功能
|
||||
|
||||
## 技术栈
|
||||
1. **完整的离线编辑**
|
||||
- 所有便签的创建、编辑、删除操作都可以在离线状态下完成
|
||||
- 支持富文本编辑器的所有功能（标题、待办事项、列表、加粗、引用、图片等）
|
||||
- 便签数据实时保存到本地 IndexedDB 数据库
|
||||
|
||||
- **框架**: Vue 3 (Composition API)
|
||||
- **构建工具**: Vite
|
||||
- **状态管理**: Pinia
|
||||
- **路由**: Vue Router
|
||||
- **UI 组件库**: Ionic Vue (部分使用)
|
||||
- **PWA 支持**: vite-plugin-pwa
|
||||
- **本地存储**: IndexedDB (通过 `src/utils/indexedDBStorage.js` 封装)
|
||||
- **CSS 预处理器**: Less
|
||||
- **动画库**: @oku-ui/motion
|
||||
- **拖拽库**: vue-draggable-plus
|
||||
2. **智能数据同步**
|
||||
- 网络恢复时自动同步离线期间的操作
|
||||
- 离线操作队列管理，确保数据一致性
|
||||
- 冲突解决机制（时间戳优先）
|
||||
|
||||
## 项目结构
|
||||
3. **资源缓存**
|
||||
- 核心静态资源（CSS、JS、图片）缓存到浏览器缓存
|
||||
- 应用界面在离线状态下完全可用
|
||||
- 字体和图标资源本地缓存
|
||||
|
||||
```
|
||||
.
|
||||
├── android/ # Capacitor Android 项目文件
|
||||
├── public/ # 静态资源目录 (图标等)
|
||||
├── src/ # 源代码目录
|
||||
│ ├── App.vue # 根组件
|
||||
│ ├── main.js # 应用入口文件
|
||||
│ ├── common/ # 通用样式
|
||||
│ ├── components/ # 可复用的 UI 组件
|
||||
│ ├── pages/ # 页面组件
|
||||
│ ├── stores/ # Pinia 状态管理
|
||||
│ └── utils/ # 工具函数
|
||||
├── index.html # 应用入口 HTML 文件
|
||||
├── package.json # 项目依赖和脚本
|
||||
├── vite.config.js # Vite 配置文件
|
||||
└── capacitor.config.json # Capacitor 配置文件
|
||||
```
|
||||
4. **网络状态感知**
|
||||
- 实时检测网络连接状态
|
||||
- 离线/在线状态切换时的用户提示
|
||||
- 网络类型识别（2G/3G/4G/WiFi）
|
||||
|
||||
## 开发与构建
|
||||
## 技术实现
|
||||
|
||||
### 前置条件
|
||||
### Service Worker
|
||||
|
||||
确保已安装 Node.js (>=14) 和 npm。
|
||||
应用使用自定义 Service Worker (`src/sw.js`) 实现以下功能：
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 开发
|
||||
|
||||
启动开发服务器:
|
||||
- **缓存策略**：
|
||||
- 静态资源：缓存优先
|
||||
- 数据请求：网络优先，失败时回退到缓存
|
||||
- API 请求：网络优先，失败时返回离线响应
|
||||
|
||||
- **后台同步**：
|
||||
- 支持后台数据同步
|
||||
- 离线操作队列处理
|
||||
|
||||
### IndexedDB 存储
|
||||
|
||||
使用 IndexedDB 作为本地数据存储：
|
||||
|
||||
- **数据结构**：
|
||||
- 便签存储 (`notes`)
|
||||
- 文件夹存储 (`folders`)
|
||||
- 设置存储 (`settings`)
|
||||
|
||||
- **离线队列**：
|
||||
- 操作记录到本地存储队列
|
||||
- 网络恢复时自动处理队列
|
||||
|
||||
### 网络状态管理
|
||||
|
||||
- 实时网络状态检测
|
||||
- 网络类型识别
|
||||
- 在线/离线状态切换处理
|
||||
|
||||
## 使用说明
|
||||
|
||||
### 离线使用
|
||||
|
||||
1. 应用首次加载时会缓存核心资源
|
||||
2. 断网后应用仍可正常使用所有功能
|
||||
3. 离线期间的所有操作都会保存到本地
|
||||
|
||||
### 数据同步
|
||||
|
||||
1. 网络恢复时自动开始同步
|
||||
2. 可在设置中查看同步状态
|
||||
3. 支持手动触发同步（未来版本）
|
||||
|
||||
## 开发说明
|
||||
|
||||
### 构建命令
|
||||
|
||||
```bash
|
||||
# 开发模式
|
||||
npm run dev
|
||||
```
|
||||
|
||||
这将在 `http://localhost:3000` 启动应用。
|
||||
|
||||
### 构建
|
||||
|
||||
构建标准 Web 应用:
|
||||
|
||||
```bash
|
||||
# 构建标准版本
|
||||
npm run build
|
||||
```
|
||||
|
||||
构建 PWA 应用:
|
||||
|
||||
```bash
|
||||
# 构建PWA版本（支持离线）
|
||||
npm run build:pwa
|
||||
```
|
||||
|
||||
构建所有版本 (标准 + PWA):
|
||||
|
||||
```bash
|
||||
# 构建所有版本
|
||||
npm run build:all
|
||||
```
|
||||
|
||||
### 部署 PWA
|
||||
|
||||
构建 PWA 并上传到服务器:
|
||||
|
||||
```bash
|
||||
# 部署PWA版本
|
||||
npm run deploy:pwa
|
||||
```
|
||||
|
||||
这将执行 `vite build --mode pwa` 并运行 `upload-pwa.js` 脚本。
|
||||
### 目录结构
|
||||
|
||||
### Android 应用
|
||||
```
|
||||
src/
|
||||
├── sw.js # Service Worker 实现
|
||||
├── utils/
|
||||
│ ├── indexedDBStorage.js # IndexedDB 存储管理
|
||||
│ ├── networkUtils.js # 网络状态工具
|
||||
│ └── dateUtils.js # 日期工具
|
||||
├── stores/
|
||||
│ └── useAppStore.js # 应用状态管理
|
||||
├── components/
|
||||
│ └── ... # UI 组件
|
||||
└── pages/
|
||||
├── NoteListPage.vue # 便签列表页面
|
||||
├── NoteEditorPage.vue # 便签编辑页面
|
||||
└── SettingsPage.vue # 设置页面
|
||||
```
|
||||
|
||||
运行 Android 应用:
|
||||
## 测试离线功能
|
||||
|
||||
```bash
|
||||
npm run android
|
||||
```
|
||||
1. 使用浏览器开发者工具的 Network Throttling 功能模拟离线环境
|
||||
2. 在离线状态下创建、编辑、删除便签
|
||||
3. 恢复网络连接，观察数据同步过程
|
||||
4. 检查离线期间的操作是否正确同步
|
||||
|
||||
## 未来改进
|
||||
|
||||
1. 添加手动同步按钮
|
||||
2. 增强冲突解决机制
|
||||
3. 支持多设备数据同步
|
||||
4. 添加数据导出/导入功能
|
||||
5. 增强离线状态下的用户提示
|
||||
Reference in New Issue
Block a user