拡張の仕組みと設計方針

管理画面の JavaScript 拡張が、なぜ3つの仕組みに分かれているのか。どれを選べばよいのか。なぜ実験的機能として提供しているのか。手順ではなく、判断のための背景をまとめたページです。

すぐに拡張を書きたい場合は はじめてのプラグイン から読んでください。

3つの仕組みと、その選び方

管理画面の拡張は「イベント」「UI の差し込み」「機能の登録」の3つに分かれています。同じことを別の方法でもできてしまうと、拡張が壊れやすくなるため、役割で明確に分けています。

たとえば「独自のユニットを追加し、そのツールバーにボタンを置き、保存前に検査する」という拡張は、3つすべてを使います。1つの巨大な API ではなく3つに分けているのは、どの仕組みが何を保証するかを明確にするためです。イベントは「操作の前後に割り込める」こと、UI の差し込みは「決められた位置に UI を置ける」こと、機能の登録は「選べる種類を増やせる」ことを担当します。

なぜ「処理を止められる」イベントと通知だけのイベントを分けているのか

操作の直前に呼ばれるイベント（ゲート）だけ、操作を中止したり値を書き換えたりできます。それ以外は通知だけです。

ゲートのハンドラは (payload, gate) を受け取り、gate.cancel() を呼ぶと操作を中止します。通知のハンドラは payload だけを受け取るため、中止する手段がそもそもありません。どちらのイベントかは イベント一覧 の種別で決まります。 名前の末尾が .before のものはほとんどがゲートですが、名前だけで判断せず、一覧で確認してください。

中止を return false ではなく gate.cancel() という明示的な呼び出しにしているのは、別の目的で書いた return false; が意図せず操作を中止してしまう事故を避けるためです。

通知イベントで値を返しても無視されます（TypeScript を使っている場合は型エラーになります）。

なぜ従来のイベントも発火し続けるのか

acms.media-updated などの従来の DOM イベントと ACMS.addListener は、対応する新しいイベントがあるものについて、新しいイベントと同時に発火します。

• 既存のテーマ・プラグインを壊さないため。 従来のイベントを止めると、すでに公開されているサイトのカスタマイズが動かなくなります。
• 新しい仕組みでしかできないことがあるため。 中止・値の書き換え・非同期の待機は、従来の方式では表現できません。新しいイベントを追加しないと、これらの拡張が書けません。

そのため「置き換え」ではなく「並行して提供する」形にしています。どちらを使うべきかの判断は次のとおりです。

• これから書くもの → 新しいイベント（ACMS.events）
• すでに動いているカスタマイズ → 書き換え不要。そのままで問題ありません

メニューへの表示を設定に任せている理由

オリジナルブロック・オリジナルユニットは、登録しただけではメニューに現れません。表示するかどうかは、管理者が編集設定で選びます。

これは、「機能を提供すること」と「その機能を使わせること」を分けているためです。プラグインを入れた時点でメニューが増えると、運用者が意図しない選択肢が現れます。ブログごとに使う・使わないを選べる形にすることで、同じプラグインを複数のサイト・複数のブログで使い回せます。

そのぶん「登録したのに出てこない」という詰まりが起きやすいため、各ガイドでは設定手順まで含めて説明しています。

なぜ実験的機能として提供しているのか

管理画面の拡張の仕組みは、Ver. 3.2 の間は実験的機能として提供し、Ver. 3.3 で正式に提供する予定です。

用意した拡張ポイント（イベント・差し込み位置・登録できる種類）が実際の制作で必要とされる粒度になっているかは、実際に使われた結果を見て判断する必要があります。そのため、次のような見直しが起こりえます。

• 足りないタイミングのイベントを追加する
• 用途が重複しているイベントを整理する（名前の変更を含む）
• 差し込み位置で受け取れる値を増やす・変える

このドキュメントに掲載しているイベント名・差し込み位置・登録名を公開仕様として扱います。

管理画面に追加した独自の JavaScript・CSS は、バージョンアップ後の動作を保証しません。これらを原因とする不具合は、サポートの対象外です。

一方で、次のものは実験的機能の対象外です。従来どおりの仕様として提供しています。

• 従来の DOM イベントと ACMS.addListener / ACMS.dispatchEvent
• PHP 側のフック処理・テンプレート挿入・アセット API・ユニットの登録
• 管理画面カスタム要素
• 管理画面の CSS クラス名

関連ページ

• 管理画面の JavaScript 拡張
• イベント（ACMS.events）
• UI の差し込み（Slot / Fill）
• 機能の登録（レジストリ）