クライアント API フォーム コンテキスト (formContext) は、現在のコードの実行対象となる、フォームまたはフォーム上の項目 (クイック ビュー コントロールや編集可能なグリッド内の行など) への参照を提供します。 formContext オブジェクトを使用すると、フォームまたはどこから呼び出されるかに応じて編集可能なグリッドで動作できる一般的なイベント ハンドラーを作成できます。 詳細については、「 getFormContext (クライアント API リファレンス)」を参照してください。
Note
フォーム コンテキストを操作する際に覚えておく必要がある重要な点をいくつか次に示します。
リボン アクションでの JavaScript 関数用 formContext オブジェクトの取得は、フォーム スクリプト内での取得方法とは異なります。 詳細については、「 リボン アクションのフォームとグリッドのコンテキスト」を参照してください。
フォーム コンテキストは、渡されたイベントの間のみ有効です。 実行コンテキストと同じ制限が適用されます。
formContext オブジェクトを使用するイベント ハンドラーを定義するときに、[ハンドラーのプロパティ] ダイアログで [実行コンテキストを最初のパラメーターとして渡す] オプションを選択します。 詳細については、「 クライアント API の実行コンテキスト」を参照してください。
formContext は、2017 年に非推奨の Xrm.Page オブジェクトを置き換えました。 Xrm.Page オブジェクトの代わりに formContext オブジェクトを使用する方法を学ぶ
formContext オブジェクト モデル
モデル駆動型アプリのデータおよびユーザー インターフェイス要素をプログラムで処理するために、formContext オブジェクトの下でデータおよび ui オブジェクトを使用します。
データ オブジェクト
テーブル データやビジネス プロセス フロー コントロールのデータなど、フォーム上のデータを扱うプロパティとメソッドを提供します。 以下のオブジェクトを含みます:
| オブジェクト | 説明 |
|---|---|
attributes |
フォーム上のテーブル以外のデータのコレクションです。 このコレクションのアイテムは列のコレクションと同じタイプですが、フォーム テーブルのカラムではありません。 詳細: コレクション |
entity |
レコードに特有の情報を取得するためのメソッド、および保存メソッド、さらにフォームに含まれるすべての列のコレクションを提供します。 列データは、フォーム上に表示されている列に限定されています。 詳細: formContext.data.entity |
process |
フォーム上のビジネス プロセス フロー データを操作するためのオブジェクトおよびメソッドを提供します。 詳細: formContext.data.process |
また、テーブルに縛られないコントロールへのアクセスに使用する属性のコレクションも用意されています。 この記事の後の方にある formContextオブジェクト モデルのコレクションセクションを参照してください。
詳細: formContext.data
UI オブジェクト
フォームまたはグリッドの複数のサブコンポーネントのコレクションに加えて、ユーザー インターフェイスに関する情報を取得するメソッドを提供します。 以下のオブジェクトを含みます:
| オブジェクト | 説明 |
|---|---|
formSelector |
現在のユーザーが使用できるフォームのクエリに使用できるアイテム コレクションを提供します。
navigateメソッドを使用して現在のフォームを閉じ、別のフォームを開きます。 |
navigation |
メソッドを含みません。 アイテムのコレクションによってナビゲーション アイテムへのアクセスを提供します。 詳細については、コレクションの次のセクションを参照してください。 |
process |
フォームのビジネス プロセス フローのコントロールを操作するためのメソッドを提供します。 |
詳細: formContext.ui
formContextオブジェクト モデルのコレクション
次の表では、 Xrm オブジェクト モデルのコレクションについて説明します。 一般にコレクションに使用できるメソッドの詳細については、「 コレクション (クライアント API 参照)」を参照してください。
| コレクション | 説明 |
|---|---|
| attributes | 2つのオブジェクトには列のコレクションが含まれています: - formContext.data.attributes コレクションでは、テーブル バインドされていない列にアクセスできます。 - formContext.data.entity.attributes コレクションは、フォームで使用できる各テーブル列へのアクセスを提供します。 フォームに追加された列のみを使用できます。 |
| controls | 次の 3 つのオブジェクトに、controls コレクションが含まれます。 - formContext.ui.controls: フォームに存在する各コントロールへのアクセスを提供します。 - formContext.data.entity.attribute.controls : 列にはフォーム上に複数のコントロールがある場合があるため、このコレクションはそれぞれのコントロールへのアクセスを提供します。 このコレクションには、列で使用する複数のコントロールがフォームに追加されていない限り、1 つのアイテムしか含まれません。 - formContext.ui.tabs.sections.controls: このコレクションには、セクションで見つかるコントロールしか含まれません。 |
| formContext.data.process.ステージ および formContext.data.process.ステップ | 業務プロセス フロー内のステージおよびステップコレクションへのアクセスを提供します。 また、これらにより、コレクションからアイテムの追加および削除ができます。 |
| formContext.ui.formSelector.項目 | 1 つのテーブルに複数のフォームが用意されている場合、各フォームにセキュリティ ロールを関連付けることができます。 ユーザーに関連付けられているセキュリティ ロールによって、ユーザーに複数のフォームを表示できる場合、 formContext.ui.formSelector.items コレクションはそのユーザーが利用できる各フォーム定義へのアクセスを提供します。 |
| formContext.ui.navigation.アイテム | formContext.ui.navigation.items コレクションは、フォーム エディターのナビゲーション領域を使用して定義されているナビゲーション アイテムへのアクセスを提供します。 ユーザーは、コマンド バーを使用してこれらの項目に移動します。 |
| formContext.ui.quickForms | フォームのすべての簡易ビューコントロールおよびその構成コントロールにアクセスするためのメソッドを提供します。 |
| formContext.ui.tabs | 1 つ以上のタブを使用して、各フォームを整理できます。 このコレクションは、これらの各タブへのアクセスを提供します。 |
| formContext.ui タブ。セクション | 1 つ以上のセクションを使用して、各フォーム タブを整理できます。 タブセクションコレクションは、これらの各セクションへのアクセスを提供します。 目的のセクションを含むタブを定義するか、、各タブを繰り返して関連するセクションを見つける必要があります。 |
Xrm.Page オブジェクトの代わりに formContext オブジェクトを使用する
以前は、人々はグローバル Xrm.Page オブジェクトを使用してフォームまたはフォーム上のアイテムを表しました。 Xrm.Page オブジェクトは 2017 年に非推奨になりました。 代わりに、渡された実行コンテキスト オブジェクトの getFormContext メソッドを使用して、フォーム上の適切なフォームまたは項目への参照を返します。
Important
非推奨 とは、Microsoft がモデル駆動型アプリの今後のメジャー リリースから機能を削除することを意味します。 該当する機能は、正式に削除されるまで引き続き機能し、完全にサポートされます。 Microsoft は、削除の少なくとも 6 か月前、ドキュメント、公式ブログ、その他多くの場所で公開発表を行います。
既存のスクリプトとの下位互換性を維持するために、 Xrm.Page オブジェクトをプライマリ フォーム コンテキストへの静的アクセスとして使用することは 引き続き サポートされており、「 クライアント API の廃止 」セクションに記載されている他のクライアント API メソッドがすぐに削除されることはありません。 可能な場合は、バージョン 9.0 以降を対象とするコード内の Xrm.Page オブジェクトの代わりに、新しい formContext オブジェクトを使用します。
Xrm.Page を使用する既存のコードを変換して、新しい formContext オブジェクトを使用するのは簡単です。 たとえば、 Xrm.Page オブジェクトを使用する次のスクリプトを考えてみてください:
function displayName()
{
var firstName = Xrm.Page.getAttribute("firstname").getValue();
var lastName = Xrm.Page.getAttribute("lastname").getValue();
console.log(firstName + " " + lastName);
}
静的な Xrm.Page オブジェクトを使用する代わりに、渡された実行コンテキストを使用して formContext オブジェクトを取得する更新されたスクリプトを次に 示 します。
function displayName(executionContext)
{
var formContext = executionContext.getFormContext(); // get formContext
// use formContext instead of Xrm.Page
var firstName = formContext.getAttribute("firstname").getValue();
var lastName = formContext.getAttribute("lastname").getValue();
console.log(firstName + " " + lastName);
}
関連記事
getFormContext メソッド
getGlobalContext メソッド
getAttribute メソッド
getControl メソッド
実行コンテキストのメソッド