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 后端调用,使用示例:

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/)

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

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 - 辅助函数

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 操作

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 - 通知组件

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

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

Modal - 模态框

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

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

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

Loading - 加载指示器

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

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

开发工作流

1. 启动开发服务器

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 变量

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

主题切换

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

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

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

响应式设计

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

Tauri 集成

调用 Rust 后端命令

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

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

监听后端事件

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