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 分隔符

组件使用示例

基础使用

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

<template>
  <GalleryView />
</template>

自定义使用

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

导出功能使用

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 变量支持主题定制：

: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. 内存管理

   • 大量图片时注意内存占用
   • 建议定期清理旧记录

扩展开发

添加自定义导出格式

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

添加批量操作

// 在 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/报告）