開発環境と型定義

プラグインは2つの書き方から選べます。どちらでも同じことができます（型補完を除く）。

ビルドなしで書く

JS ファイルを1つ作り、<script type="module"> として読み込みます。

// /extension/acms/assets/my-plugin.js
ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    ctx.events.on('media.upload.before', (event) => event);
  },
});

\Acms\Services\Facades\Asset::script('my-plugin', '/extension/acms/assets/my-plugin.js', [
    'position' => 'body_end',
    'attrs' => ['type' => 'module'],
]);

React が必要な場面（値を受け取る UI の差し込みなど）でも、ACMS.Library.React.createElement を使えばビルドは不要です。

ctx.ui.fill('preview.actions', function MyButton() {
  return ACMS.Library.React.createElement('button', { type: 'button', className: 'acms-admin-btn' }, '送信');
});

ビルドありで書く

インストール

npm install @ablogcms/types@3.2.37

パッケージのバージョンは、利用している a-blog cms と同じバージョンを指定してください（上の例は Ver. 3.2.37 の場合）。パッケージは CMS 本体と同じバージョン番号で公開しており、Ver. 3.2.29 以降のものを npm から入手できます。

用途に応じて追加します。

一覧は npm パッケージ を参照してください。

型定義を有効にする

window.ACMS の型を有効にするには、tsconfig.json に追加します。

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

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

import type {} from '@ablogcms/types/acms';
import type {} from '@ablogcms/events/acms'; // ACMS.events の型が付く
import type {} from '@ablogcms/url/acms'; // ACMS.Library.acmsLink の型が付く

ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    ctx.events.on('media.upload.before', (payload) => {
      console.log(payload.files);
    });
  },
});

イベントの型を自分で宣言する

イベントが受け取る値の型は、AcmsEventMap に宣言したものだけが付きます。a-blog cms 本体のイベントの型は npm パッケージには含まれないため、使うイベントは自分のプロジェクトで宣言します。独自のイベントを発火する場合も同じ方法で宣言します。

import type { AcmsGateEvent, AcmsNotifyEvent } from '@ablogcms/events';

declare module '@ablogcms/events' {
  interface AcmsEventMap {
    'media.upload.before': AcmsGateEvent<{ files: File[] }>;
    'my-plugin.sync.success': AcmsNotifyEvent<{ count: number }>;
  }
}

宣言しなくてもイベントは使えます（値の型が緩くなるだけです）。

JSX で書く

import { withFillProps } from '@ablogcms/plugins';

type AltFillProps = {
  item: { media_title: string };
  setAlt: (value: string) => void;
};

ACMS.plugins.register('my-plugin', {
  setup(ctx) {
    ctx.ui.fill(
      'media.edit-modal.field.alt',
      withFillProps<AltFillProps>(({ item, setAlt }) => (
        <button type="button" className="acms-admin-btn" onClick={() => setAlt(item.media_title)}>
          タイトルを入れる
        </button>
      ))
    );
  },
});

React を同梱しないでください

React に依存するパッケージは react を peerDependencies として要求します。バンドラの設定で React を外部依存にし、管理画面が公開している ACMS.Library を参照させてください。 react/jsx-runtime も外部依存にします（外し忘れると、react/jsx-runtime だけがバンドルに入ります）。

// webpack.config.js
module.exports = {
  mode: 'production',
  entry: './src/plugin.tsx',
  output: { filename: 'plugin.js' },
  resolve: { extensions: ['.tsx', '.ts', '.js'] },
  module: {
    rules: [{ test: /\.tsx?$/, use: 'babel-loader' }],
  },
  externals: {
    react: 'var ACMS.Library.React',
    'react/jsx-runtime': 'var ACMS.Library.ReactJsxRuntime',
    'react-dom': 'var ACMS.Library.ReactDom',
    'react-dom/client': 'var ACMS.Library.ReactDomClient',
  },
};

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: { entry: 'src/plugin.tsx', name: 'MyPlugin', formats: ['iife'], fileName: () => 'plugin.js' },
    rollupOptions: {
      external: ['react', 'react/jsx-runtime', 'react-dom', 'react-dom/client'],
      output: {
        globals: {
          react: 'ACMS.Library.React',
          'react/jsx-runtime': 'ACMS.Library.ReactJsxRuntime',
          'react-dom': 'ACMS.Library.ReactDom',
          'react-dom/client': 'ACMS.Library.ReactDomClient',
        },
      },
    },
  },
});

@ablogcms/components を import する場合も、バンドルに含めず外部依存にします。サブパス名は ACMS.Library.components のキーと同じです（button-v2 のようにハイフンを含む名前は components['button-v2'] と書きます）。

// webpack.config.js の externals に追加する
'@ablogcms/components/popover': 'var ACMS.Library.components.popover',
'@ablogcms/components/button-v2': "var ACMS.Library.components['button-v2']",

ACMS.Library.components で使えないサブパスは、dataview / date-picker / time-picker / syntax-highlight / rich-select / select / device-mode / icon-picker の8つです。

出力形式は IIFE にしてください。 ESM で出力すると import ... from "react" が残り、ブラウザが解決できません。IIFE で出力したファイルを、<script type="module"> として読み込みます。配布用のファイルは production ビルドで作ってください（開発用の react/jsx-dev-runtime は共有していません）。

Tiptap を参照する

ブロックエディターの拡張を書く場合、Tiptap と ProseMirror は @ablogcms/block-editor/tiptap/* から参照します。

import type { Tiptap } from '@ablogcms/block-editor/tiptap';
import type { Node } from '@ablogcms/block-editor/tiptap/pm/model';

ctx.blockEditor.registerExtension('callout', ({ core }) =>
  core.Node.create({ name: 'callout', group: 'block', content: 'paragraph+' })
);

その他の注意

• ESM のみを配布しています。 require() では読み込めません。バンドラ、または ESM に対応した Node.js で利用してください。
• 公開しているサブパス以外を import しないでください。 内部のパスは予告なく変わります。

関連ページ

• npm パッケージ（@ablogcms/*）
• プラグイン API
• 管理画面と同じ見た目で画面を作る
• プラグイン開発