cutThink_lite/docs/GALLERY_QUICKSTART.md

# 图库视图快速开始

## 安装依赖

```bash
npm install jszip
npm install --save-dev @types/jszip
```

## 基础使用

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

<template>
  <GalleryView />
</template>

<style>
/* 全局样式变量（可选） */
:root {
  --primary-color: #2563eb;
  --primary-light: #eff6ff;
  --danger-color: #ef4444;
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;
  --border-color: #e5e7eb;
  --text-primary: #111827;
  --text-secondary: #6b7280;
}
</style>
```

## 主要功能

### 1. 图片浏览
- 网格/列表视图切换
- 懒加载 + 无限滚动
- 多种排序方式

### 2. 图片预览
- 全屏预览模式
- 缩放（0.1x - 5x）
- 旋转（90°步进）
- 键盘快捷键支持

### 3. 搜索筛选
- 快速搜索（Cmd/Ctrl + K）
- 高级筛选面板
- 多条件组合

### 4. 批量操作
- 多选模式
- 批量上传/下载/删除
- 批量编辑标签
- 批量移动分类

### 5. 数据导出
- JSON 格式（完整元数据）
- CSV 格式（电子表格）
- ZIP 格式（打包文件）
- HTML 报告（统计分析）

## 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Cmd/Ctrl + K` | 聚焦搜索框 |
| `←` / `→` | 上一张/下一张 |
| `+` / `-` | 放大/缩小 |
| `0` | 重置缩放 |
| `F` | 适应屏幕 |
| `R` | 旋转图片 |
| `I` | 显示信息 |
| `ESC` | 关闭预览 |

## 文档

- [完整使用指南](./GALLERY_USAGE.md)
- [Phase 6 完成总结](./PHASE6_SUMMARY.md)

## 示例代码

### 导出功能

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

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

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

// 导出为 ZIP
await exportData(records, 'zip', {});

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

### 搜索筛选

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

const handleSearch = (query: string, filters: any) => {
  console.log('搜索:', query, filters);
  // 实现搜索逻辑
};
</script>

<template>
  <SearchFilter @search="handleSearch" />
</template>
```

### 自定义网格

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { GalleryGrid } from '@/components/views/gallery';
import type { Record } from '@/api';

const items = ref<Record[]>([]);
const selectedIds = ref<Set<string>>(new Set());

const handleSelectionChange = (ids: Set<string>) => {
  selectedIds.value = ids;
  console.log('已选择:', ids.size, '项');
};
</script>

<template>
  <GalleryGrid
    :items="items"
    :selection-mode="true"
    @selection-change="handleSelectionChange"
  />
</template>
```

## 常见问题

**Q: 图片无法显示？**

A: 检查文件路径和访问权限，确保图片 URL 可访问。

**Q: 搜索无结果？**

A: 尝试清除筛选条件，确认搜索关键词拼写正确。

**Q: 导出失败？**

A: 确认已安装 `jszip` 依赖，检查浏览器下载权限。

**Q: 性能问题？**

A: 对于大数据集，组件已内置懒加载和虚拟滚动优化。

## 技术支持

- 查看完整文档: [GALLERY_USAGE.md](./GALLERY_USAGE.md)
- 查看 API 参考: [GALLERY_USAGE.md#api-接口](./GALLERY_USAGE.md#api-接口)
- 查看故障排除: [GALLERY_USAGE.md#故障排除](./GALLERY_USAGE.md#故障排除)

## 更新日志

### v1.0.0 (2025-02-12)
- ✅ 图库网格视图
- ✅ 图片预览功能
- ✅ 搜索与筛选
- ✅ 批量操作
- ✅ 导出功能
- ✅ 完整文档