カスタムCKEditor 5プラグインの追加

Liferay DXP 2026.Q1+

Editor Config Contributorクライアント拡張機能を使用すると、Liferayのエディターに独自のCKEditor 5プラグインを追加できます。この例では、タイムスタンプツールバーボタンを追加するサンプルクライアント拡張機能 を使用します。ボタンをクリックすると、カーソル位置に現在の日時が挿入されます。このクライアント拡張機能の種類について詳しくは、 エディター設定コントリビュータークライアント拡張機能の使用 を参照してください。

前提条件

Editor Config Contributorクライアント拡張機能を使用するには、以下の手順に従ってください。

1. サポートされているバージョンの Java をインストールしてください。

   注記

   サポートされているJDK、データベース、および環境については、互換性マトリックスをご確認ください。推奨される JVM 設定については、 JVM 構成 を参照してください。

2. サンプルワークスペースをダウンロードして解凍してください。

   curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip
   

   unzip com.liferay.sample.workspace-latest.zip
   

これで、サンプルのエディター設定コントリビュータークライアント拡張機能を調べたり、変更したりできるようになりました。

クライアント拡張機能を検査および変更する

エディター設定コントリビューターの例は、サンプルワークスペースの client-extensions/liferay-sample-editor-config-contributor-3/ フォルダーにあります。その client-extension.yaml ファイルには、以下の詳細が定義されています。

assemble:
    -   from: build
        into: static
liferay-sample-editor-config-contributor-3:
    editorConfigKeys:
        -   sampleReactCKEditor5ClassicEditor
    name: Liferay Sample Editor Config Contributor CKEditor 5 Timestamp
    type: editorConfigContributor
    url: index.js

クライアント拡張機能は、その ID (liferay-sample-editor-config-contributor-3)、そのタイプ (editorConfigContributor)、および適用対象のエディター (editorConfigKeys ) を宣言します。その url プロパティは、ビルドによって生成されるバンドルされた JavaScript ファイルである index.jsを指しています。 assemble ブロックは、 build/ フォルダ全体を、 index.js ファイルを含む静的リソースとしてクライアント拡張機能の .zip ファイルにパッケージ化します。詳細については、 エディター設定コントリビューター YAML 設定リファレンス を参照してください。

Liferay DXP のリッチテキストフィールド（Web コンテンツの Content フィールドを含む）にプラグインを適用するには、キーリストに rich_text を追加します。

editorConfigKeys:
    -   rich_text
    -   sampleReactCKEditor5ClassicEditor

プラグインコードを調べる

プラグインのソースは src/index.ts にあります。これは 2 つの部分から構成されています。 タイムスタンプ プラグイン クラスと、プラグインをエディタの設定に接続するエディタ トランスフォーマーです。

import {Plugin} from '@ckeditor/ckeditor5-core/dist/index.js';
import {ButtonView} from '@ckeditor/ckeditor5-ui/dist/index.js';
import {
	EditorConfigTransformer,
	EditorTransformer,
} from '@liferay/js-api/editor';

const TIMESTAMP_ICON =
	'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M10 1a9 9 0 1 0 9 9 9 9 0 0 0-9-9zm0 16a7 7 0 1 1 7-7 7 7 0 0 1-7 7z"/><path d="M10.5 5h-1v5.5l3.7 3.7.7-.7-3.4-3.4z"/></svg>';

class Timestamp extends Plugin {
	init() {
		const editor = this.editor;

		editor.ui.componentFactory.add('timestamp', () => {
			const button = new ButtonView();

			button.set({
				icon: TIMESTAMP_ICON,
				label: 'Timestamp',
				tooltip: true,
			});

			button.on('execute', () => {
				const now = new Date();

				editor.model.change((writer) => {
					editor.model.insertContent(
						writer.createText(`Current time: ${now.toString()} `)
					);
				});
			});

			return button;
		});
	}
}

タイムスタンプ クラスは、CKEditor 5 の プラグイン クラスを拡張します。 init()では、 timestamp から editor.ui.componentFactory.add() まで、コンポーネントが登録されます。このコンポーネントは、インライン SVG 時計アイコン、ラベル タイムスタンプ、および tooltip: trueを持つ ButtonView です。そのため、ラベルはホバー時にツールチップとして表示されます。ボタンをクリックすると、その 実行 ハンドラが、 現在の時刻: <date> を、 editor.model.change() および writer.createText() を介して現在の選択範囲に挿入します。

コンポーネントを登録するとボタンが使用可能になりますが、実際に表示されるかどうかはエディタの設定によって決まります。ファイルの残りの部分でその処理が行われます。

const editorConfigTransformer: EditorConfigTransformer<any> = (config) => {
	const toolbar = config.toolbar as any;
	const existingItems = Array.isArray(toolbar)
		? toolbar
		: toolbar?.items ?? [];

	return {
		...config,
		extraPlugins: [...(config.extraPlugins ?? []), Timestamp],
		toolbar: {
			items: [...existingItems, 'timestamp'],
		},
	};
};

const editorTransformer: EditorTransformer<any> = {
	editorConfigTransformer,
};

export default editorTransformer;

トランスフォーマーはエディターの設定を受け取り、変更されたコピーを返します。これは Timestamp クラスを extraPluginsに追加し、プラグインをエディタにロードし、 'timestamp' アイテムをツールバーに追加してボタンを表示します。 config.toolbar は、アイテム名の単純な配列または items 配列を持つオブジェクトになる可能性があるため、トランスフォーマーは見つかった形状を読み取り、結果を {items: [...existingItems, 'timestamp']} に正規化します。ファイルのデフォルトのエクスポートは、設定トランスフォーマーを含む EditorTransformer オブジェクトです。Liferay は、クライアント拡張機能の editorConfigKeys に一致するエディターにそれを適用します。

依存関係とビルド設定を確認する

カスタムプラグインはCKEditorのコードをインポートするため、他のクライアント拡張機能タイプよりも、その依存関係とビルド設定が重要になります。サンプルの package.json を開きます。

{
	"dependencies": {
		"@ckeditor/ckeditor5-core": "46.0.3",
		"@ckeditor/ckeditor5-ui": "46.0.3",
		"@liferay/js-api": "0.8.0"
	},
	"description": "Liferay Sample Editor Config Contributor CKEditor 5 Timestamp",
	"devDependencies": {
		"serve": "^14.2.0",
		"typescript": "^5.0.4"
	},
	"main": "./src/index.ts",
	"name": "@liferay/liferay-sample-editor-config-contributor-3",
	"scripts": {
		"build": "esbuild src/index.ts --outdir=build --bundle --format=esm --external:@ckeditor/*",
		"start": "PORT=3002 serve --cors",
		"watch": "tsc --watch"
	},
	"type": "module",
	"version": "0.0.0"
}

@ckeditor/ckeditor5-core および @ckeditor/ckeditor5-ui パッケージは、プラグインがインポートする Plugin および ButtonView クラスを提供し、両方とも 46.0.3 に固定されています。あなたのプロジェクトでは、これらのパッケージはビルド時にTypeScriptの型チェックのみを提供します。実行時には、同じインポートは、Liferay DXPに同梱されているCKEditor 5の単一コピーに解決されます。 @liferay/js-api パッケージは、トランスフォーマー契約を記述する EditorConfigTransformer および EditorTransformer 型を提供します。

ビルド スクリプトによって、その分割が機能します。これは、 src/index.ts を esbuild と共に build/ フォルダーに ES モジュールとしてバンドルし、 assemble ブロックと url: index.js プロパティが期待するものと一致します。キーフラグは --external:@ckeditor/*です。単一のワイルドカードは、すべての @ckeditor パッケージを外部としてマークするため、esbuild は CKEditor のコードをバンドルにコピーする代わりに、これらの import ステートメントを出力に保持します。デプロイされたバンドルには、プラグインのコードのみが含まれています。

ワイルドカードが重要なのは、すべてのプラグインがLiferay DXPに同梱されているCKEditor 5のコピーに対して実行される必要があるためです。 @ckeditor パッケージをバンドルすると、クライアント拡張機能が CKEditor の 2 つ目のコピーをページにロードし、エディタが壊れてしまいます。ワイルドカードはコードに合わせて拡張されます。プラグインが別の @ckeditor パッケージをインポートするように拡張された場合でも、除外によって既にカバーされます。

開発依存関係はローカル作業をサポートします。 watch スクリプトは tsc --watch を実行して、esbuild が型チェックなしで TypeScript をバンドルしているため、編集時にプラグインの型チェックを行います。 start スクリプトは、 serve を CORS を有効にしてポート 3002 で実行し、拡張機能のファイルをローカルで提供します。サンプルワークスペースには esbuild 自体が含まれているため、ワークスペース外のスタンドアロンプロジェクトでは、それを開発依存関係として追加する必要があります。

クライアント拡張機能をデプロイする

Liferay DXP の新しいインスタンスを起動するには、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/dxp:2026.q1.9-lts

http://localhost:8080 に、メールアドレス test@liferay.com とパスワード test を使用して Liferay にサインインします。プロンプトが表示されたら、パスワードを learn に変更してください。

Liferayが起動したら、新しいターミナルを開き、 client-extensions/liferay-sample-editor-config-contributor-3/ フォルダから次のコマンドを実行します。

../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)

これによりバンドルがビルドされ、クライアント拡張機能 .zip ファイルが Liferay の deploy/ フォルダーにデプロイされます。 Liferay SaaS にデプロイするには、 エディター設定コントリビュータークライアント拡張機能の使用 を参照してください。

Liferayインスタンスのコンソールで、デプロイが成功したことを確認してください。

STARTED liferaysampleeditorconfigcontributor3_...

タイムスタンプボタンをテストする

クライアント拡張機能がデプロイされ、その rich_text が editorConfigKeysに含まれている場合、プラグインは Web コンテンツのリッチ テキスト フィールドに適用されます。

1. サイトメニュー (を開き、 コンテンツ & データを展開し、 Web コンテンツ をクリックします。

2. 新規 をクリックし、 基本ウェブコンテンツ を選択します。

3. コンテンツ フィールドのツールバーにある タイムスタンプ をクリックします。

   

   これは、カーソルの位置に現在の日時を次の形式で挿入します。 現在時刻: <date>。このボタンは時計のアイコンを使用しており、カーソルを合わせるとタイムスタンプのツールチップが表示されます。

   

Editor Config Contributorクライアント拡張機能を使用して、独自のCKEditor 5プラグインを正常に追加しました。

関連トピック

• エディター設定コントリビュータークライアント拡張機能の使用
• CKEditor 5 にカスタムスタイルを追加する
• エディター設定コントリビューターYAML設定リファレンス
• CKEditor 5へのアップグレード
• クライアント拡張機能の操作