craft-garnish

Garnish — Craft CMS コントロールパネル JavaScript ツールキット

Craft CMS 組み込みの JavaScript UI フレームワーク、Garnish のリファレンスです。クラスシステム、UI ウィジェット、ドラッグ操作、フォームコンポーネント、アクセシビリティヘルパー、Craft の CP との連携について説明します。

このスキルの対象は Garnish 自体、つまり src/web/assets/garnish/ にある JavaScript ライブラリです。PHP 側のプラグイン開発（エレメント、コントローラー、サービス）については、craftcms スキルを参照してください。Garnish ウィジェットがアタッチされる CP テンプレートのマークアップについては、craftcms スキルの cp.md リファレンスを参照してください。

関連スキル — 必要に応じて読み込む

• craftcms — PHP のアセットバンドルクラス、プラグインのアーキテクチャ、または Garnish ウィジェットがアタッチされる CP テンプレートのマークアップがタスクに関係する場合に読み込みます。純粋な JavaScript のリファクタリング、Garnish API の質問、JavaScript のみのタスクでは読み込む必要はありません。
• craft-php-guidelines — PHP ファイル（アセットバンドルクラス、JavaScript を登録するコントローラー）を編集する場合にのみ読み込みます。純粋な JavaScript 作業では読み込む必要はありません。

ドキュメント

• Garnish のソース：Craft CMS リポジトリ内の src/web/assets/garnish/src/
• 公式の外部ドキュメントはありません — このスキル自体がドキュメントです。

PHP 側のアセットバンドル登録を調べる場合は、Craft のクラスリファレンス（https://docs.craftcms.com/api/v5/）を WebFetch で参照してください。

よくある落とし穴（全般）

• this.addListener() の代わりに jQuery の .on() を直接使う — jQuery 経由で追加したリスナーは destroy() 時に自動でクリーンアップされず、メモリリークの原因になります。
• destroy() をオーバーライドする際に this.base() を呼び忘れる — 親クラスのクリーンアップ（リスナーの削除、イベントの解除）がスキップされます。
• <button> 以外の要素で activate イベントの代わりに click を使う — activate はクリックとキーボード（Space／Enter）の両方に対応しているため、UI のアクセシビリティが確保されます。
• ESC を直接バインドして UiLayerManager に逆らう — Garnish.uiLayerManager.registerShortcut(Garnish.ESC_KEY, callback) を使うと、レイヤースタックを通じて適切にエスケープキーを処理できます。
• Garnish.ESC_KEY、Garnish.RETURN_KEY などの代わりにマジックナンバーのキーコードを使う — 定数を使うと意図が明確になり、一貫性も保てます。
• DOM の準備ができる前に Garnish ウィジェットをインスタンス化する — Garnish の使用前に jQuery とすべての依存関係を読み込む必要があります。プラグインアセットでは、CpAsset の依存関係チェーンを利用してください。
• ウィジェットを削除するときに destroy() を呼び出さない — リスナーが残り続け、特にスライドアウトやライブプレビューでは、DOM が繰り返し生成・破棄されるため問題になります。
• 外部モジュールを使わず、Garnish を webpack バンドルにインポートする — import Garnish from 'garnishjs' は webpack の external によって window.Garnish を参照します。バンドルに含めると 134KB の重複が発生します。
• 別のフォームに挿入されるパネル（エントリー編集のサイドバーパネルや CP テンプレートフック）内の入力要素に name 属性を付ける — ホストフォームが保存時にそれらをシリアライズするため、プラグインの値が気づかれないまま取り込まれます。入力要素は ID のみを持たせ、JavaScript から ID で値を取得して独自のエンドポイントに送信し、Enter キーによるホストフォームの送信を防ぐガードを設けてください。integration.md（別のフォームに挿入されるパネル）を参照してください。
• 非推奨の Garnish.Menu を Garnish.CustomSelect の代わりに使う — Menu は後方互換性のためだけに残されているエイリアスです。
• 非推奨の Garnish.escManager や Garnish.shortcutManager を Garnish.uiLayerManager の代わりに使う — 新しいマネージャーはレイヤーを考慮したキーボード処理を提供し、モーダル／メニューのスタックを適切に扱います。

参照ファイル

タスクに関連する参照ファイルを確認してください。複数のファイルが該当することもよくあります。

タスクの例：

• 「プラグインの CP JS にモーダルダイアログを作成する」→ class-system.md + ui-widgets.md を読む
• 「カスタムフィールドタイプにドラッグで並べ替える機能を追加する」→ drag-system.md + class-system.md を読む
• 「カスタム CP ウィジェットクラスを作成する」→ class-system.md + integration.md を読む
• 「CP テンプレートに開閉メニューを追加する」→ ui-widgets.md + integration.md を読む
• 「CP JavaScript でキーボードイベントを処理する」→ utilities.md + class-system.md を読む
• 「インラインエディター HUD を作成する」→ ui-widgets.md（HUD セクション）を読む
• 「要素の選択インターフェースを作成する」→ ui-widgets.md（Select セクション）を読む
• 「Garnish 用にプラグインの webpack 設定を行う」→ integration.md を読む
• 「カスタム要素インデックスクラスが読み込まれない」→ integration.md（Element Index JS Loading）を読む
• 「Vite で要素インデックスの JS を読み込む」→ integration.md（Element Index JS Loading — Vite doesn't work for element index classes）を読む
• 「カスタムモーダルに ARIA 属性を追加する」→ utilities.md（ARIA & Focus セクション）を読む
• 「Garnish.Base 上にカスタムのスライドアウト／オーバーレイ／ランチャーを作成する」→ ui-widgets.md（Building a custom overlay/slideout）+ class-system.md（Enable / Disable）+ utilities.md（ARIA & Focus）を読む
• 「ランチャーボタンが一度しか動作しない／「Blocked aria-hidden」警告が出る」→ class-system.md（Enable / Disable）+ utilities.md（Closing an overlay: move focus OUT before hiding）を読む
• 「Craft.CP が Garnish をどのように拡張するかを理解する」→ integration.md + class-system.md を読む
• 「プラグインからエントリー編集画面のサイドバーにインタラクティブなパネルを追加する」→ integration.md（Panels Injected Into Another Form）+ craftcms スキルの cp-ui-patterns.md（マークアップ）を読む
• 「エントリー保存時にパネルのフィールドが消える／Enter キーでエントリーフォームが送信される」→ integration.md（Panels Injected Into Another Form）を読む
• 「複数の状態を持つ送信ボタンを作成する」→ integration.md（Form Widgets セクション）を読む
• 「テキストエリアを入力に合わせて自動拡張する動作を追加する」→ integration.md（Form Widgets セクション）を読む

参照先	範囲
references/class-system.md	Garnish.Base、継承（extend/init/base）、イベント（on/off/trigger）、リスナー（addListener/removeListener）、設定、名前空間、有効化／無効化、破棄のライフサイクル
references/ui-widgets.md	Modal、HUD、DisclosureMenu、MenuBtn、SelectMenu、CustomSelect、ContextMenu、Select — コンストラクター引数、設定／デフォルト値、メソッド、イベント、ARIA の動作
references/drag-system.md	BaseDrag、Drag、DragSort、DragDrop、DragMove — クラス階層、設定／デフォルト値、イベント、ヘルパーシステム、挿入位置、スクロール処理
references/utilities.md	Garnish 名前空間オブジェクト、キー定数、カスタム jQuery イベント（activate、textchange、resize）、ARIA／フォーカス管理、ジオメトリ／ヒットテスト、アニメーション、フォームヘルパー、検出機能
references/integration.md	GarnishAsset PHP バンドル、webpack externals、読み込み順序、Craft.* クラスパターン、Twig JS ブロック、フォームウィジェット（NiceText、CheckboxSelect、MultiFunctionBtn、MixedInput）