初期化の完了を待つ

ACMS.Ready() は従来どおり使えます。Ver. 3.2.29 からは、初期化が完了しているかどうかを直接確認することもできます（実験的機能。Ver. 3.2 の間は実験的機能として提供し、Ver. 3.3 で正式に提供する予定です）。

if (ACMS.readyStates.ready === 'complete') {
  console.log('すでに初期化が完了しています');
} else {
  ACMS.events.on('acms.state.ready', () => {
    console.log('初期化が完了しました');
  });
}

管理画面のカスタマイズについて

管理画面の動作を変えたい場合は、組み込み JS ではなく 管理画面の JavaScript 拡張（実験的機能）を使います。

イベントハンドラを設定する事で、ある特定のJavaScriptのイベント（クリックイベントなど）が発生した時に処理を挟み込めます。a-blog cmsでは組み込みJSが実行したイベントの後に処理を実行できるようにするため、いくつかのイベントハンドラを用意しています。

a-blog cms が用意しているイベントは ACMS.addListener を利用することでイベントに対してリスナーを登録することができます。

Ver. 3.2.29 以降は、新しいイベントの仕組み ACMS.events が使えます。ACMS.addListener と ACMS.dispatchEvent について、これまでのコードはそのまま動作し、既存のイベントも引き続き発火します。新しく書くコードでは ACMS.events を使うことをおすすめします。

ACMS.events は、イベントが発火した後に登録したリスナーには、過去の発火を届けません（ACMS.addListener は届けます）。そのため、起動時のイベント（acmsReady・acmsAdminReady）は ACMS.events.on ではなく、ACMS.ready()・ACMS.adminReady() を使ってください。

ACMS.addListener('eventName', function (event) {
  console.log(event);
});

また、event オブジェクト の detail プロパティにアクセスすることでイベント独自のカスタムデータを参照することができます。

ACMS.addListener('eventName', function (event) {
  console.log(event.detail); // or console.log(event.obj)
});

// acmsReady（Ver. 3.2.29 以降）
ACMS.ready(() => {
  ACMS.Config.postIncludeEffect = 'fade';
});

// acmsAdminReady（Ver. 3.2.29 以降）
ACMS.adminReady(() => {
  // 管理画面の初期化後に行う処理
});

// acmsDispatch（Ver. 3.2.29 以降）
ACMS.events.on('acms.dispatch.after', () => {
  $('[href*=bxslider]').remove();
});

// acmsAddCustomFieldGroup（Ver. 3.2.29 以降）
ACMS.events.on('field-group.add.after', ({ element }) => {
  console.log(element); // カスタムフィールドグループの DOM
});

// acmsValidateFailed（Ver. 3.2.29 以降）
ACMS.events.on('validator.submit-fail.after', ({ results, form }) => {
  console.log(results); // バリデーション結果
});

// acmsFormInvalid / acmsFormValid / acmsFormValidated も同じ形
ACMS.events.on('validator.valid.after', ({ results, element }) => {
  console.log(results);
});

ACMS.events.on は、リスナーの登録を解除するための関数を返します。

acms.dispatch.after は、ACMS.Dispatch() が実行されるたびに（ダイアログやインライン編集で動的にコンテンツが追加される都度）発火します。

acmsFormInvalid

「組み込みJSによるバリデーション」に失敗したタイミングで発生するイベントです。

ACMS.addListener("acmsFormInvalid", function(event) {
  console.log(event.detail.results); // バリデーション結果を取得できます。
});

acmsFormValid

「組み込みJSによるバリデーション」に成功したタイミングで発生するイベントです。

ACMS.addListener("acmsFormValid", function(event) {
  console.log(event.detail.results); // バリデーション結果を取得できます。
});

acmsFormValidated

「組み込みJSによるバリデーション」によるバリデーションが行われたタイミングで発生するイベントです。

ACMS.addListener("acmsFormValidated", function(event) {
  console.log(event.detail.results); // バリデーション結果を取得できます。
});

acmsLazyLoaded

組み込みJSの 「遅延読み込み」により要素の遅延読み込みが完了したタイミングで発火するイベントです。

ACMS.addListener("acmsLazyLoaded", function() {

});

管理画面向けのイベント（実験的機能）

Ver. 3.2.29 から、管理画面の操作に割り込むための新しいイベントの仕組み（ACMS.events）が加わりました。この機能は、Ver. 3.2 の間は実験的機能として提供し、Ver. 3.3 で正式に提供する予定です。従来のイベントと同時に発火するため、既存の購読はそのまま動作します。

新しい仕組みでは、次のことができます。

• 操作の中止（確認ダイアログを出して、キャンセルされたら保存しない）
• 送信内容の書き換え
• 非同期処理の待機（外部 API に問い合わせてから続行する）

従来のイベントとの対応表は イベント一覧 にあります。

ACMS.addListener について

ACMS.addListener は今後も動作します（撤廃しません）。新しく書く場合は ACMS.events.on を使ってください。詳細は イベント（ACMS.events） を参照してください。

アセット API で読み込む（Ver. 3.2.29 以降）

Ver. 3.2.29 からは、JS / CSS をハンドル（名前）と依存関係で宣言して読み込めます。テンプレートに直接 <script> を書く代わりに使うと、読み込み順が依存関係から自動的に決まります。

// extension/acms/Hook.php
public function afterBuild(&$res)
{
    \Acms\Services\Facades\Asset::script('my-theme-script', '/themes/my-theme/js/main.js', [
        'position' => 'body_end',
    ]);
}

詳細は アセット API（JS / CSS の登録） を参照してください。

a-blog cms は、サイトの表示側と管理画面の両方を JavaScript でカスタマイズできます。目的によって使う仕組みが違うので、まずどれに当てはまるかを選んでください。

1. サイトの表示側に JavaScript を足したい

テーマに独自の JavaScript を読み込んだり、a-blog cms が用意している組み込み JS（バリデーション・遅延読み込み・地図など）の設定を変えたい場合です。

• 組み込みJSについて — 組み込み JS の有効化と設定方法
• 組み込みJSのイベントハンドラ — 組み込み JS の処理の前後に自分の処理を挟む
• 任意のJavaScriptを使用する — テーマに独自の JS ファイルを読み込む
• Google Translate APIを使って翻訳ボタンを作る — 実装例
• リファレンス: 組み込みJS

2. 管理画面の動作を変えたい・UI を足したい

「アップロードする前に画像をチェックしたい」「エントリー一覧に独自のボタンを足したい」「独自のブロックやユニットを追加したい」といったカスタマイズです。プラグインの形で JavaScript を書きます。

• 管理画面の JavaScript 拡張 — 概要と、できることの一覧
• はじめてのプラグイン — まず1つ動かす

JavaScript が書ければ始められます。ビルド環境（webpack や Vite）は必要ありません。

3. 管理画面と同じ見た目の画面を作りたい

プラグインの設定画面や独自の管理ツールを、a-blog cms の管理画面と同じデザインで作りたい場合です。管理画面で使っている CSS フレームワークと React コンポーネントを npm パッケージとして公開しています。

• npm パッケージ（@ablogcms/*） — 公開しているパッケージの一覧
• 管理画面と同じ見た目で画面を作る — CSS だけで作る方法と、コンポーネントを使う方法
• リファレンス: スタイルガイド

PHP 側のカスタマイズを探している場合

JavaScript ではなく PHP で処理を挟みたい場合は、次のページを参照してください。

• フック処理 — 保存や表示の前後に PHP の処理を挟む
• プラグイン開発 — 拡張アプリの作り方
• アセット API（JS / CSS の登録） — JS / CSS ファイルを管理画面やサイトに読み込む

管理画面フロントエンドの一部を npm パッケージとして公開しています。型補完を受けながらプラグインを開発したり、管理画面と同じ UI コンポーネントを使って独自の画面を作れます。

npm パッケージを使わなくてもプラグインは書けます。 window.ACMS 経由のグローバル API だけで、イベントの購読・UI の差し込み・機能の登録はすべて行えます（管理画面の JavaScript 拡張）。

対応バージョン: Ver. 3.2.29 以降（パッケージは、同じバージョン番号の a-blog cms 向けに npm で公開しています）

公開ポリシー

• このページで説明しているものが公開 API です。 それ以外のパッケージ・サブパスも利用できますが（保証対象外）、告知なく変更されることがあります。
• バージョンは a-blog cms 本体と一致します。 利用している CMS と同じバージョンを指定してください。
• ESM のみを配布しています。 require() では読み込めません。バンドラ、または ESM に対応した Node.js で利用してください。
• 公開しているサブパス以外を import しないでください。内部のパスは予告なく変わります。

npm install @ablogcms/types@3.2.37

上の例は Ver. 3.2.37 の場合です。^3.2.37 のような範囲指定ではなく、利用している CMS と同じバージョンを固定することを推奨します。

公開 API

使い方をドキュメントで説明しているパッケージです。

保証対象外のパッケージ

管理画面が内部で使っているパッケージです。利用は自由ですが、個別の使い方は説明しておらず、告知なく変更されることがあります。バージョンを固定して利用してください。

これらの機能をサイト表示側で使う場合は、npm ではなく ACMS.Library 経由の呼び出し（組み込み JS）を使ってください。そちらは従来からの公開仕様です。

公開 API の使い方

url と validator は、上の表のリンク先（組み込み JS のドキュメント）で、同じ機能の使い方を説明しています。npm パッケージでも、引数と戻り値は同じです。以下は、それ以外のパッケージの使い方です。

fetch-client

CSRF トークン（window.csrfToken）と X-Requested-With ヘッダーを付けて、fetch で通信します。window.csrfToken は、組み込み JS が、ページの <meta name="csrf-token"> から設定します。組み込み JS を読み込んでいないページで使う場合は、自分で設定してください。ステータスが成功以外のときは FetchError を投げます。

import { fetchClient, isFetchError } from '@ablogcms/fetch-client';

try {
  const { data, status } = await fetchClient.get(location.pathname, { responseType: 'text' });
  console.log(status, data.length);
} catch (error) {
  if (isFetchError(error)) {
    console.log(error.status, error.statusText);
  }
}

fetchClient.post(url, body, config) の body には、FormData・URLSearchParams・オブジェクト（JSON として送信）を渡せます。ファイルのアップロードで進捗が必要な場合は、@ablogcms/fetch-client/xhr-upload の xhrUpload(url, formData, { onUploadProgress }) を使います。

dom-ready

DOM の構築が終わってからコールバックを実行します。すでに終わっていれば、その場で実行します。

import domReady from '@ablogcms/dom-ready';

domReady(() => {
  console.log('DOM の準備ができました');
});

deprecated

デバッグモードのときだけ、コンソールに非推奨の警告を出します。本番では何も出しません。

import deprecated from '@ablogcms/deprecated';

deprecated('旧オプション old-option', {
  since: '2026.01.01',
  version: '3.2.0',
  alternative: 'new-option',
});

a11y

スクリーンリーダーにメッセージを読み上げさせます。第2引数は 'polite'（既定）か 'assertive' です。

import { announce } from '@ablogcms/a11y';

announce('保存しました');
announce('保存に失敗しました', 'assertive');

i18n

ACMS.i18n と同じ翻訳を引きます。プラグインが ctx.i18n.addResources() で登録した翻訳は、プラグイン名:キー の形で引きます（機能の登録（レジストリ））。

import { t, getLanguage } from '@ablogcms/i18n';

console.log(getLanguage());
console.log(t('my-plugin:greeting'));

コンポーネントの一覧と実例

管理画面の UI コンポーネントは Storybook で確認できます。実際の表示、指定できる props、バリエーションが載っています。

→ Storybook

ACMS グローバルの型を使う

{
  "compilerOptions": {
    "types": ["@ablogcms/types/acms"]
  }
}

使う機能の型は、対応するパッケージの ./acms を import した分だけ厳密になります（型だけを読み込むため import type {} from と書きます）。

import type {} from '@ablogcms/types/acms';
import type {} from '@ablogcms/events/acms';
import type {} from '@ablogcms/url/acms';

詳細は 開発環境と型定義 を参照してください。

管理画面と同じ見た目を使う

npm install @ablogcms/acms.css@3.2.37

import '@ablogcms/acms.css';

クラス名の一覧は スタイルガイド を参照してください。管理画面のテンプレートの中に差し込む場合は、CSS はすでに読み込まれているためインストールは不要です。

組み込み JS との対応

サイト表示側の機能は、従来どおり組み込み JS として提供しています。テーマの書き方は変わりません。 参考として、実装が入っているパッケージを示します。

変更履歴