# electron-template

**Repository Path**: zzginfo/electron-template

## Basic Information

- **Project Name**: electron-template
- **Description**: 项目模板：electron跨平台客户端。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-05
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Electron 应用容器

一个轻量级的 Electron 桌面应用容器，用于加载前端应用并提供原生功能支持。

## 📋 功能特性

- 🚀 加载远程或本地前端应用
- 📁 文件系统操作支持
- 🖥️ 系统功能集成
- ⚙️ 配置持久化
- 🔒 安全的 IPC 通信
- 📦 跨平台打包支持

## 🛠️ 技术栈

- **Electron**: 桌面应用框架
- **TypeScript**: 类型安全
- **ESBuild**: 快速构建
- **Electron Store**: 配置存储
- **Electron Builder**: 应用打包

## 📁 项目结构

```
electron-app-container/
├── electron/          # Electron 主进程代码
│   ├── main.ts       # 主进程入口
│   ├── preload.ts    # 预加载脚本
│   ├── config/       # 配置管理
│   ├── ipc/          # IPC 处理器
│   ├── services/     # 核心服务
│   └── utils/        # 工具函数
├── types/            # TypeScript 类型定义
├── resources/        # 资源文件
├── scripts/          # 构建脚本
└── DESIGN.md         # 详细设计文档
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- npm >= 9.0.0

### 安装依赖

```bash
npm install
```

### 配置环境变量

复制 `.env.example` 为 `.env.local` 并配置：

```bash
cp .env.example .env.local
```

编辑 `.env.local` 设置前端应用地址：

```env
FRONTEND_URL_DEV=http://localhost:3000
FRONTEND_URL_PROD=https://your-app.com
```

### 开发模式

1. 先启动你的前端应用（确保运行在配置的端口上）
2. 启动 Electron 应用：

```bash
npm run dev
```

### 构建应用

```bash
# 构建 TypeScript
npm run build

# 打包 Windows 版本
npm run build:win

# 打包 macOS 版本
npm run build:mac

# 打包 Linux 版本
npm run build:linux

# 打包所有平台
npm run build:all
```

## 🔌 API 使用

### 前端调用示例

```typescript
// 检测 Electron 环境
if (window.electronAPI) {
  // 文件操作
  const filePath = await window.electronAPI.fs.selectFile();
  const content = await window.electronAPI.fs.readFile(filePath);

  // 系统功能
  await window.electronAPI.system.showNotification('提示', '操作成功');

  // 配置管理
  await window.electronAPI.config.set('theme', 'dark');
  const theme = await window.electronAPI.config.get('theme');

  // 窗口控制
  window.electronAPI.window.minimize();
}
```

### TypeScript 类型支持

将 `types/global.d.ts` 复制到你的前端项目中以获得完整的类型提示。

## 📚 详细文档

查看 [DESIGN.md](./DESIGN.md) 了解详细的设计文档和架构说明。

## 🔧 开发工具

### 代码检查

```bash
npm run lint
```

### 代码格式化

```bash
npm run format
```

### 类型检查

```bash
npm run type-check
```

### 清理构建

```bash
npm run clean
```

## 🌟 可用的 IPC 频道

### 文件系统
- `fs:read` - 读取文件
- `fs:write` - 写入文件
- `fs:selectFile` - 选择文件
- `fs:selectFolder` - 选择文件夹
- `fs:openPath` - 打开路径
- `fs:showItemInFolder` - 在文件夹中显示

### 系统功能
- `system:version` - 获取应用版本
- `system:platform` - 获取操作系统平台
- `system:openExternal` - 打开外部链接
- `system:copyToClipboard` - 复制到剪贴板
- `system:showNotification` - 显示通知

### 窗口控制
- `window:minimize` - 最小化窗口
- `window:maximize` - 最大化窗口
- `window:close` - 关闭窗口
- `window:isMaximized` - 查询最大化状态
- `window:setFullscreen` - 设置全屏

### 配置管理
- `config:get` - 获取配置
- `config:set` - 设置配置
- `config:getAll` - 获取所有配置
- `config:delete` - 删除配置

## 🔒 安全特性

- ✅ Context Isolation 启用
- ✅ Node Integration 禁用
- ✅ Sandbox 模式启用
- ✅ Web Security 启用
- ✅ 类型安全的 IPC 通信

## 📝 待办事项

- [ ] 添加托盘图标支持
- [ ] 实现自动更新功能
- [ ] 添加全局快捷键
- [ ] 实现多窗口管理
- [ ] 添加深度链接支持

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题或建议，请联系开发团队。