fix-xml-globals

XML ビュー／フラグメントのグローバルアクセスを修正する

このスキルは、UI5 リンターで検出されるものの、モジュールパスとハンドラーの場所を理解する必要があるため自動修正できない XML ビューとフラグメントの問題を修正します。

対応するリンタールール

ルール ID	メッセージのパターン	このスキルでの対応
no-globals	グローバル変数「...」（...）へのアクセス	core:require を追加し、ローカル名を使用する
no-ambiguous-event-handler	イベントハンドラー「...」には、ドット「.」を付けるか、ローカル名を指定する必要があります	コントローラーメソッドに . を付けるか、モジュールに core:require を追加する
no-deprecated-api	テンプレートの require におけるスペース区切りのリスト「...」の使用	オブジェクト記法に変換する

使用するタイミング

次のようなリンター出力が表示された場合に、このスキルを適用します。

Main.view.xml:15:5 error Access of global variable 'formatter' (my.app.model.formatter)  no-globals
Main.view.xml:20:5 warning Event handler 'onPress' must be prefixed by a dot '.' or refer to a local name  no-ambiguous-event-handler
Main.view.xml:25:5 error Usage of space-separated list 'formatter helper' in template:require  no-deprecated-api

修正方法

1. no-globals - core:require でグローバル変数へのアクセスを修正する

フォーマッター、型、ユーティリティ関数がグローバル名前空間（例：my.app.formatter.formatDate）経由でアクセスされている場合は、core:require 宣言を追加し、ローカル名を使用します。

手順 1：xmlns:core 名前空間がない場合は追加する

<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns:core="sap.ui.core"
    xmlns="sap.m">

手順 2：モジュールを使用する最も近いコントロールに core:require を追加する

core:require は、グローバル参照を使用するコントロールに指定します。複数のコントロールが同じモジュールを使用する場合は、それらに共通する最も近い祖先に指定します。詳細は、下記の「core:require の配置ルール」セクションを参照してください。

<Text core:require="{formatter: 'my/app/model/formatter'}"
      text="{path: 'date', formatter: 'formatter.formatDate'}" />

<VBox core:require="{formatter: 'my/app/model/formatter'}">
    <Text text="{path: 'date', formatter: 'formatter.formatDate'}" />
    <Text text="{path: 'name', formatter: 'formatter.formatName'}" />
</VBox>

手順 3：参照を更新してローカル名を使用する

<Text text="{path: 'date', formatter: 'my.app.model.formatter.formatDate'}" />


<Text text="{path: 'date', formatter: 'formatter.formatDate'}" />

手順 4：this を使用するフォーマッターには .bind($control) を追加する

フォーマッター関数が内部で this にアクセスする場合は、コントロールのコンテキストを保持するために .bind($control) を追加します。これはフォーマッターにのみ適用されます。イベントハンドラーやファクトリー関数には .bind($control) を追加しないでください。

<Text core:require="{formatter: 'my/app/model/formatter'}"
      text="{path: 'name', formatter: 'formatter.formatWithContext.bind($control)'}" />

2. no-ambiguous-event-handler - イベントハンドラーを修正する

イベントハンドラーは、次のいずれかである必要があります。

• コントローラーメソッドを示すため、ドット（.）で始まる
• ローカル名で読み込まれたモジュールを使用する

コントローラーメソッド（ドットを先頭に追加）：

<Button press="onPress" />


<Button press=".onPress" />

モジュールのメソッド（core:require を使用）：

<Button press="my.app.util.Handler.onPress" />


<mvc:View
    core:require="{
        Handler: 'my/app/util/Handler'
    }">
    <Button press="Handler.onPress" />
</mvc:View>

3. no-deprecated-api - 古い template:require 構文を修正する

スペース区切りのモジュールリストをオブジェクト記法に変換します。

<template:require name="formatter helper" />


<template:require name="{
    formatter: 'my/app/model/formatter',
    helper: 'my/app/util/helper'
}" />

4. 複数のグローバル参照に対応する

複数のグローバル変数を使用する場合は、それらに共通する最も近い祖先に、1 つの core:require をまとめて指定します。

<mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns:core="sap.ui.core"
    xmlns="sap.m"
    core:require="{
        formatter: 'my/app/model/formatter',
        types: 'my/app/model/types',
        utils: 'my/app/util/utils'
    }">

5. no-globals - バインディングの型プロパティを修正する

バインディングオブジェクトの type プロパティでグローバル変数を使用する場合も、core:require が必要です。

<Input value="{
    path: '/amount',
    type: 'sap.ui.model.type.Currency'
}" />


<Input core:require="{Currency: 'sap/ui/model/type/Currency'}"
       value="{
           path: '/amount',
           type: 'Currency'
       }" />

これは、すべての UI5 の型（Currency、Date、Float、Integer、String など）とカスタム型クラスに適用されます。

6. no-globals - ファクトリー関数を修正する

ファクトリー関数（例：List の factory 属性）にも同じ core:require の方法を使用しますが、.bind($control) は決して使用しません。

<List items="{/items}" factory="my.app.util.ListFactory.createItem" />


<List core:require="{ListFactory: 'my/app/util/ListFactory'}"
      items="{/items}" factory="ListFactory.createItem" />

core:require の配置ルール

core:require で宣言したモジュールにアクセスできるのは、その要素とその子孫要素のみです。兄弟要素からはアクセスできません。

• 1 つのコントロールがモジュールを使用する場合：そのコントロールに直接 core:require を指定する
• 複数のコントロールが同じモジュールを使用する場合：それらに共通する最も近い祖先に core:require を指定する
• すべてのコントロールが View の直接の子要素である場合：View のルートに指定しても問題ありません

常にルートに指定するのではなく、より細かい範囲に指定することを推奨します。不要なスコープを減らし、使用箇所で依存関係を明確にできます。

ネストした要素間での細かな配置や、兄弟要素間でのスコープエラーなど、詳しい例については references/placement-and-binding.md を参照してください。

.bind($control) を使用するタイミング

core:require 経由で関数を呼び出しても、this コンテキストは自動的に設定されません。.bind($control) を追加するかどうかは、使用箇所の種類（フォーマッター、ファクトリー、イベントハンドラー）によって異なります。

使用箇所の種類	.bind($control)	理由
フォーマッター（{path:..., formatter:'...'} または {parts:[...], formatter:'...'} 内）	はい。関数が this を使用する場合	this はバインディングを所有するコントロールインスタンスです。実行時に $control は ManagedObject に解決されます。
ファクトリー（集約バインディングの factory= 属性）	いいえ。.bind() は追加しません	ファクトリー関数はパラメーターとして (sId, oContext) を受け取ります。コントロールコンテキストに this は使用しません。.bind() の追加は不要であり、誤りです。
イベントハンドラー（press=、change=、confirm=、select=、valueHelpRequest= など）	いいえ。.bind() は追加しません	core:require を使用した XML のイベントハンドラー解決では、イベントをパラメーターとして関数を直接呼び出します。.bind() を追加すると、この解決が妨げられます。

XML で使用箇所の種類を判別する方法：

• フォーマッター：バインディング式内に記述されています — {path:..., formatter:'Module.fn'} または {parts:[...], formatter:'Module.fn'}
• ファクトリー：集約バインディングの factory='Module.fn' 属性として記述されています
• イベントハンドラー：press=、change=、confirm=、cancel=、select=、selectionChange=、valueHelpRequest=、tokenUpdate=、close=、delete=、titlePress= などのイベント属性として記述されています

フォーマッター固有のルール：

• 関数の実装を確認します。this を使用する場合は、.bind($control) を追加します
• 常に $control を使用します（$controller は使用しません）。これによりコントロールインスタンスにバインドされます
• 関数が this を使用しない場合は、.bind($control) を省略します

<Text core:require="{formatter: 'my/app/model/formatter'}"
      text="{path: 'name', formatter: 'formatter.formatWithContext.bind($control)'}" />


<Text core:require="{formatter: 'my/app/model/formatter'}"
      text="{path: 'date', formatter: 'formatter.formatDate'}" />


<List core:require="{ListFactory: 'my/app/util/ListFactory'}"
      items="{/items}" factory="ListFactory.createItem" />


<Button core:require="{Handler: 'my/app/util/Handler'}"
        press="Handler.onExport" />

検出には scripts/verify-this-bind.js audit-fn を実行してください。 このスクリプトは、メンバーアクセス、動的プロパティ、裸の引数（jQuery.proxy(fn, this)、.call(this)、.apply(this)、.bind(this)）、別名（var self = this; self.foo）、アロー関数で継承されたものなど、あらゆる形式の this を一度に処理します。コメントと文字列リテラルは除外されます。ネストされた非アロー関数の本体は除外されます（独自の this を持つため）。アロー関数の本体は保持されます（this を継承するため）。標準の UI5 型（sap.ui.model.type.*）にはバインドが不要であり、スクリプトでそのことを確認できます。一括判断に手動の grep を使うことはできません。このスクリプトを正としてください。

node scripts/verify-this-bind.js audit-fn --file <module.js> --fn <name> [--fn <name> ...]

USES_THIS と報告された関数には、XML で .bind($control) を追加する必要があります。NO_THIS と報告された関数には追加してはいけません。名前の形で分類してはいけません。formatX／decideX／isX という名前だけでは、純粋な値を扱うフォーマッターである証拠になりません。判定の根拠となるのはソース本体のみです。

grep ではなくスクリプトを使う理由：this\.（ドット形式）を検索しても、ドットのない裸の this を使う書き方は見落とされます。jQuery.proxy(fn, this) は、ドットのない位置引数として this を渡します。目視確認や単純な grep では見過ごされ、フォーマッターが純粋に見えて .bind($control) が省略されます。実行時には、プロキシされたコールバックのコンテキストが誤ったものになり、this.getModel(...) が例外を発生させます。このスクリプトは \bthis\b のスキャンと別名の追跡を組み合わせ、すべての形式を一度に検出します。スクリプトが利用できない場合に限り、grep -nE '\bthis\b' <module.js> を代わりに使用してください。

フォーマッター、ハンドラー、ファクトリーの変更前後の例については、references/placement-and-binding.md を参照してください。

FragmentDefinition の処理

フラグメントでは <mvc:View> の代わりに <core:FragmentDefinition> を使用します。同じ配置原則が適用されますが、重要な違いが1つあります。

core:require は FragmentDefinition ではなく、子コントロールに配置してください。 FragmentDefinition は構造上のラッパーであり、実際のコントロールではありません。core:require は、その内部にある実際のルートコントロール（例：Dialog、VBox）か、そのモジュールを使用するコントロールの最も近い共通の祖先に配置してください。

<core:FragmentDefinition xmlns="sap.m" xmlns:core="sap.ui.core">
    <Dialog title="Settings"
            core:require="{formatter: 'my/app/model/formatter', Actions: 'my/app/util/Actions'}">
        <content>
            <Input value="{path: 'name', formatter: 'formatter.toUpperCase'}" />
            <Button text="Save" press="Actions.onSave" />
        </content>
    </Dialog>
</core:FragmentDefinition>

例外： フラグメントに、同じモジュールを必要とする直接の子が複数ある場合、FragmentDefinition が最も近い共通の祖先となるため、そこに core:require を配置しても問題ありません。

複数の子を持つフラグメントと、フラグメント内でスコープ指定されたモジュールの例については、references/placement-and-binding.md を参照してください。

その他のエッジケース

名前の競合

複数のモジュールで同じクラス名が使われている場合は、わかりやすいエイリアスを使用してください。

<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" xmlns:core="sap.ui.core"
          core:require="{
              ReportFormatter: 'my/app/report/Formatter',
              KPIFormatter: 'my/app/kpi/Formatter'
          }">
    <Input value="{path: 'report', formatter: 'ReportFormatter.format'}" />
    <Text text="{path: 'kpi', formatter: 'KPIFormatter.format'}" />
</mvc:View>

複数パートのフォーマッター／式バインディング

複数パートのバインディングと式バインディングにも、同じ core:require パターンが適用されます。ドット区切りのグローバル名をローカルエイリアスに置き換えるだけです。式バインディングの例：

<Text text="{= formatter.formatCount(${/count})}" />

XML 内のアプリ名前空間グローバル

UI5 リンターは、no-globals ルールの下で XML 内のアプリ名前空間グローバルを報告します。このルールは sap.* および jQuery.* グローバルにも使用されます。このスキルは、以下を含む XML ファイル内のすべての no-globals を処理します。

1. sap 名前空間 — sap.m.ButtonType.Accept、sap.ui.model.type.Currency → モジュールに対して core:require を指定します
2. jQuery 名前空間 — jQuery.sap.getModulePath → core:require を指定します
3. アプリ名前空間のイベントハンドラー — com.example.app.utils.Handler.onPress → ユーティリティモジュールに対して core:require を指定します
4. アプリ名前空間のフォーマッター — com.example.app.model.formatter.formatDate → フォーマッターモジュールに対して core:require を指定します

すべての修正パターンは同じです。モジュールパス（ドットをスラッシュに置換）を指定した core:require 属性を追加し、ドット区切りのグローバル名をローカルエイリアスに置き換えます。

修正前：

<core:FragmentDefinition xmlns="sap.m" xmlns:core="sap.ui.core">
    <Button press="com.example.app.utils.Handler.onPress" />
</core:FragmentDefinition>

修正後：

<core:FragmentDefinition xmlns="sap.m" xmlns:core="sap.ui.core">
    <Button core:require="{Handler: 'com/example/app/utils/Handler'}"
            press="Handler.onPress" />
</core:FragmentDefinition>

「.bind($control) を使用する場合」セクションのルールを適用してください。フォーマッター：はい（関数が this を使用する場合）、ファクトリー：使用しない、イベントハンドラー：使用しない。

重要： XML のアプリ名前空間グローバルを fix-linter-blind-spots（フェーズ3、ステップ3.2）に回さないでください。このスキルが処理するのは、リンターが検出できない JS のアプリ名前空間グローバルのみです。XML のアプリ名前空間グローバルはリンターによって報告されるため、フェーズ3で必ず修正してください。

実装手順

1. XML のビュー／フラグメントファイルを読み込みます

2. ルール ID ごとにリンターエラーを特定するため、解析します：

   • no-globals：バインディング内のグローバル名前空間への参照（フォーマッター、型、イベントハンドラー、ファクトリー）
   • no-ambiguous-event-handler：適切なプレフィックスが付いていないイベントハンドラー
   • no-deprecated-api：レガシーな template:require 構文

3. no-globals エラーの場合：

   • ルート要素に xmlns:core="sap.ui.core" がない場合は追加します
   • モジュールパスを特定します：ドット区切り表記をスラッシュ区切り表記に変換します（例：my.app.formatter → my/app/formatter）
   • 配置場所を特定します：そのモジュールを使う最も近いコントロール、または複数のコントロールが使う場合は最も近い共通の祖先を見つけます
   • フラグメントの場合：FragmentDefinition ではなく、実際のルートコントロール（例：Dialog）に core:require を配置することを優先します
   • フォーマッターごとのソース監査は必須です。 このバッチで名前を変更するフォーマッターごとに、node scripts/verify-this-bind.js audit-fn --file <module.js> --fn <name> [--fn <name> ...] を実行します（ファイルにあるフォーマッターの数だけ --fn フラグを指定し、まとめて実行します）。USES_THIS と報告された関数は、XML のフォーマッター参照の末尾に .bind($control) を追加する必要があります。NO_THIS と報告された関数には追加してはいけません。ファクトリーとイベントハンドラーは、this の使用状況にかかわらず、バインドしてはいけません。
   • 必要なモジュールをすべて含む core:require オブジェクトを作成します（名前が競合する場合はエイリアスを使用します）
   • すべての参照をローカル名を使うように更新します

4. no-ambiguous-event-handler エラーの場合：

   • リンターが報告した line:col を使って、該当する属性を特定します。その行だけを読み込みます。
   • その座標にある値だけを編集します。ハンドラー名が単独の場合は先頭に . を付けます。名前空間パスの場合は core:require とエイリアス置換を適用します。
   • 同じハンドラー名文字列がほかにないか、ファイル内を検索してはいけません。リンターは違反箇所をすべて列挙済みです。文字列が別の場所にあり、報告されていない場合は、別の属性（id、selectedKey、key、name、プレーンテキストなど）であり、変更してはいけません。リンターの検出箇所 1 つにつき、編集は 1 つです。

5. no-deprecated-api（template:require）の場合：

   • スペース区切りのリストをオブジェクト表記に変換します

6. 更新したファイルを書き込みます

7. 編集後の検証（必須）。 この段階の XML 編集をすべて完了した後、完了と判断する前に、次を実行します：

   node scripts/verify-this-bind.js verify-xml \
       --xml-root webapp \
       --js-roots webapp/utils,webapp/model
   

   終了コード 0 → 完了です。終了コード 1 → 報告された MISSING_BIND 違反を修正し、再実行します。このスクリプトが合否判定の基準です。エージェントが目視で判断してはいけません。

修正例

例 1：基本 — フォーマッター + イベントハンドラー

リンターの出力が次の場合：

Main.view.xml:15:5 error Access of global variable 'formatter' (my.app.model.formatter)  no-globals
Main.view.xml:20:5 warning Event handler 'onPress' must be prefixed by a dot '.' or refer to a local name  no-ambiguous-event-handler

Main.view.xml の変換：

<mvc:View
    controllerName="my.app.controller.Main"
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m">
    <Page title="Main">
        <content>
            <Text text="{path: 'date', formatter: 'my.app.model.formatter.formatDate'}" />
            <Button text="Submit" press="onPress" />
        </content>
    </Page>
</mvc:View>


<mvc:View
    controllerName="my.app.controller.Main"
    xmlns:mvc="sap.ui.core.mvc"
    xmlns:core="sap.ui.core"
    xmlns="sap.m"
    core:require="{
        formatter: 'my/app/model/formatter'
    }">
    <Page title="Main">
        <content>
            <Text text="{path: 'date', formatter: 'formatter.formatDate'}" />
            <Button text="Submit" press=".onPress" />
        </content>
    </Page>
</mvc:View>

例 2：応用 — 詳細な配置、型バインディング、.bind($control)

リンターの出力が次の場合：

OrderDetail.view.xml:8:9 error Access of global variable 'formatter' (my.app.model.formatter)  no-globals
OrderDetail.view.xml:10:13 error Access of global variable 'Currency' (sap.ui.model.type.Currency)  no-globals
OrderDetail.view.xml:14:13 error Access of global variable 'Handler' (my.app.util.Handler)  no-globals
OrderDetail.view.xml:18:9 warning Event handler 'onBack' must be prefixed by a dot '.'  no-ambiguous-event-handler

<mvc:View controllerName="my.app.controller.OrderDetail"
    xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m">
    <Page title="Order">
        <content>
            <Text text="{path: 'status', formatter: 'my.app.model.formatter.formatStatus'}" />
            <VBox>
                <Input value="{path: '/amount', type: 'sap.ui.model.type.Currency'}" />
                <Text text="{path: 'note', formatter: 'my.app.model.formatter.formatNote'}" />
            </VBox>
        </content>
        <footer>
            <Bar>
                <contentRight>
                    <Button text="Export" press="my.app.util.Handler.onExport" />
                </contentRight>
            </Bar>
        </footer>
        <headerContent>
            <Button press="onBack" icon="sap-icon://nav-back" />
        </headerContent>
    </Page>
</mvc:View>


<mvc:View controllerName="my.app.controller.OrderDetail"
    xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" xmlns:core="sap.ui.core">
    <Page title="Order"
          core:require="{formatter: 'my/app/model/formatter'}">
        <content>
            <Text text="{path: 'status', formatter: 'formatter.formatStatus'}" />
            <VBox>
                <Input core:require="{Currency: 'sap/ui/model/type/Currency'}"
                       value="{path: '/amount', type: 'Currency'}" />
                <Text text="{path: 'note', formatter: 'formatter.formatNote'}" />
            </VBox>
        </content>
        <footer>
            <Bar>
                <contentRight>
                    <Button core:require="{Handler: 'my/app/util/Handler'}"
                            text="Export" press="Handler.onExport" />
                </contentRight>
            </Bar>
        </footer>
        <headerContent>
            <Button press=".onBack" icon="sap-icon://nav-back" />
        </headerContent>
    </Page>
</mvc:View>

配置の判断：

• formatter は content 内の 2 つの <Text> コントロールで使用されているため、Page に core:require を配置します（最も近い共通の祖先）。
• Currency は 1 つの <Input> でのみ使用されているため、Input に直接 core:require を配置します。
• Handler はフッター内の 1 つの <Button> でのみ使用されているため、Button に直接 core:require を配置します。
• Handler.onExport はイベントハンドラーです。イベントハンドラーに .bind($control) は不要です。
• onBack はシンプルなコントローラーメソッドのため、ドットのプレフィックスを追加します。

注意事項

• モジュールを使用する最も近いコントロール、または複数のコントロールで共有する場合は最も近い共通の祖先に core:require を配置します。ルートに常に配置するのではなく、細かく配置することを優先してください

• core:require のモジュールパスには、ドットではなくスラッシュ（/）を使用します

• JSON オブジェクト表記では、複数のモジュールをカンマで区切ります

• クラス名が同じモジュール間で名前が競合しないよう、内容が分かるエイリアスを使用します

• まず使用タイプを必ず確認してください。関数が this を使用する場合、フォーマッターには .bind($control) が必要なことがあります。ファクトリーとイベントハンドラーには不要です

• フラグメントの場合、FragmentDefinition ではなく実際の子コントロール（例：Dialog）に core:require を配置します。ただし、共通の祖先が FragmentDefinition だけの場合は除きます

• フォーマッター／ユーティリティモジュールが指定されたパスに存在することを確認します

• 動的なモジュール読み込みを伴う複雑なケースでは、代わりにコントローラー内で sap.ui.require を使用することを検討してください

• this の検出に名前のパターンによる近道を使うことは禁止されています。 formatX、decideX、isX、getX などのフォーマッター名は、値だけを扱う処理である証拠にはなりません。一見、値だけを扱うように見えても this を読み取るよくあるパターン：

  • this.getModel(...)、this.getBindingContext()、this.getId() を使って、コンテキストに紐づいた状態を読み取る（ヘルパーの分岐内で使われることもよくあります）
  • jQuery.proxy(fn, this)、fn.call(this)、fn.apply(this)、fn.bind(this) など、コールバックラッパーに単独の this を渡す（this の後に . がないため、ざっと読むとメンバーアクセスがないように見えます）
  • 先に this に別名を付ける（var self = this; ... self.getX()）。この場合、別名を付けた行の後、フォーマッター本体には this が出てきません

  これらはいずれも、フォーマッターが .bind($control) なしで呼び出されると実行時エラーになります。デフォルトでは this がコントロールにバインドされないためです。verify-this-bind.js スクリプトはこれらすべての形式を一度に検出します。目視確認や grep 'this\\.' では見落とします。スクリプトを必ず実行してください。名前を理由に実行を省略してはいけません

• no-ambiguous-event-handler および no-globals の識別子名変更では、リンターが示す位置情報を正とします。 警告された識別子の「すべての使用箇所」を見つけるために、grep やファイル全体に対する正規表現を使ってはいけません。リンターはすでに検索を行っており、問題のある箇所はすべて出力に示されています。リンターの出力にない行を編集することは対象範囲外であり、ほぼ確実に誤りです。イベントハンドラー名として現れる名前が、コントロールの id、selectedKey、バインディングパス、文字列リテラルにも使われている場合があります。これらはハンドラーではなく、書き換えると実行時の動作が予期せず変わります（例：Fragment.byId の検索が壊れる）。例外：core:require の追加はファイル単位で判断します（最も近い共通の祖先に一度配置）。各ファイルにつき一度適用し、検出箇所ごとには適用しません。

関連スキル

• fix-xml-native-html：XML ビューでネイティブ HTML／SVG を置き換える場合（no-deprecated-api のメッセージに「native HTML」または「SVG」が含まれる場合）は、fix-xml-native-html を使用します
• fix-js-globals：JavaScript ファイル（コントローラー／ユーティリティのグローバルアクセス）における no-globals には、fix-js-globals を使用します。このスキルでは、XML 修正に相当する JavaScript 側の処理を行います