You've already forked SmartisanNote.Remake
199 lines
7.0 KiB
Markdown
199 lines
7.0 KiB
Markdown
# SmartisanNote.Remake - IFLOW 上下文
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 Vue 3、Vite 和 Pinia 的移动端现代化 Web 应用，旨在重现并改进经典的锤子便签应用体验。该项目采用 PWA（渐进式 Web 应用）技术，支持离线使用和安装到主屏幕。
|
||
|
||
### 主要技术栈
|
||
|
||
* **框架**: 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
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── android/ # Capacitor Android 项目文件
|
||
├── public/ # 静态资源目录 (图标等)
|
||
│ ├── assets/ # 应用资源文件
|
||
│ │ └── icons/ # 图标文件
|
||
│ │ ├── drawable-xxhdpi/ # Android 图标资源
|
||
│ │ └── drawable-xxxhdpi/ # Android 图标资源
|
||
│ └── icons/ # PWA 图标
|
||
│ ├── icon-192.png
|
||
│ └── icon-512.png
|
||
├── src/ # 源代码目录
|
||
│ ├── App.vue # 根组件
|
||
│ ├── main.js # 应用入口文件
|
||
│ ├── common/ # 通用样式
|
||
│ │ └── base.css # 基础样式文件
|
||
│ ├── components/ # 可复用的 UI 组件
|
||
│ │ ├── FolderItem.vue # 文件夹项组件
|
||
│ │ ├── FolderManage.vue # 文件夹管理组件
|
||
│ │ ├── Header.vue # 头部组件
|
||
│ │ ├── Modal.vue # 模态框组件
|
||
│ │ ├── NoteItem.vue # 便签项组件
|
||
│ │ ├── RichTextEditor.vue # 富文本编辑器组件
|
||
│ │ ├── Search.vue # 搜索组件
|
||
│ │ ├── SettingGroup.vue # 设置组组件
|
||
│ │ └── SwitchButton.vue # 开关按钮组件
|
||
│ ├── pages/ # 页面组件
|
||
│ │ ├── FolderPage.vue # 文件夹页面
|
||
│ │ ├── NoteEditorPage.vue # 便签编辑页面
|
||
│ │ ├── NoteListPage.vue # 便签列表页面
|
||
│ │ └── SettingsPage.vue # 设置页面
|
||
│ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── useAppStore.js # 应用状态管理
|
||
│ │ └── useAppStore.test.js # 应用状态管理测试
|
||
│ └── utils/ # 工具函数
|
||
│ ├── dateUtils.js # 日期工具函数
|
||
│ └── indexedDBStorage.js # IndexedDB 存储封装
|
||
├── index.html # 应用入口 HTML 文件
|
||
├── .nvmdrc # node.js 版本
|
||
├── package.json # 项目依赖和脚本
|
||
├── vite.config.js # Vite 配置文件
|
||
└── capacitor.config.json # Capacitor 配置文件
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
* **便签管理**: 创建、编辑、删除、置顶、加星便签。
|
||
* **文件夹管理**: 将便签分类到不同的文件夹中。
|
||
* **搜索功能**: 按标题或内容搜索便签。
|
||
* **回收站**: 临时存储已删除的便签，支持彻底删除。
|
||
* **多种排序方式**: 按更新时间、标题、星标状态排序。
|
||
* **PWA 支持**: 可安装为独立应用，支持离线使用。
|
||
* **本地存储**: 所有数据存储在浏览器的 `IndexedDB` 中。
|
||
* **富文本编辑**: 支持标题、待办事项、列表、加粗、引用、图片等多种格式。
|
||
* **动画效果**: 使用 Oku Motion 实现流畅的动画效果。
|
||
* **拖拽排序**: 支持图片拖拽排序。
|
||
* **深色模式**: (计划中) 支持切换深色/浅色主题。
|
||
* **云同步**: (计划中) 支持多设备间数据同步。
|
||
|
||
## 开发与构建
|
||
|
||
### 前置条件
|
||
|
||
确保已安装 Node.js (>=14) 和 npm。
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 开发
|
||
|
||
启动开发服务器:
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
这将在 `http://localhost:3000` 启动应用。
|
||
|
||
### 构建
|
||
|
||
构建标准 Web 应用:
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建 PWA 应用:
|
||
|
||
```bash
|
||
npm run build:pwa
|
||
```
|
||
|
||
构建所有版本 (标准 + PWA):
|
||
|
||
```bash
|
||
npm run build:all
|
||
```
|
||
|
||
### 部署 PWA
|
||
|
||
构建 PWA 并上传到服务器:
|
||
|
||
```bash
|
||
npm run deploy:pwa
|
||
```
|
||
|
||
这将执行 `vite build --mode pwa` 并运行 `upload-pwa.js` 脚本。
|
||
|
||
### Android 应用
|
||
|
||
运行 Android 应用:
|
||
|
||
```bash
|
||
npm run android
|
||
```
|
||
|
||
## 代码规范与约定
|
||
|
||
### 代码风格与结构
|
||
|
||
* **框架**: Vue 3 (Composition API) 与 Pinia 状态管理
|
||
* **构建工具**: Vite
|
||
* **路由**: Vue Router
|
||
* **UI 组件库**: Ionic Vue (部分使用)
|
||
* **PWA 支持**: vite-plugin-pwa
|
||
* **本地存储**: IndexedDB (通过 `src/utils/indexedDBStorage.js` 封装)
|
||
* **CSS 预处理器**: Less
|
||
* **CSS 命名**: 使用 BEM 命名规范，部分使用原子化 CSS 类名（以 `code-fun-` 开头）
|
||
* **响应式设计**: 使用 viewport 单位 (vw/vh) 和 CSS 变量实现响应式布局
|
||
* **图标**: 使用 PNG 图片作为图标，存储在 `public/assets/icons/` 目录下
|
||
* **动画**: 使用 Oku Motion 实现动画效果
|
||
* **拖拽**: 使用 vue-draggable-plus 实现拖拽功能
|
||
|
||
### 命名规范
|
||
|
||
* **文件命名**:
|
||
* 组件文件使用 PascalCase 命名法，如 `NoteItem.vue`
|
||
* 页面文件使用 PascalCase 命名法，如 `NoteListPage.vue`
|
||
* 工具文件使用 camelCase 命名法，如 `dateUtils.js`
|
||
* Store 文件使用 `use` 前缀 + PascalCase 命名法，如 `useAppStore.js`
|
||
* **组件命名**: 使用 PascalCase 命名法，如 `NoteItem`
|
||
* **变量命名**: 使用 camelCase 命名法，如 `noteToDelete`
|
||
* **常量命名**: 使用 UPPER_SNAKE_CASE 命名法，如 `NOTES_KEY`
|
||
* **函数命名**: 使用 camelCase 命名法，如 `handleNotePress`
|
||
|
||
### 代码组织
|
||
|
||
* **组件结构**:
|
||
* 使用 `<template>`, `<script setup>`, `<style>` 三段式结构
|
||
* 计算属性 (`computed`) 置于响应式数据之后
|
||
* 方法 (`methods`) 置于计算属性之后
|
||
* 生命周期钩子 (`onMounted`, `onUnmounted` 等) 置于方法之前
|
||
* 样式使用 Less 预处理器，并使用 `scoped` 属性避免样式污染
|
||
* **状态管理**:
|
||
* 使用 Pinia 进行全局状态管理
|
||
* Store 文件中按照 state, getters, actions 的顺序组织代码
|
||
* 异步操作使用 `async/await` 语法
|
||
* **工具函数**:
|
||
* 工具函数按功能模块划分文件，如 `indexedDBStorage.js`, `dateUtils.js`
|
||
* 工具函数使用 `export const` 导出
|
||
|
||
### 注释规范
|
||
|
||
* **单行注释**: 使用 `//` 进行单行注释，注释应位于代码上方或行尾
|
||
* **多行注释**: 使用 `/* */` 进行多行注释，用于解释复杂逻辑
|
||
* **函数注释**: 使用 JSDoc 格式为函数添加注释，包含函数描述、参数类型和返回值类型
|
||
|
||
## 代码提交规范
|
||
|
||
* 提交信息应清晰描述变更内容，如 `修复 搜索功能空值检查` 或 `新增 删除按钮功能`。
|
||
* 对于功能性的新增或修改，使用 `新增` 前缀。
|
||
* 对于错误修复，使用 `修复` 前缀。
|
||
* 对于性能优化、代码重构（既不修复错误也不添加功能），使用 `优化` 前缀。
|
||
* 对于文档更新，使用 `文档` 前缀。
|
||
* 提交信息应使用中文。 |