Ant-Browser/docs

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

安装依赖

# 安装 Wails CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# 安装项目依赖
go mod tidy
cd frontend && npm install

开发模式

# Windows
bat\dev.bat

# 或直接使用 Wails
wails dev

构建应用

# 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 调用
• 支持分页、筛选、新建、编辑、删除

数据结构：

interface DataRecord {
  id: string
  name: string
  category: string
  status: string
  createdAt: string
  updatedAt: string
}

2. 指纹浏览器基础环境管理

功能特性：

• ✅ 多套浏览器环境配置与切换
• ✅ 默认环境一键设置
• ✅ 核心路径与连接类型配置
• ✅ 启动时自动检测环境路径

入口位置：

• 侧边栏：指纹浏览器 -> 基础环境

环境字段：

• coreId：环境标识
• coreName：环境名称
• corePath：核心路径（支持相对路径）
• connectorType：连接类型
• isDefault：是否默认

环境示例：

{
  "coreId": "chrome-114",
  "coreName": "Chrome 114",
  "corePath": "chrome/114",
  "connectorType": "standard",
  "isDefault": true
}

默认行为：

• 默认环境用于实例启动时的核心解析
• corePath 支持相对路径，会自动解析到可执行目录或工作目录

3. 表格组件

特性：

• 固定高度容器（默认 calc(100vh - 320px)）
• 内容在表格内滚动
• 固定表头（sticky 定位）
• 自定义列渲染
• 加载状态
• 空数据提示

使用示例：

<Table
  columns={columns}
  data={data}
  rowKey="id"
  maxHeight="500px"
  stickyHeader
/>

4. 分页组件

特性：

• 首页/末页快速跳转
• 上一页/下一页导航
• 智能页码显示（超过 5 页显示省略号）
• 每页条数选择（10/20/50）
• 总数显示

使用示例：

<Pagination
  current={page}
  total={total}
  pageSize={pageSize}
  onChange={setPage}
  onPageSizeChange={setPageSize}
/>

5. 主题系统

特性：

• 亮色/暗色主题切换
• CSS 变量管理颜色
• 平滑过渡动画
• 持久化存储

主题切换：

<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（警告提示）

<Alert
  type="success"
  title="成功"
  message="操作已完成"
  closable
  onClose={() => console.log('closed')}
/>

类型： success | error | warning | info

Toast（消息提示）

import { toast } from '@/shared/components'

toast.success('操作成功')
toast.error('操作失败')
toast.warning('警告信息')
toast.info('提示信息', 5000) // 5秒后消失

Modal（弹窗）

<Modal
  open={visible}
  onClose={() => setVisible(false)}
  title="标题"
  footer={
    <>
      <Button variant="secondary" onClick={onClose}>取消</Button>
      <Button onClick={onConfirm}>确定</Button>
    </>
  }
>
  <div>弹窗内容</div>
</Modal>

Drawer（抽屉）

<Drawer
  open={visible}
  onClose={() => setVisible(false)}
  title="侧边抽屉"
  placement="right"
  width="400px"
>
  <div>抽屉内容</div>
</Drawer>

方向： left | right | top | bottom

Popover（气泡卡片）

<Popover
  content={<div>提示内容</div>}
  placement="top"
  trigger="hover"
>
  <Button>悬停显示</Button>
</Popover>

触发方式： click | hover
位置： top | bottom | left | right

Dropdown（下拉菜单）

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（进度条）

// 线性进度条
<Progress percent={60} />
<Progress percent={100} status="success" size="lg" />

// 圆形进度条
<CircleProgress percent={75} size={120} />

状态： normal | success | error | warning

Loading & Skeleton

// 加载器
<Loading size="md" text="加载中..." />
<Loading fullscreen />

// 骨架屏
<Skeleton width="100%" height="20px" />
<Skeleton width="48px" height="48px" circle />

组件展示页面

访问 /components 路由查看所有组件的实时示例和交互演示。

---

数据管理

后端 API

所有数据管理 API 都通过 Wails 绑定暴露给前端：

// 获取数据列表（支持分页）
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)

前端调用

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 修改应用配置：

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 修改：

export const projectConfig = {
  name: '应用名称',
  shortName: '简称',
  primaryColor: 'primary',
}

---

构建部署

Windows 构建

bat\build.bat

构建产物：build/bin/news-platform.exe

跨平台构建

# macOS
wails build -platform darwin/universal

# Linux
wails build -platform linux/amd64

构建选项

编辑 wails.json 配置构建选项：

{
  "name": "news-platform",
  "outputfilename": "news-platform",
  "frontend:install": "npm install",
  "frontend:build": "npm run build",
  "wailsjsdir": "./frontend/src/wailsjs"
}

---

专项方案

• 配置发布与增量迁移方案（2026-03-09）

---

最佳实践

组件使用建议

场景	推荐组件	说明
操作反馈	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 变量：

:root {
  --color-accent: #your-color;
}

Q: 如何禁用某个功能模块？

A: 在 frontend/src/config/project.config.ts 修改：

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
状态： ✅ 生产就绪