You've already forked SmartisanNote.Remake
216 lines
10 KiB
Markdown
216 lines
10 KiB
Markdown
# SmartisanNote.vue 项目概览
|
||
|
||
## 项目简介
|
||
|
||
这是一个基于 Vue 3 和 Vite 构建的单页 Web 应用（SPA），旨在模仿锤子科技（Smartisan）的便签应用。该项目使用 localStorage 进行本地数据持久化，支持便签的增删改查、文件夹管理、便签置顶、星标标记、基础设置（如云同步、深色模式）以及丰富的交互功能。
|
||
|
||
## 技术栈
|
||
|
||
* **核心框架**: Vue 3 (Composition API)
|
||
* **构建工具**: Vite
|
||
* **路由管理**: vue-router
|
||
* **状态管理**: Pinia (Vue 3 状态管理库)
|
||
* **UI 库**: 原生 CSS，使用了锤子便签的经典配色方案（定义在 `index.html` 的 CSS 变量中）
|
||
* **移动端支持**: Capacitor (用于构建 Android/iOS 应用)
|
||
* **样式预处理器**: Less
|
||
* **代码语言**: JavaScript (ES6+)
|
||
* **UI 组件库**: Ionic Framework
|
||
* **日期处理**: moment.js
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── android/ # Capacitor Android 项目文件
|
||
├── dist/ # 构建后的生产文件
|
||
├── node_modules/ # 项目依赖
|
||
├── public/ # 静态资源目录
|
||
├── src/
|
||
│ ├── common/ # 全局样式和通用工具
|
||
│ ├── components/ # 可复用的 Vue 组件 (Header, NoteItem, FolderItem)
|
||
│ ├── pages/ # 页面级别的 Vue 组件 (NoteList, NoteEditor, Folder, Settings)
|
||
│ ├── stores/ # Pinia 状态管理 stores
|
||
│ │ └── useAppStore.js # 全局状态管理 store
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── dateUtils.js # 日期处理工具，基于 moment.js
|
||
│ │ └── storage.js # localStorage 封装，负责数据的读写
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.js # 应用入口，初始化路由、Pinia 和挂载
|
||
├── index.html # HTML 模板，包含 CSS 变量定义
|
||
├── package.json # 项目元数据和脚本命令
|
||
├── vite.config.js # Vite 构建配置
|
||
└── capacitor.config.json # Capacitor 配置文件
|
||
```
|
||
|
||
## 开发与构建命令
|
||
|
||
* **安装依赖**: `npm install`
|
||
* **启动开发服务器**: `npm run dev`
|
||
* 默认端口: 3000
|
||
* 基于 Vite，支持热更新。
|
||
* **构建生产版本**: `npm run build`
|
||
* 使用 Vite 构建，并同步到 Capacitor 项目 (`npx cap sync`)。
|
||
* **构建所有版本**: `npm run build:all`
|
||
* 构建标准版本和 PWA 版本
|
||
* **部署PWA版本**: `npm run deploy:pwa`
|
||
* 构建并部署PWA版本到FTP服务器
|
||
* **在 Android 设备上运行**: `npm run android`
|
||
* 需要预先配置好 Android 开发环境。
|
||
|
||
## 核心功能
|
||
|
||
### 便签管理
|
||
* **增删改查**: 支持创建、查看、编辑和删除便签
|
||
* **星标标记**: 可以将重要便签标记为星标便签
|
||
* **置顶功能**: 支持将便签置顶显示在列表顶部
|
||
* **图片标记**: 可以标记便签中是否包含图片
|
||
* **滑动删除**: 支持右滑显示删除按钮，带有阻尼效果的交互体验
|
||
* **富文本编辑**: 支持加粗、居中、待办事项、列表、标题、引用等格式
|
||
|
||
### 文件夹管理
|
||
* **分类组织**: 支持创建文件夹对便签进行分类管理
|
||
* **默认文件夹**: 提供"全部便签"、"加星便签"、"回收站"等默认文件夹
|
||
|
||
### 搜索功能
|
||
* **全文搜索**: 支持按标题和内容搜索便签
|
||
* **实时过滤**: 搜索结果实时更新
|
||
|
||
### 设置功能
|
||
* **云同步**: 支持云同步设置（待实现）
|
||
* **深色模式**: 支持深色模式切换（待完善）
|
||
|
||
### 日期时间处理
|
||
* **智能格式化**: 根据时间范围自动格式化日期显示
|
||
* **多场景适配**: 不同页面使用不同的日期格式化规则
|
||
* **本地化支持**: 支持中文日期格式显示
|
||
|
||
## 代码规范与开发约定
|
||
|
||
* **状态管理**: 使用 Pinia 进行全局状态管理，通过 `useAppStore` composable 函数访问状态。
|
||
* **数据持久化**: 所有数据（便签、文件夹、设置）均通过 `src/utils/storage.js` 与 `localStorage` 进行交互。
|
||
* **路由**: 使用 `vue-router` 和 `createWebHashHistory` 进行前端路由管理。
|
||
* **UI 风格**: 颜色方案严格遵循 `index.html` 中定义的 CSS 变量，以保持锤子便签的视觉风格。
|
||
* **组件组织**: 页面组件 (`pages/`) 和可复用组件 (`components/`) 分离，结构清晰。
|
||
* **代码风格**: 采用标准的 Vue 3 Composition API 写法，使用 ES6 模块系统 (`import`/`export`)。
|
||
* **日期处理**: 使用 moment.js 进行日期处理，通过 `src/utils/dateUtils.js` 统一管理日期格式化逻辑。
|
||
|
||
## 样式
|
||
|
||
* 全局样式文件是位于 `common/` 目录下的 `base.css`。
|
||
* 使用 Codefun 原子类样式，用于快速布局。
|
||
* 样式规范应遵循项目中已有的风格。
|
||
* 使用 Less 作为 CSS 预处理器。
|
||
|
||
## JavaScript
|
||
|
||
* 严格遵循ES6规范。
|
||
* 遵循JavaScript函数式编程范式。
|
||
* 方法类函数应该使用 `function` 进行定义。
|
||
* 避免出现超过4个以上的 `ref`，超过4个则使用 `reactive`。
|
||
* 全局变量都集中放置于代码顶部。
|
||
* 变量名使用小驼峰命名法。
|
||
* 常量名使用全大写。
|
||
* 状态类变量命名参考 `isLogin`、`isOpen`。
|
||
* 事件类方法命名参考 `onClick`、`onSelect`。
|
||
* 变量都应该写有注释说明、类型说明。
|
||
* `Promise` 方法使用 `async` `await` 写法，并进行容错处理。
|
||
* 字符串拼接使用ES6的模板语法。
|
||
* JavaScript规范应遵循项目中已有的风格。
|
||
|
||
## 组件
|
||
|
||
* 全局组件放在 `components/` 目录下。
|
||
* 页面独立组件放在页面根目录下的 `components/`。
|
||
* 每个组件应该附带 `README.MD` 文档。
|
||
* 组件编写应遵循项目中已有的风格。
|
||
|
||
### Header 组件
|
||
* **动态按钮**: 根据页面状态显示不同的操作按钮（新建、保存、插入图片）
|
||
* **文件夹管理**: 支持文件夹展开/收起功能
|
||
|
||
### NoteItem 组件
|
||
* **滑动交互**: 支持右滑显示删除按钮，带有阻尼效果
|
||
* **状态切换**: 支持星标和置顶状态的切换
|
||
* **视觉反馈**: 滑动时便签夹会切换状态，提供直观的交互反馈
|
||
* **日期显示**: 显示格式化后的便签更新时间
|
||
|
||
### RichTextEditor 组件
|
||
* **富文本编辑**: 支持多种文本格式（加粗、居中、待办事项、列表、标题、引用）
|
||
* **图片插入**: 支持插入图片功能
|
||
* **图片删除**: 支持通过短按图片显示删除按钮，二次点击删除按钮执行删除操作
|
||
* **图片拖拽排序**: 支持长按图片进行拖拽排序
|
||
* **工具栏**: 提供浮动工具栏，支持格式化操作
|
||
|
||
## 页面
|
||
|
||
* 页面使用 Composition API (setup语法糖) 编写。
|
||
* 注释、结构规范应遵循项目中已有的风格。
|
||
|
||
### NoteListPage
|
||
* **便签列表**: 显示所有便签，支持置顶便签优先显示
|
||
* **文件夹管理**: 支持文件夹的展开和切换
|
||
* **搜索功能**: 提供便签搜索功能
|
||
* **交互反馈**: 显示便签总数和置顶便签数量
|
||
* **智能日期显示**: 根据时间范围显示不同的日期格式
|
||
* 今天：显示为 "今天 下午 4:00"
|
||
* 昨天：显示为 "昨天 下午 4:00"
|
||
* 超过两天但小于一周：显示为 "星期一 10/8 上午 3:00"
|
||
* 超过一周但小于一年：显示为 "10天前 9/20 下午 2:00"
|
||
* 超过一年：显示为 "635天前 2024/8/10 上午 9:00"
|
||
|
||
### NoteEditorPage
|
||
* **编辑模式**: 支持新建和编辑便签
|
||
* **富文本编辑**: 集成RichTextEditor组件，支持丰富的文本格式
|
||
* **图片插入**: 支持通过工具栏插入图片
|
||
* **图片删除**: 支持通过短按图片显示删除按钮，二次点击删除按钮执行删除操作
|
||
* **状态管理**: 根据路由参数判断是新建还是编辑模式
|
||
* **智能日期显示**: 根据时间范围显示不同的日期格式
|
||
* 今天：显示为 "今天 下午 4:00"
|
||
* 昨天：显示为 "昨天 下午 4:00"
|
||
* 超过两天但小于一个月：显示为 "10/8 上午 3:00"
|
||
* 超过一个月：显示为 "2024/8/10 上午 9:00"
|
||
|
||
## 状态管理 (Pinia)
|
||
|
||
项目现在使用 Pinia 作为状态管理解决方案，主要特点包括：
|
||
|
||
* **Store 定义**: 在 `src/stores/useAppStore.js` 中定义了全局状态 store
|
||
* **状态结构**: 包含 notes、folders 和 settings 三个主要状态
|
||
* **Getters**: 提供了计算属性如 starredNotesCount 和 allNotesCount
|
||
* **Actions**: 包含所有状态变更操作，如 addNote、updateNote、deleteNote 等
|
||
* **数据持久化**: 通过 storage.js 工具函数与 localStorage 进行数据交互
|
||
* **Mock 数据**: 支持加载预设的 mock 数据用于开发和演示
|
||
* **使用方式**: 在组件中通过 `const store = useAppStore()` 来访问状态和方法
|
||
|
||
## 新增功能特性
|
||
|
||
### 滑动交互
|
||
* **阻尼效果**: 右滑超过阈值后提供阻尼效果，增强交互体验
|
||
* **状态切换**: 滑动时便签夹会切换到展开状态，松开后根据位置决定是否保持展开
|
||
* **视觉反馈**: 滑动过程中提供实时视觉反馈
|
||
|
||
### Mock 数据
|
||
* **自动加载**: 当检测到无数据时自动加载预设的 mock 数据
|
||
* **手动加载**: 可通过 URL 参数 `?mock=true` 强制加载 mock 数据
|
||
* **丰富内容**: 包含多种类型的便签、文件夹和设置示例
|
||
* **固定日期**: 使用固定的日期值确保数据一致性
|
||
|
||
### 增强的便签功能
|
||
* **置顶支持**: 便签可以置顶显示在列表顶部
|
||
* **图片标记**: 可以标记便签是否包含图片
|
||
* **排序优化**: 置顶便签优先显示，按更新时间排序
|
||
|
||
### PWA 支持
|
||
* **离线使用**: 支持构建PWA版本，可离线使用
|
||
* **自动部署**: 支持一键构建并部署到FTP服务器
|
||
|
||
### 智能日期处理
|
||
* **统一管理**: 通过 `dateUtils.js` 统一管理所有日期处理逻辑
|
||
* **多格式支持**: 支持多种日期格式化方式以适应不同场景
|
||
* **本地化显示**: 支持中文友好的日期时间显示
|
||
* **场景适配**: 不同页面使用最适合的日期格式化规则
|
||
|
||
### 图片处理增强
|
||
* **图片删除优化**: 通过二次点击机制避免误删，提升用户体验
|
||
* **图片拖拽排序**: 支持长按图片进行拖拽排序，操作更直观
|
||
* **事件冲突解决**: 优化了图片删除按钮与容器短按事件的冲突问题 |