管理画面と同じ見た目で画面を作る

プラグインの設定画面や独自の管理ツールを、a-blog cms の管理画面と同じデザインで作ります。方法は2つあり、必要に応じて使い分けます。

対応バージョン: CSS クラスを使う方法は制限なし。React コンポーネントを管理画面と共有する方法は Ver. 3.2.38 以降

CSS クラスを使う

管理画面のスタイルは CSS フレームワークとして提供しています。テンプレートに管理画面と同じクラス名を書くだけで、同じ見た目になります。フォームのクラスは、acms-admin-form を付けた要素の内側で有効になります。

<div class="acms-admin-form">
  <label for="api-key" class="acms-admin-form-label">API キー</label>
  <input type="text" id="api-key" name="api_key" class="acms-admin-form-width-full">
  <button type="submit" class="acms-admin-btn acms-admin-btn-primary">保存</button>
</div>

• クラス名の一覧 → スタイルガイド
• 管理画面の中に設定画面を差し込む方法 → テンプレート挿入

管理画面の中に差し込む場合、CSS は管理画面側で読み込まれているため、追加の読み込みは不要です。

管理画面の外で使う

独自のツール画面など、管理画面のテンプレートの外で使う場合は、CSS を npm から取得できます。

npm install @ablogcms/acms.css@3.2.37

import '@ablogcms/acms.css';

バージョンは、利用している a-blog cms と同じものを指定してください（3.2.37 は例です）。

React コンポーネントを使う

管理画面で使っている React コンポーネントを npm パッケージとして公開しています。

npm install @ablogcms/components@3.2.37

バージョンは、利用している a-blog cms と同じものを指定してください（3.2.37 は例です）。

次の例は、管理画面に差し込んだテンプレートの <div id="acme-settings"></div> の中に、設定フォームを描画します。

import { createRoot } from 'react-dom/client';
import { Button } from '@ablogcms/components/button';
import { Field, FieldControl, FieldLabel } from '@ablogcms/components/field';
import { Input } from '@ablogcms/components/input';

function SettingsForm() {
  return (
    <form className="acms-admin-form">
      <Field>
        <FieldLabel>API キー</FieldLabel>
        <FieldControl>
          <Input name="api_key" width="full" />
        </FieldControl>
      </Field>
      <Button type="submit" variant="primary">保存</Button>
    </form>
  );
}

ACMS.adminReady(() => {
  const container = document.getElementById('acme-settings');
  if (container !== null) {
    createRoot(container).render(<SettingsForm />);
  }
});

コンポーネントのスタイルは、acms-admin-form を付けた要素の内側で有効になります。上の例のように、フォームを acms-admin-form で囲んでください。

実際の表示と指定できる値を確認する

コンポーネントの一覧・実際の表示・指定できる props は Storybook で確認できます。

• Storybook（コンポーネント一覧）
• よく使うもの: Button / Field / Input / Table

React と管理画面のコンポーネントを同梱しないでください

管理画面の中で動かす場合、React と react-dom はプラグイン側でバンドルしないでください。管理画面が読み込んでいる React を使います。ACMS.Library.React と ACMS.Library.ReactDomClient から取得できます。

ACMS.adminReady(() => {
  const { createElement, useState } = ACMS.Library.React;
  const { createRoot } = ACMS.Library.ReactDomClient;

  function Counter() {
    const [count, setCount] = useState(0);
    return createElement(
      'button',
      { type: 'button', className: 'acms-admin-btn', onClick: () => setCount(count + 1) },
      `クリック数: ${count}`
    );
  }

  const container = document.getElementById('acme-counter');
  if (container !== null) {
    createRoot(container).render(createElement(Counter));
  }
});

@ablogcms/components のコンポーネントも、同梱せずに管理画面のものを共有できます（ACMS.Library.components.button のような形で参照できます）。共有されていないコンポーネント（dataview / date-picker / time-picker / syntax-highlight / rich-select / select / device-mode / icon-picker）は、プラグイン側に同梱されます。ビルド設定で React とコンポーネントを外部依存にする方法は 開発環境と型定義 を参照してください。

設定値を JavaScript に渡す

PHP 側の設定値は ctx.config から読み取れます。PHP で jsModule() に、プラグイン名をキャメルケースにしたキーで渡します（acme-tools のプラグインなら acmeTools）。

jsModule('acmeTools', ['apiEndpoint' => '/api/acme/']);

ACMS.adminReady(() => {
  ACMS.plugins.register('acme-tools', {
    setup(ctx) {
      console.log(ctx.config.apiEndpoint);
    },
  });
});

値は配列（連想配列）で渡します。数値や真偽値も、JavaScript 側では文字列として届きます。

API キーなどの秘密の情報は渡さないでください（ブラウザから閲覧できます）。制約の詳細は プラグイン API を参照してください。

関連ページ

• npm パッケージ（@ablogcms/*）
• スタイルガイド
• 開発環境と型定義

変更履歴