ui5-best-practices-smart-controls

UI5 Smart Controls のベストプラクティス

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

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

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

トリガー	読み込むリファレンス
sap.ui.comp.smartfield.SmartField を使用または導入する場合	references/smart-field.md
sap.ui.comp.smartform.SmartForm を使用または導入する場合	references/smart-form.md
sap.ui.comp.smartfilterbar.SmartFilterBar を使用または導入する場合	references/smart-filter-bar.md
sap.ui.comp.smartchart.SmartChart を使用または導入する場合	references/smart-chart.md
sap.ui.comp.navpopover.SmartLink を使用または導入する場合	references/smart-link.md
sap.ui.comp.smartmultiinput.SmartMultiInput を使用または導入する場合	references/smart-multi-input.md
sap.ui.comp.filterbar.FilterBar を使用または導入する場合	references/filter-bar.md
sap.ui.comp.valuehelpdialog.ValueHelpDialog を使用または導入する場合	references/value-help-dialog.md

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

---

基本ルール

必須

• Smart コントロールには常に entitySet を指定するか、コントロールがエンティティ型を解決できるバインディングコンテキストを継承するようにしてください。
• SmartFilterBar のフィールドを上書きする場合は、XML で ControlConfiguration を使用してください（コントロールの種類、フィルターの種類、インデックス）。実行時に変更できるのは visible、label、visibleInAdvancedArea のみです。
• 正しい階層を使用してください：SmartForm > Group > GroupElement > SmartField。SmartField を SmartForm に直接配置しないでください。
• 内部コントロール（例：getInnerControl()、getChart()）にプログラムからアクセスする前に、initialise イベントを待ってください。
• OData V2 モデルと併用するバインディングでは、sap.ui.model.odata.type.* 型を使用してください。OData V2 で sap.ui.model.type.* を使用しないでください。
• アクセシビリティのため、表示されているタイトルを参照する ariaLabelledBy を SmartFilterBar と SmartChart に設定してください。
• データ送信前に、クライアント側の必須フィールド検証を行うため、SmartForm で check() を使用してください。
• コントロール API の確認には get_api_reference MCP ツールを使用してください。コードの検証には run_ui5_linter を使用してください。

禁止事項

• OData V4 サービスでは Smart コントロールを使用しないでください。代わりに MDC コントロール（sap.ui.mdc）を使用してください。
• SmartField の value プロパティにカスタムフォーマッターを設定しないでください。SmartField はメタデータに基づいて独自にレンダリングを管理します。動作に影響を与えるにはアノテーションを使用してください。
• SmartField で複合バインディング構文（parts: [...]）を使用しないでください。単位／通貨フィールドの複合バインディングは SmartField が独自に管理します。
• 初期化中に getChart() を同期的に呼び出さないでください。initialise イベントまたは getChartAsync() を使用してください。
• SmartChart や SmartTable の内部コントロール（内部の sap.chart.Chart など）を直接変更しないでください。スマートコントロールの公開 API を使用してください。
• フィールドラベルをハードコードしないでください。OData メタデータの sap:label または @Common.Label アノテーションを使用してください。
• HTML でインラインスタイルやスクリプトを使用しないでください（CSP 準拠のため）。
• グローバルアクセス（sap.ui.comp.smartfield.SmartField）を使用しないでください。sap.ui.define または ES6 インポートを使用してください。

---

選択マトリックス

コントロール	使用する場合	使用しない場合
SmartField	OData V2、単一プロパティの表示／編集、Edm 型とアノテーションによる自動レンダリング	OData V4、JSON モデル、カスタムレンダリングが必要な場合、複合／複数プロパティのフィールド
SmartForm	OData V2、複数の SmartField を使ったエンティティの編集、アノテーションによる自動ラベル	OData V4、複雑なカスタムレイアウト、OData 以外のデータ
SmartFilterBar	OData V2、アノテーション駆動のフィルター UI、SmartTable／SmartChart との連携	OData V4（MDC FilterBar を使用）、JSON のみ、完全なカスタムフィルターロジック
SmartChart	OData V2、アノテーション駆動のチャート表示、ドリルダウン、バリアント管理	OData V4（MDC Chart を使用）、分析以外のデータ、カスタムチャート JS
SmartLink	OData V2、セマンティックオブジェクトナビゲーション、FLP を介したアプリ間ナビゲーション	OData V4（MDC Link を使用）、単純な静的リンク、FLP を利用できない場合
SmartMultiInput	OData V2、トークンを使った複数値入力、範囲指定による値ヘルプ	OData V4、単純な単一値入力、JSON のみ
FilterBar	OData アノテーションを使わない手動フィルター UI、ValueHelpDialog 内、カスタムフィルター	アノテーション付きの OData V2（SmartFilterBar を使用）、OData V4（MDC FilterBar を使用）
ValueHelpDialog	テーブルと条件タブを使った複雑な値選択、トークンベースの複数選択	単純なドロップダウン、単一値の選択、OData V4（MDC ValueHelp を使用）

---

よくあるエラー

症状	原因	対処方法
編集モードで SmartField がプレーンテキストとして表示される	バインディングコンテキストがない、または entitySet が正しくない	value="{PropertyName}" とエンティティコンテキストの解決を確認します。
SmartField に DatePicker ではなく Input が表示される	プロパティに sap:display-format="Date" がない	アノテーションを追加するか、ControlConfiguration で controlType を使用します。
SmartForm のラベルが表示されない	OData メタデータに sap:label アノテーションが設定されていない	プロパティに sap:label を追加するか、GroupElement に label を設定します。
SmartFilterBar の先行入力が機能しない	正しいターゲットパスを持つ ValueList アノテーションがない	ターゲットが {Namespace}.{EntityName}/{FieldName} であることを確認します。
SmartFilterBar のデフォルト値が無視される	initialise の後に ControlConfiguration を動的に設定している	XML で値を静的に設定するか、setFilterData() API を使用します。
SmartChart の高さが 0／表示されない	コンテナーに明示的な高さが指定されていない	親コンテナーに高さを設定します（例：height="50vh"）。
SmartChart にディメンション／メジャーが表示されない	UI.Chart アノテーションが間違っている、または存在しない	アノテーションの MeasureAttributes と DimensionAttributes を確認します。
SmartLink のポップオーバーに「コンテンツがありません」と表示される	FLP でセマンティックオブジェクトのナビゲーションターゲットがない	FLP の設定とユーザー権限を確認します。
SmartLink がテキストとして表示され、クリックできない	プロパティに SemanticObject アノテーションがない	OData プロパティに @Common.SemanticObject アノテーションを追加します。
SmartMultiInput のトークンが保持されない	ValueList がない、またはバインディングが正しくない	ValueList アノテーションとナビゲーションプロパティのバインディングを確認します。

---

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

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

• すべての値リストを事前に要求する（遅延読み込みを使用してください。値リストはデフォルトでオンデマンドに読み込まれます）。
• バックエンドクエリの負荷が高い SmartFilterBar で liveMode="true" を使用する（再取得が頻繁に発生します）。
• SmartForm のグループを深くネストする（階層は Form > Group > GroupElement のようにフラットに保ちます）。
• SmartChart API を使わずに内部のチャートを直接変更する（パーソナライズとバリアント管理が機能しなくなります）。
• 特定のチャートタイプが不要な場合に ignoredChartTypes を設定しない（不要な UI オプションが表示されます）。

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

• SmartFilterBar の ariaLabelledBy に、表示されているタイトルを指定します。
• SmartChart の ariaLabelledBy に、表示されているタイトルを指定します。
• SmartForm はアノテーションを介して SmartField にラベルを自動的に伝播します。
• SmartFilterBar の「フィルターの調整」ダイアログで、キーボードナビゲーションが機能することを確認します。
• スクリーンリーダーで SmartLink のポップオーバーをテストします（ナビゲーションターゲットが読み上げられる必要があります）。