syncfusion-javascript-image-editor

Syncfusion TypeScript Image Editor の実装

TypeScript アプリケーションで Syncfusion Image Editor コントロールを実装するための包括的なスキルです。このスキルでは、初期化、画像の読み込み／保存、注釈ツール、画像操作（ズーム、トリミング、回転、変形）、フィルター、微調整、アクセシビリティ、カスタマイズのパターンについて説明します。

概要

Syncfusion Image Editor は、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 など）
• 初期化、crop、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 入力を信頼できる許可リストに照らして必ず検証またはサニタイズしてください。SSRF や間接的なインジェクションを防ぐため、サードパーティのコンテンツに由来する URL は決して渡さないでください
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)	図形を 1 つ前面に移動します
sendBackward(shapeId)	図形を 1 つ背面に移動します
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	選択／切り抜きの外観（塗りつぶし、線、円形表示）
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	エディターキャンバス内のクリック時

一般的なユースケース

プロ向け画像編集スイート - すべてのツールを備えたフル機能エディター 注釈ワークフロー - ドキュメントへのマークアップと墨消し クイック切り抜きツール - 切り抜きに特化したシンプルな UI ソーシャルメディアツール - 各プラットフォーム用のプリセット縦横比 スクリーンショットのマークアップ - スクリーンショットへのすばやい注釈 ドキュメント処理 - スキャン画像の傾き補正、切り抜き、エクスポート ダイアログとの統合 - モーダル形式の画像編集ワークフロー

関連スキル

• implementing-rich-text-editor - テキストドキュメントの編集用
• implementing-buttons - コントロールのカスタマイズ用
• implementing-dialogs - モーダルワークフローの統合用