コンテキスト オブジェクト
イベント ハンドラーを作成し、クライアント スクリプト API を使用する場合は、使用可能なコンテキスト オブジェクトとそれらの使用方法を理解しておく必要があります。 コンテキスト オブジェクトは、コードが実行されているコンテキストに関する情報を提供するために使用します。 このコンテキストにより、ロジック内の情報をハードコーディングする必要がなくなります。 コンテキストにより、さらに汎用的な関数を作成でき、関数が現在の UI コンポーネントの特定のレイアウトの影響を受けにくくなります。
実行コンテキスト
イベント ハンドラーを登録するときは、最初のパラメーターとして実行コンテキストを渡すことができます。 フォームのプロパティを使用してイベント ハンドラーを登録する場合は、このオプションを有効にすることができます。 この画像は、OnLoad ハンドラーを登録し、実行コンテキストを有効にする方法を示しています。
通常、フォームのプロパティを使用してイベント ハンドラーを登録する場合は、常にこのオプションを選択することをお勧めします。 コードを使用してイベント ハンドラーを登録する場合は、このオプションが自動的に選択されます。
最初のパラメーターとして実行コンテキストを取得する関数定義は、次のようになります。
実行コンテキストの最も一般的な用途は、フォーム コンテキストとグリッド コンテキストの取得です。 このコンテキストでのもう 1 つの有用なメソッドは、getEventSource です。 イベント ソースは、イベントをトリガーしたオブジェクトへの参照を返します。 このオブジェクトにより、実行時にイベント ソースを調べる汎用ハンドラーを記述して、イベントの発生をトリガーしたコントロールを特定することができます。 このオブジェクトは、コントロールごとに別個のイベント ハンドラーを作成するのではなく、複数のコントロールのイベントに登録できる単一のメソッドを記述する場合に役立ちます。 たとえば、複数のフィールドに対する OnChange イベントがある場合は、getEventSource を使用して、イベントをトリガーしたフィールドを特定し、そのイベントを適切に使用できます。
フォーム コンテキスト
クライアント 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 オブジェクトのオブジェクトとコレクションを要約しています。
| 名前 | 説明 |
|---|---|
| Controls | ページ上のすべてのコントロールのコレクション。 コレクション、コントロール、およびコレクション内のコントロール オブジェクトについては、コレクションを参照してください。 |
| FormSelector | フォームに関する情報を取得する方法。 現在使用中のフォームに関する情報を取得するには、formSelector.getCurrentItem メソッドを使用します。 ユーザーが使用できるすべてのフォームに関する情報を返すには、formSelector.items コレクションを使用します。 |
| Navigation | ページ上のすべてのナビゲーション品目のコレクション。 コレクション内の項目に関する情報については、formContext.ui.navigation 項目を参照してください。 タブレット PC 用 Microsoft Dynamics 365 では、ナビゲーションは使用できません。 全体的なアプリケーションのナビゲーションを自動化するために、Xrm.Navigation 名前空間を使用する傾向があります。 |
| Process | 可視性の設定など、フォーム上のビジネス プロセス フロー制御を操作するためのオブジェクトおよびメソッド。 詳細については、formContext.ui.process を参照してください。 |
| QuickForms | フォーム上のすべての簡易表示コントロールのコレクション。 詳細については、formContext.ui.quickForms を参照してください。 |
| Tabs | ページ上のすべてのタブのコレクション。 コレクション内の品目に関する情報については、formContex.ui.tabs を参照してください。 |
一般的に、テーブル列の値を取得または設定するには、UI オブジェクトの代わりにデータ オブジェクトを使用します。 データ オブジェクトには、テーブル列の値を表す 1 つの属性のみが含まれます。 比較すると、UI オブジェクトにはフォーム上の同じテーブル列に対して複数のコントロールがあり、それぞれに属性への参照があります。 したがって、データ オブジェクトを使用する方が簡単に属性 (値) を操作できます。一方、フォーム上の属性を表すコントロールを操作する場合は、UI オブジェクトを使用する方が簡単です。
スクリプトでコンテキスト オブジェクトを使用すると、フォームやクライアント API での変更に対する回復性が高まります。