cutThink_lite/docs/GALLERY_USAGE.md

# 图库视图使用指南

## 概述

图库视图是 CutThink Lite 的核心功能之一，提供了强大的图片管理、搜索、筛选和批量操作功能。

## 功能特性

### 1. 图库网格视图

- **网格/列表视图切换**
  - 支持网格和列表两种显示模式
  - 网格视图：适合浏览大量图片
  - 列表视图：适合查看详细信息

- **懒加载与无限滚动**
  - 图片按需加载，提升性能
  - 滚动到底部自动加载更多内容
  - 可配置的每页显示数量

- **排序功能**
  - 按日期排序（最新/最旧）
  - 按名称排序（A-Z/Z-A）
  - 按文件大小排序

### 2. 图片预览

- **全屏预览**
  - 点击图片进入全屏预览模式
  - 支持缩放（滚轮或按钮）
  - 支持旋转（左转/右转）
  - 支持拖拽移动

- **键盘快捷键**
  - `←/→`：上一张/下一张
  - `+/-`：放大/缩小
  - `0`：重置缩放
  - `F`：适应屏幕
  - `R`：旋转
  - `I`：显示/隐藏信息
  - `ESC`：关闭预览

- **图片操作**
  - 下载图片
  - 复制到剪贴板
  - 在新窗口打开
  - 全屏模式

### 3. 搜索与筛选

- **快速搜索**
  - 支持文件名搜索
  - 支持 URL/内容搜索
  - 支持 OCR 文本搜索
  - 支持标签搜索
  - 键盘快捷键：`Cmd/Ctrl + K`

- **高级筛选**
  - 日期范围筛选
  - 快速日期选择（今天/本周/本月/今年）
  - 记录类型筛选（图片/文本/文件）
  - 文件大小筛选
  - 多条件组合筛选

- **搜索高亮**
  - 显示搜索结果数量
  - 活跃筛选标签显示
  - 一键清除筛选

### 4. 批量操作

- **多选功能**
  - 点击图片进行多选
  - 支持全选/取消全选
  - 显示已选择数量

- **批量操作**
  - 批量上传图片
  - 批量下载图片
  - 批量删除记录
  - 批量编辑标签
  - 批量移动分类
  - 批量导出

- **批量标签编辑**
  - 替换标签：清空原标签，设置新标签
  - 添加标签：在原标签基础上添加
  - 删除标签：从原标签中删除指定标签

### 5. 导出功能

- **导出格式**
  - JSON：包含完整元数据
  - CSV：电子表格格式
  - ZIP：打包所有文件和元数据
  - HTML 报告：统计分析报告

- **导出选项**
  - 包含/排除元数据
  - 包含/排除 OCR 文本
  - 包含/排除标签
  - 自定义 CSV 分隔符

## 组件使用示例

### 基础使用

```vue
<script setup lang="ts">
import { GalleryView } from '@/components/views/gallery';
</script>

<template>
  <GalleryView />
</template>
```

### 自定义使用

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { GalleryGrid, ImagePreview, SearchFilter } from '@/components/views/gallery';
import { useRecordsStore } from '@/store';

const recordsStore = useRecordsStore();
const selectedIds = ref<Set<string>>(new Set());

// 监听预览事件
const handlePreview = (item) => {
  console.log('预览:', item);
};

// 监听选择变化
const handleSelectionChange = (ids) => {
  selectedIds.value = ids;
};
</script>

<template>
  <div>
    <SearchFilter @search="handleSearch" />
    <GalleryGrid
      :items="recordsStore.records"
      :selection-mode="true"
      @selection-change="handleSelectionChange"
      @preview="handlePreview"
    />
    <ImagePreview />
  </div>
</template>
```

### 导出功能使用

```typescript
import { exportData } from '@/utils/export';

// 导出为 JSON
const result = await exportData(records, 'json', {
  includeMetadata: true,
  includeOCR: true,
  includeTags: true,
});

// 导出为 CSV
const result = await exportData(records, 'csv', {
  delimiter: ',',
});

// 导出为 ZIP
const result = await exportData(records, 'zip', {
  includeMetadata: true,
});

// 生成报告
const result = await exportData(records, 'report');
```

## API 接口

### SearchFilter 组件

**Props**
- 无

**Events**
- `@search(query: string, filters: SearchFilters)`: 搜索事件
- `@filter(filters: SearchFilters)`: 筛选事件

**Methods**
- `updateResultCount(count: number)`: 更新结果计数
- `setQuery(query: string)`: 设置搜索查询

### GalleryGrid 组件

**Props**
- `items: Record[]`: 显示的记录列表
- `loading?: boolean`: 加载状态
- `selectionMode?: boolean`: 是否启用选择模式

**Events**
- `@preview(item: Record)`: 预览项目
- `@edit(item: Record)`: 编辑项目
- `@delete(item: Record)`: 删除项目
- `@selection-change(ids: Set<string>)`: 选择变化
- `@load-more()`: 加载更多

### ImagePreview 组件

**Props**
- `visible: boolean`: 是否显示
- `items: Record[]`: 预览的记录列表
- `currentIndex?: number`: 当前索引

**Events**
- `@update:visible(value: boolean)`: 更新显示状态
- `@update:currentIndex(value: number)`: 更新当前索引
- `@edit(item: Record)`: 编辑项目
- `@delete(item: Record)`: 删除项目

### BatchActions 组件

**Props**
- `selectedItems: Record[]`: 选中的记录列表
- `totalCount?: number`: 总记录数

**Events**
- `@clear-selection()`: 清除选择
- `@batch-upload(items: Record[])`: 批量上传
- `@batch-download(items: Record[])`: 批量下载
- `@batch-delete(items: Record[])`: 批量删除
- `@batch-update(items: Record[], data: any)`: 批量更新
- `@export(items: Record[], format: string, options: any)`: 导出

## 样式定制

组件使用 CSS 变量支持主题定制：

```css
:root {
  --primary-color: #2563eb;
  --primary-light: #eff6ff;
  --danger-color: #ef4444;
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;
  --bg-tertiary: #f3f4f6;
  --border-color: #e5e7eb;
  --text-primary: #111827;
  --text-secondary: #6b7280;
  --text-muted: #9ca3af;
}
```

## 性能优化

1. **虚拟滚动**
   - 大量记录时自动启用虚拟滚动
   - 只渲染可见区域的项目

2. **图片懒加载**
   - 使用原生 `loading="lazy"` 属性
   - 缩略图优先加载

3. **防抖搜索**
   - 搜索输入防抖 300ms
   - 减少不必要的筛选计算

4. **分页加载**
   - 默认每页 20 条记录
   - 滚动到底部自动加载下一页

## 注意事项

1. **权限要求**
   - 下载功能需要文件访问权限
   - 剪贴板功能需要剪贴板权限

2. **浏览器兼容性**
   - 建议使用现代浏览器（Chrome、Firefox、Edge）
   - IE 不支持

3. **内存管理**
   - 大量图片时注意内存占用
   - 建议定期清理旧记录

## 扩展开发

### 添加自定义导出格式

```typescript
// 在 utils/export.ts 中添加
export async function exportToCustom(
  records: Record[],
  options: ExportOptions = {}
): Promise<ExportResult> {
  // 实现自定义导出逻辑
  return {
    success: true,
    file: blob,
    filename: 'export.custom',
  };
}
```

### 添加批量操作

```typescript
// 在 api/batch.ts 中添加
export async function batchCustomOperation(
  ids: string[],
  params: any
): Promise<void> {
  // 实现批量操作逻辑
}
```

## 故障排除

### 问题：图片无法加载

**解决方案**：
1. 检查文件路径是否正确
2. 确认文件访问权限
3. 查看浏览器控制台错误信息

### 问题：搜索无结果

**解决方案**：
1. 确认搜索关键词正确
2. 检查筛选条件是否过于严格
3. 尝试清除部分筛选条件

### 问题：导出失败

**解决方案**：
1. 确认选择了导出格式
2. 检查浏览器下载权限
3. 尝试减小导出数据量

## 更新日志

### v1.0.0 (2025-02-12)

- ✅ 实现图库网格视图
- ✅ 实现图片预览模态框
- ✅ 实现搜索与筛选功能
- ✅ 实现批量操作
- ✅ 实现导出功能（JSON/CSV/ZIP/报告）