npm パッケージ（@ablogcms/*）

管理画面フロントエンドの一部を 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 として提供しています。テーマの書き方は変わりません。 参考として、実装が入っているパッケージを示します。

変更履歴