ui5-best-practices-mdc

UI5 MDC コントロールのベストプラクティス

OData V4 サービスを使用するフリースタイルアプリケーションで MDC コントロールのコードを生成、レビュー、またはトラブルシューティングする際は、常にこれらのガイドラインを適用してください。

UI5 のバージョン基準： SAPUI5 1.136+ LTS。特記がない限り、記載されているすべての機能はこのバージョン以降で利用できます。

各リファレンスを読み込むタイミング

トリガー	読み込むリファレンス
sap.ui.mdc.FilterBar を使用または計画している	references/mdc-filter-bar.md
sap.ui.mdc.Chart を使用または計画している	references/mdc-chart.md
sap.ui.mdc.Field を使用または計画している	references/mdc-field.md
sap.ui.mdc.FilterField を使用または計画している	references/mdc-filter-field.md
sap.ui.mdc.ValueHelp を使用または計画している	references/mdc-value-help.md
sap.ui.mdc.Link を使用または計画している	references/mdc-link.md
sap.ui.mdc.MultiValueField を使用または計画している	references/mdc-multi-value-field.md
JSON モデル（OData 以外）で MDC コントロールを使用している	references/mdc-json-delegates.md

出力する前に読み込んでください。記憶だけを頼りに作業しないでください。

---

デリゲートパターン

すべての MDC コントロールは、コントロールをデータソース固有のロジックから切り離すためにデリゲートを使用します。アプリ開発者は次のことを行う必要があります。

1. XML でデリゲートを指定する：delegate="{name: 'my/app/delegate/MyDelegate', payload: {entitySet: 'Products'}}"
2. 適切なベースデリゲートを拡張するデリゲートモジュールを実装する
3. 主要なメソッド（最低限 fetchProperties）をオーバーライドする

OData V4 用のベースデリゲート：

コントロール	ベースデリゲート
Table	sap/ui/mdc/odata/v4/TableDelegate
FilterBar	sap/ui/mdc/odata/v4/FilterBarDelegate
Chart	sap/ui/mdc/odata/v4/vizChart/Delegate
ValueHelp	sap/ui/mdc/ValueHelpDelegate
Link	sap/ui/mdc/LinkDelegate
MultiValueField	sap/ui/mdc/field/MultiValueFieldDelegate

JSON モデルの使用： MDC コントロールは JSON モデルでも動作します。OData V4 用のバリアントではなく、ベースデリゲート（sap/ui/mdc/TableDelegate、sap/ui/mdc/FilterBarDelegate）を直接拡張してください。詳細については、references/mdc-json-delegates.md を参照してください。

PropertyInfo — fetchProperties が返す中核的なメタデータ形式：

{
    key: "propertyName",        // Unique identifier (required)
    label: "Display Label",     // User-visible label (required)
    dataType: "sap.ui.model.odata.v4.type.String"  // Data type (required)
}

---

基本ルール

必須事項

• すべての MDC コントロールには、有効なモジュールパスを参照する delegate プロパティが必要です。
• デリゲートに fetchProperties を実装し、最低限 key、label、dataType を含む PropertyInfo[] を返してください。
• OData V4 サービスでは、適切な OData V4 基底デリゲートを拡張してください（上の表を参照）。JSON モデルやその他のモデルでは、ジェネリック基底デリゲートを直接拡張してください。
• パーソナライズを有効にするには p13nMode を使用してください（Table では Column、Sort、Filter、Group、Chart では Item、Sort、Filter、Type、FilterBar では Item）。
• 条件をプログラムで構築するには sap.ui.mdc.condition.Condition.createCondition() を使用してください。
• OData V4 モデルでは、PropertyInfo の dataType フィールドに sap.ui.model.odata.v4.type.* 型を使用してください。JSON モデルでは sap.ui.model.type.* を使用してください。型は TypeMap に登録してください。
• アクセシビリティのため、FilterBar と Chart に ariaLabelledBy を設定してください。
• フリースタイルの MDC より、Fiori elements のビルディングブロックを優先してください。Fiori elements の対象範囲外である場合にのみ MDC を使用してください。
• コントロール API の確認には MCP ツール get_api_reference を使用してください。コードの検証には run_ui5_linter を使用してください。

禁止事項

• OData V2 モデルで MDC コントロールを使用しないでください。代わりに Smart コントロール（sap.ui.comp）を使用してください。MDC は OData V4 および JSON モデルで動作します。
• 内部コントロール（例：内部の sap.chart.Chart や sap.m.Table）に直接アクセスしないでください。デリゲートまたは MDC コントロールの公開 API を使用してください。
• PropertyInfo オブジェクトから key を省略しないでください（以前の name は現在非推奨です）。
• 条件オブジェクトを通常の JSON として手動で構築しないでください。必ず Condition.createCondition(operator, values) を使用してください。
• 本番コードでデリゲートの実装を省略しないでください（組み込みの既定値はデモ専用です）。
• インラインのスタイルやスクリプトを使用しないでください（CSP 準拠のため）。
• グローバルアクセス（sap.ui.mdc.FilterBar）を使用しないでください。sap.ui.define または ES6 のインポートを使用してください。

---

選択マトリックス

コントロール	使用する場合	使用しない場合
MDC FilterBar	OData V4 または JSON モデル、デリゲート駆動のフィルター UI、MDC Table／Chart	OData V2（SmartFilterBar を使用）、シンプルな検索バー
MDC Chart	OData V4、デリゲート駆動のチャート表示、ドリルダウン	OData V2（SmartChart を使用）、シンプルな静的チャート、分析データがない場合
MDC Field	OData V4 または JSON、データ型に応じた自動レンダリングを行う単一フィールド	OData V2（SmartField を使用）、完全にカスタムなレンダリングが必要な場合
MDC FilterField	MDC FilterBar 内の個別のフィルター条件	FilterBar のコンテキスト外での単独のフィルタリング
MDC ValueHelp	OData V4 または JSON、入力補完＋ダイアログでの値選択	OData V2（ValueHelpDialog を使用）、検索機能のないシンプルなドロップダウン
MDC Link	OData V4、セマンティックオブジェクトのナビゲーション、デリゲート駆動のリンク先	OData V2（SmartLink を使用）、シンプルな静的リンク
MDC MultiValueField	OData V4 または JSON、items 集約による複数値のトークン入力	OData V2（SmartMultiInput を使用）、シンプルな単一値フィールド

---

よくあるエラー

症状	原因	修正
「Delegate module could not be loaded」と表示される	delegate プロパティのパスが間違っています	モジュールのパスがプロジェクト内の実際のファイル位置と一致していることを確認します。
チャートにデータが表示されない	fetchProperties が誤った PropertyInfo を返しています（groupable／aggregatable が不足しています）	ディメンションに groupable: true、メジャーに aggregatable: true が設定されていることを確認します。
FilterBar のフィールドが表示されない	PropertyInfo がない、または hiddenFilter: true になっています	delegate の fetchProperties が、可視性の正しいプロパティを返すことを確認します。
フィールドに誤った内部コントロールが表示される	PropertyInfo の dataType が想定される形式と一致していません	dataType に完全修飾型名（例：sap.ui.model.odata.v4.type.String）を使用していることを確認します。
パーソナライズダイアログが空になる	p13nMode が設定されていない、または PropertyInfo が不完全です	p13nMode="Column,Sort,Filter" を追加し、PropertyInfo に sortable／filterable フラグがあることを確認します。
ValueHelp が開かない	ValueHelp が Field に接続されていない、またはコンテナーがありません	Field の valueHelp アソシエーションと、Popover／Dialog コンテナーが定義されていることを確認します。
条件がバインディングに適用されない	delegate に updateBindingInfo が実装されていません	OData バインディングにフィルター条件を適用する updateBindingInfo を実装します。
リンクが常にテキストとして表示される	fetchLinkType が LinkType.Text を返す、または失敗しています	Popup または DirectLink タイプを返す fetchLinkType を実装します。

---

パフォーマンスとアクセシビリティ

避けるべきアンチパターン

• 必要なものが一部のみなのに、すべての PropertyInfo を先行して読み込む（fetchProperties から最小限のセットを返します）。
• updateBindingInfo を実装しない（条件がデータバインディングに適用されません）。
• p13nMode の設定を省略する（パーソナライズ機能はデフォルトで無効です）。
• 大規模な delegate モジュールを作成する（複雑なロジックは、必要に応じて読み込むヘルパーモジュールに分割します）。
• delegate メソッドで同期処理を使用する（すべての delegate メソッドは Promise を返す必要があります）。

アクセシビリティチェックリスト

• FilterBar の ariaLabelledBy に、表示されているタイトルを指定します。
• Chart の ariaLabelledBy に、表示されているタイトルを指定します。
• パーソナライズダイアログでキーボード操作が機能することを確認します。
• スクリーンリーダーで ValueHelp の入力補完とダイアログをテストします。
• すべての FilterField に、PropertyInfo の label を使って意味のあるラベルが設定されていることを確認します。