feat: 新增编辑器功能与优化
1. 添加编辑器3D场景服务接口及实现 2. 实现平台IO工具类与数据库连接 3. 新增SVG图标资源 4. 优化编辑器操作Mixin架构 5. 修复Web端兼容性问题 6. 更新依赖配置与构建脚本 7. 改进主题自适应服务 8. 添加对齐辅助线组件 9. 完善迷你文字编辑栏 10. 优化页面过渡动画
This commit is contained in:
Developer
691
docs/09_三方库扩展功能开发文档.md
Normal file
691
docs/09_三方库扩展功能开发文档.md
Normal file
@@ -0,0 +1,691 @@
|
||||
# 闲言APP — 三方库扩展功能开发文档
|
||||
|
||||
> 创建时间: 2026-04-25
|
||||
> 更新时间: 2026-04-25
|
||||
> 版本: v0.22.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 — 接口详解 (✅ 已归档)
|
||||
|
||||
> Phase 2 核心已完成，Scene3DService + Platform3DService 已实现
|
||||
|
||||
### 3.1 关键接口速查
|
||||
|
||||
| 类别 | 核心API | 已适配到 |
|
||||
|------|---------|---------|
|
||||
| 场景管理 | `Scene() / add / remove / render` | Scene3DService |
|
||||
| 模型加载 | `Node.fromAsset / fromFlatbuffer` | Scene3DService |
|
||||
| 相机控制 | `PerspectiveCamera(position/target/fov)` | Scene3DService |
|
||||
| 材质系统 | `PhysicallyBasedMaterial / UnlitMaterial` | 待Phase 3 |
|
||||
| 环境光照 | `Environment / EnvironmentMap` | 待Phase 3 |
|
||||
| 动画系统 | `AnimationClip / AnimationPlayer` | Scene3DService (基础) |
|
||||
| 几何体 | `CuboidGeometry / Geometry` | 待Phase 3 |
|
||||
|
||||
### 3.2 已实现功能
|
||||
|
||||
| # | 功能 | 状态 | 产出文件 |
|
||||
|---|------|:----:|---------|
|
||||
| S1 | 🎬 3D模型贴纸 | ✅ | sticker_3d_panel.dart |
|
||||
| S2 | 🔄 3D渲染服务 | ✅ | scene_3d_service.dart |
|
||||
| S3 | 🖥️ 平台调度 | ✅ | platform_3d_service.dart |
|
||||
| S4 | 📋 模型目录 | ✅ | model_catalog_service.dart |
|
||||
|
||||
### 3.3 ⚠️ 限制
|
||||
|
||||
- 不支持Web (Impeller Web后端未就绪)
|
||||
- 模型需预编译: `.glb` → `.model` (flutter_scene_importer)
|
||||
- 需要 Flutter ≥3.29.0 + Impeller
|
||||
|
||||
---
|
||||
|
||||
## 四、flutter_3d_controller — 接口详解 (✅ 已归档)
|
||||
|
||||
> Phase 2 核心已完成，Model3DPreviewPage 已实现
|
||||
|
||||
### 4.1 关键接口速查
|
||||
|
||||
| 类别 | 核心API | 已适配到 |
|
||||
|------|---------|---------|
|
||||
| GLB查看 | `Flutter3DViewer(src:, controller:)` | Model3DPreviewPage |
|
||||
| 控制器 | `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 |
|
||||
|
||||
---
|
||||
|
||||
## 五、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 3 | PBR材质 + 环境光照 + 场景导出 | ⏳ 待开发 |
|
||||
| v0.24.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 |
|
||||
Reference in New Issue
Block a user