yu_file_preview

yu_file_preview 是一款功能强大的 Flutter 全屏媒体预览组件库，深度整合了图片与视频预览能力。

---

🔥 快速开始

只需四步，即可实现具备「高性能缓存、Hero 动画、原图查看、视频播放」能力的专业级预览。

0. 程序入口初始化 (必填)

在 main() 函数第一行调用 YuniWidgetsBinding.ensureInitialized() 以接管 Flutter 原生的图片缓存。

void main() {
  YuniWidgetsBinding.ensureInitialized();
  runApp(MyApp());
}

1. 业务配置初始化

建议在用户登录成功并获取到缓存路径后进行注入。

import 'package:yu_file_preview/yu_file_preview.dart';

  FilePreview.configure(
    FilePreviewConfig(
      imageStorage: MyUserCacheManager(user.id), 
      playerConfig: YuNiPlayerConfig(
        maxActiveCount: 3, 
        platformEngines: {
          PlatformKey.defaultKey: (source) => VideoPlayerKitEngine(source),
        },
      ),
    ),
  );

2. 定义数据模型

继承 FilePreviewItem 并重写核心字段。所有 Source 字段均支持 FutureOr 异步返回。

class MediaItem extends FilePreviewItem {
  @override
  String get id => uuid; // 必填：用于 Hero 动画

  @override
  FilePreviewType get type => isVideo ? FilePreviewType.video : FilePreviewType.image;

  @override
  FutureOr<FilePreviewSource?> get thumbnailSource => UrlPreviewSource(url: thumb);
}

3. 一键调起预览

FilePreview.show(context, items: list);

---

🏗️ API 强类型辞书 (API Reference)

FilePreview.show(...) 核心入口

此方法封装了全平台的自适应逻辑。若不传可选参数，组件库将自动识别宿主环境并应用对应 UI。

参数名	精准类型 (Dart Type)	默认值	全局缺省逻辑 / 触发时机
items	List<FilePreviewItem>	必填	预览数据集合。
initialIndex	int	0	打开时的起始索引。
theme	ViewerTheme?	见下表	全局视觉常数。
interactionConfig	ViewerInteractionConfig?	见下表	交互手势与阻尼阈值。
onDismiss	VoidCallback?	null	时序 预览页路由销毁、Hero 退出动画执行完毕后的信号。
onPageChanged	ValueChanged<int>?	null	滑动切换页签成功，且页面索引发生变化时触发。
onInfoStateChanged	ValueChanged<InfoState>?	null	信息面板在 展开 / 收起 状态切换时触发。
controller	MediaViewerController?	null	外部控制手柄，支持 jumpToPage、toggleBars 等指令。
topBarBuilder	ViewerBarBuilder?	手机端默认	自定义顶栏。缺省时手机端应用 FpTopBar。
bottomBarBuilder	ViewerBarBuilder?	手机端默认	自定义底栏。缺省时手机端应用 FpBottomBar。
infoBuilder	ViewerInfoBuilder?	null	自定义信息面板。若不为 null，则开启「上滑动呼出信息」逻辑。

---

1. 视觉主题: ViewerTheme

字段名	类型	默认值	功能意义
backgroundColor	Color	Colors.black	背景底色，支持透明度。
mediaCardInset	EdgeInsets	(h:14, v:10)	相册卡片样式的内边距。
mediaCardBorderRadius	double	18.0	媒体内容的圆角。
mediaCardAnimationDuration	Duration	300ms	卡片形态与全屏形态切换的动画耗时。
zoomDuration	Duration	250ms	双击放大 / 还原的缩放动画时长。

---

2. 交互行为: ViewerInteractionConfig

字段名	类型	默认值	功能意义
enableDismissGesture	bool	true	是否允许「下拉返回」手势。
dismissDistanceThreshold	double	110.0	判定为关闭预览器的最小下拉位移（px）。
enableDoubleTapZoom	bool	true	是否开启双击缩放。
verticalDragMinStartDistance	double	3.0	垂直手势识别起始位移（调大可减少误触）。
desktopUiMode	ViewerDesktopUiMode	auto	强制桌面风格或自动判定。

---

🎨 进阶异步场景

异步分页加载 (showPaging)

FilePreview.showPaging(
  context,
  initialItems: items,
  initialHasPrevious: true, // 初始是否有上一页
  onLoadMore: (lastItem) async {
    // 自动触底加载更多
    final result = await api.getNextPage();
    return PagingResult(items: result, hasMore: true);
  },
  onLoadPrevious: (firstItem) async {
    // 自动触顶加载上一页
    final result = await api.getPrevPage();
    return PagingResult(items: result, hasMore: true);
  },
);

按需延迟填充 (FutureOr)

利用 FilePreviewItem 所有资源字段均为 FutureOr 的特性，支持滑动到哪页才请求哪页的具体 URL，节省首屏流量消耗。

许可证

MIT