cutThink_lite/docs/GALLERY_QUICKSTART.md

图库视图快速开始

安装依赖

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

基础使用

<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	关闭预览

文档

• 完整使用指南
• Phase 6 完成总结

示例代码

导出功能

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');

搜索筛选

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

自定义网格

<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
• 查看 API 参考: GALLERY_USAGE.md#api-接口
• 查看故障排除: GALLERY_USAGE.md#故障排除

更新日志

v1.0.0 (2025-02-12)

• ✅ 图库网格视图
• ✅ 图片预览功能
• ✅ 搜索与筛选
• ✅ 批量操作
• ✅ 导出功能
• ✅ 完整文档