npm package: @nlexploit/image-editor-sdk
Description: 高性能 Web 图片编辑 SDK，基于 Fabric.js 和 Vue 3
Latest version: 1.0.4

# image-editor-sdk

> 高性能 Web 图片编辑 SDK，基于 Fabric.js 和 Vue 3

一个功能丰富的图片编辑 SDK，提供裁剪、调整、滤镜、AI 处理、绘制、文本、边框、拼图、水印等完整的图片编辑能力。

## ✨ 特性

- 🎨 **丰富的编辑功能**：裁剪、调整大小、滤镜、颜色调整、AI 处理等
- 🤖 **AI 能力集成**：图片翻译、智能消除、高清修复、一键抠图
- 🖌️ **自由绘制**：支持画笔、形状绘制
- 📝 **文本编辑**：支持文本添加、样式调整
- 🎭 **特效处理**：滤镜、颜色叠加、HDR 修复、白平衡调整
- 🧩 **拼图功能**：多图拼接、间距和圆角调整
- 🖼️ **边框与水印**：自定义边框样式、水印添加
- ⚡ **高性能**：基于 Fabric.js 5.x，支持大图处理
- 🎯 **易于集成**：支持外部配置 Token 和 API，灵活适配不同项目
- 📦 **轻量级**：核心依赖作为 peerDependencies，包体积小

## 📦 安装

```bash
# 安装 SDK
npm install @nlexploit/image-editor-sdk

# 安装 peerDependencies（必需）
npm install vue@^3.3.0 fabric@^5.3.0 file-saver@^2.0.5
```

## 🚀 快速开始

### 作为 npm 包使用（集成到其他项目）

当作为 npm 包被外部项目使用时，需要先调用 `init()` 函数传入配置：

```javascript
import ImageEditor, { init } from "@nlexploit/image-editor-sdk";
import "@nlexploit/image-editor-sdk/style.css";

// 初始化配置
init({
  api: {
    baseURL: "https://api.example.com",
    apiPrefix: "/prod-api",
  },
  token: async () => {
    // 从你的项目获取 token
    return await getTokenFromYourProject();
  },
});
```

在 Vue 组件中使用：

```vue
<template>
  <ImageEditor :imageUrl="imageUrl" />
</template>

<script setup>
import ImageEditor from "@nlexploit/image-editor-sdk";
import { ref } from "vue";

const imageUrl = ref("https://example.com/image.jpg");
</script>
```

### 开发环境使用（未集成到其他项目）

在开发本项目时，**无需调用 `init()` 函数**，SDK 会自动使用：

- **Token**：从 Cookie 读取（`Admin-Token` 或 `Platform-Admin-Token`）
- **API 配置**：从环境变量读取（`VITE_BACKEND`、`VITE_API_PREFIX`）

只需确保：

1. 环境变量已配置（`.env` 文件）
2. Cookie 中已设置 token

```vue
<template>
  <ImageEditor />
</template>

<script setup>
import ImageEditor from "./components/layout/EditorLayout.vue";
</script>
```

## ⚙️ 配置

### init() 函数配置

#### API 配置

```typescript
{
  api: {
    baseURL?: string;      // 后端基础地址，如 'https://api.example.com'
    apiPrefix?: string;    // API 前缀，如 '/prod-api'
  }
}
```

#### Token 配置

支持两种方式：

**方式 1：回调函数（推荐）**

每次请求时动态获取 token，支持 token 刷新：

```javascript
init({
  api: {
    baseURL: "https://api.example.com",
    apiPrefix: "/prod-api",
  },
  token: async () => {
    // 从你的状态管理或 API 获取 token
    return await getTokenFromYourProject();
  },
});
```

**方式 2：直接传入 token 字符串**

```javascript
init({
  api: {
    baseURL: "https://api.example.com",
    apiPrefix: "/prod-api",
  },
  token: "Bearer xxxxx",
});
```

### 组件 Props

```typescript
interface EditorLayoutProps {
  imageUrl?: string; // 初始图片链接
  textMap?: {
    // 文本映射表
    upload?: string; // 上传按钮文本
    save?: string; // 保存按钮文本
    title?: string; // 标题文本
  };
  config?: {
    // 全局配置
    aiBaseUrl?: string; // AI 后端地址
  };
}
```

### 配置优先级

- **Token 获取优先级**：外部配置的回调函数 > 外部配置的字符串 > Cookie 回退
- **API 配置优先级**：外部配置 > 环境变量 > 默认值

## 🎯 功能模块

### 调整类（Adjust）

- **裁剪（Crop）**：自由裁剪、比例裁剪
- **调整大小（Resize）**：按尺寸或比例调整
- **滤镜（Filters）**：多种内置滤镜效果
- **颜色调整（Color）**：亮度、对比度、饱和度等
- **颜色叠加（ColorOverlay）**：颜色混合模式
- **HDR 修复（HDRemaster）**：高清修复和超分辨率
- **智能消除（Inpaint）**：AI 驱动的图片内容消除
- **一键抠图（Rembg）**：自动去除背景
- **白平衡（White）**：自动和手动白平衡调整
- **标尺（Ruler）**：辅助线和标尺工具
- **马赛克（Mosaic）**：局部马赛克处理

### AI 功能

- **图片翻译**：多语言图片文字翻译
- **智能消除**：AI 驱动的图片内容消除
- **高清修复**：AI 超分辨率提升

### 其他功能

- **自由绘制（Draw）**：画笔、形状绘制
- **文本（Text）**：文本添加、样式调整
- **边框（Border）**：自定义边框样式
- **拼图（Puzzle）**：多图拼接、布局调整
- **水印（Watermark）**：水印添加和管理
- **素材（Material）**：模板素材管理

## 📝 注意事项

### 静态资源

SDK 不包含静态资源（如图片），需要使用者自行提供或通过 CDN 加载。

### peerDependencies

使用前请确保已安装以下依赖：

- `vue@^3.3.0` - Vue 3 框架
- `fabric@^5.3.0` - Canvas 图形库
- `file-saver@^2.0.5` - 文件保存工具

### 浏览器兼容性

- 现代浏览器（Chrome、Firefox、Safari、Edge 最新版本）
- 需要支持 ES6+ 和 Canvas API

## 🔧 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 预览构建结果
npm run preview
```

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 支持

如有问题或建议，请通过以下方式联系：

- 提交 [Issue](https://github.com/your-org/nlexploit-image-editor-sdk/issues)
- 查看 [文档](https://github.com/your-org/nlexploit-image-editor-sdk#readme)

---

Made with ❤️ by @nlexploit/image-editor-sdk team