コンテキスト オブジェクト
イベント ハンドラーを作成し、クライアント スクリプト API を使用する場合は、使用可能なコンテキスト オブジェクトとそれらの使用方法を理解しておく必要があります。 コンテキスト オブジェクトは、コードが実行されているコンテキストに関する情報を提供するために使用します。 このコンテキストにより、ロジック内の情報をハードコーディングする必要がなくなります。 このコンテキストにより、さらに汎用的な関数を作成でき、関数が現在の UI コンポーネントの特定のレイアウト構造の影響を受けにくくなります。
実行コンテキスト
イベント ハンドラーを登録するときは、最初のパラメーターとして実行コンテキストを渡すことができます。 フォームのプロパティを使用してイベント ハンドラーを登録する場合は、このオプションを有効にすることができます。 この画像は、OnLoad ハンドラーを登録し、実行コンテキストを有効にする方法を示しています。
通常、フォームのプロパティを使用してイベント ハンドラーを登録する場合は、常にこのオプションを選択することをお勧めします。 コードを使用してイベント ハンドラーを登録する場合は、このオプションが自動的に選択されます。
最初のパラメーターとして実行コンテキストを取得する関数定義は、次のようになります。
実行コンテキストの最も一般的な用途は、フォーム コンテキストとグリッド コンテキストの取得です。 このコンテキストでのもう 1 つの有用なメソッドは、getEventSource です。 イベント ソースは、イベントが発生したオブジェクトへの参照を返します。 このオブジェクトにより、実行時にイベント ソースを調べる汎用ハンドラーを記述して、イベントが発生したコントロールを特定することができます。 このオブジェクトは、各コントロールに対して別個のイベント ハンドラーを登録する代わりに、複数のコントロールのイベントに登録される 1 つのメソッドを記述する場合に役立ちます。
フォーム コンテキスト
クライアント API フォーム コンテキスト (formContext) は、フォームまたはフォーム上の項目 (クイック ビュー コントロールや、編集可能なグリッド内の行など) を参照します。このフォームに対して現在のコードが実行されます。 getFormContext 関数を使用すると、実行コンテキストから formContext オブジェクトを取得できます。
フォーム コンテキストよりも前には、global Xrm.Page で項目またはフォームを使用することができました。 最新バージョンでは、Xrm.Page オブジェクトは推奨されません。適切なフォームまたはフォーム上の項目への参照を返すには、実行コンテキスト オブジェクトで渡される getFormContext メソッドを使用する必要があります。 したがって、次のようなコードは記述しません。
var firstName = Xrm.Page.getAttribute("firstname").getValue();
代わりに、formContext を使用して次のコードを記述します。
var formContext = executionContext.getFormContext();
var firstName = formContext.getAttribute("firstname").getValue();
詳細については、Xrm.Page の廃止に関するページを参照してください。
次の図は、フォーム コンテキストで使用できるプロパティとメソッドの概要を示しています。
データ オブジェクト
データ オブジェクト (formContext.data) は、フォーム内のテーブルおよびプロセス データの操作に使用します。
次の表は、データ オブジェクトに含まれているオブジェクトとコレクションの概要を示しています。
| 名前 | 説明 |
|---|---|
| 属性 | フォーム上のエンティティ以外のデータのコレクション。 このコレクションの項目のデータ型はエンティティ上の属性コレクションと同じですが、フォーム テーブルの属性ではないことに注意する必要があります。 |
| エンティティ | ページに表示される行に固有の情報を取得するためのメソッド、save メソッド、およびフォームに含まれるすべての属性のコレクションを提供します。 属性データは、エンティティ構成で使用可能なすべてのフィールドとは異なり、フォーム上のフィールドによって表される属性に限定されます。 詳細については、「formContext.data.entity」を参照してください。 |
| プロセス | フォーム上のビジネス プロセス フロー データを操作するためのオブジェクトおよびメソッドを提供します。 詳細については、formContext.data.process を参照してください。 |
UI オブジェクト
UI オブジェクト (formContext.ui) は、ユーザー インターフェイスに関する情報を取得するメソッドと、フォームまたはグリッドの複数のサブ コンポーネントのコレクションを提供します。
次の表は、UI オブジェクトに含まれているオブジェクトとコレクションを要約しています。
| 名前 | 説明 |
|---|---|
| コントロール | ページ上のすべてのコントロールのコレクション。 コレクション、コントロール、およびコレクション内のコントロール オブジェクトについては、「コレクション」を参照してください。 |
| FormSelector | 現在使用中のフォームに関する情報を取得するには、formSelector.getCurrentItem メソッドを使用します。 ユーザーが使用できるすべてのフォームに関する情報を返すには、formSelector.items コレクションを使用します。 |
| ナビゲーション | ページ上のすべてのナビゲーション品目のコレクション。 コレクション内の項目に関する情報については、formContext.ui.navigation 項目 を参照してください。 タブレット PC 用 Microsoft Dynamics 365 では、ナビゲーションは使用できません。 全体的なアプリケーションのナビゲーションを自動化するために、Xrm.Navigation 名前空間を使用する傾向があります。 |
| プロセス | 可視性の設定など、フォーム上のビジネス プロセス フロー制御を操作するためのオブジェクトおよびメソッドを提供します。 詳細については、formContext.ui.process を参照してください。 |
| QuickForms | フォーム上のすべての簡易表示コントロールのコレクション。 詳細については、formContext.ui.quickForms を参照してください。 |
| タブ | ページ上のすべてのタブのコレクション。 コレクション内の品目に関する情報については、「formContex.ui.tabs」を参照してください。 |
一般的に、テーブル列の値を取得または設定する必要がある場合は、UI オブジェクトの代わりにデータ オブジェクトを使用します。 データ オブジェクトには、テーブル列の値を表す 1 つの属性のみが含まれます。 UI オブジェクトを使用すると、フォーム上の同じテーブル列に対して複数のコントロールを、それぞれの属性への参照と共に使用できます。 したがって、データ オブジェクトを使用する方が簡単に属性 (値) を操作できます。一方、フォーム上の属性を表すコントロールを操作する場合は、UI オブジェクトを使用する方が簡単です。
スクリプトでコンテキスト オブジェクトを使用すると、フォームやクライアント API での変更に対する回復性が高まります。