feat: 初始化 Timeline 桌面客户端基础框架
添加 Electron 应用基础结构，包括： - package.json 配置文件 - 主进程和预加载脚本 - README 文档 - 自动更新功能 - 系统托盘和菜单 - IPC 通信机制
This commit is contained in:
300
README.md
Normal file
300
README.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Timeline 桌面客户端
|
||||
|
||||
> 记录生活中的每一个精彩时刻 - 桌面端应用
|
||||
|
||||
## 📖 项目简介
|
||||
|
||||
Timeline 桌面客户端是基于 Electron 构建的跨平台桌面应用，支持 Windows、macOS 和 Linux 系统。提供完整的离线支持、自动更新、系统托盘等功能。
|
||||
|
||||
## 🛠️ 技术栈
|
||||
|
||||
| 技术 | 版本 | 说明 |
|
||||
|-----|------|------|
|
||||
| Electron | 28.x | 跨平台桌面应用框架 |
|
||||
| Electron Vite | 2.x | Electron 构建工具 |
|
||||
| TypeScript | 5.x | 类型安全 |
|
||||
| Electron Builder | 24.x | 打包与分发 |
|
||||
| Electron Updater | 6.x | 自动更新 |
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
timeline-desktop/
|
||||
├── src/
|
||||
│ ├── main/ # 主进程代码
|
||||
│ │ ├── main.ts # 主进程入口
|
||||
│ │ └── preload.ts # Preload 脚本
|
||||
│ └── renderer/ # 渲染进程（可选）
|
||||
├── build/ # 构建资源
|
||||
│ ├── icon.ico # Windows 图标
|
||||
│ ├── icon.icns # macOS 图标
|
||||
│ └── icon.png # Linux 图标
|
||||
├── release/ # 打包输出目录
|
||||
├── package.json
|
||||
├── electron.vite.config.ts # Vite 配置
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Node.js >= 18.x
|
||||
- npm >= 9.x 或 pnpm >= 8.x
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
# 使用 npm
|
||||
npm install
|
||||
|
||||
# 或使用 pnpm
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 开发模式
|
||||
|
||||
```bash
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
开发模式下，应用会自动加载 `http://localhost:8080`（Web 前端开发服务器）。
|
||||
|
||||
### 构建打包
|
||||
|
||||
```bash
|
||||
# 构建所有平台
|
||||
npm run build
|
||||
npm run dist
|
||||
|
||||
# 仅构建 Windows
|
||||
npm run dist:win
|
||||
|
||||
# 仅构建 macOS
|
||||
npm run dist:mac
|
||||
|
||||
# 仅构建 Linux
|
||||
npm run dist:linux
|
||||
```
|
||||
|
||||
## 📦 打包输出
|
||||
|
||||
打包完成后，安装包位于 `release/` 目录：
|
||||
|
||||
```
|
||||
release/
|
||||
├── win-unpacked/ # Windows 免安装版
|
||||
├── Timeline Setup 1.0.0.exe # Windows 安装包
|
||||
├── Timeline-1.0.0.dmg # macOS 安装包
|
||||
├── Timeline-1.0.0.AppImage # Linux AppImage
|
||||
└── timeline-desktop_1.0.0_amd64.deb # Linux DEB 包
|
||||
```
|
||||
|
||||
## ⚙️ 配置说明
|
||||
|
||||
### 应用配置 (package.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"build": {
|
||||
"appId": "com.timeline.desktop",
|
||||
"productName": "Timeline",
|
||||
"directories": {
|
||||
"output": "release"
|
||||
},
|
||||
"win": {
|
||||
"icon": "build/icon.ico",
|
||||
"target": ["nsis"]
|
||||
},
|
||||
"mac": {
|
||||
"icon": "build/icon.icns",
|
||||
"target": ["dmg", "zip"]
|
||||
},
|
||||
"linux": {
|
||||
"icon": "build/icon.png",
|
||||
"target": ["AppImage", "deb"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 环境变量
|
||||
|
||||
| 变量名 | 说明 | 默认值 |
|
||||
|-------|------|-------|
|
||||
| NODE_ENV | 运行环境 | development |
|
||||
| API_URL | API 地址 | https://api.timeline.com |
|
||||
|
||||
## 🔄 自动更新
|
||||
|
||||
### 配置自动更新
|
||||
|
||||
1. 在 `package.json` 中配置发布地址：
|
||||
|
||||
```json
|
||||
{
|
||||
"build": {
|
||||
"publish": {
|
||||
"provider": "github",
|
||||
"owner": "your-github-username",
|
||||
"repo": "timeline-desktop"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 在 GitHub 创建 Release 并上传安装包
|
||||
|
||||
3. 应用启动时会自动检查更新
|
||||
|
||||
### 更新流程
|
||||
|
||||
```
|
||||
应用启动 → 检查更新 → 发现新版本 → 提示用户 → 下载更新 → 安装更新
|
||||
```
|
||||
|
||||
## 🔌 IPC 通信 API
|
||||
|
||||
### 渲染进程可用 API
|
||||
|
||||
```typescript
|
||||
// 获取应用版本
|
||||
const version = await window.electronAPI.getVersion();
|
||||
|
||||
// 获取操作系统平台
|
||||
const platform = await window.electronAPI.getPlatform();
|
||||
|
||||
// 检查更新
|
||||
const updateInfo = await window.electronAPI.checkUpdate();
|
||||
|
||||
// 下载更新
|
||||
await window.electronAPI.downloadUpdate();
|
||||
|
||||
// 安装更新
|
||||
await window.electronAPI.installUpdate();
|
||||
|
||||
// 打开外部链接
|
||||
await window.electronAPI.openExternal('https://timeline.com');
|
||||
|
||||
// 监听更新事件
|
||||
window.electronAPI.onUpdateAvailable((info) => {
|
||||
console.log('发现新版本:', info.version);
|
||||
});
|
||||
|
||||
window.electronAPI.onUpdateDownloaded((info) => {
|
||||
console.log('更新已下载:', info.version);
|
||||
});
|
||||
```
|
||||
|
||||
## 🖥️ 功能特性
|
||||
|
||||
### 系统托盘
|
||||
|
||||
- 最小化到托盘
|
||||
- 托盘菜单快捷操作
|
||||
- 点击托盘图标显示窗口
|
||||
|
||||
### 应用菜单
|
||||
|
||||
- 文件操作
|
||||
- 编辑功能（撤销/重做/复制/粘贴）
|
||||
- 视图控制（缩放/全屏）
|
||||
- 帮助链接
|
||||
|
||||
### 安全特性
|
||||
|
||||
- Context Isolation 启用
|
||||
- Node Integration 禁用
|
||||
- 安全的 Preload 脚本
|
||||
|
||||
## 🔐 签名与公证
|
||||
|
||||
### Windows 代码签名
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
set CSC_LINK=path/to/certificate.pfx
|
||||
set CSC_KEY_PASSWORD=your-password
|
||||
|
||||
# 打包时自动签名
|
||||
npm run dist:win
|
||||
```
|
||||
|
||||
### macOS 公证
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
set APPLE_ID=your-apple-id
|
||||
set APPLE_ID_PASSWORD=app-specific-password
|
||||
set APPLE_TEAM_ID=your-team-id
|
||||
|
||||
# 打包并公证
|
||||
npm run dist:mac
|
||||
```
|
||||
|
||||
## 📋 后续拓展计划
|
||||
|
||||
### 短期计划 (1-2 个月)
|
||||
|
||||
| 功能 | 描述 | 优先级 |
|
||||
|-----|------|-------|
|
||||
| 离线模式 | 支持离线浏览和编辑 | P0 |
|
||||
| 本地存储 | 数据本地缓存 | P0 |
|
||||
| 快捷键 | 全局快捷键支持 | P1 |
|
||||
| 多窗口 | 支持多窗口操作 | P1 |
|
||||
| 深色模式 | 跟随系统深色模式 | P2 |
|
||||
|
||||
### 中期计划 (3-6 个月)
|
||||
|
||||
| 功能 | 描述 | 优先级 |
|
||||
|-----|------|-------|
|
||||
| 批量导入 | 批量导入本地照片/视频 | P1 |
|
||||
| 本地备份 | 数据本地备份与恢复 | P1 |
|
||||
| 剪贴板监听 | 自动识别剪贴板图片 | P2 |
|
||||
| 文件拖放 | 拖放文件快速上传 | P2 |
|
||||
| 系统通知 | 原生系统通知 | P2 |
|
||||
|
||||
### 长期计划 (6-12 个月)
|
||||
|
||||
| 功能 | 描述 | 优先级 |
|
||||
|-----|------|-------|
|
||||
| 插件系统 | 支持第三方插件 | P2 |
|
||||
| 主题定制 | 自定义主题和样式 | P3 |
|
||||
| 多语言 | 国际化支持 | P3 |
|
||||
| 云同步 | 数据云同步 | P3 |
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### Q: 开发模式下白屏？
|
||||
|
||||
检查 Web 前端开发服务器是否启动：
|
||||
|
||||
```bash
|
||||
cd ../timeline-frontend
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Q: 打包后应用无法启动？
|
||||
|
||||
检查 `main.ts` 中的资源路径是否正确：
|
||||
|
||||
```typescript
|
||||
// 生产环境应使用打包后的路径
|
||||
mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));
|
||||
```
|
||||
|
||||
### Q: 自动更新不生效？
|
||||
|
||||
1. 检查 `publish` 配置是否正确
|
||||
2. 确保 GitHub Release 已发布
|
||||
3. 检查网络连接
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
- 问题反馈: https://github.com/timeline/timeline-desktop/issues
|
||||
- 文档地址: https://docs.timeline.com/desktop
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user