はじめに
Fiori Elementsで画面を作るとき、画面コードは書きません。代わりにCDSビューに @UI.* アノテーションを付与し、これを設計図としてFiori Elementsが画面を生成します。
アノテーションの種類を把握していないと、「このフィルタバーはどう出すんだっけ」「Object Pageのタブはどう分けるんだっけ」と毎回ドキュメントを引き直すことになります。この記事では、実務で使用頻度の高い@UIアノテーションを網羅的に整理します。
CDSビューの基本はCDSビュー基礎を先に確認してください。
アノテーションの全体マップ
flowchart LR CDS["CDS View"] --> H["@UI.headerInfo
Object Pageヘッダ"] CDS --> L["@UI.lineItem
テーブル列"] CDS --> S["@UI.selectionField
検索フィルタ"] CDS --> F["@UI.facet
Object Pageタブ"] CDS --> FG["@UI.fieldGroup
フィールド集合"] CDS --> ID["@UI.identification
詳細画面ヘッダ項目"] CDS --> C["@UI.chart
ALP用チャート"] CDS --> PV["@UI.presentationVariant
表示切替"]
1. @UI.headerInfo
Object Pageのヘッダに表示する情報を定義します。
@UI.headerInfo: {
typeName: '発注書',
typeNamePlural: '発注書一覧',
title: { value: 'PoId' },
description: { value: 'Supplier' }
}
- typeName/typeNamePlural：単数形/複数形の名称
- title：ヘッダの主タイトルに表示する項目
- description：サブタイトルに表示する項目
2. @UI.lineItem
List ReportやObject Page内のテーブル列を定義します。
@UI.lineItem: [{ position: 10, label: '発注番号' }]
key ebeln as PoId,
@UI.lineItem: [{ position: 20, label: '仕入先' }]
lifnr as Supplier,
@UI.lineItem: [{ position: 30, importance: #HIGH }]
netwr as NetAmount
- position：列の表示順
- label：列ヘッダ
- importance：重要度（#HIGH/#MEDIUM/#LOW）。重要度低は狭い画面で非表示になる
3. @UI.selectionField
List Reportのフィルタバーに表示する検索項目を指定します。
@UI.selectionField: [{ position: 10 }]
lifnr as Supplier,
@UI.selectionField: [{ position: 20 }]
bukrs as CompanyCode
positionがフィルタバーでの並び順を決めます。
4. @UI.facet
Object Pageのタブ（ファセット）構造を定義します。
@UI.facet: [
{ id: 'general',
purpose: #HEADER,
type: #FIELDGROUP_REFERENCE,
label: '基本情報',
targetQualifier: 'GeneralInfo' },
{ id: 'items',
type: #LINEITEM_REFERENCE,
label: '明細',
targetElement: '_Items' },
{ id: 'history',
type: #FIELDGROUP_REFERENCE,
label: '履歴',
targetQualifier: 'History' }
]
- purpose：#HEADERならヘッダに、省略ならタブに配置
- type：#FIELDGROUP_REFERENCE（フィールド集合）または #LINEITEM_REFERENCE（テーブル）
- targetQualifier：参照する fieldGroup の名前
- targetElement：関連エンティティ（Navigation Property）の名前
5. @UI.fieldGroup
複数のフィールドを論理的にグルーピングします。@UI.facetから参照される「部品」として使います。
@UI.fieldGroup: [{ qualifier: 'GeneralInfo', position: 10 }]
bsart as DocumentType,
@UI.fieldGroup: [{ qualifier: 'GeneralInfo', position: 20 }]
bedat as DocumentDate
qualifierが一致するフィールドが、同じグループ内でpositionの順に表示されます。
6. @UI.identification
Object Pageのヘッダ直下の識別情報欄に表示するフィールドを指定します。主キーや参照コードに使います。
@UI.identification: [{ position: 10 }]
ebeln as PoId
7. @UI.chart（ALP用）
ALP実装ガイドでも触れたチャート定義です。
@UI.chart: [{
title: '仕入先別発注額',
chartType: #COLUMN,
dimensions: [ 'Supplier' ],
measures: [ 'NetAmount' ]
}]
8. @UI.presentationVariant
表示方法のバリアントを定義します。ALPでチャート/テーブルを切り替える場合に使います。
@UI.presentationVariant: [{
visualizations: [
{ type: #AS_CHART },
{ type: #AS_LINEITEM }
],
sortOrder: [{ by: 'NetAmount', direction: #DESC }]
}]
sortOrderでデフォルトのソート順も指定できます。
9. @UI.dataPoint（KPI表示）
OVPのKPIカードやObject Pageのヘッダで使う数値表示の書式を定義します。
@UI.dataPoint: {
title: '今月売上',
targetValue: 10000000,
criticality: 'SalesStatus'
}
netwr as NetAmount
criticalityは色分け（赤/黄/緑）の条件を指す列を指定します。
アノテーションをどこに書くか
ABAP CDS Viewで直接定義
シンプルで一貫性がある反面、CDS変更のたびにTransportが必要です。
Metadata Extension (MDE)
既存CDSに対して、UIアノテーションだけを別ファイルで追加定義できます。
@Metadata.layer: #CUSTOMER
annotate view ZV_PurchaseOrder with {
@UI.lineItem: [{ position: 10 }]
PoId;
}
お客様環境のみのUI追加に向いています。Clean Core戦略（Clean Core戦略）の観点でも、標準CDSの直接変更を避けるMDEが推奨されます。
よくある疑問
Q. 値ヘルプ（F4）はどう定義しますか？
A. @Consumption.valueHelpDefinition というアノテーションで、値ヘルプ用のCDSビューを紐付けます。Fiori Elementsは自動で値ヘルプダイアログを生成します。
Q. 項目の多言語化は？
A. @EndUserText.label: '発注番号' をフィールドに付け、翻訳はTコードSE63で多言語対応します。ラベル表示は自動で言語切替されます。
Q. positionは連番でないとダメ？
A. ダメではないですが、10/20/30とスペースを空けて振るのが慣例です。後から挿入しやすくなります。
Q. アノテーションは大文字小文字区別ありますか？
A. キーワードは大文字小文字非依存ですが、慣例的に @UI.lineItem のようなキャメルケースを使います。
まとめ
- @UI.*アノテーションはFiori Elementsの設計図
- headerInfo / lineItem / selectionField / facet / fieldGroup / identification が基本6点
- chart / presentationVariant / dataPoint は分析・KPI系で使う
- Metadata Extensionを使えば標準CDSに触らずUIを追加できる
- 値ヘルプ・多言語化も専用アノテーションが用意されている
次はFreestyle UI5 vs Fiori Elementsで、アノテーション駆動と自由実装の判断軸を整理します。
CDSアノテーションの書き方を覚えた後は、実際にCAPプロジェクトを作ってアノテーションがどう画面に反映されるかを確かめるのが一番の近道です。約15時間のハンズオン形式で、アノテーション駆動開発の実践感覚が身につきます。