ui5-best-practices

UI5 のベストプラクティスとコーディング標準

概要

このスキルでは、SAP の公式ガイドラインに基づく UI5 開発標準を適用します。重要な 4 つの領域、コーディングガイドライン、ツール統合、CAP 統合、フォーム作成ルールを対象とします。

---

1. モジュールの読み込み - 重要

グローバルアクセスを使用しない

UI5 フレームワークのオブジェクト（例：sap.m.Button）に絶対にグローバルアクセスしないでください。非同期読み込みを行うため、依存関係は必ず明示的に宣言してください。

JavaScript

// ❌ WRONG - Global access
var oButton = new sap.m.Button();

// ✅ CORRECT - Explicit dependency
sap.ui.define(["sap/m/Button"], function(Button) {
    var oButton = new Button();
});

// ✅ CORRECT - Dynamic loading with sap.ui.require
sap.ui.require(["sap/m/MessageBox"], function(MessageBox) {
    MessageBox.show("Hello");
});

TypeScript

// ❌ WRONG - Global namespace
const button: sap.m.Button;

// ✅ CORRECT - Import module
import Button from "sap/m/Button";
const button: Button;

XML ビュー

<m:Button text="Click Me"/>


<ObjectListItem
    core:require="{
        Currency: 'sap/ui/model/type/Currency'
    }"
    number="{
        parts: ['invoice>Price', 'view>/currency'],
        type: 'Currency'
    }"/>

理由：適切な非同期読み込みを保証し、本番ビルドのパフォーマンスを向上させます。

参考資料：UI5 ドキュメントの「XML ビューおよびフラグメントでのモジュールの要求」ページ

---

2. コンポーネントの初期化

**初期（ルート）**コンポーネントを宣言的に初期化するには、sap/ui/core/ComponentSupport を使用します。

<script id="sap-ui-bootstrap"
    src="resources/sap-ui-core.js"
    data-sap-ui-on-init="module:sap/ui/core/ComponentSupport"
    data-sap-ui-async="true"
    data-sap-ui-resource-roots='{ "my.app": "./" }'>
</script>

<body class="sapUiBody">
    <div data-sap-ui-component 
         data-name="my.app" 
         data-id="container">
    </div>
</body>

参考資料：UI5 ドキュメントの「初期コンポーネントの宣言的 API」ページ

**注記：**ネストされたコンポーネントは、コンポーネント使用として管理してください（包含するコンポーネントの manifest.json で宣言します）。

---

3. データバインディングのベストプラクティス

組み込みデータ型を必ず使用する

ビューでデータバインディングを使用し、UI コントロールをデータまたは i18n モデルに接続してください。

優先順位：

1. OData 型（sap/ui/model/odata/type/*） - 推奨
2. シンプル型（sap/ui/model/type/*） - OData に相当する型がない場合のみ
3. カスタム型 - 特別な双方向バインディングのシナリオや複雑な検証に使用
4. カスタムフォーマッター - 独自のビジネスロジックに限り使用（片方向バインディング）

<Text text="{path: 'price', formatter: '.formatCurrency'}"/>


<Text text="{
    path: 'price',
    type: 'sap.ui.model.odata.type.Decimal',
    formatOptions: {
        style: 'currency',
        currencyCode: 'EUR'
    }
}"/>


<Text text="{
    path: 'quantity',
    type: 'sap.ui.model.odata.type.Decimal',
    formatOptions: {
        groupingEnabled: true
    }
}"/>

一般的な OData 型：

• sap.ui.model.odata.type.Decimal - 小数を含む数値
• sap.ui.model.odata.type.String - 文字数制限のあるテキスト
• sap.ui.model.odata.type.DateTime - 日付と時刻

一般的なシンプル型（OData に相当する型がない場合のみ使用）：

• sap.ui.model.type.DateInterval - 日付の範囲
• sap.ui.model.type.FileSize - ファイルサイズの書式設定

例：桁区切りを使用して数値を書式設定する場合は、sap.ui.model.type.Integer やカスタムフォーマッターよりも、formatOptions: {groupingEnabled: true} を指定した sap.ui.model.odata.type.Decimal を優先してください。

カスタム型を使用する場合

組み込み型では必要な検証または変換ロジックを提供できない特別な双方向バインディングのシナリオでは、カスタム型が必要です。

例：双方向バインディングによるメールアドレス検証用カスタム型

// controller/EmailType.js
sap.ui.define(["sap/ui/model/SimpleType"], function(SimpleType) {
    return SimpleType.extend("my.app.type.EmailType", {
        formatValue: function(oValue) {
            return oValue;
        },
        parseValue: function(oValue) {
            return oValue;
        },
        validateValue: function(oValue) {
            const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
            if (oValue && !emailRegex.test(oValue)) {
                throw new sap.ui.model.ValidateException("Invalid email format");
            }
        }
    });
});

ビューでの使用方法：

<Input value="{path: 'email', formatter: '.validateEmail'}"/>


<Input 
    core:require="{EmailType: 'my/app/type/EmailType'}"
    value="{
        path: 'email',
        type: 'EmailType'
    }"/>

カスタム型を使用する理由：

• ✅ 双方向バインディングをサポート（formatValue + parseValue + validateValue）
• ✅ ユーザーの入力に応じてリアルタイムで検証
• ✅ 有効な入力があると、モデルがただちに更新される
• ❌ カスタムフォーマッターは片方向（表示）バインディングでのみ動作

ビューでのデータバインディング

コントロールをモデルに接続するには、データバインディングを必ず使用してください。

<Input value="{/customer/name}"/>


<List items="{/products}">
    <StandardListItem title="{name}" description="{price}"/>
</List>


<Text text="{= ${quantity} * ${price} }" visible="{= ${stock} > 0 }"/>

---

4. 国際化（i18n）

翻訳ワークフローのガイドライン

.properties ファイルを変更する場合は、プロジェクトの種類に応じた適切なワークフローに従ってください。

開発およびテストの場合：

• i18n.properties（ベースファイル）のみ更新します
• 変更は開発環境にただちに反映されます

本番環境での翻訳ワークフロー：

• SAP S/4HANA アプリ：ローカライズファイル（i18n_de.properties、i18n_fr.properties など）を手動で編集することは絶対に避けてください
  • 翻訳は SAP 内部の翻訳プロセスを通じて処理されます
• SAP Translation Hub または Translation Export/Import（TEW）を使用するアプリ：ローカライズファイルには手を加えないでください
  • 翻訳はベースファイルから自動的に生成されます
• 手動翻訳のみを使用するアプリ：一貫性を保つため、すべてのロケールファイルに変更を適用します

理由：専門的な翻訳ワークフローでは、ベースの i18n.properties ファイルからローカライズファイルが生成されます。ローカライズファイルを手動で編集すると、翻訳プロセス中に上書きされます。

---

5. セキュリティ - コンテンツセキュリティポリシー

インラインスクリプトやインラインスタイルは使用しないでください

HTMLでインラインスクリプトやインラインスタイルを絶対に使用しないでください。UI5 アプリケーションで推奨されている CSP 設定に違反します。

<script>
    alert("Hello");
</script>

<style>
    .error { color: red; }
</style>

<div style="color: red;">Styled text</div>


<script src="controller/Main.controller.js"></script>
<link rel="stylesheet" href="css/style.css">


<div class="errorText">Styled text</div>

要件:

• アプリケーションのロジックはすべて専用の JS または TS ファイルに記述すること
• スタイルはすべて専用の CSS ファイルに記述すること
• インラインの <script> タグは CSP に違反します
• インラインの <style> タグは CSP に違反します
• インラインの style 属性は CSP に違反します

参考資料: UI5 ドキュメントページ「Content Security Policy」

---

6. TypeScript のイベント処理（UI5 >= 1.115.0）

コントロール固有のイベント型を使用する

UI5 1.115.0 以降では、コントロールのモジュールからイベント固有の型をインポートして使用してください。

パターン: <ControlName>$<EventName>Event（「Event」サフィックスに注意）

// ✅ CORRECT - Import specific event type
import { Button$PressEvent } from "sap/m/Button";
import { Table$RowSelectionChangeEvent } from "sap/ui/table/Table";
import Controller from "sap/ui/core/mvc/Controller";

export default class MainController extends Controller {
    public onPress(event: Button$PressEvent): void {
        const button = event.getSource();  // Correctly typed as Button
        // ...
    }
    
    public onRowSelectionChange(event: Table$RowSelectionChangeEvent): void {
        // Correctly typed: getParameter is known and return value inferred
        const selectedContext = event.getParameter("rowContext");
        // ...
    }
}

古いバージョン向けの代替方法

UI5 < 1.115.0：コントロール固有のイベント型は使用できません。汎用の Event 型を使用してください。

import Event from "sap/ui/base/Event";
import Controller from "sap/ui/core/mvc/Controller";

export default class MainController extends Controller {
    public onPress(event: Event): void {
        // Generic Event type for UI5 < 1.115.0
        // ...
    }
}

利点：手動で型キャストしなくても、イベントパラメーターの静的型チェックと自動補完が利用できます。

---

7. MCP ツールの統合

API の参照

UI5 コントロールと API の情報を取得するには、必ず get_api_reference ツールを使用してください。使用中の UI5 バージョンに対応するコントロール、クラス、名前空間の公式 API ドキュメントが返されます。

コードの検証

問題（非推奨 API、アクセシビリティの問題、バグ）を特定するには、必ず run_ui5_linter ツールを使用してください。

コードの修正

1. 必ず最初にユーザーの確認を得てください
2. run_ui5_linter ツールの fix パラメーターを使用してください
3. 提供されたコンテキスト情報を使って、残りの問題を手動で修正してください

ローカルサーバーの動作

重要：UI5 CLI 開発サーバーはデフォルトのインデックスファイルを提供しません。完全なパスを使用してください：http://localhost:8080/index.html

コード品質チェック

変更後は、プロジェクトのリンター（npm run lint、eslint .、または ui5lint .）を実行してください。コミットする前に、すべてのエラーを修正してください。

---

8. CAP との統合

CAP（Cloud Application Programming Model）プロジェクト内に UI5 プロジェクトを作成する場合：

プロジェクトの配置場所

UI5 プロジェクトは必ず、CAP プロジェクトのルートにある app/ ディレクトリ内に作成してください。

cap-project/
├── app/                    # ← UI5 apps go here
│   └── my-ui5-app/
├── srv/                    # CAP services
├── db/                     # Database models
└── package.json

サービス情報

サービス情報の取得：

• CDS ツールが利用できる場合：定義、サービス、エンドポイントの取得に使用してください
• CDS ツールが利用できない場合：次のコマンドを実行してください

  cds compile '*'                        # Get definitions
  cds compile '*' --to serviceinfo       # Get services and endpoints
  

サービスとの統合

UI5 プロジェクトを作成する際は、必ず以下を指定してください。

• 絶対 OData V4 サービス URL
• 対象エンティティセット

プラグインのインストール

必ず CAP プロジェクトのルートで実行してください。

npm i -D cds-plugin-ui5

このプラグインは UI5 アプリケーションの提供を自動的に処理します。

サーバーの実行

# ❌ WRONG - Never run separate UI5 server
cd app/my-ui5-app
ui5 serve                    # Don't do this!
npm start                    # Don't do this!

# ✅ CORRECT - Run from CAP project root
cds watch                    # Serves both backend and UI5 apps
# or
cds run                      # Alternative command

理由：1つのコマンドでバックエンドサービスとすべての UI5 アプリケーションを、同じオリジン（http://localhost:4004）から提供できます。

データ接続

ui5.yaml で ui5-middleware-simpleproxy を絶対に設定しないでください。

# ❌ WRONG - No proxy needed
server:
  customMiddleware:
    - name: ui5-middleware-simpleproxy    # Don't add this!

理由：cds watch により UI とサービスが同じオリジンから提供されるため、プロキシは不要です。

アプリへのアクセス

CAP のランチページ（通常は http://localhost:4004）で、次を確認してください。

• 利用可能なサービスの一覧
• UI5 アプリケーションへのリンク

---

9. フォーム作成ルール

SimpleForm は使用しない（明示的に要求された場合を除く）

<form:SimpleForm>
    <Label text="Name"/>
    <Input value="{name}"/>
</form:SimpleForm>


<form:Form editable="true">
    <form:layout>
        <form:ColumnLayout
            columnsM="2"
            columnsL="3"
            columnsXL="4"/>
    </form:layout>
    <form:formContainers>
        <form:FormContainer title="Personal Data">
            <form:formElements>
                <form:FormElement label="Name">
                    <form:fields>
                        <Input value="{name}"/>
                    </form:fields>
                </form:FormElement>
            </form:formElements>
        </form:FormContainer>
    </form:formContainers>
</form:Form>

デフォルトの列設定

別途指定がない限り、必ず次のデフォルト値を使用してください。

• M サイズ：2列
• L サイズ：3列
• XL サイズ：4列

---

ドキュメントの参考資料

詳細については、次の UI5 ドキュメントページを参照してください。

• 「Require Modules in XML View and Fragment」
• 「Declarative API for Initial Components」
• 「Content Security Policy」
• 公式 UI5 API リファレンス（get_api_reference ツールを使用）

---