【API紹介】formContext.ui編

こんにちは。

前回の記事では、『formContext.data.entity』の中から5つの関数を紹介しましたが、今回は『formContext.ui』から4つの関数をご紹介します。

formContext.ui の概要

Microsoft社のAPI一覧では、以下の様に説明されています。
記載内容の通り、"UIに関する情報を取得する"関数となっていますので、レコードやフィールドに対して何かしらの処理を行う訳ではなく、どちらかというとビューやリボン、フォームの情報にアクセスするための関数となっています。

ユーザー インターフェイス (UI) に関する情報を取得するプロパティおよびメソッド、およびフォームのいくつかのサブコンポーネントのコレクションを提供します。

フォーム単位に通知を行う (setFormNotification)

『setFormNotification』は、フォーム上に通知を表示する関数です。
この関数は結構有用で、フォームにアクセスしたユーザに対して情報発信したり、行った操作に対する警告をヘッダー付近に表示することができます。

構文

formContext.ui.setFormNotification(message, level, uniqueId);

パラメータ

値	種類	必須	説明
message	String	Yes	表示するテキスト文を入力
level	String	Yes	ERROR：エラーアイコンとテキスト文を表示 WARNING：警告アイコンとテキスト文を表示 INFO：情報アイコンとテキスト文を表示
uniqueId	String	Yes	『clearFormNotification』関数で、通知を削除する際に使用するIDを指定

戻り値

処理に成功した場合は「true」、そうでない場合は「false」を返却します。

関数の使用例

[JavaScript]

function SetFormNotification (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    formContext.ui.setFormNotification("必須のフィールドは全て入力してください。", "INFO", "abc123");
}

[実行結果]

参考ページ

モデル駆動型アプリの setFormNotification (クライアント API 参照) - PowerApps | Microsoft Docs

フォーム単位の通知を削除する (clearFormNotification)

『clearFormNotification』は、フォーム上に表示された通知を削除する関数です。
この関数は、通知を表示したり非表示にしたりする処理が必要な場合に、上記で紹介した『setFormNotification』とセットで使われることが多い関数ですが、通知を常に表示しておきたい場合は利用しなくても構いません。

構文

formContext.ui.clearFormNotification(uniqueId);

パラメータ

値	種類	必須	説明
uniqueId	String	Yes	『setFormNotification』関数で指定したIDを指定

戻り値

処理に成功した場合は「true」、そうでない場合は「false」を返却します。

関数の使用例

[JavaScript]

function ClearFormNotification (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    formContext.ui.setFormNotification("必須のフィールドは全て入力してください。", "INFO", "abc123");
    formContext.ui.clearFormNotification("abc123");
}

[実行結果]

参考ページ

モデル駆動型アプリの clearFormNotification (クライアント API 参照) - PowerApps | Microsoft Docs

フォームを閉じる (close)

『close』は、フォームを閉じる関数です。
ブラウザ自体を[×]で閉じる『Window.close』のような挙動ではなく、Dynamics 365 の画面内でフォームを閉じるような挙動となるため、例えば、とあるレコードのフォーム画面上でこの関数が実行された場合、ビューの画面に遷移するか、もしくは前に開いていたレコードのフォーム画面に遷移します。

構文

formContext.ui.close();

パラメータ

(特になし)

戻り値

(特になし)

関数の使用例

[JavaScript]

function Close (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    formContext.ui.close();
}

[実行結果]
画像はありませんが、とあるレコード上で処理が実行された後、ビュー画面に遷移しました。

参考ページ

モデル駆動型アプリの close (クライアント API 参照) - PowerApps | Microsoft Docs

フォームの種類を取得する (getFormType)

『getFormType 』は、フォームの種類を取得する関数で、新規作成時(フォームタイプが"1"の場合)のみ実行させたい処理などがある場合に利用することができます。

構文

formContext.ui.getFormType();

パラメータ

(特になし)

戻り値

値	フォームの種類
0	未定義のフォームの場合
1	新規作成のフォームの場合
2	既存のフォームの場合
3	フォームが読み取り専用になっている場合
4	フォームが無効になっている場合
6	一括編集のフォームの場合

関数の使用例

[JavaScript]

function GetFormType (executionContext) {
    // 実行コンテキストの取得
    var formContext = executionContext.getFormContext();
    if (formContext.ui.getFormType() === 1) {
        alert("このフォームは新規作成フォームです");
    } else if (formContext.ui.getFormType() === 2) {
        alert("このフォームは既存のフォームです");
    }
}

[実行結果]
※新規作成フォームを開いた場合

※既存のフォームを開いた場合

参考ページ

モデル駆動型アプリの getFormType (クライアント API 参照) - PowerApps | Microsoft Docs

UI周りの関数は、私も実案件で本当によく使う関数ばかりです。
特にフォームの種類を取得する『getFormType』関数は利用頻度が高く、OnLoadのJavaScriptの中でif分岐させて、新規作成フォームの場合のみ何かしらの処理をするようなシーンで使える関数なので、ご存知でなかった方は、これを機に使ってみてはいかがでしょうか？