syncfusion-react-image-editor

实现 Syncfusion React Image Editor

Syncfusion React Image Editor 是一个功能全面、特性丰富的组件，可直接在 React 应用中编辑图像。它提供直观的界面，并配备强大的变换、注释、特效等工具。

组件概述

Image Editor 将基于画布的编辑环境与全面的工具栏和上下文工具相结合。它支持：

• 多种输入源： 文件、URL、base64、blob、文件管理器、树视图
• 丰富的注释功能： 文本（含样式设置）、形状、手绘图、水印
• 专业特效： 滤镜和微调控件
• 高级操作： Z 顺序管理、涂黑、边框装饰
• 无障碍优先： 完整的键盘导航、符合 WCAG 标准、支持 RTL、120 多个本地化键
• 灵活集成： 可独立使用，也可嵌入对话框，并支持自定义工具栏

文档与导航指南

🔹 API 参考

📄 阅读： references/api.md

• 完整的 API 文档，涵盖所有属性、方法和事件
• 属性概览（核心、工具栏、设置）
• 用于图像操作、变换和注释的方法
• 生命周期、交互、特效和工具栏相关事件
• 枚举和类型定义（ArrowheadType、FrameType、RedactType 等）
• 完整的可运行示例，并验证了方法签名

入门指南

📄 阅读： references/getting-started.md

• 使用 Vite 和 create-react-app 安装
• CSS 导入和主题设置
• 基本组件初始化
• 设置宽度、高度和初始渲染

打开和保存图像

📄 阅读： references/opening-saving-images.md

• 从文件路径、URL、base64 字符串和 blob 打开
• 从文件上传器、文件管理器和树视图打开
• 保存/导出为 PNG、JPEG、SVG、WEBP
• 图像尺寸和宽高比控制
• 文件打开、保存和生命周期事件

选择和裁剪

📄 阅读： references/selection-cropping.md

• 插入自定义、正方形和圆形选区
• 按宽高比裁剪（2:3、3:2、3:4、4:3、4:5、5:4、5:7、7:5、9:16、16:9）
• 裁剪方法和选区事件
• 裁剪时保持原始图像尺寸
• 调整大小时锁定选区

变换：旋转、翻转和拉直

📄 阅读： references/transform-rotate-flip.md

• 按角度顺时针/逆时针旋转
• 水平和垂直翻转
• 以精细角度调整拉直图像（-45° 至 +45°）
• 与图像一同变换注释
• 旋转和翻转事件

缩放和平移操作

📄 阅读： references/zooming-panning.md

• 使用可配置的最小/最大倍数放大或缩小
• 缩放后或裁剪期间平移
• 缩放触发方式（工具栏、捏合、鼠标滚轮、键盘）
• 缩放和平移事件
• 缩放点计算

文本注释

📄 阅读： references/text-annotations.md

• 添加文本并设置位置、内容和字体
• 文本样式（粗体、斜体、下划线、删除线）
• 字体系列、大小和颜色
• 使用换行符输入多行文本
• 删除文本注释
• 通过 shapeChanging 事件自定义字体颜色

手绘

📄 阅读： references/freehand-drawing.md

• 启用/禁用手绘模式
• 自定义笔画宽度和颜色
• 删除手绘注释
• 通过 shapeChanging 事件在绘制期间调整笔画

形状标注

📄 阅读： references/shape-annotations.md

• 绘制矩形、椭圆、直线、箭头和路径
• 使用描边颜色、描边宽度和填充颜色自定义形状
• 使用角度参数旋转形状
• 删除形状标注
• 自定义默认描边颜色
• 形状更改和自定义事件

图像标注

📄 阅读： references/image-annotations.md

• 添加图像或图标作为标注
• 控制位置、大小、旋转角度和不透明度
• 保持宽高比
• 水印和装饰元素

滤镜

📄 阅读： references/filters.md

• 应用预设滤镜（Chrome、Cold、Warm、Grayscale、Sepia、Invert）
• 图像滤镜事件
• 将滤镜重置为原始状态

微调

📄 阅读： references/finetune.md

• 调整亮度、对比度和饱和度
• 控制色调、曝光度、模糊度和不透明度
• 微调值更改事件
• 使用滑块实时调整

撤销和重做

📄 阅读： references/undo-redo.md

• 使用 16 步历史记录撤销和重做操作
• 键盘快捷键（Ctrl+Z、Ctrl+Y）
• 历史记录管理和限制

工具栏自定义

📄 阅读： references/toolbar-customization.md

• 内置工具栏项（20 多种默认工具）
• 添加、移除、启用和禁用工具栏项
• 带事件处理程序的自定义工具栏项
• 用于标注的上下文工具栏
• 用于全面自定义的工具栏模板
• 工具栏创建和项点击事件

快速访问工具栏

📄 阅读： references/quick-access-toolbar.md

• 用于标注的快速访问工具栏
• 显示/隐藏快速访问工具栏
• 向快速访问工具栏添加自定义项
• 快速访问工具栏打开事件

调整图像大小

📄 阅读： references/resize-image.md

• 调整大小时保持或不保持宽高比
• 宽度和高度参数
• 包含调整前后尺寸的调整大小事件

边框装饰

📄 阅读： references/frame-decoration.md

• 应用边框（Mat、Bevel、Line、Inset、Hook）
• 自定义边框颜色、大小和线条样式
• 边框更改事件

Z 顺序分层

📄 阅读： references/z-order-layering.md

• 将标注前移/后移
• 将标注置于顶层/底层
• 管理标注图层顺序

涂抹敏感信息

📄 阅读： references/redact-sensitive-info.md

• 模糊敏感区域
• 将敏感信息像素化
• 涂抹操作（选择、更新、删除、获取）
• 隐私与合规

无障碍访问和本地化

📄 阅读： references/accessibility-localization.md

• 符合 WCAG 2.2、Section 508 标准
• 支持屏幕阅读器
• 键盘快捷键（Ctrl+Z、Ctrl+S、Ctrl+O、Delete、Enter、Escape）
• 支持 RTL 语言
• 使用 120 多个区域设置键进行本地化

图像限制和验证

📄 阅读： references/image-restrictions-validation.md

• 允许的文件扩展名（.jpg、.png、.svg、.webp、.bmp）
• 最小和最大文件大小限制
• 文件验证和错误提醒

清除图像

📄 阅读： references/clear-image.md

• 清除编辑器状态
• 对话框复用模式
• 移除先前加载的图像

适应宽度和高度

📄 阅读： references/fit-width-height.md

• 让图像适应编辑器容器宽度
• 让图像适应编辑器容器高度
• 实现完美适应的缩放计算

在对话框中渲染

📄 阅读： references/render-in-dialog.md

• 在 Dialog 组件中渲染图像编辑器
• 集成内容模板
• 对话框显示/隐藏模式

重置图像

📄 阅读： references/reset-image.md

• 将所有修改重置为原始状态
• 恢复未修改的版本
• 清除批注和效果

快速入门示例

import { ImageEditorComponent } from '@syncfusion/ej2-react-image-editor';
import React from 'react';

function App() {
  let imgObj: ImageEditorComponent;

  function imageEditorCreated(): void {
    imgObj.open('https://ej2.syncfusion.com/react/documentation/image-editor/images/bridge.jpeg');
  }

  return (
    <div>
      <ImageEditorComponent
        ref={(img) => { imgObj = img }}
        width="550px"
        height="350px"
        created={imageEditorCreated}
      />
    </div>
  );
}

export default App;

常见模式

模式 1：打开 + 编辑 + 保存工作流

1. 通过 open() 方法打开图像
2. 应用变换、批注或效果
3. 使用 export() 将图像保存为 PNG/JPEG/SVG/WEBP
4. 可选：转换为 base64 或 blob，以便存储在后端

模式 2：自适应工具栏

1. 在 toolbar 属性中定义自定义工具栏项
2. 通过 toolbarItemClicked 事件处理点击操作
3. 根据点击的工具栏项执行 rotate()、zoom()、drawText() 等方法
4. 通过 toolbarUpdating 事件更新上下文工具栏

模式 3：批注工作流

1. 启用批注模式（徒手绘制、文本、形状）
2. 通过 shapeChanging 事件自定义颜色、描边和字体
3. 使用形状 ID，通过 deleteShape() 删除形状
4. 通过 z-order 方法管理图层

模式 4：对话框集成

1. 在 Dialog 的 content 模板中渲染 Image Editor
2. 在对话框打开时，通过 fileOpened 事件加载图像
3. 在关闭对话框前调用 clearImage()
4. 通过 export() 或 getImageData() 获取编辑后的图像数据

模式 5：滤镜 + 微调流程

1. 通过 applyImageFilter() 应用滤镜
2. 通过 finetuneImage() 微调亮度、对比度等
3. 监听 imageFiltering 和 finetuneValueChanging 事件
4. 组合效果以获得专业效果

关键属性

属性	类型	用途
width	string	编辑器画布宽度（例如："550px"、"100%"）
height	string	编辑器画布高度（例如："350px"、"100%"）
toolbar	array	自定义工具栏项及其可见性
fontFamily	object	添加自定义字体系列
uploadSettings	object	配置文件限制（扩展名、大小）
zoomSettings	object	设置最小/最大缩放系数
showQuickAccessToolbar	boolean	显示/隐藏快速访问工具栏
locale	string	设置本地化选项（例如：'de-DE'）

关键事件

事件	触发条件	使用场景
created	组件已初始化	在启动时加载图像
fileOpened	图像已加载	添加水印、应用默认设置
beforeSave	导出前	验证并添加元数据
cropping	裁剪期间	防止缩放、锁定尺寸
zooming	缩放期间	验证缩放级别
rotating	旋转期间	跟踪旋转角度
shapeChanging	批注已修改	自定义描边和字体
toolbarUpdating	工具栏已渲染	添加/移除上下文工具栏项

支持的文件格式

打开： PNG、JPEG、JPG、SVG、WEBP、BMP（本地、URL、base64、blob）
保存/导出： PNG、JPEG、SVG、WEBP

后续步骤

• 从 getting-started.md 开始设置
• 探索 opening-saving-images.md，了解数据流
• 在对应的参考文件中查看具体功能
• 使用 accessibility-localization.md 支持多语言