syncfusion-aspnetcore-image-editor

Name: syncfusion-aspnetcore-image-editor
Author: syncfusion

github.com/syncfusion开发0106 次安装2 周前更新

代码仓库

关于 syncfusion-aspnetcore-image-editor

用于在 ASP.NET Core 应用中集成 Syncfusion EJ2 Image Editor 的技能，介绍浏览器内多种常见格式的图像编辑，包括变换、标注、滤镜和撤销重做。

主要功能

01打开并导出常见图像格式
02旋转、翻转、缩放和裁剪图像
03添加文本、形状和图像标注
04调整图像参数并应用滤镜
05调整尺寸并遮盖图像区域
06自定义工具栏并撤销或重做更改

适用场景

01在 ASP.NET Core 页面中加入图像编辑
02裁剪并标注用户提供的图像
03导出前遮盖图像中的敏感区域

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/syncfusion/aspnetcore-ui-components-skills --skill syncfusion-aspnetcore-image-editor

安装后在 Claude Code 中输入/syncfusion-aspnetcore-image-editor确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

image-editor-annotation.md

image-editor-api.md

image-editor-finetune-filter.md

image-editor-frames-localization-accessibility.md

image-editor-getting-started.md

image-editor-open-save.md

image-editor-resize-redact.md

image-editor-selection-cropping.md

image-editor-toolbar-quickaccess.md

image-editor-transform.md

详细介绍

实现 Syncfusion ASP.NET Core 图像编辑器

Syncfusion EJ2 图像编辑器可直接在浏览器中提供丰富的交互式图像编辑体验。它支持打开、编辑和保存 PNG、JPEG、SVG、WEBP 和 BMP 格式的图像。所有操作（包括注释、变换和滤镜）都会记录在包含 16 步的撤消/重做历史记录中。

导航指南

入门

📄 阅读： references/getting-started.md

NuGet 安装和设置
在 _ViewImports.cshtml 中注册标记帮助程序
添加样式表和脚本引用——本地资源（推荐）或带 SRI 哈希的 CDN
渲染基本的 <ejs-imageeditor> 标签
用于正确调整大小的容器 CSS

打开和保存图像

📄 阅读： references/open-save.md

open() 方法——本地文件、base64、Blob、URL、文件上传器、文件管理器
使用 imageSettings 打开时设置自定义宽度/高度
export()——使用格式和质量选项保存
getImageData()——以 base64 / Blob 格式获取图像
clearImage() 和 reset() 用法
在对话框中渲染图像编辑器
打开时自动添加水印
FileOpened、Saving 和 BeforeSave 事件

变换（旋转、翻转、缩放、平移）

📄 阅读： references/transform.md

rotate()——按角度顺时针/逆时针旋转
flip()——水平或垂直翻转
straightenImage()——±45° 范围内校正对齐
zoom()——放大，可选设置缩放点
ZoomSettings——minZoomFactor、maxZoomFactor
图像超出画布时的平移行为
Rotating、Flipping、Zooming、Panning 事件

选择和裁剪

📄 阅读： references/selection-cropping.md

select()——自定义、正方形、圆形、宽高比类型
crop()——裁剪选定区域
裁剪时保持原始图像大小（preventScaling）
SelectionChanging 事件——以编程方式调整选区
锁定选区以防止调整大小
使用公共方法按自定义比例裁剪

注释

📄 阅读： references/annotation.md

drawText()——设置字体、字号、粗体、斜体、下划线、删除线、填充和描边的文本
在文本内容中使用 \n 添加多行文本
drawRectangle()、drawEllipse()、drawLine()、drawArrow()、drawPath()
drawImage()——叠加图像、徽标和水印
freehandDraw()——启用/禁用自由绘制模式
deleteShape() / getShapeSetting()——管理注释
FontFamily 属性——添加自定义字体系列
Z 轴顺序管理（上移、下移、置于顶层、置于底层）
ShapeChanging / ShapeChange 事件

微调和滤镜

📄 阅读： references/finetune-filter.md

finetuneImage()——亮度、对比度、饱和度、色调、曝光、模糊、不透明度
FinetuneSettings 属性，用于配置可用的微调选项
applyImageFilter()——冷色、暖色、Chrome、棕褐色、灰度、反色
FinetuneValueChanging 事件
支持取消的 ImageFiltering 事件

调整大小和遮盖

📄 阅读： references/resize-redact.md

resize()——宽度、高度、宽高比控制
Resizing 事件，包含调整前后的尺寸
drawRedact()——模糊或像素化敏感区域
selectRedact()、deleteRedact()、updateRedact()、getRedacts()

工具栏与快速访问工具栏

📄 阅读： references/toolbar-quickaccess.md

内置工具栏项列表（打开、撤销、重做、裁剪、批注、滤镜、保存等）
Toolbar 属性 — 添加、移除或隐藏工具栏项
ToolbarTemplate — 使用自定义 HTML 替换整个工具栏
ToolbarUpdating 事件 — 自定义上下文工具栏
ShowQuickAccessToolbar — 切换快速访问工具栏
QuickAccessToolbarOpen 事件 — 向快速访问工具栏添加自定义项
ToolbarCreated / ToolbarItemClicked 事件

边框、本地化、无障碍与撤销重做

📄 阅读： references/frames-localization-accessibility.md

drawFrame() — 垫框、斜面、线条、钩形、内嵌边框类型
UploadSettings — 限制文件扩展名和文件大小
Locale 属性 — 使用翻译对象进行国际化
符合 WCAG 2.2 AA 标准，支持键盘快捷键
undo() / redo() 方法和 AllowUndoRedo 属性（16 步历史记录）

API 参考

📄 阅读： references/api.md

所有属性：AllowUndoRedo、CssClass、Disabled、Height、Width、Theme、Locale
复杂设置对象：ZoomSettings、FinetuneSettings、SelectionSettings、UploadSettings、FontFamily
所有事件及其参数类型
所有客户端 JavaScript 方法

快速入门

1. 安装 NuGet 包

Install-Package Syncfusion.EJ2.AspNet.Core

2. 注册标记帮助程序（`~/Pages/_ViewImports.cshtml`）

@addTagHelper *, Syncfusion.EJ2

3. 添加 CSS 和脚本（`~/Pages/Shared/_Layout.cshtml`）

仅使用本地资源（安全合规要求）

从官方发行版下载 Syncfusion EJ2 分发包，并在本地托管：

<head>
     
     <link rel="stylesheet" href="/lib/ej2/fluent2.css" />
</head>
<body>
    ...
    
    
    <script src="/lib/ej2/ej2.min.js"></script>
    <ejs-scripts></ejs-scripts>
</body>

**⚠️ 安全策略：**不允许从外部 CDN 加载。所有 Syncfusion 运行时资源都必须托管在应用程序本地。

4. 渲染图像编辑器（`~/Pages/Index.cshtml`）

<div class="e-img-editor-sample">
    <ejs-imageeditor id="image-editor"></ejs-imageeditor>
</div>

<style>
    .e-img-editor-sample {
        height: 80vh;
        width: 100%;
    }
</style>

常见模式

以编程方式打开图像

选项 A：本地图像文件（推荐）

<ejs-imageeditor id="image-editor" created="onCreated"></ejs-imageeditor>

<script>
function onCreated() {
    var imageEditor = document.getElementById('image-editor').ej2_instances[0];
    // Reference local image in wwwroot/images/
    imageEditor.open('/images/nature.png');
}
</script>

选项 B：用户上传的图像（Base64）

<ejs-uploader id="fileUpload" selected="onFileSelected"></ejs-uploader>
<ejs-imageeditor id="image-editor"></ejs-imageeditor>

<script>
function onFileSelected(args) {
    if (args.filesData.length > 0) {
        var reader = new FileReader();
        reader.onload = function() {
            // Pass base64-encoded local data (no external fetch)
            var imageEditor = document.getElementById('image-editor').ej2_instances[0];
            imageEditor.open(reader.result);
        };
        reader.readAsDataURL(args.filesData[0].rawFile);
    }
}
</script>

导出 / 保存图像

<button onclick="saveImage()">Save</button>
<ejs-imageeditor id="image-editor" created="onCreated"></ejs-imageeditor>

<script>
function onCreated() {
    var imageEditor = document.getElementById('image-editor').ej2_instances[0];
    // Load local image
    imageEditor.open('/images/nature.png');
}

function saveImage() {
    var imageEditor = document.getElementById('image-editor').ej2_instances[0];
    imageEditor.export('PNG');  // saves as PNG to local device
}
</script>

处理 FileOpened 事件

<ejs-imageeditor id="image-editor" fileOpened="onFileOpened"></ejs-imageeditor>

<script>
function onFileOpened(args) {
    console.log('Opened file:', args.fileName, 'Type:', args.fileType);
}
</script>

限制上传文件类型

<ejs-imageeditor id="image-editor">
    <e-imageeditor-uploadsettings allowedExtensions=".jpg, .png, .webp"
                                  minFileSize="10000"
                                  maxFileSize="5000000">
    </e-imageeditor-uploadsettings>
</ejs-imageeditor>

常用属性一览

属性	类型	默认值	用途
`height`	string	"100%"	编辑器高度
`width`	string	"100%"	编辑器宽度
`allowUndoRedo`	bool	true	启用撤销/重做（16 步）
`disabled`	bool	false	禁用控件
`showQuickAccessToolbar`	bool	true	显示批注快速访问工具栏
`theme`	Theme	Bootstrap5	形状选择外观主题
`locale`	string	"en-US"	本地化区域设置
`imageSmoothingEnabled`	bool	false	启用高质量渲染平滑处理
`toolbar`	object	default items	工具栏项数组
`toolbarTemplate`	string	null	自定义工具栏模板选择器

安全与信任边界

⚠️ 严重：切勿加载外部 URL

不要将外部或不受信任的 URL 用于 imageEditor.open() 或 drawImage()：

// ❌ FORBIDDEN — Loads remote content from untrusted sources
imageEditor.open('https://untrusted-external-cdn.com/bridge.png');
imageEditor.open('https://example.com/user-uploads/image.jpg');  // Arbitrary external URL
imageEditor.drawImage('https://external-site.com/logo.png', 10, 10, 100, 50);

// ✅ SAFE — Use only local/trusted sources
imageEditor.open('/images/local-image.png');  // Local file in wwwroot
imageEditor.open(base64DataUrl);              // Base64 encoded (local data)
imageEditor.open(blobUrl);                    // Blob URL from File input
imageEditor.drawImage('/images/company-logo.png', 10, 10, 100, 50);  // Local asset

外部 URL 会带来供应链和注入风险，无法完全缓解。

运行时与内容安全

**关键策略：**此技能要求所有运行时代码和内容都来自本地。

要求 1：仅使用本地运行时资源（W012）

Syncfusion EJ2 运行时库必须托管在本地：

✅ 从 Syncfusion 官方发行版下载
✅ 托管在 wwwroot/lib/ej2/
✅ 引用为 /lib/ej2/ej2.min.js（仅限本地路径）
❌ 不要从任何外部 CDN 或远程 URL 加载

**要求 2：仅使用本地内容（W011）

内容安全实践

1. 将图像加载为 Base64 或 Blob（推荐）

在本地加载用户上传的文件，并以 Base64 或 Blob 形式传递，以避免任何外部获取：

// ✅ SAFE: Load user file locally as base64
function selected(args) {
    if (args.filesData.length > 0) {
        var reader = new FileReader();
        reader.onload = function() {
            imageEditor.open(reader.result);  // Base64 data, not URL
        };
        reader.readAsDataURL(args.filesData[0].rawFile);
    }
}

2. 服务端图像验证

在处理所有图像上传前，先在服务端进行验证：

// ASP.NET Core controller
[HttpPost]
public IActionResult ValidateImage(IFormFile file)
{
    // Whitelist allowed MIME types only
    var allowedTypes = new[] { "image/png", "image/jpeg", "image/webp", "image/bmp" };
    if (!allowedTypes.Contains(file.ContentType))
        return BadRequest("Invalid image format");
    
    // Enforce file size limits (e.g., max 5MB)
    if (file.Length > 5 * 1024 * 1024)
        return BadRequest("File too large");
    
    return Ok();
}

3. 叠加内容仅使用本地资源

使用 drawImage() 添加徽标或水印时，仅引用本地资源：

// ✅ SAFE: Local asset in wwwroot/images/
imageEditor.drawImage('/images/company-logo.png', 10, 10, 100, 50);

// ❌ FORBIDDEN: External URLs not permitted
// imageEditor.drawImage('https://external-site.com/logo.png', ...);

4. 实施内容安全策略

将所有内容来源限制为本地或受信任的源：


<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline';">

信任评估

因素	评估
供应商	Syncfusion Inc. —— 成熟的企业级组件供应商，应用广泛
协议	所有 CDN 资源均通过 HTTPS 提供服务，并可实施证书固定
透明度	通过 Syncfusion 支持渠道定期发布安全更新和 CVE 披露
监控	检查 Syncfusion 安全公告和 NuGet 包安全建议数据库
撤销/重做	16 步历史记录仅保存在本地；不进行云同步或外部遥测

最佳实践

✅ 运行时资源安全

将所有 Syncfusion 运行时资源托管在本地的 wwwroot/lib/ej2/ 中
切勿从外部 CDN 或远程服务加载
定期更新到最新稳定版本
关注 Syncfusion 安全公告
使用 NuGet 包签名验证包完整性

✅ 内容与图像安全

将所有图像加载为 Base64 或 Blob（仅限本地数据）
在服务端验证文件类型、大小和内容
切勿直接信任用户提供的 URL
叠加内容（徽标、水印）仅引用内部资源
所有应用图像均使用 wwwroot/images/

✅ 合规与监控

实施严格的 CSP：script-src 'self'; img-src 'self' data:
在 CI/CD 流水线中执行安全扫描
使用 snyk、dotnet list package --vulnerable 等工具审计依赖项
维护所有本地托管资源的清单
在生产部署前，先在预发布环境中测试安全更新

基本信息

作者: syncfusion
仓库: syncfusion/aspnetcore-ui-components-skills
分类: 开发
安装次数: 106
GitHub Stars: 0

报告问题