primeng-developer

PrimeNG 開発者向けガイドライン

angular-developer と併用してください — このスキルでは Angular の基礎（シグナル、DI、ルーティング、フォーム、SSR、アクセシビリティ）を扱います。このスキルでは PrimeNG 固有の内容に焦点を当てます。最適な体験のため、両方をインストールしてください。

互換性

• 対象バージョン： PrimeNG 22.1.3（リリース日：2026-10-20）。@primeuix/themes と @primeuix/styles はどちらも 3.x（現在は 3.0.2）です。PrimeNG は Angular のメジャーバージョンに追従するため、v22 には Angular v22 が必要です（22.1 以降では peer @angular/core@^22.1.0、22.0.x では ^22.0.0）。
• 対応プロジェクト： PrimeNG v18 → v22 のプロジェクト。このスキルのリファレンスには、v18 のコンポーネント名の変更（Calendar→DatePicker、Dropdown→Select など）と v21→v22 での削除を扱う migration.md が含まれています。そのため、v18〜v21 のプロジェクトでもこのスキルを使用できますが、テーマ設定や一部のコンポーネント API には差異があることを想定してください。v22 が最も適合します。
• v21 → v22： v22 では Angular 22 との整合性が図られ、@primeuix/themes／@primeuix/styles が v3 になりました。また、以前のバージョンで「v22 で削除予定」として非推奨になっていた API を確実に削除しています。これには @primeng/themes のインポートパス、pTemplate、styleClass、showTransitionOptions／hideTransitionOptions、キャメルケースのセレクター、pButton のアイコン／ラベルプロパティなどが含まれます。これらは単に非推奨になったのではなく、削除済みとして扱ってください。migration.md を参照してください。
• v22.0 → v22.1： 破壊的変更はありません。22.1 では、マイクロフロントエンドや埋め込みウィジェット向けの実験的な withIsolation() 機能（primeng/isolation）、p-select の filterMessage／selectionMessage／emptySelectionMessage 入力、p-tree の filteredNodes モデルが追加され、Angular の peer 依存関係が ^22.1.0 に引き上げられました。また、v22 ではコンポーネントのサイズ計算にルートフォントサイズ 16pxを使用します。ルートフォントサイズがまだ 14px のアプリでは、-compat プリセットを使用してください（theming.md を参照）。migration.md を参照してください。
• ドキュメントのドメイン： 公式ドキュメントは primeng.org から primeng.dev に移転しました（以前のリンクは 301 リダイレクトされます）。
• Angular： v18 以降が必要です（PrimeNG v22 では v22 が必要）。PrimeNG コンポーネントは v18 以降スタンドアロンです。このスキルでは、スタンドアロンコンポーネント、制御フロー（@if／@for）、シグナルベースの API を前提としています。
• Tailwind： v3 または v4 と tailwindcss-primeui プラグイン（オプション、Unstyled モード用）。
• 非対応： PrimeNG v17 以前（prime.css ベースの異なるテーマ設定方式）、Angular v17 以前（NgModule パターン）。

プロジェクトの PrimeNG バージョンが v18 より前の場合は、PrimeNG v17 のドキュメントを案内し、v17 のプロジェクトに v18 以降のパターンを生成しないでください。コンパイルできません。

1. ガイダンスを提供する前に、必ずプロジェクトの PrimeNG バージョンを確認してください。PrimeNG v18 では、主要なコンポーネント名の変更（Calendar→DatePicker、Dropdown→Select、InputSwitch→ToggleSwitch、OverlayPanel→Popover、Sidebar→Drawer）と、新しいデザイントークンベースのテーマ設定システムが導入されました。API を推奨する際は、package.json を信頼できる情報源とし、迷ったらまず確認してください。migration.md を参照してください。

2. コンポーネントを追加する前に、プロジェクトで使用しているテーマ設定モードを確認してください。

   • @primeuix/themes がインポートされ、providePrimeNG({ theme: ... }) が設定されている場合 → Styled モード（デフォルト）。
   • providePrimeNG で unstyled: true が設定されている場合、またはプロジェクトで tailwindcss-primeui を使用している場合 → Unstyled モード。
   • 2 つのモードでは、カスタマイズ方法が根本的に異なります。styled-vs-unstyled.md を参照してください。

3. コンポーネントは v18 以降、スタンドアロンです。常にスタンドアロンのクラス（例：'primeng/button' からの Button）をインポートし、レガシーな *Module は使用しないでください。レガシーモジュールも後方互換性のために引き続きエクスポートされていますが、新しいコードには追加しないでください。

4. PrimeNG コードの生成後、ng build を実行してコンパイルエラーを検出します。AI がよく間違える点は次のとおりです。（a）非推奨のパスである @primeuix/themes ではなく、@primeuix/themes からインポートしてしまうこと。（b）v18 から v20 のプロジェクトで provideAnimationsAsync() を忘れること（PrimeNG v21 以降はネイティブの CSS アニメーションを使用するため、不要になっています）。（c）v18 で名称が変更された後も、v17 のコンポーネント名（Calendar、Dropdown、OverlayPanel、Sidebar、InputSwitch）を使うこと。（d）v20 以降非推奨の styleClass="…" をコンポーネントに指定すること。代わりにネイティブの class="…"（または [class]／[ngClass]）を使います。（e）単独でインポートしたコンポーネント内で pTemplate="item" を記述すること。SharedModule（または再エクスポートする TableModule などの *Module）をインポートしない限り、PrimeTemplate ディレクティブはスコープに含まれません。そのため、テンプレートは登録されないまま、コンポーネントには空の行が表示されますが、ビルドエラーもコンソールエラーも発生しません。代わりにテンプレート参照（<ng-template #item>、#content、#header など）を使います。v21 の各コンポーネントは、これらの参照をコンテンツクエリで直接取得します。setup.md と migration.md を参照してください。

PrimeNG のアーキテクチャ：Styled、Unstyled、PassThrough

PrimeNG は node_modules 内にコンパイル済みの状態で提供されており、ソースをコピーする CLI はありません。カスタマイズには、段階的に高度になる次の 3 つの方法があります。

• デザイントークン（Styled モード）：definePreset(Aura, {...}) を使い、プリセットレベルでテーマ変数をオーバーライドします。ほとんどのテーマ設定に適しています。theming.md を参照してください。
• PassThrough（pt）：コンポーネントごとのプロパティで、内部 DOM セクションにクラスや属性を挿入します。Styled モードと Unstyled モードの両方で機能します。デザイントークンだけでは不十分な場合に使います。passthrough.md を参照してください。
• Unstyled モード：PrimeNG のスタイルを完全に取り除き、独自のスタイル（通常は tailwindcss-primeui を使った Tailwind）を適用します。すでに独自のデザインシステムがあるチームに適しています。styled-vs-unstyled.md を参照してください。

基本的には Aura プリセットを使った Styled モードを選びます。 特定の内部セクションをオーバーライドする必要がある場合は PassThrough を使います。Tailwind 主導のデザインシステムを採用しているプロジェクトに限り、Unstyled を使います。

インストールとテーマ設定

• セットアップ：primeng @primeuix/themes @primeuix/styles をインストールし、providePrimeNG()（v18 から v20 では provideAnimationsAsync() も）を設定します。よくある問題については、setup.md を参照してください。
• テーマ設定：Aura／Lara／Nora／Material のプリセット、デザイントークン、ダークモード、definePreset によるオーバーライド、実行時のプリセット切り替え、CSS レイヤーの順序については、theming.md を参照してください。
• Styled と Unstyled の比較：各モードの使いどころ、Tailwind v4 と tailwindcss-primeui の統合、Volt UI の参考パターンについては、styled-vs-unstyled.md を参照してください。
• PassThrough：pt API、providePrimeNG でのグローバルな pt、ネストされたコンポーネントのプレフィックス（pcBadge）、ptOptions.mergeSections と mergeProps については、passthrough.md を参照してください。

コンポーネント

PrimeNG には、カテゴリ別にまとめられた 80 種類以上のコンポーネントがあります。各カテゴリのファイルでは、コンポーネントの API、一般的なパターン、注意点を説明しています。

• フォームコントロール：AutoComplete、CascadeSelect、Checkbox、ColorPicker、DatePicker、Editor、FloatLabel、IconField、IftaLabel、InputMask、InputNumber、InputOtp、InputText、Knob、Listbox、MultiSelect、Password、RadioButton、Rating、Select、SelectButton、Slider、Textarea、ToggleButton、ToggleSwitch、TreeSelect。form-controls.mdを参照してください。
• ボタン：Button、SpeedDial、SplitButton。buttons.mdを参照してください。
• オーバーレイ：ConfirmDialog、ConfirmPopup、Dialog、Drawer、DynamicDialog、Popover、Toast、Tooltip。overlays.mdを参照してください。
• レイアウト：Accordion、BlockUI、Card、Divider、Fieldset、Panel、Scroller（VirtualScroller）、ScrollTop、Splitter、Stepper、Tabs、Toolbar。layout.mdを参照してください。
• データ表示：Carousel、DataView、Galleria、OrderList、Paginator、PickList、Table、Timeline、Tree、TreeTable。data-display.mdを参照してください。
• 表示：Avatar、Badge、Chip、Image、Inplace、Message、MeterGroup、OverlayBadge、ProgressBar、ProgressSpinner、Ripple、Skeleton、Tag、Terminal。display.mdを参照してください。
• メニュー：Breadcrumb、ContextMenu、Dock、MegaMenu、Menu、MenuBar、PanelMenu、TieredMenu。menus.mdを参照してください。

フォーム連携

• フォーム：PrimeNG のフォームコンポーネントを ReactiveForms または Signal Forms に接続する方法、.ng-invalid.ng-dirtyに代わる[invalid]プロパティ（v20 以降）、ControlValueAccessorのパターン、バリデーションの表示について説明しています。forms.mdを参照してください。

アクセシビリティ

• アクセシビリティ：WCAG 2.1 AA への準拠、p-sr-onlyユーティリティ、コンポーネントごとの ARIA 規則、キーボード操作、フォーカス管理について説明しています。accessibility.mdを参照してください。

移行

• 移行：v18 でのコンポーネント名の変更（Calendar→DatePicker など）、非推奨 API、.ng-invalid.ng-dirtyに代わる[invalid]プロパティ、レガシー SCSS テーマに代わるデザイントークンシステムについて説明しています。migration.mdを参照してください。