# blinko-plugin-heif-processor

**Repository Path**: slamkk/blinko-plugin-heif-processor

## Basic Information

- **Project Name**: blinko-plugin-heif-processor
- **Description**: HEIF Image Processor Plugin
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HEIF Image Processor Plugin

一个为 Blinko 平台开发的 HEIF/HEIC 图片处理插件，能够自动检测并转换 HEIF 格式图片为通用的 JPEG/PNG 格式，同时保留图片元数据，提升用户上传体验。

## 🌟 功能特性
- **自动检测**：监听文件上传事件，自动识别 HEIF/HEIC 格式文件（通过 MIME 类型和扩展名）
- **格式转换**：将 HEIF/HEIC 图片转换为 JPEG/PNG 格式（默认 JPEG，质量 90）
- **元数据保留**：完整读取并嵌入原始图片的 EXIF 元数据
- **批量处理**：支持多文件批量转换，提供实时进度提示
- **自定义配置**：可通过设置面板调整转换格式、质量及是否保留元数据
- **友好提示**：转换成功/失败的 Toast 消息反馈

## 🛠 技术栈
- 核心语言：TypeScript
- UI 框架：Preact
- 转换库：heic2any (HEIF 格式转换)
- 元数据处理：exifr (EXIF 数据读取/写入)
- 集成接口：Blinko 插件 API

## 📦 安装与使用

### 前置条件
- 已安装 Node.js (v14+) 和 npm
- 已接入 Blinko 插件开发框架

### 安装依赖
```bash
# 安装核心依赖
npm install heic2any exifr

# 安装开发依赖（如需要）
npm install -D @types/heic2any @types/exifr
```

### 插件配置
1. 更新 `plugin.json` 文件，配置插件基本信息（名称、版本、描述、权限等）
2. 将插件代码放入 Blinko 插件目录指定位置

### 构建与发布
```bash
# 构建插件（需在 package.json 中配置 build 脚本）
npm run build

# 发布插件（需在 package.json 中配置 release:publish 脚本）
npm run release:publish
```

## 📂 代码结构
```
src/
├── index.tsx          # 插件入口文件，注册文件上传钩子
├── app.tsx            # 插件主组件（UI 渲染）
├── setting.tsx        # 设置面板组件（配置转换选项）
├── heifConverter.ts   # 核心转换逻辑（检测、转换、元数据处理）
├── locales/           # 国际化资源文件
│   ├── en.json        # 英文翻译
│   └── zh.json        # 中文翻译
└── types/             # TypeScript 类型定义
    └── index.ts       # 类型声明（转换配置、文件信息等）
```

## 🚀 核心流程
1. 插件初始化时，通过 Blinko API 注册文件上传监听钩子
2. 用户上传文件时，`handleFileUpload` 函数检测文件类型
3. 若为 HEIF/HEIC 文件，调用 `heifConverter.ts` 中的转换逻辑
4. 使用 `heic2any` 转换图片格式，`exifr` 处理元数据
5. 实时返回转换进度，转换完成后返回处理后的文件
6. 显示转换结果提示，完成整个流程

## ⚙️ 配置说明
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `targetFormat` | string | `jpeg` | 转换目标格式（jpeg/png） |
| `quality` | number | 90 | JPEG 转换质量（1-100） |
| `preserveMetadata` | boolean | true | 是否保留 EXIF 元数据 |
| `batchProcessing` | boolean | true | 是否启用批量转换 |

## 🧪 测试
```bash
# 运行单元测试（需配置 test 脚本）
npm run test

# 运行集成测试（验证转换功能）
npm run test:integrate
```

测试用例覆盖场景：
- HEIF/HEIC 文件检测准确性
- 不同格式转换结果验证
- 元数据保留完整性
- 批量转换功能
- 异常处理（损坏文件、超大文件等）

## 📄 许可证
本项目采用 MIT 许可证 - 详见 LICENSE 文件

## 📞 反馈与贡献
- 如有问题或建议，欢迎提交 Issue
- 代码贡献请遵循项目代码规范，提交 PR 前请确保测试通过

---

## 总结
1. 该插件核心解决 HEIF/HEIC 图片在 Blinko 平台的兼容性问题，自动转换为通用格式并保留元数据，全程适配 npm 包管理工具。
2. 依赖 `heic2any` 实现格式转换，`exifr` 处理元数据，基于 Blinko 插件 API 完成集成，所有命令均替换为 npm 指令。
3. 提供可配置的转换选项和友好的用户反馈，支持批量处理，提升图片上传体验，且兼容 Node.js 生态的 npm 环境。