syncfusion-react-image-editor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Image Editor

实现Syncfusion React Image Editor

The Syncfusion React Image Editor is a comprehensive, feature-rich component for editing images directly in your React applications. It provides an intuitive interface with powerful tools for transformations, annotations, effects, and more.

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

Component Overview

组件概述

The Image Editor combines a canvas-based editing environment with a comprehensive toolbar and contextual tools. It supports:

Multiple Input Sources: Files, URLs, base64, blobs, file managers, treeviews
Rich Annotation Support: Text (with styling), shapes, freehand drawings, watermarks
Professional Effects: Filters and fine-tuning controls
Advanced Operations: Z-order management, redaction, frame decoration
Accessibility First: Full keyboard navigation, WCAG compliance, RTL support, 120+ localization keys
Flexible Integration: Standalone or within dialogs, with customizable toolbars

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

多种输入源： 文件、URL、base64、blob、文件管理器、树形视图
丰富的注释支持： 文本（带样式）、形状、手绘、水印
专业特效： 滤镜和精细调整控件
高级操作： Z轴顺序管理、脱敏处理、边框装饰
优先支持无障碍： 完整的键盘导航、WCAG合规、RTL支持、120+本地化语言键
灵活集成： 独立使用或嵌入对话框，支持自定义工具栏

Documentation and Navigation Guide

文档与导航指南

🔹 API Reference

🔹 API参考

📄 Read: references/api.md

Complete API documentation with all properties, methods, and events
Properties overview (core, toolbar, settings)
Methods for image operations, transformations, annotations
Events for lifecycle, interactions, effects, and toolbars
Enums and type definitions (ArrowheadType, FrameType, RedactType, etc.)
Complete working examples with verified method signatures

📄 阅读： references/api.md

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

Getting Started

快速开始

📄 Read: references/getting-started.md

Installation with Vite and create-react-app
CSS imports and theme setup
Basic component initialization
Setting width, height, and initial rendering

📄 阅读： references/getting-started.md

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

Opening and Saving Images

打开与保存图像

📄 Read: references/opening-saving-images.md

Open from file paths, URLs, base64 strings, blobs
Open from file uploader, file manager, and treeview
Save/export as PNG, JPEG, SVG, WEBP
Image dimensions and aspect ratio control
File opened, saving, and lifecycle events

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

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

Selection and Cropping

选择与裁剪

📄 Read: references/selection-cropping.md

Insert custom, square, and circle selections
Crop with aspect ratios (2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 5:7, 7:5, 9:16, 16:9)
Crop method and selection events
Maintain original image size during cropping
Lock selection area during resizing

📄 阅读： references/selection-cropping.md

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

Transform: Rotate, Flip, and Straighten

变换：旋转、翻转与拉直

📄 Read: references/transform-rotate-flip.md

Rotate clockwise/counter-clockwise by degrees
Flip horizontally and vertically
Straighten images with fine degree adjustments (-45° to +45°)
Transform annotations along with image
Rotating and flipping events

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

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

Zoom and Pan Operations

缩放与平移操作

📄 Read: references/zooming-panning.md

Zoom in/out with configurable min/max factors
Pan when zoomed or during cropping
Zoom triggers (toolbar, pinch, mouse wheel, keyboard)
Zooming and panning events
Zoom point calculations

📄 阅读： references/zooming-panning.md

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

Text Annotations

文本注释

📄 Read: references/text-annotations.md

Add text with position, content, and font settings
Text styling (bold, italic, underline, strikethrough)
Font families, sizes, and colors
Multiline text with newline characters
Delete text annotations
Customize font color via shapeChanging event

📄 阅读： references/text-annotations.md

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

Freehand Drawing

手绘

📄 Read: references/freehand-drawing.md

Enable/disable freehand drawing mode
Customize stroke width and color
Delete freehand annotations
Adjust stroke during drawing via shapeChanging event

📄 阅读： references/freehand-drawing.md

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

Shape Annotations

形状注释

📄 Read: references/shape-annotations.md

Draw rectangles, ellipses, lines, arrows, and paths
Customize shapes with stroke color, stroke width, and fill color
Rotate shapes with degree parameter
Delete shape annotations
Customize default stroke colors
Shape changing and customization events

📄 阅读： references/shape-annotations.md

绘制矩形、椭圆、直线、箭头和路径
自定义形状的笔触颜色、笔触宽度和填充颜色
通过角度参数旋转形状
删除形状注释
自定义默认笔触颜色
形状更改和自定义事件

Image Annotations

图像注释

📄 Read: references/image-annotations.md

Add images or icons as annotations
Control position, size, rotation, and opacity
Aspect ratio preservation
Watermarks and decorative elements

📄 阅读： references/image-annotations.md

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

Filters

滤镜

📄 Read: references/filters.md

Apply predefined filters (Chrome, Cold, Warm, Grayscale, Sepia, Invert)
Image filtering event
Reset filter to original

📄 阅读： references/filters.md

应用预设滤镜（Chrome、Cold、Warm、灰度、棕褐色、反色）
图像过滤事件
将滤镜重置为原始状态

Fine-Tuning

精细调整

📄 Read: references/finetune.md

Adjust brightness, contrast, saturation
Control hue, exposure, blur, opacity
Finetune value changing events
Real-time adjustments with sliders

📄 阅读： references/finetune.md

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

Undo and Redo

撤销与重做

📄 Read: references/undo-redo.md

Undo/redo operations with 16-step history
Keyboard shortcuts (Ctrl+Z, Ctrl+Y)
History management and limits

📄 阅读： references/undo-redo.md

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

Toolbar Customization

工具栏自定义

📄 Read: references/toolbar-customization.md

Built-in toolbar items (20+ default tools)
Add, remove, enable, disable toolbar items
Custom toolbar items with event handlers
Contextual toolbar for annotations
Toolbar templates for complete customization
Toolbar created and item clicked events

📄 阅读： references/toolbar-customization.md

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

Quick Access Toolbar

快速访问工具栏

📄 Read: references/quick-access-toolbar.md

Quick access toolbar for annotations
Show/hide quick access toolbar
Add custom items to quick access toolbar
Quick access toolbar open event

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

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

Resize Image

调整图像大小

📄 Read: references/resize-image.md

Resize with or without aspect ratio
Width and height parameters
Resizing event with before/after dimensions

📄 阅读： references/resize-image.md

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

Frame Decoration

边框装饰

📄 Read: references/frame-decoration.md

Apply frames (Mat, Bevel, Line, Inset, Hook)
Customize frame color, size, and line style
Frame changing event

📄 阅读： references/frame-decoration.md

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

Z-Order Layering

Z轴顺序图层

📄 Read: references/z-order-layering.md

Bring forward/send backward annotations
Bring to front/send to back
Manage annotation layer order

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

将注释上移一层/下移一层
移至顶层/移至底层
管理注释图层顺序

Redact Sensitive Information

敏感信息脱敏

📄 Read: references/redact-sensitive-info.md

Blur sensitive areas
Pixelate sensitive information
Redact CRUD operations (select, update, delete, get)
Privacy and compliance

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

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

Accessibility and Localization

无障碍与本地化

📄 Read: references/accessibility-localization.md

WCAG 2.2, Section 508 compliance
Screen reader support
Keyboard shortcuts (Ctrl+Z, Ctrl+S, Ctrl+O, Delete, Enter, Escape)
RTL language support
Localization with 120+ locale keys

📄 阅读： references/accessibility-localization.md

符合WCAG 2.2、Section 508标准
屏幕阅读器支持
键盘快捷键（Ctrl+Z、Ctrl+S、Ctrl+O、Delete、Enter、Escape）
RTL语言支持
120+语言键的本地化

Image Restrictions and Validation

图像限制与验证

📄 Read: references/image-restrictions-validation.md

Allowed file extensions (.jpg, .png, .svg, .webp, .bmp)
Min and max file size restrictions
File validation and error alerts

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

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

Clear Image

清除图像

📄 Read: references/clear-image.md

Clear editor state
Dialog reuse patterns
Remove previously loaded images

📄 阅读： references/clear-image.md

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

Fit to Width and Height

适配宽度和高度

📄 Read: references/fit-width-height.md

Fit image to editor container width
Fit image to editor container height
Zoom calculations for perfect fit

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

将图像适配编辑器容器宽度
将图像适配编辑器容器高度
完美适配的缩放计算

Render in Dialog

在对话框中渲染

📄 Read: references/render-in-dialog.md

Render Image Editor within Dialog component
Content template integration
Dialog show/hide patterns

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

在Dialog组件中渲染Image Editor
内容模板集成
对话框显示/隐藏模式

Reset Image

重置图像

📄 Read: references/reset-image.md

Reset all modifications to original state
Restore unmodified version
Clear annotations and effects

📄 阅读： references/reset-image.md

将所有修改重置为原始状态
恢复未修改版本
清除注释和特效

Quick Start Example

快速开始示例

tsx

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;

tsx

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;

Common Patterns

常见模式

Pattern 1: Open + Edit + Save Workflow

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

Open image via
```
open()
```
method
Apply transformations, annotations, or effects
Use
```
export()
```
to save as PNG/JPEG/SVG/WEBP
Optionally convert to base64 or blob for backend storage

通过
```
open()
```
方法打开图像
应用变换、注释或特效
使用
```
export()
```
保存为PNG/JPEG/SVG/WEBP格式
可选转换为base64或blob用于后端存储

Pattern 2: Responsive Toolbar

模式2：响应式工具栏

Define custom toolbar items in
```
toolbar
```
property
Handle clicks via
```
toolbarItemClicked
```
event
Execute methods like
```
rotate()
```
,
```
zoom()
```
,
```
drawText()
```
based on clicked item
Update contextual toolbar via
```
toolbarUpdating
```
event

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

Pattern 3: Annotation Workflow

模式3：注释工作流

Enable annotation mode (freehand, text, shape)
Customize via
```
shapeChanging
```
event (color, stroke, font)
Delete via
```
deleteShape()
```
with shape ID
Manage layers via z-order methods

启用注释模式（手绘、文本、形状）
通过
```
shapeChanging
```
事件自定义（颜色、笔触、字体）
使用
```
deleteShape()
```
和形状ID删除注释
通过Z轴顺序方法管理图层

Pattern 4: Dialog Integration

模式4：对话框集成

Render Image Editor in Dialog's
```
content
```
template
Load image when dialog opens via
```
fileOpened
```
event
Call
```
clearImage()
```
before closing dialog
Retrieve edited image data via
```
export()
```
or
```
getImageData()
```

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

Pattern 5: Filter + Finetune Pipeline

模式5：滤镜 + 精细调整流程

Apply filter via
```
applyImageFilter()
```
Fine-tune via
```
finetuneImage()
```
(brightness, contrast, etc.)
Listen to
```
imageFiltering
```
and
```
finetuneValueChanging
```
events
Combine effects for professional results

通过
```
applyImageFilter()
```
应用滤镜
通过
```
finetuneImage()
```
进行精细调整（亮度、对比度等）
监听
```
imageFiltering
```
和
```
finetuneValueChanging
```
事件
组合特效以获得专业效果

Key Properties

关键属性

Property	Type	Purpose
`width`	string	Editor canvas width (e.g., "550px", "100%")
`height`	string	Editor canvas height (e.g., "350px", "100%")
`toolbar`	array	Customize toolbar items and visibility
`fontFamily`	object	Add custom font families
`uploadSettings`	object	Configure file restrictions (extensions, size)
`zoomSettings`	object	Set min/max zoom factors
`showQuickAccessToolbar`	boolean	Show/hide quick access toolbar
`locale`	string	Set localization (e.g., 'de-DE')

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

Key Events

关键事件

Event	Trigger	Use Case
`created`	Component initialized	Load image on startup
`fileOpened`	Image loaded	Add watermarks, apply defaults
`beforeSave`	Before export	Validate, add metadata
`cropping`	During crop	Prevent scaling, lock dimensions
`zooming`	During zoom	Validate zoom level
`rotating`	During rotate	Track rotation angle
`shapeChanging`	Annotation modified	Customize stroke, font
`toolbarUpdating`	Toolbar rendered	Add/remove contextual items

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

Supported File Formats

支持的文件格式

Open: PNG, JPEG, JPG, SVG, WEBP, BMP (local, URL, base64, blob) Save/Export: PNG, JPEG, SVG, WEBP

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

Next Steps

后续步骤

Start with getting-started.md for setup
Explore opening-saving-images.md to understand data flow
Check specific features in their dedicated reference files
Use accessibility-localization.md for multi-language support

从getting-started.md开始设置
探索opening-saving-images.md以了解数据流
在各自的参考文件中查看特定功能
使用accessibility-localization.md获取多语言支持