immich_file_list 1.0.0

A high-performance, professional photo grid library for Flutter with 100,000+ items support, macOS-style desktop interactions, and 100% decoupled architecture.

Photo Grid (immich_file_list)

一个专为极速相册体验设计的 Flutter 高性能网格库。支持十万级数据的顺滑滚动、分级别逻辑吸附、专业级桌面交互以及真正的数据与 UI 彻底解耦。

---

🌟 核心特性 (Key Features)

• 🚀 极致性能: 基于分段异步渲染与视口外缓存，轻松应对 100,000+ 照片数据的秒级加载，保持丝滑 60FPS。
• 📑 真正解耦 (Design): 采用了全新的 ItemBuilder 模式。核心层 (Core) 100% 不依赖 Flutter UI，实现了数据模型与渲染逻辑的完美分离。
• 🖥️ 专业桌面方案 (Desktop Pro):
  • Finder 级选择: 支持类似 macOS 访达的鼠标框选（Marquee Selection），几何算法确保滑出屏幕的项依然保持精准选中。
  • 键盘导航: 完整的方向键支持、焦点环显示，支持 Shift 范围选择与 Ctrl/Cmd 组合选。
  • 自动跟随: 键盘切换或拖拽至边界时，滚动视图智能补正。
• 🎨 深度定制 Scrubber: 内置高度可定制的侧边滑块，支持自定义：
  • labelBuilder: 气泡标签样式。
  • thumbBuilder: 滑块手柄视觉。
  • segmentBuilder: 背景年度/月份刻度样式。
• 📱 多端适配: 内置 AdaptiveContainer 处理窗口拉伸防抖，确保从手机到 4K 显示器都有极致体验。

---

📂 架构设计 (Architecture)

库采用了分层架构，确保逻辑清晰且易于扩展：

• core/: 100% 纯 Dart 逻辑层。包含布局算法、段落计算、偏移映射。不依赖 material 或 widgets，可独立于 UI 运行。
• logic/: 交互逻辑层。包含多选状态管理 (PhotoSelectionController)、框选算法、键盘导航策略。
• widgets/: 渲染组件层。提供 PhotoGridView、PhotoGridScrubber 以及各种自适应容器。

---

🛠️ 快速上手 (Quick Start)

1. 定义数据模型

只需实现 PhotoGridItem 接口，无需包含任何 UI 代码：

class MyPhotoItem implements PhotoGridItem {
  @override final String id;
  @override final DateTime date;

  MyPhotoItem({required this.id, required this.date});
}

2. 构建网格

使用 PhotoGridView 并提供 itemBuilder。由于数据与 UI 已解耦，您可以自由决定如何渲染图片。

PhotoGridView(
  items: myPhotos,
  assetsPerRow: 4,
  groupBy: GroupPhotoBy.day, // 按天分组
  itemBuilder: (context, item) {
    return Image.network(
      'https://api.example.com/photo/${item.id}/thumbnail',
      fit: BoxFit.cover,
    );
  },
  onTap: (item) => print('点击了: ${item.id}'),
)

---

⌨️ 桌面端交互配置 (Desktop Setup)

要开启专业级的桌面端操作（如框选），建议使用 PhotoGridGallery 快捷包装或手动组合组件：

PhotoDesktopSelectionRegion(
  selectionController: myController,
  allItemIds: myPhotos.map((e) => e.id).toList(),
  child: PhotoGridView(
    items: myPhotos,
    selectionController: myController,
    itemBuilder: (context, item) => MyThumbnail(item),
  ),
)

---

🎛️ API 参考

PhotoGridView

属性	类型	描述
items	List<PhotoGridItem>	必填。照片数据源。
itemBuilder	PhotoGridItemBuilder	必填。定义单项渲染逻辑。
assetsPerRow	int	每行显示的列数。
groupBy	GroupPhotoBy	聚合维度：year, month, day, none。
margin	double	网格间距。
selectionController	PhotoSelectionController?	绑定多选控制器。
topSliver	Widget?	在网格上方插入自定义 Sliver（如吸顶 Header）。

---

📖 演示案例 (Examples)

查看 example/ 目录获取更多灵感：

• macos_finder_style: 体验极致的桌面端框选。
• cyberpunk_scrubber: 演示如何通过 Builders 打造霓虹风格的进度条。
• adaptive_layout: 窗口缩放时的自适应处理。

---

许可证

MIT License.