SKILLOfficialdevelopment

ui5-best-practices-smart-controls

プラグイン: ui5
ソース: GitHub で見る ↗

説明

UI5 スマートコントロール（sap.ui.comp）の OData V2 アノテーション（メタデータに付与する注記）駆動型コントロールのベストプラクティスです。 **次のような場合に使用:** SmartField、SmartForm、SmartFilterBar、SmartChart、SmartLink、SmartMultiInput、SmartTable の作成やトラブルシューティング時 **カバー範囲:** - コントロール選択 - アノテーション（ValueList、FieldControl、SemanticObject、UI.LineItem、UI.Chart） - 必須ルール - 一般的なエラーと対処法 - コントロール別 API リファレンス **トリガーキーワード:** SmartField、SmartForm、SmartFilterBar、SmartChart、SmartLink、SmartMultiInput、sap.ui.comp、スマートコントロールアノテーション、OData V2 メタデータ駆動、値ヘルプアノテーション、ValueList アノテーション、フィールドコントロールアノテーション、セマンティックオブジェクトナビゲーション **キーワード:** sap.ui.comp、SmartField、SmartForm、SmartFilterBar、SmartChart、SmartLink、SmartMultiInput、SmartTable、ValueHelpDialog、OData V2、アノテーション、ValueList、FieldControl、SemanticObject、entitySet、ControlConfiguration、GroupConfiguration、textArrangement、FilterProvider、initialise、beforeRebindChart、navigationTargetsObtained

原文を表示

UI5 smart controls (sap.ui.comp) best practices for OData V2 annotation-driven controls. Use when creating/troubleshooting SmartField, SmartForm, SmartFilterBar, SmartChart, SmartLink, SmartMultiInput, or SmartTable. Covers control selection, annotations (ValueList, FieldControl, SemanticObject, UI.LineItem, UI.Chart), mandatory rules, common errors, and per-control API reference. Triggers: "SmartField", "SmartForm", "SmartFilterBar", "SmartChart", "SmartLink", "SmartMultiInput", "sap.ui.comp", "smart control annotations", "OData V2 metadata-driven", "value help annotations", "ValueList annotation", "field control annotation", "semantic object navigation". Keywords: sap.ui.comp, SmartField, SmartForm, SmartFilterBar, SmartChart, SmartLink, SmartMultiInput, SmartTable, ValueHelpDialog, OData V2, annotations, ValueList, FieldControl, SemanticObject, entitySet, ControlConfiguration, GroupConfiguration, textArrangement, FilterProvider, initialise, beforeRebindChart, navigationTargetsObtained

ユースケース

SmartField、SmartFormなどの作成時
SmartControlのトラブルシューティング時
ODataアノテーション駆動型設計時
ValueList、FieldControlなどのアノテーション設定時
コントロール別APIの確認が必要な場面

本文（日本語訳）

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

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`

出力を作成する前に必ず読み込んでください。記憶に頼らないでください。

基本ルール

必須事項

スマートコントロールには常に 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.* は使用しないでください。
SmartFilterBar と SmartChart に ariaLabelledBy を設定し、表示されているタイトルを参照してアクセシビリティを確保してください。
データを送信する前に SmartForm で check() を使用して、クライアント側の必須フィールド検証を実行してください。
get_api_reference MCP ツール（API リファレンス取得ツール）でコントロール API を確認してください。run_ui5_linter でコードを検証してください。

禁止事項

OData V4 サービスではスマートコントロールを使用しないでください。代わりに 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 にインラインスタイルやスクリプトを使用しないでください（セキュリティポリシー対応）。
グローバルアクセス（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 を使用）、分析データでない、カスタムチャート JavaScript
`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 を表示する	OData メタデータのプロパティに `sap:display-format="Date"` アノテーションがない	アノテーションを追加するか、ControlConfiguration で `controlType` を使用してください。
SmartForm のラベルが表示されない	OData メタデータに `sap:label` アノテーションが設定されていない	プロパティに `sap:label` を追加するか、GroupElement に `label` を設定してください。
SmartFilterBar のタイプアヘッド（入力候補表示）が機能しない	ValueList アノテーションが不足しているか、ターゲットパスが誤っている	ターゲットが正しいか確認してください：`{Namespace}.{EntityName}/{FieldName}`
SmartFilterBar のデフォルト値が無視される	ControlConfiguration を `initialise` イベント後に動的に設定している	値を 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 ポップオーバーをテストしてください（ナビゲーションターゲットがアナウンスされる必要があります）。

原文（English）を表示

UI5 Smart Controls Best Practices

Apply these guidelines whenever generating, reviewing, or troubleshooting UI5 smart control code in freestyle applications using OData V2 services.

UI5 version baseline: SAPUI5 1.136+ LTS. All features mentioned are available from this version unless noted.

When to load each reference

Trigger	Load
Working on or planning a `sap.ui.comp.smartfield.SmartField`	`references/smart-field.md`
Working on or planning a `sap.ui.comp.smartform.SmartForm`	`references/smart-form.md`
Working on or planning a `sap.ui.comp.smartfilterbar.SmartFilterBar`	`references/smart-filter-bar.md`
Working on or planning a `sap.ui.comp.smartchart.SmartChart`	`references/smart-chart.md`
Working on or planning a `sap.ui.comp.navpopover.SmartLink`	`references/smart-link.md`
Working on or planning a `sap.ui.comp.smartmultiinput.SmartMultiInput`	`references/smart-multi-input.md`
Working on or planning a `sap.ui.comp.filterbar.FilterBar`	`references/filter-bar.md`
Working on or planning a `sap.ui.comp.valuehelpdialog.ValueHelpDialog`	`references/value-help-dialog.md`

Load before producing any output. Do not work from memory.

Core Rules

Mandatory

Always specify entitySet on Smart controls or ensure the control inherits a binding context that resolves the entity type.
Use ControlConfiguration in XML for SmartFilterBar field overrides (control type, filter type, index). Only visible, label, and visibleInAdvancedArea can be changed at runtime.
Use the correct hierarchy: SmartForm > Group > GroupElement > SmartField. Never place SmartFields directly in a SmartForm.
Wait for the initialise event before programmatically accessing inner controls (e.g., getInnerControl(), getChart()).
Use sap.ui.model.odata.type.* types in bindings alongside OData V2 models. Never use sap.ui.model.type.* with OData V2.
Set ariaLabelledBy on SmartFilterBar and SmartChart referencing a visible title for accessibility.
Use check() on SmartForm for client-side mandatory field validation before submitting data.
Use get_api_reference MCP tool to verify control APIs. Use run_ui5_linter to validate code.

Prohibitions

Do not use Smart controls with OData V4 services. Use MDC controls (sap.ui.mdc) instead.
Do not set custom formatters on SmartField value property. SmartField manages its own rendering based on metadata. Use annotations to influence behavior.
Do not use composite binding syntax (parts: [...]) on SmartField. It manages its own composite bindings for unit/currency fields.
Do not call getChart() synchronously during initialization. Use the initialise event or getChartAsync().
Do not directly modify inner controls of SmartChart or SmartTable (e.g., the inner sap.chart.Chart). Use the smart control's public API.
Do not hardcode field labels. Use sap:label or @Common.Label annotations in OData metadata.
Do not use inline styles or scripts in HTML (CSP compliance).
Do not use global access (sap.ui.comp.smartfield.SmartField). Use sap.ui.define or ES6 imports.

Selection Matrix

Control	Use when	Do not use when
`SmartField`	OData V2, single property display/edit, auto-rendering by Edm type and annotations	OData V4, JSON models, custom rendering required, composite/multi-property fields
`SmartForm`	OData V2, entity editing with multiple SmartFields, auto-labels from annotations	OData V4, complex custom layouts, non-OData data
`SmartFilterBar`	OData V2, annotation-driven filter UI, integration with SmartTable/SmartChart	OData V4 (use MDC FilterBar), JSON-only, purely custom filter logic
`SmartChart`	OData V2, annotation-driven chart visualization, drill-down, variant management	OData V4 (use MDC Chart), non-analytical data, custom chart JS
`SmartLink`	OData V2, semantic object navigation, cross-app navigation via FLP	OData V4 (use MDC Link), simple static links, no FLP available
`SmartMultiInput`	OData V2, multi-value entry with tokens, value help with ranges	OData V4, simple single-value input, JSON-only
`FilterBar`	Manual filter UI without OData annotations, inside ValueHelpDialog, custom filters	OData V2 with annotations (use SmartFilterBar), OData V4 (use MDC FilterBar)
`ValueHelpDialog`	Complex value selection with table + conditions tabs, token-based multi-select	Simple dropdowns, single-value selection, OData V4 (use MDC ValueHelp)

Common Errors

Symptom	Cause	Fix
SmartField renders as plain text in edit mode	Missing binding context or wrong `entitySet`	Verify `value="{PropertyName}"` and entity context resolution.
SmartField shows Input instead of DatePicker	Missing `sap:display-format="Date"` on property	Add annotation or use `controlType` in ControlConfiguration.
SmartForm labels missing	`sap:label` annotation not set in OData metadata	Add `sap:label` to property or set `label` on GroupElement.
SmartFilterBar type-ahead not working	Missing `ValueList` annotation with correct target path	Verify target: `{Namespace}.{EntityName}/{FieldName}`.
SmartFilterBar default values ignored	Setting ControlConfiguration dynamically after `initialise`	Set values statically in XML or use `setFilterData()` API.
SmartChart height is 0 / not visible	Container does not provide explicit height	Set height on parent container (e.g., `height="50vh"`).
SmartChart missing dimensions/measures	Wrong or missing `UI.Chart` annotation	Verify `MeasureAttributes` and `DimensionAttributes` in annotation.
SmartLink popover shows "No content available"	No navigation targets for semantic object in FLP	Verify FLP configuration and user authorizations.
SmartLink rendered as text (not clickable)	No `SemanticObject` annotation on property	Add `@Common.SemanticObject` annotation to OData property.
SmartMultiInput tokens not persisting	Missing ValueList or incorrect binding	Verify ValueList annotation and navigation property binding.

Performance & Accessibility

Anti-patterns to avoid

Requesting all value lists eagerly (use lazy loading; value lists load on-demand by default).
Using liveMode="true" on SmartFilterBar with expensive backend queries (causes rapid re-fetching).
Deep nesting of SmartForm groups (keep hierarchy flat: Form > Group > GroupElement).
Bypassing SmartChart API to modify inner chart directly (breaks personalization and variant management).
Not setting ignoredChartTypes when certain chart types are irrelevant (unnecessary UI options).

Accessibility checklist

Set ariaLabelledBy on SmartFilterBar referencing a visible title.
Set ariaLabelledBy on SmartChart referencing a visible title.
SmartForm automatically propagates labels to SmartFields via annotations.
Verify keyboard navigation works for SmartFilterBar "Adapt Filters" dialog.
Test SmartLink popover with screen reader (navigation targets must be announced).

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。