xianyan/docs/09_三方库扩展功能开发文档.md

闲言APP — 三方库扩展功能开发文档

创建时间: 2026-04-25 更新时间: 2026-04-27 版本: v0.23.0 关联文档: 08_编辑器功能清单 说明: 7个三方库接口分析、扩展功能、开发流程

---

一、库总览与平台兼容性

1.1 七库定位

库	版本	定位	渲染引擎	跨平台等级
flutter_advanced_canvas_editor	2.1.0	图层管理系统	Flutter Canvas	🟢 全平台
flutter_scene	0.9.2-0	高性能3D渲染	Flutter GPU (Impeller)	🟡 移动+桌面
flutter_3d_controller	2.3.0	3D模型交互预览	WebView + model-viewer	🟠 移动+Web
image_size_getter	2.4.1	图片尺寸/格式检测	纯Dart (读文件头)	🟢 全平台
extended_image	10.0.1	增强图片组件	Flutter Canvas	🟢 全平台
photo_view	0.15.0	图片缩放查看器	Flutter Canvas	🟢 全平台
flutter_image_compress	2.4.0	原生图片压缩	平台原生SDK	🟢 全平台

1.2 平台兼容性矩阵

平台	canvas_editor	flutter_scene	3d_controller	image_size_getter	extended_image	photo_view	image_compress
Android	✅	✅	✅	✅	✅	✅	✅
iOS	✅	✅	✅	✅	✅	✅	✅
macOS	✅	✅	✅	✅	✅	✅	✅
Windows	✅	✅	❌	✅	✅	✅	✅
Linux	✅	✅	❌	✅	✅	✅	✅
Web	✅	❌	✅	✅	✅	✅	⚠️

1.3 依赖关系

库	核心依赖	包体积影响
flutter_advanced_canvas_editor	无 (纯Dart)	~0KB
flutter_scene	flutter_gpu, flutter_scene_importer, vector_math	~2MB
flutter_3d_controller	flutter_inappwebview, vector_math, http	~5-10MB
image_size_getter	无 (纯Dart)	~0KB
extended_image	无 (纯Flutter)	~0KB
photo_view	无 (纯Flutter)	~0KB
flutter_image_compress	平台原生SDK	~0.5MB

---

二、flutter_advanced_canvas_editor — 接口详解 (✅ 已归档)

Phase 1 已完成，核心API已适配到 LayerManagerService

2.1 关键接口速查

类别	核心API	已适配到
图层CRUD	createLayer / deleteLayer / reorderLayer / duplicateLayer / mergeLayerDown	LayerManagerService
图层属性	setLayerVisibility / setLayerOpacity / setLayerLocked / renameLayer	LayerManagerService
撤销重做	undo / redo / clearAll (50步快照)	LayerSnapshotService
组件操作	addComponent / updatePosition / rotateComponent / deleteComponent	LayerManagerService
导出	exportCanvas / scaleAllPositions	ExportService

2.2 已实现功能清单

#	功能	状态	产出文件
A1	🗂️ 专业图层面板	✅	layer_panel.dart
A2	👁️ 图层可见性切换	✅	layer_manager_service.dart
A3	🔒 图层锁定	✅	layer_manager_service.dart
A4	🌫️ 图层不透明度	✅	layer_manager_service.dart
A5	↩️ 增强撤销/重做	✅	layer_snapshot_service (集成在LayerManagerService)
A6	🔀 图层排序拖拽	✅	layer_panel.dart
A7	📋 图层复制	✅	layer_manager_service.dart
A8	🔗 图层合并	✅	layer_manager_service.dart
A9	🏷️ 图层命名	✅	layer_panel.dart
A10	🧹 图层清空	✅	layer_manager_service.dart

---

三、flutter_scene — 接口详解 (❌ v0.23.0 已移除)

Phase 2 核心已完成，但 v0.23.0 统一3D渲染路径后已移除 flutter_scene 依赖 所有3D功能统一由 flutter_3d_controller (WebView) 承载

3.1 关键接口速查 (已弃用)

类别	核心API	原适配到	替代方案
场景管理	Scene() / add / remove / render	Scene3DService	flutter_3d_controller
模型加载	Node.fromAsset / fromFlatbuffer	Scene3DService	Flutter3DViewer(src: .glb)
相机控制	PerspectiveCamera(position/target/fov)	Scene3DService	Flutter3DController
材质系统	PhysicallyBasedMaterial / UnlitMaterial	待Phase 3	暂不实现

3.2 移除原因

• flutter_scene 需要 .model 预编译格式，流程繁琐
• WebView 方案 (flutter_3d_controller) 跨平台更稳定
• useScene 双分支增加维护复杂度
• v0.23.0 统一使用 flutter_3d_controller

---

四、flutter_3d_controller — 接口详解 (✅ 已归档 · v0.23.0 统一3D路径)

Phase 2 核心已完成，v0.23.0 统一3D渲染路径后成为唯一3D引擎 Model3DPreviewPage + Sticker3DPanel + 画布3D贴纸 全部使用 Flutter3DViewer

4.1 关键接口速查

类别	核心API	已适配到
GLB查看	Flutter3DViewer(src:, controller:)	Model3DPreviewPage + Sticker3DPanel + 画布3D贴纸
控制器	Flutter3DController.playAnimation / pauseAnimation / resetCameraOrbit	Model3DPreviewPage
动画列表	getAvailableAnimations	Model3DPreviewPage
自动旋转	startRotation / pauseRotation	Model3DPreviewPage
加载进度	onProgress(double)	Model3DPreviewPage

4.2 已实现功能

#	功能	状态	产出文件
C1	🎬 3D模型预览	✅	model_3d_preview_page.dart
C2	🎭 动画播放控制	✅	model_3d_preview_page.dart
C3	🔄 自动旋转	✅	model_3d_preview_page.dart
C4	📷 相机重置	✅	model_3d_preview_page.dart
C5	⏳ 加载进度	✅	model_3d_preview_page.dart
C6	🧊 3D贴纸面板预览	✅	sticker_3d_panel.dart (v0.23.0真实3D渲染)
C7	🎨 画布3D贴纸	✅	pro_editor_bridge.dart (v0.23.0 Flutter3DViewer)
C8	📤 3D贴纸导出	✅	widget_layer_renderer.dart (v0.23.0 静态快照)
C9	📱 低端设备检测	✅	platform_3d_service.dart (v0.23.0 UI降级提示)

---

五、image_size_getter ^2.4.1 — 接口详解

5.1 库架构

image_size_getter/
├── lib/
│   ├── image_size_getter.dart  — 导出入口
│   └── src/
│       ├── image_size_getter.dart  — 核心类 + 解码器注册
│       ├── decoder/               — 格式解码器
│       │   ├── jpeg_decoder.dart
│       │   ├── png_decoder.dart
│       │   ├── gif_decoder.dart
│       │   ├── webp_decoder.dart
│       │   └── bmp_decoder.dart
│       └── wrapper/               — 输入包装器
│           ├── file_input.dart
│           └── memory_input.dart

5.2 核心API

class ImageSizeGetter {
  /// 同步获取图片尺寸 + 解码器
  static SizeResult getSizeResult(ImageInput input);

  /// 异步获取图片尺寸
  static Future<SizeResult> getSizeResultAsync(ImageInput input);

  /// 格式检测
  static bool isPng(ImageInput input);
  static bool isJpg(ImageInput input);
  static bool isGif(ImageInput input);
  static bool isWebp(ImageInput input);
  static bool isBmp(ImageInput input);

  /// 注册自定义解码器
  static void registerDecoder(BaseDecoder decoder);
}

class SizeResult {
  final Size size;           // width, height
  final BaseDecoder decoder; // 使用的解码器
}

class Size {
  final int width;
  final int height;
  final bool needRotate;     // EXIF旋转标记 (JPEG)
}

// 输入类型
class FileInput implements ImageInput {
  FileInput(File file);
  bool exists();
}

class MemoryInput implements ImageInput {
  MemoryInput(List<int> bytes);
  bool exists();
}

5.3 可扩展功能清单

#	功能	对应API	与现有功能结合点	优先级	状态
IS1	📐 导入图片智能适配	getSizeResult	ImageImportService → 画布缩放比	P0	✅
IS2	🔄 EXIF旋转自动校正	Size.needRotate	ImageImportService → 自动旋转	P0	✅
IS3	🏷️ 图片格式检测	isPng/isJpg/isGif/isWebp	导入时显示格式标签	P1	✅
IS4	🖼️ GIF帧数检测	GifDecoder	GIF导出预览帧数	P2	❌ API不可用
IS5	ℹ️ 图片信息面板	Size + format	编辑器信息展示	P1	✅

5.4 与现有代码结合点

• ImageImportService.pickFromGallery() → 导入后立即读取尺寸
• ExportService.exportHighRes() → 导出前校验尺寸
• GifExportService → GIF帧数检测
• 编辑器状态栏 → 显示当前画布/图片尺寸

---

六、extended_image ^10.0.1 — 接口详解

6.1 库架构

extended_image/
├── lib/
│   ├── extended_image.dart     — 导出入口
│   └── src/
│       ├── extended_image.dart       — ExtendedImage Widget
│       ├── image/                    — 图片Provider扩展
│       │   ├── extended_memory_image_provider.dart
│       │   ├── extended_file_image_provider.dart
│       │   └── extended_resize_image.dart
│       ├── editor/                   — 裁剪编辑器
│       │   ├── editor.dart           — ExtendedImageEditor
│       │   ├── edit_action_details.dart
│       │   └── editor_utils.dart
│       ├── gesture/                  — 手势系统
│       │   ├── gesture.dart          — ExtendedImageGesture
│       │   └── gesture_config.dart   — GestureConfig
│       └── page/                     — 页面组件
│           ├── extended_image_gesture_page_view.dart
│           └── extended_image_slide_page.dart

6.2 核心API

// === 增强图片组件 ===
ExtendedImage({
  required ImageProvider image,       // 图片Provider
  ExtendedImageMode mode,             // none / gesture / editor
  // 手势模式配置
  GestureConfig? initGestureConfigHandler,
  VoidCallback? onDoubleTap,
  // 编辑模式配置
  EditorConfig? initEditorConfigHandler,
  // 通用属性
  BoxFit fit, double? width, double? height,
  BorderRadius? borderRadius, ShapeBorder? border,
  LoadStateChanged? loadStateChanged,
  bool clearMemoryCacheWhenDispose,
  bool enableLoadState,
  BeforePaintImage? beforePaintImage,
  AfterPaintImage? afterPaintImage,
})

// === 手势配置 ===
GestureConfig({
  double minScale = 0.8,              // 最小缩放
  double maxScale = 5.0,              // 最大缩放
  double speed = 1.0,                 // 惯性速度
  bool cacheGesture = false,          // 缓存手势状态
  AnimationConfig? inertialAnimation, // 惯性动画
  AnimationConfig? doubleTapAnimation,// 双击动画
})

// === 裁剪编辑器 ===
ExtendedImageEditor({
  required ExtendedImageState extendedImageState,
})

class ExtendedImageEditorState {
  void rotate({double degree = 90, bool animation = false});
  void flip({bool animation = false});
  void reset();
  void undo();
  void redo();
  bool get canRedo;
  bool get canUndo;
  EditActionDetails get editAction;
  Rect getCropRect();
  Future<Uint8List> cropImageData();
}

// === 编辑器配置 ===
EditorConfig({
  double maxScale = 5.0,
  double? cropAspectRatio,            // null=自由裁剪
  Color cropRectPadding = 20,
  Color cornerColor,
  Color cropLayerPainter,             // 自定义裁剪蒙层
})

// === 内存优化 ===
ExtendedResizeImage({
  required ImageProvider imageProvider,
  double compressionRatio = 1.0,      // 压缩比
  int? maxBytes,                      // 最大内存字节
  int? width,                         // 缓存宽
  int? height,                        // 缓存高
})

// === 滑动退出页面 ===
ExtendedImageSlidePage({
  required Widget child,
  SlidePageConfig? slidePageConfigHandler,
})

// === 手势PageView ===
ExtendedImageGesturePageView({
  required List<Widget> children,
  PageController? controller,
})

6.3 可扩展功能清单

#	功能	对应API	与现有功能结合点	优先级	状态
EI1	✂️ 裁剪编辑器	ExtendedImageEditor + cropImageData	编辑器新增裁剪工具	P1	✅
EI2	🔄 图片旋转/翻转	rotate()/flip()	裁剪编辑器内置	P1	✅
EI3	🖼️ 大图内存优化	ExtendedResizeImage	大图导入防OOM	P0	✅
EI4	👆 手势缩放查看	ExtendedImage + gesture模式	图片预览	P2	⏳
EI5	📱 图片滑动退出	ExtendedImageSlidePage	大图预览iOS风格	P2	⏳
EI6	📖 手势PageView	ExtendedImageGesturePageView	图片画廊	P3	⏳
EI7	🎨 自定义裁剪蒙层	EditorCropLayerPainter	裁剪UI定制	P3	⏳
EI8	↩️ 编辑历史undo/redo	editor.undo()/redo()	裁剪编辑器内置	P1	✅

6.4 ⚠️ 与 ProImageEditor 的关系

项目已使用 pro_image_editor 作为主编辑器，extended_image 的编辑功能与之有重叠。 建议策略: 重点使用其 内存优化 + 手势查看 + 滑动退出 功能；裁剪编辑器作为快速裁剪模式的补充。

---

七、photo_view ^0.15.0 — 接口详解

7.1 库架构

photo_view/
├── lib/
│   ├── photo_view.dart           — 导出入口
│   └── src/
│       ├── core/
│       │   ├── photo_view_core.dart      — 核心渲染
│       │   └── photo_view_computed_scale.dart — 计算型缩放
│       ├── controllers/
│       │   ├── photo_view_controller.dart       — 外部控制器
│       │   └── photo_view_scale_state_controller.dart — 缩放状态控制器
│       ├── gestures/
│       │   └── photo_view_gesture_detector.dart — 手势检测
│       └── widgets/
│           ├── photo_view_default.dart    — 默认加载/错误Widget
│           └── photo_view_gallery.dart    — 画廊组件

7.2 核心API

// === 单图缩放查看 ===
PhotoView({
  required ImageProvider imageProvider,  // 图片Provider
  // 缩放控制
  double? minScale,                      // 最小缩放 (可用PhotoViewComputedScale)
  double? maxScale,                      // 最大缩放
  double? initialScale,                  // 初始缩放
  PhotoViewComputedScale basePosition,   // 基准位置
  // 手势
  bool enableRotation = false,           // 启用旋转手势
  bool disableGestures = false,          // 禁用手势
  bool enablePanAlways = false,          // 始终允许平移
  bool strictScale = false,              // 严格缩放模式
  // 双击缩放循环
  ScaleStateCycle? scaleStateCycle,      // 自定义双击缩放逻辑
  // 回调
  VoidCallback? scaleStateChangedCallback,
  Function(PhotoViewScaleState)? onScaleEnd,
  Function(BuildContext, TapDownDetails)? onTapDown,
  Function(BuildContext, TapUpDetails)? onTapUp,
  // 控制器
  PhotoViewController? controller,
  PhotoViewScaleStateController? scaleStateController,
  // Hero动画
  PhotoViewHeroAttributes? heroAttributes,
  // 样式
  BoxDecoration? backgroundDecoration,
  bool gaplessPlayback = false,
  FilterQuality? filterQuality,
  Size? customSize,
  bool tightMode = false,
  // 加载/错误
  LoadingBuilder? loadingBuilder,
  ImageErrorWidgetBuilder? errorBuilder,
})

// === 自定义子组件缩放 ===
PhotoView.customChild({
  required Widget child,                 // 自定义子组件
  Size? childSize,                       // 子组件逻辑尺寸
  // 其余参数同PhotoView
})

// === 计算型缩放值 ===
class PhotoViewComputedScale {
  static PhotoViewComputedScale contained;   // 包含模式
  static PhotoViewComputedScale covered;     // 覆盖模式
  double get value;                          // 实际缩放值
  PhotoViewComputedScale operator *(double multiplier);
}

// === 缩放状态枚举 ===
enum PhotoViewScaleState {
  initial,        // 初始
  covering,       // 覆盖
  originalSize,   // 原始大小
  zoomedIn,       // 放大
  zoomedOut,      // 缩小
}

// === 画廊 ===
PhotoViewGallery({
  required List<PhotoViewGalleryPageOptions> pageOptions,
  // 或
  required PhotoViewGalleryBuilder builder,
  int? itemCount,
  PageController? pageController,
  VoidCallback? onPageChanged,
  bool reverse = false,
  Axis scrollDirection = Axis.horizontal,
  bool allowImplicitScrolling = false,
  bool pageSnapping = true,
})

class PhotoViewGalleryPageOptions {
  PhotoViewGalleryPageOptions({
    required ImageProvider imageProvider,
    double? minScale,
    double? maxScale,
    PhotoViewHeroAttributes? heroAttributes,
  });
}

// === 外部控制器 ===
class PhotoViewController {
  Offset get position;
  double get scale;
  double get rotation;
  void reset();
  void setScale(double scale);
  void setPosition(Offset position);
  void setRotation(double rotation);
}

class PhotoViewScaleStateController {
  PhotoViewScaleState get scaleState;
  void setScaleState(PhotoViewScaleState state);
}

7.3 可扩展功能清单

#	功能	对应API	与现有功能结合点	优先级	状态
PV1	🔍 全屏大图预览	PhotoView(imageProvider:)	编辑器图层图片点击 → 全屏查看	P0	✅
PV2	🖼️ 多图画廊浏览	PhotoViewGallery	作品集/草稿列表图片浏览	P1	✅
PV3	🧩 自定义子组件缩放	PhotoView.customChild	SVG/3D模型/Canvas内容缩放查看	P2	⏳
PV4	🎬 Hero动画过渡	PhotoViewHeroAttributes	列表→大图过渡动画	P1	✅
PV5	👆 双击缩放循环	scaleStateCycle	自定义双击缩放逻辑	P2	✅
PV6	🔄 旋转手势	enableRotation	图片旋转查看	P2	✅
PV7	🎛️ 外部缩放控制	PhotoViewController	程序化控制缩放/位置/旋转	P3	⏳

7.4 与 extended_image 的分工

场景	使用库	原因
图片编辑 (裁剪/旋转/翻转)	extended_image	内置编辑器
图片查看 (缩放/平移/旋转)	photo_view	专注查看体验
多图画廊	photo_view	PhotoViewGallery 专用组件
内存优化	extended_image	ExtendedResizeImage
滑动退出	extended_image	ExtendedImageSlidePage

---

八、flutter_image_compress ^2.4.0 — 接口详解

8.1 库架构

flutter_image_compress/
├── lib/
│   ├── flutter_image_compress.dart  — 导出入口 + 核心API
│   └── platform_interface/         — 平台接口定义
├── android/                         — Android原生实现
├── ios/                             — iOS原生实现
├── macos/                           — macOS原生实现
├── windows/                         — Windows原生实现
└── linux/                           — Linux原生实现

8.2 核心API

class FlutterImageCompress {
  /// 内存字节压缩 (Uint8List → Uint8List)
  static Future<Uint8List> compressWithList(
    Uint8List image, {
    int minWidth = 1920,               // 最小宽度
    int minHeight = 1080,              // 最小高度
    int quality = 95,                  // 质量 0-100
    int rotate = 0,                    // 旋转 0/90/180/270
    int inSampleSize = 1,              // 采样率 (降采样)
    bool autoCorrectionAngle = true,   // 自动校正EXIF旋转
    CompressFormat format = CompressFormat.jpeg, // 输出格式
    bool keepExif = false,             // 保留EXIF信息
  });

  /// 文件路径压缩 (path → Uint8List)
  static Future<Uint8List?> compressWithFile(
    String path, {
    int minWidth = 1920,
    int minHeight = 1080,
    int quality = 95,
    int rotate = 0,
    int inSampleSize = 1,
    bool autoCorrectionAngle = true,
    CompressFormat format = CompressFormat.jpeg,
    bool keepExif = false,
    int numberOfRetries = 5,
  });

  /// 文件到文件压缩 (path → targetPath)
  static Future<XFile?> compressAndGetFile(
    String path,
    String targetPath, {
    int minWidth = 1920,
    int minHeight = 1080,
    int quality = 95,
    int rotate = 0,
    int inSampleSize = 1,
    bool autoCorrectionAngle = true,
    CompressFormat format = CompressFormat.jpeg,
    bool keepExif = false,
    int numberOfRetries = 5,
  });

  /// Asset图片压缩
  static Future<Uint8List?> compressAssetImage(
    String assetName, {
    int minWidth = 1920,
    int minHeight = 1080,
    int quality = 95,
    int rotate = 0,
    bool autoCorrectionAngle = true,
    CompressFormat format = CompressFormat.jpeg,
    bool keepExif = false,
  });

  /// 忽略平台支持检查
  static void ignoreCheckSupportPlatform(bool value);

  /// 显示原生日志
  static set showNativeLog(bool value);

  /// 平台验证器
  static FlutterImageCompressValidator get validator;
}

/// 输出格式枚举
enum CompressFormat {
  jpeg,   // JPEG (全平台)
  png,    // PNG (全平台)
  webp,   // WebP (Android/iOS/macOS)
  heic,   // HEIC (iOS only)
}

8.3 可扩展功能清单

#	功能	对应API	与现有功能结合点	优先级	状态
IC1	🗜️ 导出图片压缩	compressWithList JPEG quality:90	ExportService → 体积减少70%+	P0	✅
IC2	📥 导入大图预处理	compressWithList minWidth:4096	ImageImportService → 防OOM	P0	✅
IC3	🔄 EXIF旋转自动校正	autoCorrectionAngle: true	ImageImportService → 方向正确	P0	✅
IC4	🌐 WebP格式导出	CompressFormat.webp	导出对话框 → 格式选择	P1	⏳
IC5	🍎 HEIC格式导出	CompressFormat.heic	iOS专用格式	P2	⏳
IC6	📸 草稿缩略图生成	compressWithList quality:50	DraftService → 列表加速	P1	✅
IC7	🎚️ 导出质量选择	quality 参数	导出对话框 → 质量滑块	P1	⏳
IC8	🎞️ GIF帧压缩	compressWithList 逐帧	GifExportService → GIF体积优化	P2	✅

8.4 与现有代码结合点

• ExportService.saveToGallery() → PNG→JPEG压缩后保存
• ExportService.shareImage() → 压缩后分享
• ImageImportService.pickFromGallery() → 大图压缩后加载
• GifExportService → 逐帧压缩减小GIF体积
• DraftService → 保存时生成压缩缩略图

---

九、综合功能扩展矩阵

9.1 按优先级排序

优先级	功能	涉及库	收益	Phase
P0	导出图片压缩 (JPEG/WebP)	flutter_image_compress	导出体积减少70%+	5
P0	导入大图预处理	flutter_image_compress + image_size_getter	防OOM崩溃	5
P0	EXIF旋转自动校正	image_size_getter + flutter_image_compress	修复图片方向错误	5
P0	全屏大图预览	photo_view	查看体验大幅提升	5
P1	裁剪编辑器	extended_image	专业裁剪功能	5
P1	大图内存优化	extended_image	内存占用减少50%+	5
P1	图片信息面板	image_size_getter	编辑器信息展示	5
P1	多图画廊浏览	photo_view	作品集浏览	5
P1	WebP/HEIC导出	flutter_image_compress	格式多样化	5
P1	草稿缩略图	flutter_image_compress	列表加载加速	5
P1	导出质量选择	flutter_image_compress	用户可控质量	5
P2	图片滑动退出	extended_image	iOS风格交互	5
P2	GIF帧压缩	flutter_image_compress	GIF体积优化	5
P2	自定义子组件缩放	photo_view	SVG/3D缩放查看	5
P3	手势PageView画廊	extended_image	图片画廊	5

9.2 新增文件规划

lib/editor/
├── services/
│   ├── export/
│   │   └── image_compress_service.dart — 图片压缩服务 (flutter_image_compress) ✅
│   └── image/
│       └── image_info_service.dart      — 图片信息读取服务 (image_size_getter) ✅
├── pages/tools/
│   ├── image_preview_page.dart          — 全屏大图预览+多图画廊 (photo_view) ✅
│   └── image_crop_page.dart             — 裁剪编辑器 (extended_image) ✅
└── widgets/editors/
    └── image_info_panel.dart            — 图片信息面板 (image_size_getter) ✅

---

十、版本规划

版本	Phase	功能	状态
v0.20.0	Phase 1	图层管理面板 + 撤销/重做增强	✅ 已完成
v0.21.0	Phase 2	3D模型贴纸 + 3D预览器 + 平台调度	✅ 核心完成
v0.22.0	Phase 5	图片压缩 + 大图预览 + 裁剪编辑器 + 图片信息	✅ 核心完成
v0.23.0	Phase 2修复	统一3D渲染 + 图层模型统一 + bridge拆分 + 3D模型扩展	✅ 已完成
v0.24.0	Phase 3	PBR材质 + 环境光照 + 场景导出	⏳ 待开发
v0.25.0	Phase 4	3D文字 + 网络3D模型	⏳ 待开发

---

十一、风险与对策

风险	影响	对策
flutter_scene 不支持Web	Web用户无3D渲染	Web降级为flutter_3d_controller或静态图片
flutter_3d_controller 不支持Win/Linux	桌面用户无3D预览	Win/Linux使用flutter_scene替代
extended_image与ProImageEditor重叠	裁剪功能冲突	仅作快速裁剪补充，主编辑仍用ProImageEditor
flutter_image_compress Web有限制	Web端压缩能力弱	Web端降级为Dart纯编码压缩
大图内存溢出	导入超大图OOM	compressWithList预处理 + ExtendedResizeImage

---

十二、参考链接

资源	链接
flutter_advanced_canvas_editor	https://pub.dev/packages/flutter_advanced_canvas_editor
flutter_scene	https://pub.dev/packages/flutter_scene
flutter_3d_controller	https://pub.dev/packages/flutter_3d_controller
image_size_getter	https://pub.dev/packages/image_size_getter
extended_image	https://pub.dev/packages/extended_image
photo_view	https://pub.dev/packages/photo_view
flutter_image_compress	https://pub.dev/packages/flutter_image_compress
Impeller	https://github.com/flutter/flutter/wiki/Impeller

---

十三、归档列表

已完成集成的三方库及其产出，记录版本和状态

13.1 已归档库

库	归档版本	核心产出	完成度	归档日期
flutter_advanced_canvas_editor	v0.20.0	LayerManagerService + LayerSnapshotService + LayerPanel	92%	2026-04-24
flutter_scene	v0.23.0	❌ 已移除，统一flutter_3d_controller	—	2026-04-27
flutter_3d_controller	v0.21.0/v0.23.0	Model3DPreviewPage + Sticker3DPanel + 画布3D贴纸 + 3D导出	85%	2026-04-27
image_size_getter	v0.22.0	ImageInfoService + ImageInfoPanel + EditorStatusBar	100%	2026-04-25
extended_image	v0.22.0	ImageCropPage + ExtendedResizeImage	100%	2026-04-25
photo_view	v0.22.0	ImagePreviewPage + ImageGalleryPage	100%	2026-04-25
flutter_image_compress	v0.22.0	ImageCompressService + ExportService压缩集成	100%	2026-04-25

13.2 v0.23.0 变更归档

变更项	说明
统一3D渲染路径	移除useScene/SceneFallbackViewer，统一flutter_3d_controller WebView
Sticker3DPanel真实3D	预览弹窗从静态占位→Flutter3DViewer实时渲染
低端设备检测	device_info_plus检测 + UI降级提示
画布3D贴纸真实渲染	静态图标→Flutter3DViewer实时渲染
图层模型统一	sticker_picker从StickerLayer→StickerLayerInfo/LayerInfo
pro_editor_bridge拆分	992行→3文件 (bridge + sticker_config_builder + widget_layer_factory)
3D模型扩展	model_catalog.json新增decoration(3)+nature(2)共5个模型
3D贴纸导出	WidgetLayerRenderer支持3D层(静态快照替代WebView截图)

13.3 待开发

Phase	版本	功能	前置条件
Phase 3	v0.24.0	PBR材质+环境光照+场景截图	flutter_3d_controller深度适配
Phase 4	v0.25.0	3D文字+网络3D模型	Phase 3完成

---

十四、flutter_slidable ^4.0.3 — 接口详解 (🆕 v1.9.0 新增)

滑动操作组件，iOS风格列表项左滑/右滑操作

14.1 核心API

Slidable({
  Key? key,
  required Widget child,
  SlidableController? controller,
  ActionPane? startActionPane,  // 左滑/上滑操作面板
  ActionPane? endActionPane,    // 右滑/下滑操作面板
  double closeOnScrollThreshold = 8.0,
  bool closeOnScroll = true,
  Duration closeDuration = const Duration(milliseconds: 400),
})

ActionPane({
  required Widget motion,       // 动画效果
  double extentToPreviousChild = 0.0,
  DismissiblePane? dismissible,
  List<Widget> children,        // 操作按钮
})

SlidableAction({
  VoidCallback? onPressed,
  Color backgroundColor,
  Color? foregroundColor,
  Widget? icon,
  String? label,
  bool autoClose = true,
  int flex = 1,
  BorderRadius? borderRadius,
  EdgeInsets? padding,
})

// 4种内置动画
ScrollMotion()     // 滚动效果（推荐iOS风格）
BehindMotion()     // 背后显示
StretchMotion()    // 拉伸效果（最接近iOS原生）
DrawerMotion()     // 抽屉效果

// 控制器
SlidableController controller;
controller.openStartActionPane();
controller.openEndActionPane();
controller.close();

14.2 可扩展功能清单

#	功能	对应API	与现有功能结合点	优先级	状态
SL1	📝 笔记滑动操作	endActionPane	笔记列表左滑删除/编辑	P0	⏳
SL2	❤️ 收藏滑动操作	startActionPane	收藏列表右滑取消收藏	P0	⏳
SL3	📜 历史滑动删除	DismissiblePane	阅读历史滑动删除	P0	⏳
SL4	🔍 搜索历史滑动	SlidableAction	搜索页历史记录管理	P1	⏳
SL5	🏷️ 标签滑动操作	endActionPane	标签重命名/删除	P1	⏳
SL6	🛠️ 工具滑动操作	startActionPane	工具置顶/取消收藏	P1	⏳
SL7	💬 句子卡片滑动	SlidableAction	收藏/分享/纠错快捷操作	P2	⏳
SL8	🎨 自定义滑动动画	StretchMotion	iOS风格拉伸效果	P2	⏳

---

十五、flutter_sticky_header ^0.8.0 — 接口详解 (🆕 v1.9.0 新增)

粘性分组头组件，CustomScrollView中实现分组吸顶

15.1 核心API

SliverStickyHeader({
  Key? key,
  required Widget header,
  required Widget sliver,
  bool sticky = true,
  SliverStickyHeaderController? controller,
  bool overlapsContent = false,
})

SliverStickyHeader.builder({
  Key? key,
  required SliverStickyHeaderBuilderCallback builder,
  required Widget sliver,
  bool sticky = true,
  SliverStickyHeaderController? controller,
  bool overlapsContent = false,
})

typedef SliverStickyHeaderBuilderCallback =
  Widget Function(BuildContext context, SliverStickyHeaderState state);

class SliverStickyHeaderState {
  double get scrollPercentage;  // 0.0~1.0 滚动百分比
  bool get isPinned;            // 是否吸顶
}

class SliverStickyHeaderController
  extends ChangeNotifier {
  double get scrollOffset;      // 当前粘性头偏移
}

15.2 可扩展功能清单

#	功能	对应API	与现有功能结合点	优先级	状态
SH1	📂 工具中心分类吸顶	SliverStickyHeader	工具面板按分类吸顶	P0	⏳
SH2	🔥 热搜平台分组吸顶	SliverStickyHeader	热搜榜按平台分组	P0	⏳
SH3	📝 笔记日期分组吸顶	builder + isPinned	笔记列表按日期分组	P1	⏳
SH4	📜 历史日期分组吸顶	SliverStickyHeader	阅读历史按日期分组	P1	⏳
SH5	🎨 传统色色系吸顶	SliverStickyHeader	传统色按色系分组	P1	⏳
SH6	📝 汉语拼音分组吸顶	SliverStickyHeader	汉字查询A-Z分组	P2	⏳
SH7	🍶 酒方分类吸顶	SliverStickyHeader	酒方按分类分组	P2	⏳
SH8	🎭 吸顶动画效果	builder + scrollPercentage	吸顶时header渐变/缩放	P2	⏳

---

十六、value_layout_builder ^0.5.0 — 接口详解 (🆕 v1.9.0 新增)

LayoutBuilder扩展，布局阶段传递自定义值，flutter_sticky_header底层依赖

16.1 核心API

ValueLayoutBuilder<T>({
  Key? key,
  required ValueLayoutWidgetBuilder<T> builder,
})

typedef ValueLayoutWidgetBuilder<T> =
  Widget Function(BuildContext context, BoxValueConstraints<T> constraints);

class BoxValueConstraints<T> extends BoxConstraints {
  final T value;
}

class SliverValueLayoutBuilder<T> {
  SliverValueWidgetBuilder<T> builder;
}

class SliverValueConstraints<T> extends SliverConstraints {
  final T value;
}

16.2 可扩展功能清单

#	功能	对应API	与现有功能结合点	优先级	状态
VL1	📐 响应式断点传递	ValueLayoutBuilder<Breakpoint>	替代MediaQuery布局断点	P2	⏳
VL2	🎨 主题值布局传递	ValueLayoutBuilder<ThemeData>	配合sticky_header传递滚动偏移	P3	⏳
VL3	📊 列表项位置感知	SliverValueLayoutBuilder	列表项可见性检测	P3	⏳

注：此库主要作为 flutter_sticky_header 的依赖，独立使用场景较少

---

十七、已有库 + API 组合扩展 (🆕 v1.9.0 新增)

17.1 现有库未充分利用能力

已有库	当前用途	🔓 可扩展功能
cached_network_image	图片缓存显示	配合热搜API显示热搜配图
connectivity_plus	网络检测	工具状态实时监测（离线灰显）
image_picker + file_picker	选图	OCR识别工具 + 图片压缩工具
share_plus	分享	所有工具结果一键分享
shimmer	骨架屏	工具列表加载态 + 搜索结果加载态
flutter_animate	动画	工具卡片入场动画 + 签到庆祝动画
confetti	庆祝效果	签到成功 + 成就解锁
lottie	Lottie动画	工具加载动画 + 空状态动画
adaptive_palette	图片主色提取	句子卡片自动取色背景
flutter_svg	SVG渲染	工具分类图标 + 空状态插画
google_fonts	字体	笔记编辑器字体选择 + 卡片字体
gal	保存到相册	卡片导出保存 + 传统色保存
archive + crypto	压缩/加密	数据导出加密 + 笔记备份
drift	本地数据库	工具使用统计持久化 + 搜索历史
flutter_secure_storage	安全存储	隐私笔记加密存储

17.2 API + 已有库组合扩展

组合	功能	需新增库
/api/hanzi/search + drift + shimmer + flutter_sticky_header	17种汉语工具 + 本地缓存 + 加载态 + 分组吸顶	❌
/api/hot/read + cached_network_image + flutter_sticky_header	热搜榜 + 配图 + 平台分组吸顶	❌
/api/hanzi/china_colors + gal + adaptive_palette + flutter_sticky_header	传统色浏览 + 保存 + 取色 + 色系吸顶	❌
/api/webapi/ocr + image_picker + flutter_slidable	OCR识别 + 历史记录滑动删除	❌
/api/webapi/ImgCompress + image_picker + gal	图片压缩 + 保存	❌
/api/hanzi/search + share_plus + flutter_animate + flutter_slidable	趣味工具 + 分享 + 动画 + 滑动操作	❌
/api/hitokoto/* + confetti + flutter_animate	一言句子 + 庆祝效果 + 动画	❌
/api/user/note + flutter_slidable + flutter_sticky_header	笔记CRUD + 滑动操作 + 日期分组吸顶	❌
/api/user/favorite + flutter_slidable	收藏管理 + 滑动取消收藏	❌

17.3 还需要的第三方库

库	用途	对应功能	优先级	状态
flutter_markdown	Markdown渲染	工具结果/笔记/说明展示	P1	⬜
pull_down_button	iOS下拉菜单	工具操作菜单	P1	⬜
sliver_tools	Sliver组合工具	多Sliver布局组合	P2	⬜
bot_toast	Toast提示	操作反馈	P2	⬜
in_app_review	应用评分	引导用户评分	P3	⬜
app_links	深度链接	外部打开工具	P3	⬜