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

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

> 创建时间: 2026-04-25
> 更新时间: 2026-05-18
> 版本: v0.26.0
> 关联文档: [07_三方库清单](./07_三方库清单.md) | [10_三方库接入开发清单](./10_三方库接入开发清单.md)
> 说明: 三方库接口分析、扩展功能、开发流程 + 鸿蒙适配状态
> v0.26更新: 版本号同步pubspec.yaml + 新增文件传输层库接口 + 鸿蒙30包适配标注 + 状态更新

---

## 一、库总览与平台兼容性

### 1.1 核心库定位

| 库 | 版本 | 定位 | 渲染引擎 | 跨平台等级 | 鸿蒙 |
|----|------|------|---------|-----------|:----:|
| flutter_advanced_canvas_editor | 2.1.0 | 图层管理系统 | Flutter Canvas | 🟢 全平台 | ✅ |
| 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 | 🟢 全平台 | ✅ |
| flutter_slidable | 4.0.3 | 列表项滑动操作 | Flutter Canvas | 🟢 全平台 | ✅ |
| flutter_sticky_header | 0.8.0 | 粘性分组头 | Flutter Canvas | 🟢 全平台 | ✅ |
| pull_down_button | 0.10.1 | iOS下拉菜单 | Flutter Canvas | 🟢 全平台 | ✅ |

### 1.2 平台兼容性矩阵

| 平台 | canvas_editor | 3d_controller | image_size_getter | extended_image | photo_view | image_compress | slidable | sticky_header |
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| Android | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| iOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| macOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Web | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ |
| 鸿蒙 | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

### 1.3 依赖关系

| 库 | 核心依赖 | 包体积影响 |
|----|---------|-----------|
| flutter_advanced_canvas_editor | 无 (纯Dart) | ~0KB |
| 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_slidable | 无 (纯Dart) | ~0KB |
| flutter_sticky_header | value_layout_builder | ~0KB |
| pull_down_button | 无 (纯Dart) | ~0KB |

---

## 二、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 移除原因

- 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 核心API

```dart
class ImageSizeGetter {
  static SizeResult getSizeResult(ImageInput input);
  static Future<SizeResult> getSizeResultAsync(ImageInput input);
  static bool isPng/isJpg/isGif/isWebp/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)
}
```

### 5.2 可扩展功能清单

| # | 功能 | 对应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 | ✅ |

---

## 六、extended_image ^10.0.1 — 接口详解

### 6.1 核心API

```dart
ExtendedImage({
  required ImageProvider image,
  ExtendedImageMode mode,             // none / gesture / editor
  GestureConfig? initGestureConfigHandler,
  EditorConfig? initEditorConfigHandler,
})

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

ExtendedResizeImage({
  required ImageProvider imageProvider,
  double compressionRatio = 1.0,
  int? maxBytes, int? width, int? height,
})

ExtendedImageSlidePage({required Widget child})
ExtendedImageGesturePageView({required List<Widget> children})
```

### 6.2 可扩展功能清单

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

### 6.3 与 ProImageEditor 的关系

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

---

## 七、photo_view ^0.15.0 — 接口详解

### 7.1 核心API

```dart
PhotoView({
  required ImageProvider imageProvider,
  double? minScale, double? maxScale, double? initialScale,
  bool enableRotation = false,
  ScaleStateCycle? scaleStateCycle,
  PhotoViewController? controller,
  PhotoViewHeroAttributes? heroAttributes,
})

PhotoView.customChild({required Widget child, Size? childSize})
PhotoViewGallery({required List<PhotoViewGalleryPageOptions> pageOptions})
PhotoViewController { setPosition, setScale, setRotation, reset }
```

### 7.2 可扩展功能清单

| # | 功能 | 对应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.3 与 extended_image 的分工

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

---

## 八、flutter_image_compress ^2.4.0 — 接口详解

### 8.1 核心API

```dart
class FlutterImageCompress {
  static Future<Uint8List> compressWithList(Uint8List image, {
    int minWidth = 1920, int minHeight = 1080, int quality = 95,
    CompressFormat format = CompressFormat.jpeg, bool autoCorrectionAngle = true,
  });
  static Future<Uint8List?> compressWithFile(String path, {...});
  static Future<XFile?> compressAndGetFile(String path, String targetPath, {...});
  static Future<Uint8List?> compressAssetImage(String assetName, {...});
}

enum CompressFormat { jpeg, png, webp, heic }
```

### 8.2 可扩展功能清单

| # | 功能 | 对应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 | ✅ |

---

## 九、flutter_slidable ^4.0.3 — 接口详解 (✅ 已归档)

> 滑动操作组件，iOS风格列表项左滑/右滑操作，已封装为 AppSlidable

### 9.1 核心API

```dart
Slidable({
  required Widget child,
  ActionPane? startActionPane,  // 左滑/上滑操作面板
  ActionPane? endActionPane,    // 右滑/下滑操作面板
  bool closeOnScroll = true,
})

ActionPane({required Widget motion, List<Widget> children})
SlidableAction({VoidCallback? onPressed, Color backgroundColor, Widget? icon, String? label})

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

### 9.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 — 接口详解 (✅ 已归档)

> 粘性分组头组件，已封装为 AppStickyHeaderSliver

### 10.1 核心API

```dart
SliverStickyHeader({
  required Widget header,
  required Widget sliver,
  bool sticky = true,
})

SliverStickyHeader.builder({
  required SliverStickyHeaderBuilderCallback builder,
  required Widget sliver,
})

class SliverStickyHeaderState {
  double get scrollPercentage;  // 0.0~1.0
  bool get isPinned;
}
```

### 10.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 | ⏳ |

---

## 十一、文件传输层库 — 接口详解 (🆕 v0.26.0 新增)

> 文件传输模块涉及7个传输通道，核心三方库接口分析

### 11.1 shelf ^1.4.0 — HTTP 服务器

```dart
import 'package:shelf/shelf.dart';
import 'package:shelf_router/shelf_router.dart';

Router app = Router()
  ..get('/api/files', handleFileList)
  ..post('/api/upload', handleUpload)
  ..get('/api/download/<id>', handleDownload);

Handler handler = const Pipeline()
    .addMiddleware(logRequests())
    .addHandler(app.call);

await IOServer.bind('0.0.0.0', 8080).then((server) => server.handler = handler);
```

**用途**: LocalSend 模式 HTTP 文件服务器，局域网设备发现 + 文件收发

### 11.2 flutter_webrtc ^1.4.0-ohos.1 — WebRTC 传输

```dart
RTCPeerConnection connection = await createPeerConnection({
  'iceServers': [{'urls': 'stun:stun.l.google.com:19302'}],
});

connection.onIceCandidate = (candidate) => signaling.sendCandidate(candidate);
connection.onDataChannel = (channel) => handleDataChannel(channel);

RTCDataChannel dc = await connection.createDataChannel('fileTransfer', RTCDataChannelConfig());
dc.onMessage = (RTCDataChannelMessage msg) => handleChunk(msg);
```

**用途**: WebRTC P2P 传输，支持 NAT 穿透 + 数据通道文件分块传输

### 11.3 flutter_blue_plus ^2.1.0-ohos.1 — 蓝牙 BLE

```dart
FlutterBluePlus.startScan(timeout: Duration(seconds: 10));
List<BluetoothDevice> devices = FlutterBluePlus.connectedDevices;

BluetoothDevice device = devices.first;
await device.connect();
List<BluetoothService> services = await device.discoverServices();

BluetoothCharacteristic characteristic = services.first.characteristics.first;
await characteristic.write(data);
```

**用途**: 蓝牙 BLE 配对 + 小文件传输，适合近距离快速分享

### 11.4 flutter_nfc_kit ^3.6.0-rc.6-ohos — NFC

```dart
NFCTag tag = await FlutterNfcKit.poll(timeout: Duration(seconds: 10));
await FlutterNfcKit.transceive(data);
await FlutterNfcKit.finish();
```

**用途**: NFC 碰一碰配对，交换设备信息后切换到 WiFi/蓝牙传输

### 11.5 mobile_scanner ^7.1.4-ohos.1 — 二维码扫描

```dart
MobileScannerController controller = MobileScannerController();
MobileScanner(
  controller: controller,
  onDetect: (capture) {
    final List<Barcode> barcodes = capture.barcodes;
    for (Barcode barcode in barcodes) {
      handleQRCode(barcode.rawValue!);
    }
  },
);
```

**用途**: QR 码配对扫描，扫描对方设备二维码获取连接信息

### 11.6 web_socket_channel ^3.0.3 — WebSocket 中继

```dart
WebSocketChannel channel = WebSocketChannel.connect(Uri.parse('wss://relay.example.com'));
channel.stream.listen((message) => handleMessage(message));
channel.sink.add(jsonEncode({'type': 'file_chunk', 'data': chunk}));
```

**用途**: WebSocket 中继传输，NAT 穿透失败时的备选通道 + 断点续传

### 11.7 wifi_iot ^0.3.19-ohos.1 — WiFi Hotspot

```dart
await WiFiIoT.setEnabled(true);
await WiFiIoT.setWiFiAPEnabled(true);
String? ssid = await WiFiIoT.getWiFiAPSSID();
```

**用途**: WiFi Direct / 热点模式，创建局域网直连传输通道

---

## 十二、综合功能扩展矩阵

### 12.1 按优先级排序

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

---

## 十三、已有库深度利用

### 13.1 现有库未充分利用能力

| 已有库 | 当前用途 | 🔓 可扩展功能 |
|--------|----------|---------------|
| `cached_network_image` | 图片缓存显示 | ✅ 热搜配图 + 头像缓存 |
| `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` | 安全存储 | ✅ 隐私笔记加密存储 |
| `audioplayers` | 音频播放 | ✅ 语音消息播放 + 提示音效 |
| `record` | 录音 | ✅ 语音消息录制 |
| `flutter_webrtc` | WebRTC | ✅ P2P文件传输 + 屏幕共享 |
| `flutter_blue_plus` | 蓝牙 | ✅ BLE配对 + 小文件传输 |
| `mobile_scanner` | 扫描 | ✅ QR码配对扫描 |

### 13.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` | 收藏管理 + 滑动取消收藏 | ❌ |
| `shelf` + `network_info_plus` + `mobile_scanner` | LocalSend局域网传输 | ❌ |
| `flutter_webrtc` + `shelf_web_socket` + `web_socket_channel` | WebRTC+WebSocket中继传输 | ❌ |
| `flutter_blue_plus` + `flutter_nfc_kit` + `wifi_iot` | 蓝牙+NFC+WiFi近场传输 | ❌ |

---

## 十四、版本规划

| 版本 | 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 6 | 滑动操作 + 粘性头部 + Markdown + iOS菜单 | ✅ 已完成 |
| v0.25.0 | Phase 7 | Feed API + 离线模式 + 缓存管理 | ✅ 已完成 |
| v0.26.0 | Phase 8 | 文件传输层库接入 + 鸿蒙30包适配 | ✅ 已完成 |
| v0.27.0 | Phase 9 | PBR材质 + 环境光照 + 场景导出 | ⏳ 待开发 |
| v0.28.0 | Phase 10 | 3D文字 + 网络3D模型 | ⏳ 待开发 |

---

## 十五、风险与对策

| 风险 | 影响 | 对策 |
|------|------|------|
| flutter_3d_controller 不支持鸿蒙 | 鸿蒙用户无3D渲染 | 鸿蒙端降级为静态图片 |
| flutter_3d_controller 不支持Win/Linux | 桌面用户无3D预览 | 桌面端降级为静态图片 |
| extended_image与ProImageEditor重叠 | 裁剪功能冲突 | 仅作快速裁剪补充，主编辑仍用ProImageEditor |
| flutter_image_compress Web有限制 | Web端压缩能力弱 | Web端降级为Dart纯编码压缩 |
| 大图内存溢出 | 导入超大图OOM | compressWithList预处理 + ExtendedResizeImage |
| WebRTC NAT穿透失败 | P2P传输不可用 | 降级为WebSocket中继传输 |
| 蓝牙BLE传输速度慢 | 大文件传输体验差 | 仅用于小文件/配对，大文件走WiFi |

---

## 十六、归档列表

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

### 16.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 |
| flutter_slidable | v1.9.0 | AppSlidable + SlideActionConfig + DeleteConfirm | 100% | 2026-04-29 |
| flutter_sticky_header | v1.9.0 | AppStickyHeaderSliver + 分类吸顶 | 100% | 2026-04-29 |
| pull_down_button | v1.9.0 | AppPopupMenu | 100% | 2026-04-29 |
| flutter_markdown_plus | v1.9.0 | AppMarkdownBody + AppMarkdown | 100% | 2026-04-29 |
| sliver_tools | v1.9.0 | SliverPinnedHeader + AppToast | 100% | 2026-04-29 |

### 16.2 文件传输层已集成

| 库 | 集成版本 | 核心产出 | 完成度 | 集成日期 |
|----|---------|---------|--------|---------|
| shelf + shelf_router | v0.26.0 | LocalSendService (HTTP文件服务器) | 100% | 2026-05-12 |
| shelf_web_socket | v0.26.0 | WsRelayService (WebSocket中继) | 100% | 2026-05-12 |
| flutter_webrtc | v0.26.0 | WebRTCService (P2P传输) | 100% | 2026-05-12 |
| flutter_blue_plus | v0.26.0 | BluetoothPairingService (BLE配对) | 100% | 2026-05-14 |
| flutter_nfc_kit | v0.26.0 | NfcPairingService (NFC配对) | 100% | 2026-05-14 |
| mobile_scanner | v0.26.0 | QRPairingService (QR配对) | 100% | 2026-05-14 |
| wifi_iot | v0.26.0 | HotspotService (WiFi热点) | 100% | 2026-05-14 |
| web_socket_channel | v0.26.0 | WsRelayChunkAssembler + ResumeHandler | 100% | 2026-05-12 |

### 16.3 待开发

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

---

## 十七、参考链接

| 资源 | 链接 |
|------|------|
| flutter_advanced_canvas_editor | https://pub.dev/packages/flutter_advanced_canvas_editor |
| 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 |
| flutter_slidable | https://pub.dev/packages/flutter_slidable |
| flutter_sticky_header | https://pub.dev/packages/flutter_sticky_header |
| pull_down_button | https://pub.dev/packages/pull_down_button |
| shelf | https://pub.dev/packages/shelf |
| flutter_webrtc | https://pub.dev/packages/flutter_webrtc |
| flutter_blue_plus | https://pub.dev/packages/flutter_blue_plus |
| Impeller | https://github.com/flutter/flutter/wiki/Impeller |