syncfusion-angular-blockeditor

Syncfusion Angular Block Editor コンポーネント

コンポーネントの概要

Syncfusion Angular Block Editor は、Angular アプリケーション向けの強力なブロックベースのエディターコンポーネントです。最新のコンテンツ管理システムに似たドキュメント中心の編集体験を提供し、書式設定、カスタマイズ、高度な機能を幅広くサポートします。

主な機能：

• ブロック管理 - 段落、見出し、リスト、テーブル、コード、画像など、さまざまなブロックタイプを使ってドキュメントを作成できます
• テキストの書式設定 - 太字、斜体、下線、取り消し線、色、ハイライト、インラインスタイルを設定できます
• 高度なメニュー - スラッシュコマンド、コンテキストメニュー、インラインツールバー、ブロックアクションメニューを利用できます
• イベントとインタラクション - コンテンツの変更、選択、ドラッグ＆ドロップ、貼り付け操作に関する包括的なイベント処理を提供します
• コンテンツ管理 - JSON、HTML、Markdown としてインポート／エクスポートでき、シリアライズを完全に制御できます
• メソッド - API を通じてブロックをプログラムから追加、削除、移動、更新できます
• セキュリティ機能 - 安全なコンテンツを実現するため、HTML のサニタイズと XSS 防止機能を内蔵しています
• 共同編集 - Yjs を活用したリアルタイムの複数ユーザー編集に対応し、ユーザーのプレゼンス、リモートカーソル、バージョン履歴を利用できます
• ツールバーの設定 - グループ化に対応したカスタマイズ可能なスラッシュコマンドとブロックアクションメニューを利用できます
• テンプレート - ブロック、プレースホルダー、空の状態に独自のテンプレートを設定できます
• グローバル化 - 多言語、RTL 言語、ロケールに基づくキーボードショートカットをサポートします
• カスタマイズ可能な UI - テーマ、CSS 変数、レスポンシブなサイズ調整、読み取り専用モード、プレースホルダーテキストを設定できます

クイックナビゲーションガイド

はじめに

Block Editor を初めて使用する場合や、セットアップ手順を確認する場合は、こちらから始めてください。

次の場合にお読みください：

• Node.js v18+ と Angular CLI v14+ をインストールする
• 新しい Angular アプリケーションをセットアップする
• Syncfusion Block Editor パッケージをインストールする
• CSS テーマとスタイルを設定する
• 最初の Block Editor コンポーネントインスタンスを作成する
• Angular アプリケーションを実行する

👉 はじめに

---

コアコンセプト

基本となるアーキテクチャとデータ構造について学びます。

次の場合にお読みください：

• ブロックタイプとその用途を理解する
• BlockModel と ContentModel について学ぶ
• ブロックの構成と関連付けを理解する
• ブロック内のさまざまなコンテンツタイプを理解する

👉 コアコンセプト

---

ブロック管理メソッド

エディターのコンテンツと構造をプログラムから操作します。

次の場合にお読みください：

• ブロックを追加、削除、または移動する
• ブロックのプロパティを更新する
• ブロックの数とデータを照会する
• 動的なドキュメント構造を構築する

👉 ブロック管理メソッド

---

選択とカーソルのメソッド

ユーザーの選択範囲とカーソル位置を制御します。

次の場合にお読みください：

• カーソル位置をプログラムから設定する
• テキストまたはブロックを選択する
• テキスト選択機能を実装する
• 範囲と選択状態を管理する
• ツールバーアクションをプログラムから実行する（executeToolbarAction）

👉 選択とカーソルのメソッド

---

ユーティリティメソッド

エディターのフォーカス、ツールバーの状態、印刷機能を制御します。

次の場合にお読みください：

• エディターにプログラムからフォーカスを設定する、またはフォーカスを外す
• ツールバー項目を動的に有効化または無効化する
• 条件付きのツールバーアクセスを実装する
• エディターのコンテンツを印刷する
• ユーザーの操作に応じてエディターの状態を管理する

👉 ユーティリティメソッド

---

設定プロパティ

エディターのスタイル、セキュリティ設定、ユーザー、ラベルを設定します。

次の場合に参照してください：

• テーマ設定用のカスタム CSS クラスを適用する
• ダークモードやカスタムテーマを実装する
• セキュリティのために HTML エンコーディングを設定する
• XSS 対策を設定する
• CSS フレームワーク（Bootstrap、Tailwind、Material）と統合する
• 複数ユーザーでの編集用にユーザーを設定する
• ユーザーのアバターと識別情報を追加する
• @メンション機能を実装する
• ラベル／タグシステム（#tags）を作成する
• プロジェクト管理用のラベルを設定する
• ユーザーやカテゴリ別にコンテンツを追跡する

👉 設定プロパティ

---

エディターメニュー

スラッシュコマンド、コンテキストメニュー、ツールバーを設定します。

次の場合に参照してください：

• スラッシュコマンドメニュー（/）をカスタマイズする
• コンテキストメニュー項目を追加する
• ブロックアクションメニューを設定する
• インラインツールバーを作成する
• カスタムメニュー項目を追加する

👉 エディターメニュー

---

イベントとコールバック

ユーザー操作とコンテンツの変更を処理します。

次の場合に参照してください：

• 自動保存機能を実装する
• コンテンツの変更を検証する
• ユーザー操作を追跡する
• 選択範囲の変更に対応する
• 貼り付け操作を処理する

👉 イベントとコールバック

---

書式設定とスタイル

テキストの書式とスタイルを適用します。

次の場合に参照してください：

• テキストを太字、斜体、下線付きにする
• 色や背景を適用する
• 高度なテキストスタイル（上付き文字、コードなど）を使用する
• ブロックの種類（見出し、引用など）を書式設定する
• スタイル付きコンテンツを作成する

👉 書式設定とスタイル

---

データ構造とリスト

リストブロックやテーブル構造を扱います。

次の場合に参照してください：

• 箇条書きや番号付きリストを作成する
• チェックボックス付きのチェックリストを追加する
• 行と列を持つテーブルを作成する
• インデントで階層化されたコンテンツを作成する
• トグル／折りたたみ可能なブロックを扱う

👉 データ構造とリスト

---

高度な機能

元に戻す／やり直し、ドラッグ＆ドロップ、コードブロック、テンプレートを確認します。

次の場合に参照してください：

• 元に戻す／やり直しのスタックサイズを設定する
• ドラッグ＆ドロップの動作をカスタマイズする
• 構文ハイライト付きのコードブロックを追加する
• カスタムテンプレートブロックを作成する
• 複雑なドキュメントレイアウトを構築する

👉 高度な機能

---

データのエクスポートとインポート

形式を変換し、コンテンツを永続化します。

次の場合に参照してください：

• エディターのコンテンツを JSON としてエクスポートする
• HTML または Markdown に変換する
• JSON または HTML ファイルからインポートする
• 外部の HTML コンテンツを解析する
• ドキュメントを印刷する
• サーバーと同期する

👉 データのエクスポートとインポート

---

共同編集

Yjs とバージョン管理を使用して、複数ユーザーによるリアルタイム編集を有効にします。

次の場合に参照してください：

• y-websocket を使用したリアルタイム共同編集を始める
• Yjs プロバイダー（y-websocket、y-webrtc、Hocuspocus、Liveblocks、PartyKit）を選択して設定する
• 共同編集用の WebSocket サーバーを設定する
• ユーザーのプレゼンス、リモートカーソル、テキスト選択範囲を表示する
• 現在のユーザーとアクティブな共同編集者を設定する
• スナップショットを使用してドキュメントのバージョン履歴を実装する
• ドキュメントのスナップショットを作成、復元、比較、エクスポート、インポートする
• バージョン履歴イベント（snapshotCreated、snapshotRestored）を処理する
• IndexedDB またはカスタムストレージバックエンドを使用してスナップショットを永続化する

👉 共同編集

---

キーボードショートカットとグローバル化

ショートカットと多言語サポートを設定します。

次の場合に参照してください：

• キーボードショートカットをカスタマイズする
• プラットフォーム固有のショートカットを設定する
• 国際化を実装する
• RTL 言語をサポートする
• 言語固有の設定を構成する

👉 キーボードショートカットとグローバル化

---

セキュリティと貼り付け処理

エディターを保護し、コンテンツの貼り付けを管理します。

次の場合に参照してください：

• HTML サニタイズを有効にする
• XSS 攻撃を防止する
• 貼り付け時のクリーンアップルールを設定する
• 許可するスタイルとタグを管理する
• 読み取り専用モードを実装する
• ユーザー入力を検証する

👉 セキュリティと貼り付け処理

---

外観とカスタマイズ

エディターの外観をスタイル設定およびカスタマイズします。

次の場合に参照してください：

• 幅や高さをカスタム設定する
• 組み込みテーマを適用する、またはカスタムテーマを定義する
• --color-sf-* CSS 変数を上書きする
• ブロックエディターの CSS クラス（.e-blockeditor、.e-active、.e-selected、.e-list-item、.e-dropdownbase、.e-table-element）と ID（#blockeditor_contextmenu、#blockeditor_code-ddl_popup）を対象にする
• 実行時に複数のテーマを切り替える
• フォントやタイポグラフィをカスタマイズする
• レスポンシブなエディターを作成する
• Syncfusion Theme Studio を使用して完全にカスタマイズされたテーマを生成する

👉 外観とカスタマイズ

---

クイックスタートの例

1. 依存関係をインストールする

npm install @syncfusion/ej2-angular-blockeditor

2. コンポーネントを作成する

import { Component } from '@angular/core';
import { BlockEditorModule } from '@syncfusion/ej2-angular-blockeditor';

@Component({
  selector: 'app-editor',
  template: `<ejs-blockeditor [height]="'500px'" />`,
  standalone: true,
  imports: [BlockEditorModule]
})
export class EditorComponent {}

3. CSS をインポートする

アプリケーションに合ったテーマパッケージをインストールします。この例では Material 3 を使用します。

npm install @syncfusion/ej2-material3-theme

次のスタイルシートを src/styles.css に追加します。

@import '../node_modules/@syncfusion/ej2-material3-theme/styles/blockeditor/index.css';

4. モジュール／ブートストラップに追加する

// app.config.ts
import { importProvidersFrom } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

export const appConfig = {
  providers: [
    importProvidersFrom(BrowserModule)
  ]
};

// OR in app.module.ts
@NgModule({
  imports: [BlockEditorModule]
})
export class AppModule {}

---

よく使われるパターン

パターン 1：ドキュメントの自動保存

@Component({
  selector: 'app-autosave-editor',
  template: `
    <div>
      <span>Status: {{ saveStatus }}</span>
      <ejs-blockeditor #editor (blockChanged)="onContentChange()"></ejs-blockeditor>
    </div>
  `,
  standalone: true,
  imports: [BlockEditorModule]
})
export class AutosaveEditorComponent {
  @ViewChild('editor') editor!: BlockEditorComponent;
  public saveStatus = 'Saved';
  private saveTimeout: any;

  public onContentChange(): void {
    this.saveStatus = 'Unsaved';
    clearTimeout(this.saveTimeout);
    
    this.saveTimeout = setTimeout(() => {
      const content = this.editor.getDataAsJson();
      this.saveToServer(content);
    }, 1000);
  }

  private saveToServer(content: any): void {
    // Save to backend
    this.saveStatus = 'Saved';
  }
}

パターン 2：書式付きドキュメントのエクスポート

@Component({
  selector: 'app-document-exporter',
  template: `
    <div>
      <button (click)="exportJson()">Export JSON</button>
      <button (click)="exportHtml()">Export HTML</button>
      <button (click)="exportMarkdown()">Export Markdown</button>
      <ejs-blockeditor #editor></ejs-blockeditor>
    </div>
  `,
  standalone: true,
  imports: [BlockEditorModule]
})
export class DocumentExporterComponent {
  @ViewChild('editor') editor!: BlockEditorComponent;

  public exportJson(): void {
    const data = this.editor.getDataAsJson();
    this.downloadFile(JSON.stringify(data, null, 2), 'document.json', 'application/json');
  }

  public exportHtml(): void {
    const html = this.editor.getDataAsHtml();
    this.downloadFile(html, 'document.html', 'text/html');
  }

  public exportMarkdown(): void {
    // Convert to markdown format
    const data = this.editor.getDataAsJson();
    const markdown = this.convertToMarkdown(data);
    this.downloadFile(markdown, 'document.md', 'text/markdown');
  }

  private downloadFile(content: string, filename: string, type: string): void {
    const blob = new Blob([content], { type });
    const url = URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = url;
    link.download = filename;
    link.click();
  }

  private convertToMarkdown(blocks: any[]): string {
    // Implementation details in Data Export and Import reference
    return '';
  }
}

---

トラブルシューティングガイド

問題：エディターが表示されない

解決策：CSS が main.ts またはグローバルスタイルでインポートされていることを確認してください

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-splitbuttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-blockeditor/styles/material3.css';

問題：コンテンツが保存されない

解決策：getDataAsJson() メソッドを使用してコンテンツを取得してください

const content = this.blockEditor.getDataAsJson();

問題：イベントが発生しない

解決策：コンポーネントがスタンドアロンであり、インポートが正しいことを確認してください

@Component({
  standalone: true,
  imports: [BlockEditorModule]
})

---