ui5-best-practices-tables

UI5 テーブルのベストプラクティス

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

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

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

条件	読み込むリファレンス
sap.m.Table（ResponsiveTable）を使用または計画している	references/sap-m-table.md
sap.ui.table.Table（GridTable）を使用または計画している	references/grid-table.md
sap.ui.table.TreeTable を使用または計画している	references/tree-table.md
sap.ui.comp.smarttable.SmartTable を使用または計画している	references/smart-table.md
sap.ui.mdc.Table を使用または計画している	references/mdc-table.md
テーブルにドラッグ＆ドロップを追加する	references/drag-and-drop.md
列のパーソナライズを追加する	references/personalization.md
セルテンプレート、配置、またはデータ型のバインディングを選択する	references/cell-templates.md

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

---

基本ルール

必須事項

• コードを記述する前に、選択マトリックスを使ってテーブルの種類を選択してください。
• sap.ui.table.* では rows 集約を、sap.m.Table では items を使用してください。決して取り違えないでください。
• パーソナライズには sap.m.p13n.Engine を使用してください。独自のパーソナライズダイアログは作成しないでください。
• すべてのテーブルに ariaLabelledBy を設定し、テーブルのタイトルコントロールを参照してください。
• データ型に応じてセルの内容を配置してください。数値と日付は右寄せ（hAlign="End"）、テキストとリンクは左寄せにします。
• 適切なセルテンプレートを使用してください。表示には sap.m.Text、数値には sap.m.ObjectNumber、ナビゲーションには sap.m.Link を使用します。
• 合計件数が必要な場合は、sap.ui.table.* のバックエンドに $count=true を要求してください。
• sap.ui.table.* では、非推奨の visibleRowCountMode プロパティではなく、rowMode 集約を使用してください（UI5 1.119+）。

禁止事項

• グローバル変数を使用しないでください。sap.ui.define AMD モジュールまたは ES6 インポートを使用してください。
• sap.ui.table.* のセルでテキストの折り返しを有効にしないでください。仮想化が機能しなくなります。
• sap.ui.export.Spreadsheet が利用可能だと決めつけないでください。使用前にライブラリの有無を確認してください。
• モバイルファーストのシナリオで sap.ui.table.Table を使用しないでください。sap.m.Table を使用してください。
• 仮想化が必要な 1000 行以上のデータセットに sap.m.Table を使用しないでください。
• sap.ui.table.Table のセルに、複数のインタラクティブ要素を配置しないでください。
• フォーマッターから列挙型オブジェクトを返さないでください。文字列リテラルまたはプリミティブ値を返してください。
• ColumnListItem の highlight にフォーマッターを使用しないでください。直接データバインディングしてください。
• モデルの利用可能性を確認せずにアクセスしないでください。「Cannot read properties of undefined」エラーの原因になります。
• 型の名前空間を混在させないでください。JSON モデルで sap.ui.model.odata.type.* を、OData で sap.ui.model.type.* を決して使用しないでください。

OData V4 の方針

OData V4 では、フリースタイルのテーブルより SAP Fiori elements のビルディングブロックを優先してください。Fiori elements の対象外の場合に限り、sap.ui.mdc.Table を使用してください。

---

選択マトリクス

テーブルの種類	使用する場合	使用しない場合
sap.m.Table	モバイル／レスポンシブ、ポップイン動作、JSON モデル、100 行未満	1000 行以上、仮想化が必要、デスクトップ専用、セル選択が必要
sap.ui.table.Table	デスクトップ、1000 行以上、仮想化、固定列、高密度データ	モバイルファースト、ポップインが必要、テキストの折り返し、小規模なデータセット
sap.ui.table.TreeTable	階層データ、展開／折りたたみ、親子関係	フラットなデータ、モバイルファースト、グルーピング（階層ではない）
SmartTable	OData V2、アノテーション、自動列、スマートフィルタリング	JSON のみ、厳密な制御が必要、OData V4
sap.ui.mdc.Table	OData V4 のフリースタイル（Fiori elements を採用しない場合）、デリゲートパターン	JSON のみ、シンプルなアプリ、OData V2

データセットのサイズガイド

行数	推奨テーブル	方針
< 100	sap.m.Table	シンプルなバインディング、growing は任意
100–1000	sap.ui.table.Table	仮想化、threshold=100
1000+	sap.ui.table.Table	仮想化、threshold=100–500、必要に応じて $count=true

---

よくあるエラー

症状	原因	対処方法
データが表示されない	バインディングパスが正しくない、またはモデルが設定されていない	bindRows／bindItems のパスとモデルのアタッチを確認します。
行がスクロールしない（sap.ui.table.*）	件数がリクエストされていない	合計件数が必要な場合は、OData で $count=true を設定します。
選択が機能しない（sap.ui.table.*）	プラグインの競合	選択プラグインが適用されている場合は、テーブルの選択 API を呼び出さず、代わりにプラグイン API を使用します。
テキストの折り返しに関する問題	sap.ui.table.* で折り返しが有効になっている	高さを固定したコンテンツを使用するか、sap.m.Table に切り替えます。
コピー／貼り付けが機能しない	プラグインがアタッチされていない、または名前空間が正しくない	正しいプラグインをアタッチします（「ドラッグ＆ドロップ」セクションを参照）。
パーソナライズ設定が保持されない	Engine が設定されていない	sap.m.p13n.Engine の登録を確認します。
CopyProvider エラー	extractData が定義されていない	プラグインに extractData を実装します。
テーブルが表示されない	コンテナー構造が無効	有効なコンテナーを使用します（「コンテナー構造」を参照）。
JSON モデルで OData の型を使用している	型の名前空間が正しくない	型の名前空間をモデルに合わせます。JSON には sap.ui.model.type.*、OData V2 には sap.ui.model.odata.type.*、OData V4 には sap.ui.model.odata.v4.type.* を使用します。
Excel エクスポートが失敗してもエラーが表示されない	ライブラリが読み込まれていない、または extractData が無効	ライブラリを検出し、extractData から 2 次元配列を返し、dataSource のバインディングを確認します。
「データがありません」	バインディング前にモデルが設定されていない	ルーターの初期化前に Component.init() でモデルを設定します。

---

コンテナー構造

有効

構造	用途
View > Page > content > Table	標準ページ
View > Page > content > Panel > Table	グループ化されたコンテンツ
View > Page > content > IconTabBar > items > IconTabFilter > Table	タブ
View > SplitApp > detailPages > Page > Table	マスター／詳細
View > Dialog > content > Table	モーダル
View > Table	単独

無効（および理由）

構造	問題
Page > content > VBox > Table	VBox には明示的な高さが必要なため、テーブルが表示されなくなります
Page > VBox > Table	VBox が content 内にないため、テーブルがレンダリングされません
Page > content > FlexBox > Table	サイズ調整の競合により、テーブルが折りたたまれます
Page > content > ScrollContainer > Table	スクロールが二重になり、仮想化が機能しなくなります

---

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

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

• パーソナライズダイアログを手作りする（sap.m.p13n.Engine を使用します）。
• sap.ui.table.Table のセル内でテキストを折り返す。
• 1 つの GridTable セルに複数のインタラクティブ要素を配置する。
• OData V2 の SmartTable と V4 サービスを混在させる。
• セルテンプレートを深くネストする。
• 負荷テストを行わずに threshold を固定する。
• 無条件に $count=true を設定する（必要な場合にのみ件数をリクエストします）。

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

• すべてのテーブルに ariaLabelledBy を設定し、表示されているタイトルを参照します。
• セルテンプレートには、生のテキストノードではなく sap.m.Text を使用します。
• sap.ui.table.Table では、キーボード操作（Tab、矢印キー、選択時の Space/Enter）をテストします。
• パーソナライズダイアログをキーボードで操作できることを確認します。
• リリース前に、スクリーンリーダー（Windows では NVDA/JAWS、macOS では VoiceOver）でテストします。