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

> 创建时间: 2026-04-25
> 更新时间: 2026-04-27
> 版本: v0.23.0
> 关联文档: [08_编辑器功能清单](./08_编辑器功能清单.md)
> 说明: 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

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

```dart
// === 增强图片组件 ===
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

```dart
// === 单图缩放查看 ===
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

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

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

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

```dart
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 | ⬜ |