syncfusion-wpf-image-editor

在 WPF 中实现图像编辑器

Syncfusion WPF ImageEditor 控件是一款非常实用的工具，可通过添加文本、画笔和内置形状来编辑图像。它支持裁剪、旋转和翻转图像。图像编辑器控件内置工具栏，可帮助执行编辑操作。

何时使用此技能

在构建需要以下功能的 WPF 应用程序时使用此技能：

• 图像编辑功能：加载、编辑和保存图像，并进行变换和添加注释
• 照片处理：在桌面应用程序中裁剪、翻转和旋转图像
• 视觉注释：向图像添加形状（矩形、圆形、箭头）、文本或徒手绘图
• 图像标记工具：创建用于图像审查、注释或文档记录的应用程序
• 文档图像处理：构建带有图像编辑功能的文档处理应用程序
• 设计工具：在设计或创意应用程序中实现基本图像编辑
• 照片管理：为照片图库或管理应用程序添加编辑功能
• 质量控制：支持在检查或审批工作流中添加图像注释

组件概述

SfImageEditor 是一款功能全面的 WPF 控件，用于图像编辑和注释。它提供：

• 图像输入/输出：从 ImageSource 或 Stream 加载，并控制格式和大小进行保存
• 变换：裁剪（矩形/圆形，并支持比例）、翻转（水平/垂直）、旋转（以 90° 为增量）
• 注释：添加形状（矩形、圆形、箭头）、富文本和徒手画笔绘图
• 自定义：全面控制画笔设置、文本格式和视觉样式
• 图层管理：Z 顺序控制、撤销/重做、序列化/反序列化
• 导航：缩放（50-400%）、平移大型图像
• UI 灵活性：可自定义的内置工具栏、自定义视图（水印、徽标）
• 本地化：全面支持国际化

文档和导航指南

设置和基本操作

📄 阅读： references/setup-and-basic-operations.md

当用户需要：

• 安装和配置 SfImageEditor
• 在 XAML 或代码中初始化控件
• 从文件路径或流加载图像
• 以特定格式（PNG、JPG、BMP）保存编辑后的图像
• 控制图像的保存位置和大小
• 将图像重置为原始状态
• 处理保存事件
• 为编辑器应用主题

图像变换

📄 阅读： references/image-transformations.md

当用户需要：

• 裁剪图像（矩形或圆形裁剪）
• 在裁剪时应用纵横比限制
• 水平或垂直翻转图像
• 以 90 度为增量旋转图像
• 启用缩放功能（50-400% 范围）
• 使用工具栏滑块或鼠标滚轮控制缩放
• 启用平移，以浏览已缩放的图像
• 在平移模式和选择模式之间切换

注释 - 形状和文本

📄 阅读： references/annotations-shapes-and-text.md

当用户需要：

• 向图像添加形状（矩形、圆形、箭头）
• 使用画笔工具徒手绘制
• 自定义形状外观（填充、描边、不透明度）
• 添加带有丰富格式的文本注释
• 控制文本属性（字体、颜色、对齐方式、效果）
• 使形状和文本可调整大小
• 处理形状/文本选择事件
• 以编程方式删除注释

注释管理

📄 阅读： references/annotation-management.md

当用户需要：

• 为注释实现撤销/重做
• 控制注释图层顺序（置于顶层、置于底层）
• 将注释序列化为 XML 以便持久化
• 反序列化已保存的注释状态
• 访问和筛选注释集合
• 了解撤销/重做的限制

UI 自定义和扩展

📄 阅读： references/ui-customization-and-extensions.md

当用户需要：

• 显示或隐藏内置工具栏
• 添加带图标的自定义工具栏项
• 自定义工具栏外观（颜色、尺寸）
• 创建完全自定义的工具栏
• 添加自定义视图（水印、徽标、叠加层）
• 控制自定义视图属性（可调整大小、可旋转）
• 绑定到可用命令（保存、撤消、重做、缩放等）

本地化

📄 阅读： references/localization.md

当用户需要：

• 针对不同文化本地化 UI 字符串
• 创建本地化资源文件
• 配置区域性设置
• 在图像编辑器中支持多种语言

快速入门示例

基本图像编辑器设置

\\xaml <editor:SfImageEditor x:Name="imageEditor" ImageSource="Assets/photo.jpg"/> \\

从流加载图像

\\csharp using Syncfusion.UI.Xaml.ImageEditor; using System.Windows; using Microsoft.Win32;

public partial class MainWindow : Window { public MainWindow() { InitializeComponent(); LoadImageFromFile(); }

private void LoadImageFromFile()
{
    OpenFileDialog openFileDialog = new OpenFileDialog();
    openFileDialog.Filter = "Image Files(*.BMP;*.JPG;*.PNG)|*.BMP;*.JPG;*.PNG|All files (*.*)|*.*";
    
    if (openFileDialog.ShowDialog() == true)
    {
        var stream = openFileDialog.OpenFile();
        imageEditor.Image = stream;
    }
}

} \\

常见模式

模式 1：加载、编辑并保存图像

\\csharp // Load image BitmapImage image = new BitmapImage(); image.BeginInit(); image.UriSource = new Uri(@"Assets/photo.jpg", UriKind.Relative); image.EndInit(); imageEditor.ImageSource = image;

// User performs edits via toolbar or code...

// Save programmatically imageEditor.Save("C:\EditedImages\result.png"); \\

模式 2：以编程方式添加文本注释

\\csharp using Syncfusion.UI.Xaml.ImageEditor;

// Configure text settings TextSettings textSettings = new TextSettings() { FontFamily = new FontFamily("Arial"), FontSize = 24, Color = new SolidColorBrush(Colors.Red), TextAlignment = TextAlignment.Center };

// Add text at specific position imageEditor.AddText("Copyright 2026", textSettings); \\

模式 3：添加自定义样式的形状

\\csharp // Configure pen settings for shapes PenSettings penSettings = new PenSettings() { Fill = new SolidColorBrush(Colors.Yellow), Stroke = new SolidColorBrush(Colors.Red), StrokeWidth = 3, Opacity = 0.7f };

// Add rectangle shape imageEditor.AddShape(AnnotationShape.Rectangle, penSettings); \\

模式 4：实现撤消/重做

\\csharp // In toolbar or menu command private void UndoButton_Click(object sender, RoutedEventArgs e) { imageEditor.Undo(); }

private void RedoButton_Click(object sender, RoutedEventArgs e) { imageEditor.Redo(); } \\

模式 5：序列化和反序列化注释

\\csharp using System.IO;

// Serialize annotations to file private void SaveAnnotations() { using (FileStream stream = new FileStream("annotations.xml", FileMode.Create)) { imageEditor.Serialize(stream); } }

// Deserialize annotations from file private void LoadAnnotations() { using (FileStream stream = new FileStream("annotations.xml", FileMode.Open)) { imageEditor.Deserialize(stream); } } \\

模式 6：启用缩放和平移

\\csharp // 使用鼠标滚轮启用缩放 imageEditor.EnableZooming = true;

// 为缩放后的图像启用平移 imageEditor.EnablePanning = true;

\\

关键属性和方法

基本属性

属性	类型	描述
ImageSource	ImageSource	获取或设置要在编辑器中加载的图像
Image	Stream	从流源加载图像
EnableZooming	bool	启用或禁用缩放功能
EnablePanning	bool	启用或禁用用于导航的平移模式
IsToolbarVisiblity	bool	显示或隐藏内置工具栏
Annotations	ReadOnlyCollection	编辑器中所有批注的集合

基本方法

方法	参数	描述
Save()	string format = null, Size size = new Size(), string filePath = null	将编辑后的图像保存到指定路径
Reset()	-	将图像重置为原始状态
Undo()	-	撤销上一次批注操作
Redo()	-	重做之前撤销的操作
AddShape()	ShapeType shapeType, PenSettings penSettings	在指定边界处添加形状
AddText()	string text, TextSettings textSettings	在指定位置添加文本
ToggleCropping()	-	开启或关闭裁剪模式
ToggleCropping()	float xRatio, float yRatio, bool isEllipse = false	按指定的高宽比预览裁剪效果。
ToggleCropping()	Rect rect	预览裁剪指定边界。
ToggleCropping()	Rect rect, bool isEllipse	根据指定矩形边界启用图像裁剪预览。
Crop()	Rect rect = null, bool isEllipse = false	将图像裁剪为指定矩形
AddCustomView()	FrameworkElement element, CustomViewSettings customViewSettings	添加自定义叠加视图
Serialize()	Stream stream	将批注保存到 XML 流
Deserialize()	Stream stream	从 XML 流加载批注

关键事件

事件	描述
ImageSaving	在保存图像前触发，可取消保存
ImageSaved	图像成功保存后触发
BeginReset	重置操作开始前触发
EndReset	重置操作完成后触发
ItemSelected	选中批注时触发
ItemUnselected	取消选中批注时触发
ImageEdited	每当图像被编辑时触发
ImageLoaded	图像加载时触发

常见用例

1. 照片编辑应用：构建具有裁剪、旋转和滤镜功能的桌面照片编辑器
2. 文档批注：标记屏幕截图、图表或扫描文档
3. 质量控制：在产品图像上添加检验标记或备注
4. 设计评审：允许利益相关者在设计稿上添加批注
5. 医学影像：为 X 光片或扫描图像添加批注（需使用适当的图像格式）
6. 房地产：在房产照片上添加备注或高亮标记
7. 在线学习：为教学内容创建带批注的图像
8. 错误报告：允许用户在报告问题时标记屏幕截图

---

后续步骤：

• 如需详细的设置说明，请阅读 setup-and-basic-operations.md
• 如需了解变换功能，请阅读 image-transformations.md
• 如需了解批注功能，请阅读 annotations-shapes-and-text.md