syncfusion-javascript-image-editor

实现 Syncfusion TypeScript 图像编辑器

一份全面的指南，介绍如何在 TypeScript 应用程序中实现 Syncfusion 图像编辑器控件。本指南涵盖初始化、图像加载与保存、标注工具、图像操作（缩放、裁剪、旋转、变换）、滤镜、微调、无障碍功能和自定义模式。

概览

Syncfusion 图像编辑器是一个功能强大的组件，适用于 Web 应用程序中的专业图像编辑。主要功能包括：

• 图像操作 - 打开、保存并导出为 JPEG、PNG、SVG、WebP、BMP 格式
• 缩放与平移 - 多种缩放方式（工具栏、鼠标滚轮、双指捏合、键盘）
• 变换 - 裁剪、旋转、翻转、拉直、调整大小并预览
• 标注 - 文本、手绘、形状（矩形、圆形、箭头、直线）、涂黑、边框
• 滤镜与效果 - 20 多种滤镜效果以及微调控件
• 图层管理 - Z 顺序操作、多个标注
• 历史记录 - 完整的撤消/重做支持及操作跟踪
• 无障碍功能 - 符合 WCAG 2.2 标准，支持键盘导航和屏幕阅读器
• 自定义 - 工具栏、主题、事件处理程序、快捷访问
• TypeScript 支持 - 完整的类型定义和 webpack 配置

文档与导航指南

快速入门

📄 阅读： references/getting-started.md

• 使用 webpack 设置 TypeScript 项目
• 安装 NPM 包（@syncfusion/ej2-image-editor）
• 依赖管理
• CSS 主题导入与配置
• 基本组件初始化
• HTML 标记设置

核心操作

📄 阅读： references/core-operations.md

• 以编程方式打开和加载图像
• 支持的文件格式（JPEG、PNG、SVG、WebP、BMP）
• 保存和导出图像
• 文件输入验证和限制
• 文件类型限制和大小上限
• 下载与保存操作

图像操作

📄 阅读： references/image-manipulation.md

• 缩放方式（工具栏、鼠标滚轮、双指捏合、键盘、适应宽度／高度）
• 平移和图像移动
• 图像调整大小和缩放操作
• 图像旋转和翻转操作
• 使用滑块拉直
• 查询图像尺寸
• 画布和视口管理

标注工具

📄 阅读： references/annotation-tools.md

• 文本标注及字体自定义（字体系列、大小、样式、颜色）
• 手绘工具和画笔设置
• 形状标注（矩形、椭圆、箭头、直线、路径）
• 涂黑功能和遮罩
• 插入和设置边框样式
• 标注样式（填充颜色、描边颜色、描边宽度）
• 标注定位和变换

选择与裁剪

📄 阅读： references/selection-cropping.md

• 选择类型（自定义、圆形、正方形、按比例）
• 裁剪工作流和执行
• 宽高比限制和自定义比例
• 调整和重新定位选区
• 完成裁剪并预览
• 区域管理

滤镜与效果

📄 阅读： references/filters-effects.md

• 以编程方式应用滤镜效果
• 微调选项（20 多种效果类型）
• 亮度、对比度、饱和度控件
• 模糊、锐化、色相和饱和度效果
• 图像处理功能
• 效果预览与应用

撤消与重做

📄 阅读： references/undo-redo.md

• 撤消／重做键盘快捷键（Ctrl+Z、Ctrl+Y）
• 调用撤消／重做方法
• 操作历史跟踪
• 历史状态管理
• 撤销操作模式

图层管理

📄 阅读： references/layer-management.md

• Z 顺序操作和图层堆叠
• 将图层前移／后移
• 图层排列和管理
• 使用多个标注
• 重叠管理

无障碍功能

📄 阅读： references/accessibility.md

• 完整的键盘快捷键参考（Ctrl+Z、Ctrl+Y、Ctrl+S、Delete、Escape 等）
• 符合 WCAG 2.2、Section 508、ADA 标准
• 屏幕阅读器支持和 ARIA 属性
• 从右到左（RTL）支持
• 键盘导航模式
• 色彩对比度和无障碍最佳实践
• 移动设备支持

自定义

📄 阅读： references/customization.md

• 工具栏配置和自定义
• 快捷访问工具栏设置
• 主题样式和 CSS 自定义
• Theme Studio 集成
• CSS 变量和自定义主题
• 事件绑定和回调
• 配置选项参考

本地化

📄 阅读： references/localization.md

• 多语言支持设置
• 特定语言的配置
• 区域设置和资源字符串
• RTL（从右到左）支持配置
• 特定区域的自定义

操作指南

📄 阅读： references/how-to-guide.md

• 在对话框/模态窗口中渲染图像编辑器
• 重新打开对话框前清除图像
• 将图像重置为原始状态
• 使图像适应编辑器宽度或高度
• 对话框状态管理
• 常见集成模式

高级模式

📄 阅读： references/advanced-patterns.md

• 事件处理模式和事件系统
• 自定义工作流示例
• 复杂集成场景
• 性能优化技巧
• TypeScript 类型定义和接口
• 内存管理

API 参考

📄 阅读： references/api.md

• 所有公共属性的完整列表，包含类型和默认值
• 完整的方法签名，包含参数说明和返回类型
• 所有事件及其事件参数接口
• 关键模型接口（ZoomSettingsModel、FinetuneSettingsModel、SelectionSettingsModel、UploadSettingsModel）
• 关键事件参数接口（ShapeSettings、RedactSettings、ShapeChangeEventArgs、EditCompleteEventArgs 等）
• 初始化、裁剪、drawText、finetuneImage 的快速用法示例

快速入门

安装

npm install @syncfusion/ej2-image-editor

安全： 安装后，请运行 npm audit，或通过 Socket.dev 验证软件包，以确认 @syncfusion/ej2-image-editor 的供应链完整性，再部署到生产环境。

基本初始化

import { ImageEditor } from '@syncfusion/ej2-image-editor';

// Create a new instance
const imageEditor = new ImageEditor({
    width: '550px',
    height: '330px',
    toolbar: ['Open', 'Save', 'ZoomIn', 'ZoomOut', 'Crop', 'Rotate', 'Flip']
});

// Append to a container
imageEditor.appendTo('#imageeditor');

// Open an image — replace with a validated, trusted URL; never use URLs from third-party responses directly
imageEditor.open('url');

HTML 设置

<div id="imageeditor"></div>

CSS 主题

@import "@syncfusion/ej2-image-editor/styles/material.css";

常见模式

模式 1：带完整工具栏的基本图像编辑器

import { ImageEditor } from '@syncfusion/ej2-image-editor';

const imageEditor = new ImageEditor({
    width: '600px',
    height: '400px',
    toolbar: ['Open', 'Save', 'ZoomIn', 'ZoomOut', 'Crop', 
              'Rotate', 'Flip', 'Undo', 'Redo', 'Reset'],
    created: () => {
        // Replace 'url' with a validated, trusted image URL or local asset path
        imageEditor.open('url');
    }
});

imageEditor.appendTo('#imageeditor');

模式 2：添加文本注释

const dimension = imageEditor.getImageDimension();
imageEditor.drawText(
    dimension.x + 50, 
    dimension.y + 50, 
    'Annotation Text',
    'Arial',      // font family
    30,           // font size
    false,        // bold
    false,        // italic
    'blue',       // text color
    false,        // selected
    null,         // rotation
    '#FFFFCC',    // fill color
    'black'       // stroke color
);

模式 3：应用滤镜

import { ImageEditor, ImageFilterOption } from '@syncfusion/ej2-image-editor';

// Apply brightness adjustment
imageEditor.finetuneImage('brightness', 30);

// Apply blur filter
imageEditor.applyImageFilter(ImageFilterOption.Blur);

// Apply multiple fine-tune effects
imageEditor.finetuneImage('contrast', 20);
imageEditor.finetuneImage('saturation', 15);

模式 4：裁剪图像

const dimension = imageEditor.getImageDimension();

// Step 1: Programmatically select a crop region
imageEditor.select('Custom', dimension.x, dimension.y, 500, 300);

// Step 2: Apply the crop
imageEditor.crop();

模式 5：对话框集成

import { Dialog } from '@syncfusion/ej2-popups';

const dialog = new Dialog({
    width: '600px',
    height: '450px',
    isModal: true,
    visible: false
});
dialog.appendTo('#dialog');

const imageEditor = new ImageEditor({
    width: '100%',
    height: '100%'
});
imageEditor.appendTo('#imageeditor');

document.getElementById('openBtn').onclick = () => {
    dialog.show();
    // Replace 'url' with a validated, trusted image URL
    imageEditor.open('url');
};

关键 API

核心方法

方法	用途
open(fileOrUrl)	从 URL、File 或 ImageData 加载图像 — 在生产环境中，始终根据可信允许列表验证或清理 URL 输入；切勿传入源自第三方内容的 URL，以防止 SSRF 和间接注入
export(type?, fileName?, imageQuality?)	以指定格式导出/下载图像
crop()	根据当前选区执行裁剪
select(type, startX?, startY?, width?, height?)	设置裁剪选区
rotate(degree)	旋转图像（正值 = 顺时针，负值 = 逆时针）
flip(direction)	水平或垂直翻转图像
zoom(zoomFactor, zoomPoint?)	缩放到指定比例和可选位置
pan(value, x?, y?)	启用/禁用平移，或平移到 x/y 坐标
resize(width, height, isAspectRatio?)	调整图像尺寸
straightenImage(degree)	以较小旋转角度拉直图像
drawText(x?, y?, text?, ...)	添加文本注释
drawRectangle(x?, y?, width?, height?, ...)	绘制矩形注释
drawEllipse(x?, y?, radiusX?, radiusY?, ...)	绘制椭圆注释
drawArrow(startX?, startY?, endX?, endY?, ...)	绘制箭头注释
drawLine(startX?, startY?, endX?, endY?, ...)	绘制线条注释
drawPath(pointColl, ...)	绘制路径/手绘注释
drawImage(data, x?, y?, width?, height?, ...)	绘制图像注释
drawFrame(frameType, ...)	在图像周围绘制装饰边框
drawRedact(type?, x?, y?, width?, height?, value?)	绘制模糊/像素化遮盖
freehandDraw(value)	启用/禁用手绘模式
applyImageFilter(filterOption)	应用预设图像滤镜
finetuneImage(finetuneOption, value)	应用微调效果
getShapeSettings()	获取所有已绘制形状
getShapeSetting(id)	根据 id 获取单个形状
selectShape(id)	根据 id 选中形状
updateShape(setting, isSelected?)	更新现有形状
deleteShape(id)	根据 id 删除形状
cloneShape(shapeId)	根据 id 复制形状
bringToFront(shapeId)	将形状移至最前面
sendToBack(shapeId)	将形状移至最后面
bringForward(shapeId)	将形状向前移动一层
sendBackward(shapeId)	将形状向后移动一层
getRedacts()	获取所有遮盖形状
selectRedact(id)	根据 id 选中遮盖
updateRedact(setting, isSelected?)	更新遮盖
deleteRedact(id)	根据 id 删除遮盖
undo()	撤销上一步操作
redo()	重做上一步撤销的操作
canUndo()	如果可以撤销，则返回 true
canRedo()	如果可以重做，则返回 true
reset()	将图像重置为原始状态
clearImage()	清除已加载的图像
clearSelection(resetCrop?)	清除当前选区
getImageDimension()	获取当前图像的 x、y、宽度和高度
getImageData()	获取作为 ImageData 的画布图像
apply()	应用待处理的注释绘制
discard()	丢弃尚未应用的注释更改
enableShapeDrawing(shapeType, isEnabled?)	启用/禁用形状绘制
enableTextEditing()	进入文本注释编辑模式

关键属性

属性	类型	默认值	用途
width	string	'100%'	编辑器容器宽度
height	string	'100%'	编辑器容器高度
toolbar	(string | ItemModel)[]	null	工具栏项目；null = 默认工具栏，[] = 无工具栏
toolbarTemplate	string | Function	null	完全自定义的工具栏模板（覆盖 toolbar）
quickAccessToolbarTemplate	string | Function	null	快速访问工具栏模板
showQuickAccessToolbar	boolean	true	显示/隐藏快速访问工具栏
theme	string | Theme	Theme.Bootstrap5	UI 外观主题
allowUndoRedo	boolean	true	启用撤销/重做操作
disabled	boolean	false	禁用组件
cssClass	string	''	用于样式设置的自定义 CSS 类
imageSmoothingEnabled	boolean	false	启用高质量图像平滑
locale	string	''	本地化区域设置覆盖值
zoomSettings	ZoomSettingsModel	null	缩放配置（最小值、最大值、因子、触发方式、点）
finetuneSettings	FinetuneSettingsModel	—	微调控件配置（亮度、对比度等）
selectionSettings	SelectionSettingsModel	null	选区/裁剪外观（填充、描边、showCircle）
uploadSettings	UploadSettingsModel	—	文件上传限制（扩展名、最小/最大大小）
fontFamily	FontFamilyModel[]	—	文本注释下拉列表中的自定义字体系列

事件

事件	参数接口	触发时机
created	Event	组件渲染后
destroyed	Event	组件销毁后
fileOpened	OpenEventArgs	打开图像后
beforeSave	BeforeSaveEventArgs	保存/导出图像前
saved	SaveEventArgs	保存/导出图像后
editComplete	EditCompleteEventArgs	任意编辑操作完成后
cropping	CropEventArgs	裁剪进行期间
rotating	RotateEventArgs	旋转进行期间
flipping	FlipEventArgs	翻转进行期间
resizing	ResizeEventArgs	调整大小进行期间
zooming	ZoomEventArgs	缩放进行期间
panning	PanEventArgs	平移进行期间
selectionChanging	SelectionChangeEventArgs	裁剪选区发生变化期间
shapeChanging	ShapeChangeEventArgs	形状发生变化期间
shapeChange	ShapeChangeEventArgs	形状变化完成后
imageFiltering	ImageFilterEventArgs	应用滤镜时
finetuneValueChanging	FinetuneEventArgs	微调值发生变化期间
frameChange	FrameChangeEventArgs	应用边框期间
toolbarCreated	ToolbarEventArgs	工具栏创建后
toolbarUpdating	ToolbarEventArgs	工具栏刷新期间
toolbarItemClicked	ClickEventArgs	点击工具栏项目时
quickAccessToolbarOpen	QuickAccessToolbarEventArgs	快速访问工具栏打开时
quickAccessToolbarItemClick	ClickEventArgs	点击快速访问工具栏项目时
click	ImageEditorClickEventArgs	点击编辑器画布时

常见用例

专业图像编辑套件 - 配备所有工具的全功能编辑器 注释工作流 - 为文档添加标记和涂黑 快速裁剪工具 - 专注于裁剪的简化界面 社交媒体工具 - 为各平台预设宽高比 屏幕截图标注 - 快速标注屏幕截图 文档处理 - 拉直、裁剪并导出扫描件 对话框集成 - 模态图像编辑工作流

相关技能

• implementing-rich-text-editor - 用于文本编辑
• implementing-buttons - 用于控件自定义
• implementing-dialogs - 用于模态工作流集成