syncfusion-aspnetcore-image-editor

Syncfusion ASP.NET Core Image Editor の実装

Syncfusion EJ2 Image Editor は、ブラウザー上で豊富なインタラクティブな画像編集体験を提供します。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、File Uploader、File Manager
• imageSettings を使用して、幅／高さを指定して開く
• export() — 形式と品質のオプションを指定して保存
• getImageData() — 画像を base64／Blob として取得
• clearImage() と reset() の使用パターン
• ダイアログ内での Image Editor のレンダリング
• 開くときにウォーターマークを自動的に追加
• 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() — クール、ウォーム、クローム、セピア、グレースケール、反転
• FinetuneValueChanging イベント
• キャンセルをサポートする ImageFiltering イベント

サイズ変更と墨消し

📄 参照： references/resize-redact.md

• resize() — 幅、高さ、アスペクト比の制御
• 変更前後の寸法を含む Resizing イベント
• drawRedact() — 機密領域をぼかす、またはピクセル化
• selectRedact()、deleteRedact()、updateRedact()、getRedacts()

ツールバーとクイックアクセスツールバー

📄 参照： references/toolbar-quickaccess.md

• 組み込みツールバー項目の一覧（Open、Undo、Redo、Crop、Annotate、Filter、Save など）
• Toolbar プロパティ — ツールバー項目の追加、削除、非表示
• ToolbarTemplate — ツールバー全体をカスタム HTML に置き換え
• ToolbarUpdating イベント — コンテキストツールバーをカスタマイズ
• ShowQuickAccessToolbar — クイックアクセスツールバーの切り替え
• QuickAccessToolbarOpen イベント — クイックアクセスツールバーにカスタム項目を追加
• ToolbarCreated／ToolbarItemClicked イベント

フレーム、ローカライズ、アクセシビリティ、Undo-Redo

📄 参照： 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. Image Editor をレンダリングする（~/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	Undo／Redo を有効化（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 ASP.NET Coreコンポーネントの実装 — 親ライブラリのスキル