syncfusion-javascript-block-editor

Syncfusion JavaScript BlockEditor

概要

Syncfusion JavaScript BlockEditor は、さまざまなブロックタイプを使用してコンテンツの作成、書式設定、整理を行える、最新のブロックベースのテキストエディターです。ドラッグ＆ドロップによる並べ替え、スラッシュコマンド、インラインツールバー、豊富なカスタマイズオプションなどの機能を備え、直感的な編集操作を実現します。BlockEditor コントロールはブロックベースのアーキテクチャ上に構築されており、コンテンツは個別のブロックとして整理されます。各ブロックには特定のタイプ（段落、見出し、リスト、画像など）があり、書式設定されたコンテンツを含めることができます。主な特徴は次のとおりです。

• ブロックタイプ：タイポグラフィ、リスト、テーブル、画像、コード、折りたたみ可能なセクションなど、14 種類の組み込みブロックタイプ
• コンテンツモデル：BlockModel と ContentModel を使用した、プログラムから操作できる構造化コンテンツ
• 直感的な UX：スラッシュコマンド（/）、ドラッグハンドル、インラインツールバー、コンテキストメニュー
• 共同編集：Yjs によるリアルタイムの複数ユーザー編集。プレゼンス、リモートカーソル、バージョン履歴に対応
• 拡張性：カスタムブロック、コマンド、メニュー項目、テンプレート
• データ形式：柔軟な保存と交換に対応する HTML または JSON でのインポート／エクスポート
• アクセシビリティ：キーボード操作、ARIA 属性、スクリーンリーダーへの対応

ドキュメントとナビゲーションガイド

はじめに

📄 参照先： references/getting-started.md

• 前提条件と Node.js のバージョン要件（24.13.0 以上）
• Vite を使用した TypeScript アプリケーションの作成
• インストールとパッケージのセットアップ（@syncfusion/ej2-blockeditor）
• CSS のインポートとテーマの設定（Tailwind3、Material、Bootstrap など）
• Vite を使用した BlockEditor の基本的な初期化
• npm run dev を使用したアプリケーションの実行

ブロックとコンテンツモデル

📄 参照先： references/blocks-and-content-models.md

• BlockModel インターフェースの全項目（id、blockType、content、properties、cssClass、indent、parentId、template）
• BlockType 列挙型（Paragraph、Heading、BulletList、NumberedList、Checklist、Table、Image、Code、Quote、Callout、Divider、CollapsibleParagraph、CollapsibleHeading、Template）
• ContentModel インターフェース（id、contentType、content、properties）
• ContentType 列挙型（Text、Link、Mention、Label）
• ブロック固有のプロパティ（HeadingProps、ImageProps、CodeProps、ChecklistProps、CollapsibleProps など）
• コンテンツ固有のプロパティ（LinkContentProps、MentionContentProps、StyleModel）
• メンションと共同編集に使用する UserModel
• ブロック作成用のヘルパーメソッドを備えた BlockFactory クラス

組み込みブロックタイプ

📄 参照先： references/built-in-block-types.md

• タイポグラフィブロック：Paragraph、Heading（1～4）、Quote、Callout
• テキスト書式設定：太字、斜体、下線、取り消し線、大文字、小文字、下付き文字、上付き文字、インラインコード
• フォントカラーと背景色（テキストのハイライト）
• リストブロック：BulletList、NumberedList、Checklist（isChecked を使用）
• 設定可能なテーブルブロック
• メディアブロック：アップロード、サイズ変更、制約に対応した Image（imageBlockSettings）
• 構文ハイライトと言語選択に対応した Code ブロック（codeBlockSettings）
• 高度なブロック：CollapsibleParagraph、CollapsibleHeading、Divider、Template
• 親子関係を持つネストされたブロック構造

エディターメニューとツールバー

📄 参照先： references/editor-menus-and-toolbars.md

• スラッシュコマンドメニュー（/）：CommandItemModel を使用する commandMenuSettings
• ブロックアクションメニュー（⋮ ハンドル）：BlockActionItemModel を使用する blockActionMenuSettings
• コンテキストメニュー（右クリック）：ContextMenuItemModel を使用する contextMenuSettings
• インライン書式設定ツールバー：ToolbarItemModel と BuiltInToolbar 列挙型を使用する inlineToolbarSettings
• 変換メニュー：ブロックタイプの変換に使用する transformSettings
• カスタムコマンドとメニュー項目
• メニューイベント：フィルタリング、itemSelect、beforeOpen、beforeClose
• カスタマイズの詳細な例

メソッドのリファレンス

📄 参照: references/methods-reference.md

• ブロック管理：addBlock、removeBlock、moveBlock、updateBlock
• ブロックのクエリ：getBlock、getBlockCount、getSelectedBlocks
• 選択：selectBlock、selectAllBlocks、selectRange、setSelection、getRange、setCursorPosition
• データ操作：getDataAsHtml、getDataAsJson、parseHtmlToBlocks、renderBlocksFromJson
• ツールバーの制御：enableToolbarItems、disableToolbarItems、executeToolbarAction
• フォーカス管理：focusIn、focusOut
• ユーティリティ：print、refresh、dataBind
• ライフサイクル：appendTo、destroy、addEventListener、removeEventListener

イベントのリファレンス

📄 参照: references/events-reference.md

• ライフサイクル：created
• コンテンツ：blockChanged（BlockChangedEventArgs を含む）、selectionChanged
• フォーカス：focus（FocusEventArgs）、blur（BlurEventArgs）
• ドラッグ＆ドロップ：blockDragStart、blockDragging、blockDropped（BlockDragEventArgs、BlockDropEventArgs を含む）
• 貼り付け：beforePasteCleanup、afterPasteCleanup（PasteCleanupEventArgs を含む）
• ファイルアップロード：beforeFileUpload、fileUploading、fileUploadSuccess、fileUploadFailed
• イベント引数インターフェイスの全一覧
• 元に戻す／やり直しの追跡に使う ActionType 列挙型

ドラッグ＆ドロップと選択

📄 参照: references/drag-drop-and-selection.md

• ドラッグ＆ドロップの設定（enableDragAndDrop プロパティ）
• 単一および複数ブロックのドラッグ
• ドラッグイベントと視覚的なインジケーター
• 選択管理メソッド
• プログラムによる選択制御
• NodeSelection クラス
• カーソル位置の設定

貼り付け、元に戻す／やり直し、キーボード

📄 参照: references/paste-undo-redo-keyboard.md

• 貼り付け時のクリーンアップ設定（keepFormat、plainText、deniedTags を含む pasteCleanupSettings）
• 貼り付けの傍受と変更に使うイベント
• 元に戻す／やり直しスタックの設定（undoRedoStack プロパティ）
• キーボードショートカット（カスタムショートカット用の keyConfig プロパティ）
• デフォルトのキーボードコマンド
• mentions（@user）：users プロパティと UserModel を使用
• ラベル／タグ（$label）：labelSettings プロパティと LabelItemModel を使用

カスタマイズと外観

📄 参照: references/customization-and-appearance.md

• 寸法：width、height プロパティ
• カスタムスタイル：cssClass プロパティ
• フォントカラーのカスタマイズ：fontColorSettings（パレット／ピッカーモードを備えた FontColorSettingsModel）
• 背景色のカスタマイズ：backgroundColorSettings（BackgroundColorSettingsModel）
• ColorModeType 列挙型（Palette、Picker）
• 読み取り専用モード：readOnly プロパティ
• RTL サポート：enableRtl プロパティ
• ローカライズ：locale プロパティ
• カスタムブロックテンプレート
• CSS 変数によるテーマのカスタマイズ（--color-sf-* と --sf の命名規則）
• Block Editor の CSS クラスと ID（.e-blockeditor、.e-active、.e-selected、.e-list-item、.e-dropdownbase、.e-table-element、#blockeditor_contextmenu、#blockeditor_code-ddl_popup）
• CSS 変数のオーバーライドを使った複数テーマの切り替え例（Slate Light、Sage Green、Dark Pro）
• 完全カスタマイズ可能なテーマに対応する Syncfusion Theme Studio（Material 3、Fluent 2、Bootstrap 5.3、Tailwind 3）
• テーマの統合

セキュリティとサニタイズ

📄 参照: references/security-and-sanitization.md

• HTML のサニタイズ
• HTML エンコーディング（enableHtmlEncode プロパティ）
• XSS 防止策
• 閲覧専用コンテンツ向けの読み取り専用モード
• deniedTags を使った貼り付け時のセキュリティ
• 安全なコンテンツ処理のベストプラクティス
• コンプライアンスに関する考慮事項

共同編集

📄 参照： references/collaborative-editing.md

• クイックスタートガイド：Vite、Yjs、WebSocketを使って数分で共同編集をセットアップします
• Yjsドキュメント、アダプター、プロバイダー、ルーム割り当てロジックを含むcollaboration.tsファイルの作成
• 本番環境へのデプロイ向けにy-websocketを使ってWebSocketサーバーをセットアップします
• リアルタイム同期のためにYjsとWebSocketプロバイダーをインストールして設定します
• Yjs（CRDTベースの同期と競合解決）を利用したリアルタイム共同編集
• CollaborationモジュールとVersionHistoryモジュールの注入
• collaborationSettingsプロパティ（provider、adapter、enableAwareness、versionHistory）
• Yjsプロバイダーの選択（y-websocket、y-webrtc、y-indexeddb、Hocuspocus、Liveblocks、PartyKit）
• ユーザーのプレゼンス、リモートカーソル、テキスト選択のオーバーレイ（enableAwareness）
• usersとcurrentUserIdを使った現在のユーザーの設定
• IndexedDBVersionStorageの実装によるバージョン履歴
• スナップショットパネル、復元／削除ボタン、自動更新を備えたバージョン履歴UI
• バージョン履歴のメソッド：スナップショットの作成、一覧表示、名前変更、復元、比較、エクスポート、インポート
• バージョン履歴のイベント：snapshotCreated、snapshotRestored
• 共同編集のセットアップに関するベストプラクティスとトラブルシューティング

クイックスタートの例

import { BlockEditor, BlockType, ContentType } from '@syncfusion/ej2-blockeditor';

// Initialize BlockEditor with sample content
const editor = new BlockEditor({
    width: '100%',
    height: '600px',
    blocks: [
        {
            id: 'heading-1',
            blockType: BlockType.Heading,
            properties: { level: 1 },
            content: [
                {
                    contentType: ContentType.Text,
                    content: 'Welcome to BlockEditor'
                }
            ]
        },
        {
            id: 'intro-para',
            blockType: BlockType.Paragraph,
            content: [
                {
                    contentType: ContentType.Text,
                    content: 'Start typing or press "/" to open the command menu.'
                }
            ]
        },
        {
            id: 'bullet-list',
            blockType: BlockType.BulletList,
            content: [
                {
                    contentType: ContentType.Text,
                    content: 'Drag blocks to reorder'
                }
            ]
        }
    ],
    enableDragAndDrop: true,
    enableHtmlSanitizer: true
});

// Render the editor
editor.appendTo('#blockeditor');

<!DOCTYPE html>
<html>
<head>
    <link href="https://cdn.syncfusion.com/ej2/32.1.19/tailwind.css" rel="stylesheet" />
</head>
<body>
    <div id="blockeditor"></div>
</body>
</html>

よく使われるパターン

ブロックをプログラムで追加する

// Add a new paragraph block after a target block
const newBlock = {
    id: 'new-para',
    blockType: BlockType.Paragraph,
    content: [
        {
            contentType: ContentType.Text,
            content: 'This is a new paragraph.'
        }
    ]
};

editor.addBlock(newBlock, 'target-block-id', true); // true = after

コンテンツをHTML／JSONとして取得する

// Get all content as HTML
const htmlContent = editor.getDataAsHtml();

// Get all content as JSON
const jsonContent = editor.getDataAsJson();

// Get specific block content
const blockHtml = editor.getDataAsHtml('block-id');
const blockJson = editor.getDataAsJson('block-id');

ブロックの変更を処理する

const editor = new BlockEditor({
    blockChanged: (args) => {
        console.log('Blocks changed:', args.changes);
        // Auto-save functionality
        saveContent(editor.getDataAsJson());
    }
});

カスタムスラッシュコマンド

const editor = new BlockEditor({
    commandMenuSettings: {
        popupWidth: '350px',
        commands: [
            {
                id: 'custom-quote',
                type: BlockType.Quote,
                label: 'Quote Block',
                iconCss: 'e-icons e-quote',
                groupBy: 'Basic'
            },
            {
                id: 'timestamp',
                label: 'Insert Timestamp',
                iconCss: 'e-icons e-schedule',
                groupBy: 'Actions'
            }
        ],
        itemSelect: (args) => {
            if (args.command.id === 'timestamp') {
                // Custom action: insert current timestamp
                const timestamp = new Date().toLocaleString();
                // Insert logic here
            }
        }
    }
});

リアルタイム共同編集を有効にする

import { BlockEditor, Collaboration, YjsAdapter } from '@syncfusion/ej2-blockeditor';
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';

BlockEditor.Inject(Collaboration);

const yDoc = new Y.Doc();
const yFragment = yDoc.getXmlFragment('blockeditor');
const adapter: YjsAdapter = { yRuntime: Y, yXmlFragment: yFragment };
const provider = new WebsocketProvider('wss://your-server-url', 'document-room-id', yDoc);

const editor = new BlockEditor({
    users: [{ id: 'user-1', user: 'John Doe', avatarBgColor: '#e74c3c' }],
    currentUserId: 'user-1',
    collaborationSettings: {
        provider: provider,
        adapter: adapter,
        enableAwareness: true,
    }
});

editor.appendTo('#blockeditor');

画像アップロードの設定

const editor = new BlockEditor({
    imageBlockSettings: {
        saveUrl: 'https://your-server.com/api/upload',
        path: '/images/',
        allowedTypes: ['.jpg', '.jpeg', '.png', '.gif'],
        maxFileSize: 5000000, // 5MB
        maxWidth: 1200,
        maxHeight: 800,
        enableResize: true,
        saveFormat: 'Blob' // or 'Base64'
    },
    fileUploadSuccess: (args) => {
        console.log('File uploaded:', args.fileUrl);
    }
});

CSS変数によるテーマのカスタマイズ

コンポーネント設定に手を加えずにエディターの外観を変更するには、.e-blockeditor（または任意の祖先要素）の--color-sf-* CSS変数を上書きします。

const blockEditor = new BlockEditor({
    blocks: blocksData,
    width: '100%',
    height: '600px'
});
blockEditor.appendTo('#blockeditor');

// Switch theme by toggling a body class
function applyTheme(themeName: 'slateLightTheme' | 'sageGreenTheme' | 'darkProTheme') {
    document.body.classList.remove('slateLightTheme', 'sageGreenTheme', 'darkProTheme');
    document.body.classList.add(themeName);
}

/* CSS variables follow the unified --sf naming convention */
.darkProTheme .e-blockeditor {
    --color-sf-content-bg-color: #0d1117;
    --color-sf-content-bg-color-hover: #161b22;
    --color-sf-content-bg-color-selected: #21262d;
    --color-sf-content-text-color: #e6edf3;
    --color-sf-placeholder-text-color: #7d8590;
    --color-sf-border: #30363d;
    --color-sf-border-hover: #58a6ff;
    --color-sf-primary: #1f6feb;
    --color-sf-primary-text-color: #ffffff;
    --color-sf-icon-color: #8b949e;

    background: #0d1117 !important;
    border: 1px solid #30363d;
    border-radius: 20px;
}

すべてのSyncfusionコンポーネントにわたってテーマを完全にカスタマイズするには、Material 3、Fluent 2、Bootstrap 5.3、またはTailwind 3をベースとしてSyncfusion Theme Studioを使用します。

主な設定オプション

基本プロパティ

• blocks：BlockModel[] - 初期コンテンツブロック
• width：string | number - エディターの幅（デフォルト：'100%'）
• height：string | number - エディターの高さ（デフォルト：'auto'）
• readOnly：boolean - 読み取り専用モード（デフォルト：false）
• enableDragAndDrop：boolean - ブロックのドラッグ＆ドロップ（デフォルト：true）
• enableHtmlSanitizer：boolean - HTMLをサニタイズします（デフォルト：true）
• undoRedoStack：number - 最大取り消し／やり直し操作数（デフォルト：30）
• cssClass：string - スタイル設定用のカスタムCSSクラス

メニューとツールバーの設定

• commandMenuSettings：CommandMenuSettingsModel - スラッシュコマンドメニュー（/）
• blockActionMenuSettings：BlockActionMenuSettingsModel - ブロックアクションメニュー（⋮）
• contextMenuSettings：ContextMenuSettingsModel - 右クリックのコンテキストメニュー
• inlineToolbarSettings：InlineToolbarSettingsModel - テキスト書式設定ツールバー
• transformSettings：TransformSettingsModel - ブロック変換メニュー

機能の設定

• imageBlockSettings：ImageBlockSettingsModel - 画像のアップロードと設定
• codeBlockSettings：CodeBlockSettingsModel - コードの構文ハイライト
• pasteCleanupSettings：PasteCleanupSettingsModel - 貼り付け時の書式設定制御
• labelSettings：LabelSettingsModel - ラベル／タグの設定（$label）
• users：UserModel[] - メンション用のユーザー（@user）
• keyConfig：{ [key: string]: string } - カスタムキーボードショートカット

色の設定

• fontColorSettings：FontColorSettingsModel - テキスト色パレット
• backgroundColorSettings：BackgroundColorSettingsModel - 背景色／ハイライト色パレット

テーマのカスタマイズ

• CSS 変数（--color-sf-*）：コンポーネントのプロパティに触れずに、色、境界線、プレースホルダー、プライマリアクセント、アイコンをカスタマイズするには、.e-blockeditor（または任意の祖先要素）で上書きします
• CSS クラス／ID：.e-blockeditor、.e-active、.e-selected、.e-list-item、.e-dropdownbase、.e-table-element、#blockeditor_contextmenu、#blockeditor_code-ddl_popup
• Syncfusion Theme Studio：Material 3、Fluent 2、Bootstrap 5.3、Tailwind 3をベースにして、Block Editorやその他のEJ2コンポーネント用の完全にカスタマイズされたテーマを作成できます

コラボレーション設定

• collaborationSettings：CollaborationSettingsModel - リアルタイムコラボレーションの設定（プロバイダー、アダプター、enableAwareness、versionHistory）
• users：UserModel[] - 接続中のユーザー。メンションとプレゼンスにも使用されます
• currentUserId：string - プレゼンスとカーソルのハイライト表示に使用するローカルユーザーを識別します
• BlockEditor.Inject(...)を使用してCollaborationモジュール（スナップショットをサポートする場合はVersionHistoryも）をインジェクトする必要があります

ローカライズとRTL

• locale：string - ローカライズコード（デフォルト：'en-US'）
• enableRtl：boolean - 右から左への表示をサポートします（デフォルト：false）
• enablePersistence：boolean - 再読み込み後も状態を保持します（デフォルト：false）