mirror of
https://github.com/black-ant/Ant-Browser.git
synced 2026-07-14 18:48:55 +08:00
Ant Browser Release Bot
f2cc3654a5
channel: release version: 1.0.0 source-ref: master published-at-utc: 2026-03-13T13:17:53Z
705 lines
14 KiB
Markdown
705 lines
14 KiB
Markdown
# Go-Wails 桌面应用脚手架文档
|
||
|
||
> 基于 Wails + React + TypeScript 的现代化桌面应用开发脚手架
|
||
|
||
## 目录
|
||
|
||
- [项目概述](#项目概述)
|
||
- [技术栈](#技术栈)
|
||
- [快速开始](#快速开始)
|
||
- [项目结构](#项目结构)
|
||
- [核心功能](#核心功能)
|
||
- [组件库](#组件库)
|
||
- [数据管理](#数据管理)
|
||
- [开发指南](#开发指南)
|
||
- [构建部署](#构建部署)
|
||
- [专项方案](#专项方案)
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
这是一个功能完整的桌面应用脚手架，提供了：
|
||
|
||
- ✅ 完整的项目结构和开发规范
|
||
- ✅ 24+ 个常用 UI 组件
|
||
- ✅ 数据管理模块（CRUD + 分页）
|
||
- ✅ 主题切换（亮色/暗色）
|
||
- ✅ 日志系统
|
||
- ✅ 配置管理
|
||
- ✅ 响应式布局
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
### 后端
|
||
- **Go 1.21+** - 主要编程语言
|
||
- **Wails v2** - 桌面应用框架
|
||
- **SQLite** - 嵌入式数据库
|
||
- **modernc.org/sqlite** - 纯 Go SQLite 驱动
|
||
|
||
### 前端
|
||
- **React 18** - UI 框架
|
||
- **TypeScript** - 类型安全
|
||
- **Vite** - 构建工具
|
||
- **TailwindCSS** - 样式框架
|
||
- **Zustand** - 状态管理
|
||
- **React Router** - 路由管理
|
||
- **Lucide React** - 图标库
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.21+
|
||
- Node.js 18+
|
||
- Wails CLI v2
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
# 安装 Wails CLI
|
||
go install github.com/wailsapp/wails/v2/cmd/wails@latest
|
||
|
||
# 安装项目依赖
|
||
go mod tidy
|
||
cd frontend && npm install
|
||
```
|
||
|
||
### 开发模式
|
||
|
||
```bash
|
||
# Windows
|
||
bat\dev.bat
|
||
|
||
# 或直接使用 Wails
|
||
wails dev
|
||
```
|
||
|
||
### 构建应用
|
||
|
||
```bash
|
||
# Windows
|
||
bat\build.bat
|
||
|
||
# 或直接使用 Wails
|
||
wails build
|
||
```
|
||
|
||
构建产物位于 `build/bin/` 目录。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── bat/ # Windows 批处理脚本
|
||
│ ├── build.bat # 构建脚本
|
||
│ ├── dev.bat # 开发脚本
|
||
│ └── generate-bindings.bat # 生成绑定脚本
|
||
├── docs/ # 项目文档
|
||
├── frontend/ # 前端代码
|
||
│ ├── src/
|
||
│ │ ├── config/ # 配置文件
|
||
│ │ ├── modules/ # 功能模块
|
||
│ │ │ ├── dashboard/ # 控制台
|
||
│ │ │ ├── data/ # 数据管理
|
||
│ │ │ ├── components/# 组件展示
|
||
│ │ │ └── settings/ # 系统设置
|
||
│ │ ├── shared/ # 共享资源
|
||
│ │ │ ├── components/# UI 组件库
|
||
│ │ │ ├── layout/ # 布局组件
|
||
│ │ │ └── theme/ # 主题系统
|
||
│ │ ├── store/ # 状态管理
|
||
│ │ └── wailsjs/ # Wails 绑定
|
||
│ ├── index.html
|
||
│ ├── package.json
|
||
│ └── vite.config.ts
|
||
├── internal/ # 后端内部包
|
||
│ ├── config/ # 配置管理
|
||
│ ├── data/ # 数据模块
|
||
│ │ ├── controller.go # 控制器
|
||
│ │ ├── service.go # 业务逻辑
|
||
│ │ ├── dao.go # 数据访问
|
||
│ │ ├── model.go # 数据模型
|
||
│ │ └── mock.go # 模拟数据
|
||
│ ├── database/ # 数据库
|
||
│ └── logger/ # 日志系统
|
||
├── app.go # 应用主逻辑
|
||
├── main.go # 程序入口
|
||
├── config.yaml # 配置文件
|
||
├── go.mod
|
||
└── wails.json # Wails 配置
|
||
```
|
||
|
||
---
|
||
|
||
## 核心功能
|
||
|
||
### 1. 数据管理模块
|
||
|
||
**功能特性：**
|
||
- ✅ 完整的 CRUD 操作
|
||
- ✅ 分页查询（默认 10 条/页）
|
||
- ✅ 多条件筛选（关键词、分类、状态）
|
||
- ✅ 30 条模拟数据自动生成
|
||
- ✅ 表格固定高度内滚动
|
||
- ✅ 固定表头
|
||
|
||
**后端实现：**
|
||
- `internal/data/service.go` - 业务逻辑层
|
||
- `internal/data/dao.go` - 数据访问层（SQLite）
|
||
- `internal/data/mock.go` - 模拟数据生成
|
||
- `app.go` - API 绑定
|
||
|
||
**前端实现：**
|
||
- `frontend/src/modules/data/DataPage.tsx` - 数据管理页面
|
||
- `frontend/src/modules/data/api.ts` - API 调用
|
||
- 支持分页、筛选、新建、编辑、删除
|
||
|
||
**数据结构：**
|
||
```typescript
|
||
interface DataRecord {
|
||
id: string
|
||
name: string
|
||
category: string
|
||
status: string
|
||
createdAt: string
|
||
updatedAt: string
|
||
}
|
||
```
|
||
|
||
### 2. 指纹浏览器基础环境管理
|
||
|
||
**功能特性：**
|
||
- ✅ 多套浏览器环境配置与切换
|
||
- ✅ 默认环境一键设置
|
||
- ✅ 核心路径与连接类型配置
|
||
- ✅ 启动时自动检测环境路径
|
||
|
||
**入口位置：**
|
||
- 侧边栏：指纹浏览器 -> 基础环境
|
||
|
||
**环境字段：**
|
||
- coreId：环境标识
|
||
- coreName：环境名称
|
||
- corePath：核心路径（支持相对路径）
|
||
- connectorType：连接类型
|
||
- isDefault：是否默认
|
||
|
||
**环境示例：**
|
||
```json
|
||
{
|
||
"coreId": "chrome-114",
|
||
"coreName": "Chrome 114",
|
||
"corePath": "chrome/114",
|
||
"connectorType": "standard",
|
||
"isDefault": true
|
||
}
|
||
```
|
||
|
||
**默认行为：**
|
||
- 默认环境用于实例启动时的核心解析
|
||
- corePath 支持相对路径，会自动解析到可执行目录或工作目录
|
||
|
||
### 3. 表格组件
|
||
|
||
**特性：**
|
||
- 固定高度容器（默认 `calc(100vh - 320px)`）
|
||
- 内容在表格内滚动
|
||
- 固定表头（sticky 定位）
|
||
- 自定义列渲染
|
||
- 加载状态
|
||
- 空数据提示
|
||
|
||
**使用示例：**
|
||
```tsx
|
||
<Table
|
||
columns={columns}
|
||
data={data}
|
||
rowKey="id"
|
||
maxHeight="500px"
|
||
stickyHeader
|
||
/>
|
||
```
|
||
|
||
### 4. 分页组件
|
||
|
||
**特性：**
|
||
- 首页/末页快速跳转
|
||
- 上一页/下一页导航
|
||
- 智能页码显示（超过 5 页显示省略号）
|
||
- 每页条数选择（10/20/50）
|
||
- 总数显示
|
||
|
||
**使用示例：**
|
||
```tsx
|
||
<Pagination
|
||
current={page}
|
||
total={total}
|
||
pageSize={pageSize}
|
||
onChange={setPage}
|
||
onPageSizeChange={setPageSize}
|
||
/>
|
||
```
|
||
|
||
### 5. 主题系统
|
||
|
||
**特性：**
|
||
- 亮色/暗色主题切换
|
||
- CSS 变量管理颜色
|
||
- 平滑过渡动画
|
||
- 持久化存储
|
||
|
||
**主题切换：**
|
||
```tsx
|
||
<ThemeSwitcher />
|
||
```
|
||
|
||
---
|
||
|
||
## 组件库
|
||
|
||
### 组件总览（24 个）
|
||
|
||
#### 基础组件
|
||
- **Button** - 按钮（4种变体，3种尺寸）
|
||
- **Card** - 卡片容器
|
||
- **Badge** - 徽章标签
|
||
|
||
#### 表单组件
|
||
- **Input** - 输入框
|
||
- **Textarea** - 文本域
|
||
- **Select** - 选择器
|
||
- **Switch** - 开关
|
||
- **FormItem** - 表单项容器
|
||
|
||
#### 数据展示
|
||
- **Table** - 表格
|
||
- **Pagination** - 分页器
|
||
- **StatCard** - 统计卡片
|
||
- **Progress** - 进度条
|
||
- **CircleProgress** - 圆形进度条
|
||
- **Skeleton** - 骨架屏
|
||
|
||
#### 反馈组件
|
||
- **Alert** - 警告提示
|
||
- **Toast** - 消息提示
|
||
- **Loading** - 加载状态
|
||
- **Modal** - 弹窗
|
||
- **ConfirmModal** - 确认对话框
|
||
- **Drawer** - 抽屉
|
||
|
||
#### 导航组件
|
||
- **Tabs** - 标签页
|
||
|
||
#### 浮层组件
|
||
- **Popover** - 气泡卡片
|
||
- **Dropdown** - 下拉菜单
|
||
|
||
#### 其他
|
||
- **ThemeSwitcher** - 主题切换器
|
||
|
||
### 组件使用示例
|
||
|
||
#### Alert（警告提示）
|
||
|
||
```tsx
|
||
<Alert
|
||
type="success"
|
||
title="成功"
|
||
message="操作已完成"
|
||
closable
|
||
onClose={() => console.log('closed')}
|
||
/>
|
||
```
|
||
|
||
**类型：** success | error | warning | info
|
||
|
||
#### Toast（消息提示）
|
||
|
||
```tsx
|
||
import { toast } from '@/shared/components'
|
||
|
||
toast.success('操作成功')
|
||
toast.error('操作失败')
|
||
toast.warning('警告信息')
|
||
toast.info('提示信息', 5000) // 5秒后消失
|
||
```
|
||
|
||
#### Modal（弹窗）
|
||
|
||
```tsx
|
||
<Modal
|
||
open={visible}
|
||
onClose={() => setVisible(false)}
|
||
title="标题"
|
||
footer={
|
||
<>
|
||
<Button variant="secondary" onClick={onClose}>取消</Button>
|
||
<Button onClick={onConfirm}>确定</Button>
|
||
</>
|
||
}
|
||
>
|
||
<div>弹窗内容</div>
|
||
</Modal>
|
||
```
|
||
|
||
#### Drawer（抽屉）
|
||
|
||
```tsx
|
||
<Drawer
|
||
open={visible}
|
||
onClose={() => setVisible(false)}
|
||
title="侧边抽屉"
|
||
placement="right"
|
||
width="400px"
|
||
>
|
||
<div>抽屉内容</div>
|
||
</Drawer>
|
||
```
|
||
|
||
**方向：** left | right | top | bottom
|
||
|
||
#### Popover（气泡卡片）
|
||
|
||
```tsx
|
||
<Popover
|
||
content={<div>提示内容</div>}
|
||
placement="top"
|
||
trigger="hover"
|
||
>
|
||
<Button>悬停显示</Button>
|
||
</Popover>
|
||
```
|
||
|
||
**触发方式：** click | hover
|
||
**位置：** top | bottom | left | right
|
||
|
||
#### Dropdown（下拉菜单）
|
||
|
||
```tsx
|
||
const items = [
|
||
{ key: 'copy', label: '复制', icon: <Copy /> },
|
||
{ key: 'divider', label: '', divider: true },
|
||
{ key: 'delete', label: '删除', danger: true },
|
||
]
|
||
|
||
<Dropdown
|
||
items={items}
|
||
onSelect={(key) => console.log(key)}
|
||
/>
|
||
```
|
||
|
||
#### Progress（进度条）
|
||
|
||
```tsx
|
||
// 线性进度条
|
||
<Progress percent={60} />
|
||
<Progress percent={100} status="success" size="lg" />
|
||
|
||
// 圆形进度条
|
||
<CircleProgress percent={75} size={120} />
|
||
```
|
||
|
||
**状态：** normal | success | error | warning
|
||
|
||
#### Loading & Skeleton
|
||
|
||
```tsx
|
||
// 加载器
|
||
<Loading size="md" text="加载中..." />
|
||
<Loading fullscreen />
|
||
|
||
// 骨架屏
|
||
<Skeleton width="100%" height="20px" />
|
||
<Skeleton width="48px" height="48px" circle />
|
||
```
|
||
|
||
### 组件展示页面
|
||
|
||
访问 `/components` 路由查看所有组件的实时示例和交互演示。
|
||
|
||
---
|
||
|
||
## 数据管理
|
||
|
||
### 后端 API
|
||
|
||
所有数据管理 API 都通过 Wails 绑定暴露给前端：
|
||
|
||
```go
|
||
// 获取数据列表（支持分页）
|
||
func (a *App) DataGetList(filters data.DataFilters, page, pageSize int) (*data.DataListResponse, error)
|
||
|
||
// 获取单条数据
|
||
func (a *App) DataGetByID(id string) (*data.DataRecord, error)
|
||
|
||
// 创建数据
|
||
func (a *App) DataCreate(req data.CreateDataRequest) (*data.DataRecord, error)
|
||
|
||
// 更新数据
|
||
func (a *App) DataUpdate(id string, req data.UpdateDataRequest) (*data.DataRecord, error)
|
||
|
||
// 删除数据
|
||
func (a *App) DataDelete(id string) error
|
||
|
||
// 批量删除
|
||
func (a *App) DataBatchDelete(ids []string) (int, error)
|
||
|
||
// 获取统计信息
|
||
func (a *App) DataGetStats() (*data.DataStats, error)
|
||
```
|
||
|
||
### 前端调用
|
||
|
||
```typescript
|
||
import { fetchDataList, createData, updateData, deleteData } from '@/modules/data/api'
|
||
|
||
// 获取列表
|
||
const result = await fetchDataList(filters, page, pageSize)
|
||
|
||
// 创建
|
||
await createData({ name: '名称', category: '分类', status: 'active' })
|
||
|
||
// 更新
|
||
await updateData(id, { name: '新名称' })
|
||
|
||
// 删除
|
||
await deleteData(id)
|
||
```
|
||
|
||
### 模拟数据
|
||
|
||
应用首次启动时会自动检查数据库：
|
||
- 如果数据库为空，自动生成 30 条模拟数据
|
||
- 如果已有数据，跳过初始化
|
||
|
||
模拟数据包含：
|
||
- 多种分类：技术、商业、设计、产品、其他
|
||
- 多种状态：启用、禁用、待处理
|
||
- 随机的创建和更新时间
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 添加新页面
|
||
|
||
1. 在 `frontend/src/modules/` 创建新模块目录
|
||
2. 创建页面组件
|
||
3. 在 `App.tsx` 添加路由
|
||
4. 在 `config/project.config.ts` 添加导航菜单
|
||
|
||
### 添加新组件
|
||
|
||
1. 在 `frontend/src/shared/components/` 创建组件文件
|
||
2. 在 `index.ts` 导出组件
|
||
3. 遵循现有组件的设计模式
|
||
4. 添加 TypeScript 类型定义
|
||
|
||
### 添加后端 API
|
||
|
||
1. 在 `internal/` 创建新模块
|
||
2. 实现 Service、DAO、Model 层
|
||
3. 在 `app.go` 添加 API 绑定方法
|
||
4. 运行 `wails dev` 自动生成前端绑定
|
||
|
||
### 配置管理
|
||
|
||
编辑 `config.yaml` 修改应用配置：
|
||
|
||
```yaml
|
||
app:
|
||
name: "应用名称"
|
||
|
||
runtime:
|
||
max_memory_mb: 512
|
||
gc_percent: 100
|
||
|
||
logging:
|
||
level: "info"
|
||
file_enabled: true
|
||
file_path: "data/logs/app.log"
|
||
|
||
database:
|
||
sqlite:
|
||
path: "app.db"
|
||
```
|
||
|
||
### 主题定制
|
||
|
||
在 `frontend/src/config/project.config.ts` 修改：
|
||
|
||
```typescript
|
||
export const projectConfig = {
|
||
name: '应用名称',
|
||
shortName: '简称',
|
||
primaryColor: 'primary',
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 构建部署
|
||
|
||
### Windows 构建
|
||
|
||
```bash
|
||
bat\build.bat
|
||
```
|
||
|
||
构建产物：`build/bin/news-platform.exe`
|
||
|
||
### 跨平台构建
|
||
|
||
```bash
|
||
# macOS
|
||
wails build -platform darwin/universal
|
||
|
||
# Linux
|
||
wails build -platform linux/amd64
|
||
```
|
||
|
||
### 构建选项
|
||
|
||
编辑 `wails.json` 配置构建选项：
|
||
|
||
```json
|
||
{
|
||
"name": "news-platform",
|
||
"outputfilename": "news-platform",
|
||
"frontend:install": "npm install",
|
||
"frontend:build": "npm run build",
|
||
"wailsjsdir": "./frontend/src/wailsjs"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 专项方案
|
||
|
||
- [配置发布与增量迁移方案（2026-03-09）](./CONFIG_RELEASE_AND_MIGRATION_PLAN_20260309.md)
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 组件使用建议
|
||
|
||
| 场景 | 推荐组件 | 说明 |
|
||
|------|---------|------|
|
||
| 操作反馈 | Toast | 轻量级，自动消失 |
|
||
| 重要提示 | Alert | 持久显示 |
|
||
| 确认操作 | ConfirmModal | 需用户确认 |
|
||
| 详细信息 | Modal | 复杂内容 |
|
||
| 侧边表单 | Drawer | 不遮挡主内容 |
|
||
| 简单提示 | Popover | 轻量级浮层 |
|
||
| 操作菜单 | Dropdown | 结构化菜单 |
|
||
|
||
### 性能优化
|
||
|
||
1. **表格分页** - 大数据量使用分页，避免一次加载过多
|
||
2. **虚拟滚动** - 超长列表考虑虚拟滚动
|
||
3. **懒加载** - 路由懒加载，按需加载模块
|
||
4. **图片优化** - 压缩图片，使用合适的格式
|
||
5. **代码分割** - Vite 自动代码分割
|
||
|
||
### 代码规范
|
||
|
||
1. **TypeScript** - 所有代码使用 TypeScript
|
||
2. **组件命名** - PascalCase（如 `DataPage`）
|
||
3. **文件命名** - PascalCase（如 `DataPage.tsx`）
|
||
4. **函数命名** - camelCase（如 `fetchData`）
|
||
5. **常量命名** - UPPER_SNAKE_CASE（如 `API_URL`）
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何修改应用名称？
|
||
|
||
A: 修改以下文件：
|
||
- `frontend/src/config/project.config.ts` - 前端显示名称
|
||
- `wails.json` - 构建产物名称
|
||
- `config.yaml` - 应用配置名称
|
||
|
||
### Q: 如何添加新的数据表？
|
||
|
||
A:
|
||
1. 在 `internal/database/sqlite.go` 的 `Migrate()` 方法添加建表 SQL
|
||
2. 创建对应的 Model、DAO、Service
|
||
3. 在 `app.go` 添加 API 绑定
|
||
|
||
### Q: 如何自定义主题颜色？
|
||
|
||
A: 修改 `frontend/src/index.css` 中的 CSS 变量：
|
||
|
||
```css
|
||
:root {
|
||
--color-accent: #your-color;
|
||
}
|
||
```
|
||
|
||
### Q: 如何禁用某个功能模块？
|
||
|
||
A: 在 `frontend/src/config/project.config.ts` 修改：
|
||
|
||
```typescript
|
||
export const featuresConfig = {
|
||
dashboard: true,
|
||
data: false, // 禁用数据管理
|
||
settings: true,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### 2026-01-06
|
||
|
||
**新增功能：**
|
||
- ✅ 数据管理模块（CRUD + 分页）
|
||
- ✅ 30 条模拟数据自动生成
|
||
- ✅ 表格固定高度内滚动
|
||
- ✅ 分页组件
|
||
- ✅ 24 个 UI 组件
|
||
- ✅ 组件展示页面
|
||
|
||
**组件库：**
|
||
- Alert、Toast、Loading、Skeleton
|
||
- Modal、ConfirmModal、Drawer
|
||
- Popover、Dropdown
|
||
- Progress、CircleProgress
|
||
- Badge、Tabs
|
||
|
||
**优化：**
|
||
- 表格支持固定表头
|
||
- 统一的设计语言和动画
|
||
- 完整的 TypeScript 类型支持
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
- **文档位置：** `docs/README.md`
|
||
- **组件展示：** 运行应用访问 `/components`
|
||
- **示例代码：** 查看 `frontend/src/modules/` 各模块
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
**构建时间：** 2026-01-06
|
||
**版本：** 1.0.0
|
||
**状态：** ✅ 生产就绪
|