# QRCode

**Repository Path**: starryplay/qrcode

## Basic Information

- **Project Name**: QRCode
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-13
- **Last Updated**: 2025-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QRCode & Camera Snapshot 二维码生成与相机截图工具

基于 Cocos Creator 3.x 的多功能工具库，支持二维码生成与保存，以及相机截图功能，面向多平台部署（Web、Android、iOS）。该项目完全自主实现了二维码生成算法，无需依赖第三方库。

## 功能特性

- **二维码生成**
  - 高性能二维码生成，支持自定义内容、大小和颜色
  - 支持不同错误纠正级别（L、M、Q、H）
  - 支持将生成的二维码保存到相册（Android/iOS）或下载（Web）

- **相机截图**
  - 支持捕获任何相机视图并保存到相册
  - 自动处理不同平台图像数据格式差异
  - 可自定义截图尺寸和文件名

- **通用特性**
  - 简单易用的API，可在游戏或应用中快速集成
  - 提供完整的示例场景和详细文档
  - 高效的内存管理，避免资源泄漏
  - 跨平台兼容，处理平台特定的差异

## 安装说明

1. 将本项目克隆或下载到本地
2. 使用 Cocos Creator 3.8.6 或以上版本打开项目
3. 将以下文件夹复制到你的项目中：
   - `assets/scripts/qrcode` - 二维码生成相关组件
   - `assets/scripts/camera` - 相机截图相关组件
   - `assets/scripts/core` - 核心工具类和事件定义
   - `native/engine` - 原生平台实现代码（Android/iOS）

## 使用方法

### 二维码生成

#### 基本用法

1. 在场景中创建一个节点作为二维码容器
2. 添加 `Graphics` 组件用于绘制二维码
3. 添加 `QRCodeGenerator` 组件并设置参数
4. 运行场景，二维码将自动生成

```typescript
// 创建并配置二维码生成器
const qrNode = new Node('qrcode');
const graphics = qrNode.addComponent(Graphics);
const generator = qrNode.addComponent(QRCodeGenerator);

// 设置二维码参数
generator.content = "https://example.com";  // 二维码内容
generator.size = 200;                       // 二维码大小（像素）
generator.errorCorrectionLevel = "H";       // 错误纠正级别（L, M, Q, H）
generator.generateOnStart = true;           // 自动生成

// 添加到场景
canvas.addChild(qrNode);
```

#### 动态更新二维码

可以使用 `QRCodeGenerator` 组件提供的方法动态更新二维码：

```typescript
// 获取二维码生成器组件
const generator = this.node.getComponent(QRCodeGenerator);

// 更新二维码内容
generator.setContent("https://new-url.com");

// 更新二维码大小
generator.setSize(300);

// 更新二维码颜色
import { Color } from "cc";
generator.setColors(new Color(0, 0, 255, 255), new Color(255, 255, 0, 255));
```

#### 保存二维码到相册

要将生成的二维码保存到用户相册，需要使用 `QRCodeSaver` 组件：

```typescript
// 添加 QRCodeSaver 组件
const saver = this.node.addComponent(QRCodeSaver);

// 设置参数
saver.qrCodeNode = qrNode;        // 二维码节点
saver.camera = this.camera;       // 用于截图的相机（可选，会自动创建临时相机）
saver.fileName = "my_qrcode";     // 保存的文件名

// 保存到相册
saver.saveQRCodeToGallery();
```

### 相机截图功能

#### 基本用法

1. 在场景中添加一个节点
2. 添加 `CameraSnapshotSaver` 组件并设置参数
3. 调用保存方法捕获并保存相机视图

```typescript
// 添加 CameraSnapshotSaver 组件
const snapshotSaver = this.node.addComponent(CameraSnapshotSaver);

// 设置参数
snapshotSaver.camera = this.mainCamera;               // 要捕获的相机
snapshotSaver.fileName = "game_screenshot";           // 保存的文件名
snapshotSaver.snapshotWidth = 1080;                   // 截图宽度（可选）
snapshotSaver.snapshotHeight = 1920;                  // 截图高度（可选）
snapshotSaver.saveImageResultText = this.resultText;  // 显示结果的文本节点（可选）

// 保存相机截图到相册
snapshotSaver.saveCameraSnapshotToGallery();
```

#### 自定义截图尺寸

可以通过以下属性自定义截图的尺寸：

```typescript
// 设置自定义截图尺寸
snapshotSaver.snapshotWidth = 720;   // 自定义宽度
snapshotSaver.snapshotHeight = 1280; // 自定义高度

// 如果设置为0，则使用屏幕当前尺寸
snapshotSaver.snapshotWidth = 0;
snapshotSaver.snapshotHeight = 0;
```

## 原生平台支持

本项目包含原生平台的实现代码，位于 `native/engine` 目录下：

### iOS原生实现 (`native/engine/ios/QRCodeSaver.m`)

iOS原生实现主要负责将图像数据保存到相册，核心功能包括：

- 从临时文件加载原始像素数据
- 将像素数据转换为UIImage对象
- 使用PhotosAPI将图像保存到用户相册
- 处理权限请求和结果回调

关键方法：
- `saveImageFromFile:withWidth:withHeight:withChannels:` - 从文件加载图像并保存到相册
- `createImageFromPixelData:width:height:channels:` - 将原始像素数据转换为UIImage
- `checkPhotoLibraryPermission` - 检查并请求相册访问权限

### Android原生实现 (`native/engine/android/src/...`)

Android原生实现提供了将图像数据保存到相册的功能：

- 支持Base64编码的图像数据处理
- 自动申请存储权限
- 通过MediaStore API保存图像到公共相册
- 处理不同Android版本的API差异

关键类和方法：
- `QRCodeSaver` - 主要处理类，提供图像保存功能
- `saveImageToGallery` - 将图像数据保存到相册
- `onRequestPermissionsResult` - 处理权限请求结果

## 平台特定注意事项

### 图像数据处理

由于不同平台处理图像数据的方式不同，本库自动处理了跨平台兼容性：

- **iOS平台**: 图像数据不需要垂直翻转
- **Android平台**: 图像数据需要垂直翻转以修正方向
- **Web平台**: 支持Canvas绘制和下载

### 内存管理

为避免内存泄漏，特别是纹理资源的泄漏，本库实现了严格的资源清理：

- 渲染纹理在使用后通过 `destroy()` 方法显式释放
- 临时节点和相机在使用后被正确清理
- 使用 `try/finally` 块确保即使发生异常，资源也能被正确释放

## 错误纠正级别说明

二维码支持以下错误纠正级别：

- **L (Low)**: 7% 的字码可被恢复
- **M (Medium)**: 15% 的字码可被恢复
- **Q (Quartile)**: 25% 的字码可被恢复
- **H (High)**: 30% 的字码可被恢复

错误纠正级别越高，二维码可以承受的损坏程度越大，但同时数据密度会降低。

## 示例场景

项目中包含完整的示例场景：

1. `assets/scenes/main.scene` - 二维码生成与保存示例
   - 保存按钮用于将二维码保存到相册
   - 文本显示保存结果

2. `assets/scenes/main.scene` - 相机截图示例
   - 按钮用于触发截图保存操作
   - 文本显示保存结果

## 实现原理

### 二维码生成

二维码生成模块完全自主实现，核心实现包括：

1. `QRCode.ts`: 主要二维码生成类
2. `QRCodeGenerator.ts`: 在Cocos Creator中使用的组件封装
3. `QRCodeSaver.ts`: 处理二维码图片保存功能
4. 其他辅助类: 实现了掩码模式、数据编码、错误校正等功能

### 相机截图

相机截图功能核心实现：

1. `CameraSnapshotSaver.ts`: 相机截图与保存的主要组件
2. 使用RenderTexture捕获相机视图
3. 根据平台差异处理图像数据
4. 通过原生桥接将图像数据传递给原生平台处理

### 原生桥接

JavaScript与原生代码的通信通过Cocos Creator提供的桥接机制实现：

1. **JS到原生**: 
   ```typescript
   native.bridge.sendToNative(SAVE_IMAGE_EVENT.SAVE_IMAGE_TO_PHOTO, JSON.stringify(params));
   ```

2. **原生到JS**:
   ```typescript
   nativeCbMgr.registerCallback(SAVE_IMAGE_EVENT.SAVE_IMAGE_TO_PHOTO_RESULT, (data: string) => {
       // 处理回调结果
   });
   ```

## 平台支持

- **Web**: 支持生成二维码和相机截图，并下载到本地
- **Android**: 支持生成二维码和相机截图，并保存到相册
- **iOS**: 支持生成二维码和相机截图，并保存到相册

## 注意事项

1. 在 Android 和 iOS 平台上，需要确保应用有适当的权限才能保存图片到相册：
   - **iOS**: 需要在Info.plist中添加`NSPhotoLibraryUsageDescription`
   - **Android**: 需要声明`WRITE_EXTERNAL_STORAGE`权限（Android 10以下）

2. 图像处理和保存可能耗费资源，建议不要频繁调用保存功能

3. 二维码内容过长可能导致二维码密度过高，影响扫描效果，建议使用高错误纠正级别（如 H）提高扫描可靠性

## 许可证

本项目使用 MIT 许可证，详情请参见 LICENSE 文件。