syncfusion-blazor-image-editor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing the Syncfusion Blazor Image Editor Component

实现Syncfusion Blazor Image Editor组件

The Syncfusion Blazor Image Editor is a powerful, feature-rich component for building image editing capabilities into your Blazor applications. It provides a complete toolkit for image manipulation, annotation, transformation, and export with an intuitive UI and extensive API.
Syncfusion Blazor Image Editor是一个功能强大、特性丰富的组件,可用于在你的Blazor应用中构建图片编辑功能。它提供了一套完整的图片处理、注释、变换和导出工具包,拥有直观的UI和丰富的API。

Navigation Guide

导航指南

Getting Started

快速开始

📄 Read: references/getting-started.md
  • Installation of NuGet packages (Syncfusion.Blazor.ImageEditor, Syncfusion.Blazor.Themes)
  • Blazor WebAssembly and Web App setup
  • Import namespaces and register services
  • Add stylesheet and script references
  • Render the basic component
  • NEW: Component properties (AllowUndoRedo, IsReadOnly, Enabled, Theme, CssClass, EnableImageSmoothing)
📄 阅读: references/getting-started.md
  • 安装NuGet包(Syncfusion.Blazor.ImageEditor、Syncfusion.Blazor.Themes)
  • Blazor WebAssembly和Web应用设置
  • 导入命名空间并注册服务
  • 添加样式表和脚本引用
  • 渲染基础组件
  • 新增: 组件属性(AllowUndoRedo、IsReadOnly、Enabled、Theme、CssClass、EnableImageSmoothing)

Core Operations

核心操作

📄 Read: references/core-operations.md
  • Open/load images from file explorer
  • NEW: Complete OpenAsync signature with all 6 parameters (resetChanges, fillColor, width, height, isAspectRatio)
  • Save and export images (PNG, JPEG, SVG, WEBP formats)
  • Image quality settings for JPEG export
  • Undo and redo operations with keyboard shortcuts (CanUndoAsync, CanRedoAsync)
  • Reset image to original state
  • NEW: Apply and Discard changes, Clear image, Get image data methods
📄 阅读: references/core-operations.md
  • 从文件资源管理器打开/加载图片
  • 新增: 包含全部6个参数的完整OpenAsync签名(resetChanges、fillColor、width、height、isAspectRatio)
  • 保存和导出图片(PNG、JPEG、SVG、WEBP格式)
  • JPEG导出的图片质量设置
  • 带键盘快捷键的撤销和重做操作(CanUndoAsync、CanRedoAsync)
  • 将图片重置为原始状态
  • 新增: 应用和丢弃更改、清除图片、获取图片数据的方法

Image Transformations

图片变换

📄 Read: references/image-transformations.md
  • Crop images with custom, circle, square, or ratio selections
  • Rotate left, right, and arbitrary angles
  • Flip horizontally and vertically
  • Straighten images with slider control
  • NEW: StraightenImageAsync method for precise angle adjustment (-45 to +45 degrees)
  • Resize images to specific dimensions
  • Pan images within the canvas
📄 阅读: references/image-transformations.md
  • 使用自定义、圆形、方形或比例选择框裁剪图片
  • 向左、向右旋转以及任意角度旋转
  • 水平和垂直翻转
  • 使用滑块控件校正图片角度
  • 新增: StraightenImageAsync方法用于精确角度调整(-45至+45度)
  • 将图片调整为特定尺寸
  • 在画布内平移图片

Annotations

注释功能

📄 Read: references/annotations.md
  • Add text annotations with customization (font, size, color, bold, italic, underline, strikethrough)
  • NEW: Complete DrawTextAsync with underline and strikethrough parameters
  • Create multiline text annotations
  • Enable freehand drawing with stroke control
  • Draw shapes (rectangles, ellipses, arrows, paths, lines)
  • Insert image annotations (watermarks, logos, decorative elements)
  • NEW: Annotation z-order management (BringToFrontAsync, SendToBackAsync, BringForwardAsync, SendBackwardAsync)
  • NEW: Clone annotations with CloneShapeAsync
  • NEW: Enable/disable annotation modes (EnableActiveAnnotationAsync, DisableActiveAnnotationAsync)
  • NEW: Enable text editing mode
  • Delete and manage annotations using ShapeSettings and IDs
📄 阅读: references/annotations.md
  • 添加可自定义的文本注释(字体、大小、颜色、加粗、斜体、下划线、删除线)
  • 新增: 包含下划线和删除线参数的完整DrawTextAsync方法
  • 创建多行文本注释
  • 启用带笔触控制的手绘功能
  • 绘制形状(矩形、椭圆、箭头、路径、直线)
  • 插入图片注释(水印、Logo、装饰元素)
  • 新增: 注释层级管理(BringToFrontAsync、SendToBackAsync、BringForwardAsync、SendBackwardAsync)
  • 新增: 使用CloneShapeAsync克隆注释
  • 新增: 启用/禁用注释模式(EnableActiveAnnotationAsync、DisableActiveAnnotationAsync)
  • 新增: 启用文本编辑模式
  • 使用ShapeSettings和ID删除及管理注释

Annotation Styling

注释样式定制

📄 Read: references/annotation-styling.md
  • Customize stroke width, color, and fill colors
  • Apply font styling for text annotations
  • Use ShapeChanging event for dynamic customization
  • Configure default stroke colors and styles
  • Work with ShapeSettings properties
📄 阅读: references/annotation-styling.md
  • 自定义笔触宽度、颜色和填充色
  • 为文本注释应用字体样式
  • 使用ShapeChanging事件进行动态定制
  • 配置默认笔触颜色和样式
  • 操作ShapeSettings属性

Adjustments, Filters & Effects

调整、滤镜与效果

📄 Read: references/adjustments-filters-effects.md
  • Apply fine-tuning adjustments (brightness, contrast, saturation, hue, blur, etc.)
  • Use slider controls for adjustment preview
  • Apply filters to images (predefined effects)
  • Add frame effects to images
  • Commit or preview changes before applying
📄 阅读: references/adjustments-filters-effects.md
  • 应用精细调整(亮度、对比度、饱和度、色调、模糊等)
  • 使用滑块控件预览调整效果
  • 为图片应用滤镜(预定义效果)
  • 为图片添加边框效果
  • 应用前提交或预览更改

Redaction

内容打码

📄 Read: references/redaction.md NEW
  • Draw redactions with blur or pixelate effects
  • RedactType enum (Blur, Pixelate)
  • Control blur intensity and pixel size
  • Get, select, update, and delete redactions
  • RedactSettings class properties
  • Privacy protection and GDPR compliance use cases
📄 阅读: references/redaction.md 新增
  • 使用模糊或像素化效果绘制打码区域
  • RedactType枚举(Blur、Pixelate)
  • 控制模糊强度和像素大小
  • 获取、选择、更新和删除打码区域
  • RedactSettings类属性
  • 隐私保护和GDPR合规用例

Frames

边框效果

📄 Read: references/frames.md NEW
  • Apply decorative frames to images
  • FrameType enum (Mat, Bevel, Line, Inset, Hook)
  • Customize frame colors, gradients, sizes
  • FrameLineStyle for Line frames (Solid, Dashed, Dotted)
  • Configure inset, offset, border radius, and line count
  • Professional photo presentation examples
📄 阅读: references/frames.md 新增
  • 为图片应用装饰性边框
  • FrameType枚举(Mat、Bevel、Line、Inset、Hook)
  • 自定义边框颜色、渐变、尺寸
  • Line边框的FrameLineStyle(Solid、Dashed、Dotted)
  • 配置内边距、偏移量、边框半径和线条数量
  • 专业照片展示示例

Events Reference

事件参考

📄 Read: references/events-reference.md NEW
  • Complete ImageEditorEvents documentation
  • Lifecycle events (Created, Destroyed)
  • File operation events (FileOpened, Saving)
  • Transformation events (Cropping/Cropped, Rotating/Rotated, Flipping/Flipped)
  • Shape events (ShapeChanging/ShapeChanged, resize/drag start/end)
  • Adjustment events (ImageFiltering/Filtered, FinetuneValueChanging/Changed, FrameChanging/Changed)
  • User interaction events (Zooming/Zoomed, OnPanStart/End, Clicked)
  • Toolbar events (ToolbarUpdating, ToolbarItemClicked, QuickAccessToolbarOpening)
  • History events (HistoryChanged)
  • Event arguments reference for all events
📄 阅读: references/events-reference.md 新增
  • 完整的ImageEditorEvents文档
  • 生命周期事件(Created、Destroyed)
  • 文件操作事件(FileOpened、Saving)
  • 变换事件(Cropping/Cropped、Rotating/Rotated、Flipping/Flipped)
  • 形状事件(ShapeChanging/ShapeChanged、调整大小/拖动开始/结束)
  • 调整事件(ImageFiltering/Filtered、FinetuneValueChanging/Changed、FrameChanging/Changed)
  • 用户交互事件(Zooming/Zoomed、OnPanStart/End、Clicked)
  • 工具栏事件(ToolbarUpdating、ToolbarItemClicked、QuickAccessToolbarOpening)
  • 历史记录事件(HistoryChanged)
  • 所有事件的事件参数参考

Toolbar Customization

工具栏定制

📄 Read: references/toolbar-customization.md
  • Reference of built-in toolbar items (Open, Crop, Rotate, Annotation, Filters, etc.)
  • Add custom toolbar items and buttons
  • Show/hide entire toolbar or specific items
  • Enable/disable toolbar items conditionally
  • Customize contextual toolbars using ToolbarUpdating event
  • Create custom toolbar templates
📄 阅读: references/toolbar-customization.md
  • 内置工具栏项参考(Open、Crop、Rotate、Annotation、Filters等)
  • 添加自定义工具栏项和按钮
  • 显示/隐藏整个工具栏或特定项
  • 有条件地启用/禁用工具栏项
  • 使用ToolbarUpdating事件定制上下文工具栏
  • 创建自定义工具栏模板

User Interactions

用户交互

📄 Read: references/user-interactions.md
  • Zoom methods (toolbar buttons, pinch gesture, mouse wheel, keyboard shortcuts)
  • Pan/move images across the canvas
  • Selection types for cropping
  • Get image dimensions and coordinates
  • Keyboard shortcuts reference (Ctrl+Z, Ctrl+Y, Ctrl+S, etc.)
📄 阅读: references/user-interactions.md
  • 缩放方法(工具栏按钮、捏合手势、鼠标滚轮、键盘快捷键)
  • 在画布上平移/移动图片
  • 裁剪的选择类型
  • 获取图片尺寸和坐标
  • 键盘快捷键参考(Ctrl+Z、Ctrl+Y、Ctrl+S等)

Accessibility & Localization

无障碍与本地化

📄 Read: references/accessibility-localization.md
  • WCAG compliance and accessibility features
  • Keyboard navigation support
  • Screen reader compatibility
  • ARIA attributes
  • Color contrast standards
  • Localization and RTL support
📄 阅读: references/accessibility-localization.md
  • WCAG合规性和无障碍功能
  • 键盘导航支持
  • 屏幕阅读器兼容性
  • ARIA属性
  • 颜色对比度标准
  • 本地化和RTL支持

Setup Modes & Deployment

设置模式与部署

📄 Read: references/setup-modes.md
  • WebAssembly app setup (Visual Studio, VS Code, .NET CLI)
  • Web App setup with interactive render modes (Auto, WebAssembly, Server)
  • Theme configuration (Bootstrap5, Fluent2, Material3, Tailwind3)
  • Static Web Assets vs CDN references
  • Script references and dependencies
📄 阅读: references/setup-modes.md
  • WebAssembly应用设置(Visual Studio、VS Code、.NET CLI)
  • 带交互式渲染模式的Web应用设置(Auto、WebAssembly、Server)
  • 主题配置(Bootstrap5、Fluent2、Material3、Tailwind3)
  • 静态Web资源与CDN引用对比
  • 脚本引用和依赖项

Quick Start Example

快速开始示例

csharp
@using Syncfusion.Blazor.ImageEditor

<SfImageEditor @ref="ImageEditor" Height="500px" Width="100%">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;

    private async void OnCreated()
    {
        // Load an image when component is ready
        await ImageEditor.OpenAsync("path/to/image.png");
    }
}
Setup steps:
  1. Install NuGet packages:
    Syncfusion.Blazor.ImageEditor
    and
    Syncfusion.Blazor.Themes
  2. Add imports in
    _Imports.razor
    :
    @using Syncfusion.Blazor.ImageEditor
  3. Register service in
    Program.cs
    :
    builder.Services.AddSyncfusionBlazor();
  4. Add theme stylesheet to
    index.html
    or
    App.razor
  5. Add the component and load an image in the
    Created
    event
csharp
@using Syncfusion.Blazor.ImageEditor

<SfImageEditor @ref="ImageEditor" Height="500px" Width="100%">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;

    private async void OnCreated()
    {
        // 组件就绪时加载图片
        await ImageEditor.OpenAsync("path/to/image.png");
    }
}
设置步骤:
  1. 安装NuGet包:
    Syncfusion.Blazor.ImageEditor
    Syncfusion.Blazor.Themes
  2. _Imports.razor
    中添加导入:
    @using Syncfusion.Blazor.ImageEditor
  3. Program.cs
    中注册服务:
    builder.Services.AddSyncfusionBlazor();
  4. index.html
    App.razor
    添加主题样式表
  5. 添加组件并在
    Created
    事件中加载图片

Key Capabilities

核心功能

FeaturePurposeReference
Image LoadingOpen JPEG, PNG, JPG, WEBP, BMP filescore-operations.md
Text AnnotationsAdd labels, captions, watermarks with underline/strikethroughannotations.md
Shape AnnotationsDraw rectangles, ellipses, arrows, paths with z-order controlannotations.md
Freehand DrawingSketch and draw directly on imagesannotations.md
RedactionHide sensitive info with blur/pixelate for privacy complianceredaction.md
FramesApply decorative borders (Mat, Bevel, Line, Inset, Hook)frames.md
Crop & TransformCrop with multiple selection types, rotate, flip, straightenimage-transformations.md
Filters & EffectsApply fine-tuning and predefined filtersadjustments-filters-effects.md
Zoom & PanMultiple zoom methods and image panninguser-interactions.md
ExportSave as PNG, JPEG, SVG, WEBP with quality controlcore-operations.md
Undo/RedoFull history of operationscore-operations.md
Events30+ lifecycle, transformation, shape, and interaction eventsevents-reference.md
ToolbarBuilt-in or custom toolbar with eventstoolbar-customization.md
AccessibilityKeyboard navigation, screen readers, RTL, localizationaccessibility-localization.md
功能用途参考文档
图片加载打开JPEG、PNG、JPG、WEBP、BMP文件core-operations.md
文本注释添加带下划线/删除线的标签、说明、水印annotations.md
形状注释绘制带层级控制的矩形、椭圆、箭头、路径annotations.md
手绘功能在图片上直接草图和绘制annotations.md
内容打码使用模糊/像素化隐藏敏感信息以符合隐私合规要求redaction.md
边框效果应用装饰性边框(Mat、Bevel、Line、Inset、Hook)frames.md
裁剪与变换使用多种选择类型裁剪、旋转、翻转、校正角度image-transformations.md
滤镜与效果应用精细调整和预定义滤镜adjustments-filters-effects.md
缩放与平移多种缩放方法和图片平移user-interactions.md
导出功能按质量控制保存为PNG、JPEG、SVG、WEBPcore-operations.md
撤销/重做完整的操作历史记录core-operations.md
事件系统30+生命周期、变换、形状和交互事件events-reference.md
工具栏内置或自定义工具栏及事件toolbar-customization.md
无障碍支持键盘导航、屏幕阅读器、RTL、本地化accessibility-localization.md

Common Patterns

常见模式

Pattern 1: Load Image and Enable Annotations

模式1:加载图片并启用注释

csharp
<SfImageEditor @ref="ImageEditor" Height="500px">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;
    
    private async void OnCreated()
    {
        await ImageEditor.OpenAsync("https://example.com/image.png");
    }
    
    private async Task AddTextAnnotation()
    {
        ImageDimension dim = await ImageEditor.GetImageDimensionAsync();
        await ImageEditor.DrawTextAsync(dim.X.Value, dim.Y.Value, "Important", "Arial", 24);
    }
}
csharp
<SfImageEditor @ref="ImageEditor" Height="500px">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;
    
    private async void OnCreated()
    {
        await ImageEditor.OpenAsync("https://example.com/image.png");
    }
    
    private async Task AddTextAnnotation()
    {
        ImageDimension dim = await ImageEditor.GetImageDimensionAsync();
        await ImageEditor.DrawTextAsync(dim.X.Value, dim.Y.Value, "Important", "Arial", 24);
    }
}

Pattern 2: Custom Toolbar

模式2:自定义工具栏

csharp
<SfImageEditor @ref="ImageEditor" Toolbar="@CustomToolbar" Height="500px">
    <ImageEditorEvents Created="OnCreated" ToolbarItemClicked="OnToolbarClick"></ImageEditorEvents>
</SfImageEditor>

@code {
    private List<ImageEditorToolbarItemModel> CustomToolbar = new()
    {
        new ImageEditorToolbarItemModel { Name = "Open" },
        new ImageEditorToolbarItemModel { Name = "Crop" },
        new ImageEditorToolbarItemModel { Name = "Annotation" },
        new ImageEditorToolbarItemModel { Name = "Save" }
    };
}
csharp
<SfImageEditor @ref="ImageEditor" Toolbar="@CustomToolbar" Height="500px">
    <ImageEditorEvents Created="OnCreated" ToolbarItemClicked="OnToolbarClick"></ImageEditorEvents>
</SfImageEditor>

@code {
    private List<ImageEditorToolbarItemModel> CustomToolbar = new()
    {
        new ImageEditorToolbarItemModel { Name = "Open" },
        new ImageEditorToolbarItemModel { Name = "Crop" },
        new ImageEditorToolbarItemModel { Name = "Annotation" },
        new ImageEditorToolbarItemModel { Name = "Save" }
    };
}

Pattern 3: Export Image with Quality Control

模式3:带质量控制的图片导出

csharp
private async Task ExportImage()
{
    // Export as PNG (lossless, default)
    await ImageEditor.ExportAsync("edited-image.png");
    
    // Export as JPEG with quality control (0.0 to 1.0)
    await ImageEditor.ExportAsync("photo.jpg", ImageEditorFileType.JPEG, 0.85);
    
    // Export as WEBP (modern format)
    await ImageEditor.ExportAsync("image.webp", ImageEditorFileType.WEBP);
    
    // Export as SVG (vector format)
    await ImageEditor.ExportAsync("graphic.svg", ImageEditorFileType.SVG);
    
    // Or press Ctrl+S to open export dialog with format selection
}
csharp
private async Task ExportImage()
{
    // 导出为PNG(无损,默认格式)
    await ImageEditor.ExportAsync("edited-image.png");
    
    // 导出为带质量控制的JPEG(0.0至1.0)
    await ImageEditor.ExportAsync("photo.jpg", ImageEditorFileType.JPEG, 0.85);
    
    // 导出为WEBP(现代格式)
    await ImageEditor.ExportAsync("image.webp", ImageEditorFileType.WEBP);
    
    // 导出为SVG(矢量格式)
    await ImageEditor.ExportAsync("graphic.svg", ImageEditorFileType.SVG);
    
    // 或按Ctrl+S打开带格式选择的导出对话框
}

Pattern 4: Privacy Redaction Workflow

模式4:隐私打码工作流

csharp
<SfImageEditor @ref="ImageEditor" Height="500px">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;
    
    private async Task RedactSensitiveInfo()
    {
        // Draw blur redaction over sensitive areas
        await ImageEditor.DrawRedactAsync(
            RedactType.Blur, 
            startX: 100, startY: 100,
            width: 200, height: 50,
            value: 30  // Blur intensity
        );
        
        // Draw pixelate redaction over other areas
        await ImageEditor.DrawRedactAsync(
            RedactType.Pixelate,
            startX: 400, startY: 200,
            width: 200, height: 50,
            value: 20  // Pixel size
        );
        
        // Export redacted image
        await ImageEditor.ExportAsync("redacted-document.png");
    }
}
csharp
<SfImageEditor @ref="ImageEditor" Height="500px">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;
    
    private async Task RedactSensitiveInfo()
    {
        // 在敏感区域绘制模糊打码
        await ImageEditor.DrawRedactAsync(
            RedactType.Blur, 
            startX: 100, startY: 100,
            width: 200, height: 50,
            value: 30  // 模糊强度
        );
        
        // 在其他区域绘制像素化打码
        await ImageEditor.DrawRedactAsync(
            RedactType.Pixelate,
            startX: 400, startY: 200,
            width: 200, height: 50,
            value: 20  // 像素大小
        );
        
        // 导出打码后的图片
        await ImageEditor.ExportAsync("redacted-document.png");
    }
}

Pattern 5: Professional Photo Framing

模式5:专业照片边框

csharp
<SfImageEditor @ref="ImageEditor" Height="500px">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;
    
    private async Task ApplyPhotoFrame()
    {
        // Load portrait image
        await ImageEditor.OpenAsync("portrait.jpg");
        
        // Apply classic mat frame with gradient
        await ImageEditor.DrawFrameAsync(
            FrameType.Mat,
            color: "#FFFFFF",
            gradientColor: "#F5F5DC",
            size: 50,
            inset: 20
        );
        
        // Export framed image
        await ImageEditor.ExportAsync("framed-portrait.png");
    }
}
csharp
<SfImageEditor @ref="ImageEditor" Height="500px">
    <ImageEditorEvents Created="OnCreated"></ImageEditorEvents>
</SfImageEditor>

@code {
    SfImageEditor ImageEditor;
    
    private async Task ApplyPhotoFrame()
    {
        // 加载人像图片
        await ImageEditor.OpenAsync("portrait.jpg");
        
        // 应用带渐变的经典衬边边框
        await ImageEditor.DrawFrameAsync(
            FrameType.Mat,
            color: "#FFFFFF",
            gradientColor: "#F5F5DC",
            size: 50,
            inset: 20
        );
        
        // 导出带边框的图片
        await ImageEditor.ExportAsync("framed-portrait.png");
    }
}

Related Skills

相关技能

  • Implementing Blazor Components - Main library overview
  • Implementing Carousels - Image carousel display
  • Implementing Rich Text Editor - Text editing capabilities

Note: All code examples use Blazor component syntax. Refer to the Getting Started guide for setup instructions specific to your Blazor hosting model (WebAssembly, Web App, Server).
  • 实现Blazor组件 - 主库概述
  • 实现轮播组件 - 图片轮播展示
  • 实现富文本编辑器 - 文本编辑功能

注意: 所有代码示例均使用Blazor组件语法。请参考快速开始指南获取适用于你的Blazor托管模型(WebAssembly、Web App、Server)的具体设置说明。