cutThink_lite/docs/FRONTEND_GUIDE.md

# 前端开发快速参考

## 目录结构说明

```
cutThink_lite/
├── src/                    # 源代码目录
│   ├── api/                # Tauri 后端 API 封装
│   ├── components/         # UI 组件
│   │   ├── views/         # 页面视图组件
│   │   └── shared/        # 共享组件
│   ├── store/             # 状态管理
│   └── utils/             # 工具函数
├── index.html             # HTML 入口
├── main.js                # JavaScript 入口
├── style.css              # 全局样式
└── vite.config.js         # Vite 配置
```

## 核心模块说明

### 1. API 模块 (`src/api/`)

封装所有 Tauri 后端调用,使用示例:

```javascript
import { screenshotAPI, uploadAPI, settingsAPI } from '@/api/index.js'

// 截图
const result = await screenshotAPI.captureFull()

// 上传
const url = await uploadAPI.upload('/path/to/image.png')

// 获取设置
const settings = await settingsAPI.get()
```

### 2. 状态管理 (`src/store/`)

响应式状态管理,使用示例:

```javascript
import { useStore } from '@/store/index.js'

const store = useStore()

// 读取状态
console.log(store.currentView)
console.log(store.screenshots)

// 更新状态
store.setCurrentView('gallery')
store.addScreenshot(newScreenshot)

// 监听状态变化
appStore.subscribe((state, prevState) => {
  console.log('状态变化:', state, prevState)
})
```

### 3. 工具函数 (`src/utils/`)

#### helpers.js - 辅助函数

```javascript
import {
  formatDate,
  formatFileSize,
  debounce,
  throttle,
  deepClone,
  generateId,
  copyText,
  compressImage,
  parseHotkey,
  delay
} from '@/utils/helpers.js'

// 日期格式化
formatDate(date, 'relative')  // "5 分钟前"

// 文件大小格式化
formatFileSize(1024)  // "1 KB"

// 防抖
const debouncedSearch = debounce(search, 300)

// 延迟
await delay(1000)
```

#### dom.js - DOM 操作

```javascript
import {
  $, $$,
  createElement,
  show, hide,
  addClass, removeClass,
  delegate,
  dispatchEvent
} from '@/utils/dom.js'

// 查询元素
const btn = $('.btn-primary')
const items = $$('.list-item')

// 创建元素
const div = createElement('div', {
  className: 'my-class',
  text: 'Hello',
  attrs: { id: 'my-id' }
})

// 显示/隐藏
show(element)
hide(element)

// 委托事件
delegate(parent, '.btn', 'click', handler)
```

### 4. 组件使用

#### Notification - 通知组件

```javascript
import { Notification } from '@/components/shared/index.js'

Notification.success('操作成功')
Notification.error('操作失败')
Notification.warning('警告信息')
Notification.info('提示信息')
```

#### Modal - 模态框

```javascript
import { Modal } from '@/components/shared/index.js'

// 确认对话框
const result = await Modal.confirm({
  title: '确认删除',
  content: '确定要删除吗?'
})

// 警告对话框
await Modal.alert({
  title: '提示',
  content: '操作完成'
})
```

#### Loading - 加载指示器

```javascript
import { Loading } from '@/components/shared/index.js'

Loading.show('加载中...')
// 执行操作
Loading.hide()
```

## 开发工作流

### 1. 启动开发服务器

```bash
npm run dev
```

服务器会在 http://localhost:5173 启动

### 2. 修改代码后

Vite 的 HMR (热模块替换) 会自动刷新浏览器,无需手动重启。

### 3. 调试技巧

- 使用浏览器开发者工具 (F12)
- 在代码中使用 `console.log()` 调试
- 检查 Network 面板查看 Tauri 调用

### 4. 添加新功能

1. 在 `src/api/` 添加 API 调用
2. 在 `src/store/` 添加状态(如需要)
3. 在 `src/components/views/` 创建或修改视图
4. 在 `main.js` 中集成新功能

## 样式开发

### CSS 变量

```css
/* 使用预定义的颜色变量 */
color: var(--text-primary);
background: var(--bg-secondary);
border-color: var(--border-color);
```

### 主题切换

```javascript
// 切换到深色模式
document.documentElement.setAttribute('data-theme', 'dark')

// 切换到浅色模式
document.documentElement.setAttribute('data-theme', 'light')

// 跟随系统
document.documentElement.setAttribute('data-theme', 'system')
```

### 响应式设计

```css
/* 使用媒体查询 */
@media (max-width: 768px) {
  .sidebar {
    width: 60px;
  }
}
```

## Tauri 集成

### 调用 Rust 后端命令

```javascript
import { invoke } from '@tauri-apps/api/tauri'

// 调用后端命令
const result = await invoke('command_name', {
  param1: 'value1',
  param2: 'value2'
})
```

### 监听后端事件

```javascript
import { listen } from '@tauri-apps/api/event'

// 监听事件
const unlisten = await listen('event-name', (event) => {
  console.log('收到事件:', event.payload)
})

// 取消监听
unlisten()
```

## 常见问题

### Q: 如何添加新页面?

A: 在 `src/components/views/` 创建新的视图组件,然后在 `index.html` 中添加对应的 HTML 结构。

### Q: 如何修改样式?

A: 可以:
1. 修改 `style.css` 全局样式
2. 在组件中使用内联样式
3. 添加新的 CSS 文件并导入

### Q: Tauri 命令调用失败?

A: 确保:
1. Rust 后端已实现该命令
2. 命令已在 `tauri.conf.json` 中注册
3. 参数名称和类型匹配

### Q: HMR 不工作?

A: 检查:
1. Vite 开发服务器是否运行
2. 文件是否在监听目录中
3. 浏览器控制台是否有错误

## 性能优化建议

1. **使用防抖/节流**: 对频繁触发的事件使用 `debounce` 或 `throttle`
2. **按需加载**: 大型组件可以按需加载
3. **避免频繁 DOM 操作**: 批量更新 DOM
4. **使用事件委托**: 减少事件监听器数量
5. **优化图片**: 使用 `compressImage` 压缩大图片

## 下一步

- 阅读 `src/api/` 了解可用的 API
- 查看 `src/components/views/` 了解现有组件
- 运行 `npm run dev` 开始开发

---

更新时间: 2026-02-12