# flutter_cosson_image

**Repository Path**: DSRheart/flutter_cosson_image

## Basic Information

- **Project Name**: flutter_cosson_image
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flutter_cosson_image

一个用于在 Flutter 中展示加密图片的插件。

## 功能特性

- 🔐 使用 AES-GCM 加密算法保护图片

## 前置要求

- Flutter SDK >= 3.3.0
- iOS 13.0+ 
- Xcode 12.0+

## 安装

### 1. 添加依赖

在 `pubspec.yaml` 中添加依赖：

```yaml
dependencies:
  flutter_cosson_image:
    git:
      url: https://github.com/your-username/flutter_cosson_image.git
      ref: main
```

或者使用本地路径：

```yaml
dependencies:
  flutter_cosson_image:
    path: ../flutter_cosson_image
```

### 2. 安装依赖

```bash
flutter pub get
```

### 3. iOS 配置

插件已包含预构建的 `ImageDecryptLib.framework`，无需额外构建步骤。

如果需要在 iOS 项目中使用，运行：

```bash
cd ios
pod install
```

## 使用方法

### 基本用法

插件会自动处理 Flutter asset 路径，直接使用文件路径即可：

```dart
import 'package:flutter_cosson_image/flutter_cosson_image.dart';

// 使用 Flutter 实现（跨平台）
CossonImage(
  imagePath: 'assets/i2/encrypted_image.png',
  keyString: 'your_32_char_hex_key_string',
  width: 200,
  height: 200,
  fit: BoxFit.contain,
)
```

### iOS 原生实现（推荐，性能更好）

在 iOS 平台上，可以使用原生 PlatformView 获得更好的性能：

```dart
// 使用 iOS 原生实现（仅 iOS 平台）
CossonImageNative(
  imagePath: 'assets/i2/encrypted_image.png',
  keyString: 'your_32_char_hex_key_string',
  width: 200,
  height: 200,
)
```

### 编程式解密

如果需要手动控制解密过程：

```dart
final flutterCossonImage = FlutterCossonImage();
final imageData = await flutterCossonImage.decryptImage(
  'assets/i2/encrypted_image.png',
  'your_32_char_hex_key_string',
);

if (imageData != null) {
  // 使用解密后的图片数据
  Image.memory(imageData);
}
```

### 自定义占位符和错误处理

```dart
CossonImage(
  imagePath: 'assets/i2/encrypted_image.png',
  keyString: 'your_32_char_hex_key_string',
  width: 200,
  height: 200,
  placeholder: const Center(child: CircularProgressIndicator()),
  errorWidget: const Center(child: Text('加载失败')),
)
```

## API 文档

### CossonImage

用于展示加密图片的 Flutter Widget。

**参数：**

- `imagePath` (String, required): 加密图片的文件路径（支持 Flutter assets，以 `assets/` 开头）
- `keyString` (String, required): 解密密钥（32 个字符的 16 进制字符串）
- `width` (double?, optional): 图片宽度
- `height` (double?, optional): 图片高度
- `fit` (BoxFit, optional): 图片适配方式，默认为 `BoxFit.contain`
- `placeholder` (Widget?, optional): 加载中时显示的占位符
- `errorWidget` (Widget?, optional): 加载失败时显示的 Widget

### CossonImageNative

使用 iOS 原生 PlatformView 展示加密图片（仅 iOS 平台）。

**参数：**

- `imagePath` (String, required): 加密图片的文件路径（支持 Flutter assets，以 `assets/` 开头）
- `keyString` (String, required): 解密密钥（32 个字符的 16 进制字符串）
- `width` (double?, optional): 图片宽度
- `height` (double?, optional): 图片高度

**注意：** 在非 iOS 平台上，会自动回退到 `CossonImage` 实现。

### FlutterCossonImage

插件的主要 API 类。

#### decryptImage

解密加密图片。

```dart
Future<Uint8List?> decryptImage(String imagePath, String keyString)
```

**参数：**

- `imagePath` (String): 加密图片的文件路径（支持 Flutter assets，以 `assets/` 开头）
- `keyString` (String): 解密密钥（32 个字符的 16 进制字符串）

**返回值：**

- `Future<Uint8List?>`: 解密后的图片数据，如果解密失败则返回 `null`

## 加密图片格式

- **加密算法**: AES-GCM-256
- **密钥格式**: 32 个字符的 16 进制字符串（UTF-8 编码后作为 32 字节密钥）
- **数据格式**: [12 字节 nonce] + [加密数据] + [16 字节 GCM tag]

## 项目结构

```
flutter_cosson_image/
├── lib/
│   ├── flutter_cosson_image.dart              # 主入口，包含 Widget 组件
│   ├── flutter_cosson_image_platform_interface.dart
│   ├── flutter_cosson_image_method_channel.dart
│   └── flutter_cosson_image_web.dart
├── ios/
│   ├── Classes/
│   │   └── FlutterCossonImagePlugin.swift     # iOS 插件实现
│   ├── Frameworks/
│   │   └── ImageDecryptLib.framework          # 原生解密库（已预构建）
│   └── flutter_cosson_image.podspec
└── example/                                    # 示例项目
    └── lib/
        └── main.dart
```

## 注意事项

1. **Asset 路径**: 如果图片在 `assets` 目录中，使用 `assets/` 前缀的路径。插件会自动处理路径转换。

2. **密钥安全**: 密钥应该安全存储，不要硬编码在代码中。建议使用环境变量或安全的配置管理方案。

3. **平台支持**:
   - **iOS**: 使用原生 framework 实现，性能最佳
   - **Android**: 使用 Flutter 实现（通过 MethodChannel 调用原生代码）
   - **Web**: 使用 Flutter 实现（通过 MethodChannel 调用原生代码）

4. **性能优化**:
   - 在 iOS 平台上使用 `CossonImageNative` 可以获得更好的性能
   - 插件会自动处理 asset 路径，无需手动加载数据

## 示例项目

查看 `example/lib/main.dart` 获取完整的使用示例。

运行示例：

```bash
cd example
flutter run
```