アダプティブフォームおよび HTML5 フォームの外観フレームワーク

フォーム(アダプティブフォームと HTML5 フォーム)は、jQueryBackbone.jsおよびUnderscore.jsライブラリを外観とスクリプト作成のために使用します。このフォームはまた、フォーム内のすべての対話操作要素(例えばフィールドやボタン)に対して jQuery UI Widgets​アーキテクチャを使用します。このアーキテクチャはフォーム開発者が、フォームで豊富な使用可能な jQuery ウィジェットとプラグインのセットを利用できるようにします。また、ユーザーから leadDigits/trailDigits の制限やパターン形式文字列の実装などのデータを取得しながら、フォーム固有のロジックを実装することもできます。フォーム開発者はカスタム外観を作成して使用し、データ取得の体験を改善し、よりユーザーフレンドリーにすることができます。

この記事は jQuery と jQuery ウィジェットの知識が十分ある開発者向けです。外観フレームワークについての理解を深めたり、開発者がフォームフィールドに別の外観を作成するのに役立ちます。

外観フレームワークは、ユーザーのフォームとのやり取りを取得したり、モデル変更に対応してエンドユーザーに通知したりするため、さまざまなオプション、イベント(トリガー)、機能に依存しています。さらに、次の点に注意してください。

  • フレームワークは、フィールドの外観のための一連のオプションを提供します。これらのオプションはキーと値のペアであり、一般的なオプションとフィールドタイプ固有のオプションの 2 つのカテゴリに分かれます。
  • 外観はコントラクトの一部として、enter や exit などの一連の インベントのセットをトリガーします。
  • 一連の関数を実装するには、外観が必要となります。その関数には一般的なものから、フィールドタイプ固有のものも含まれています。

一般的なオプション

次にあるのはグローバルオプションのセットです。これらのオプションはすべてのフィールドで使用できます。

プロパティ 説明
name スクリプト式でこのオブジェクトまたはイベントを指定するために使用される識別子です。例えば、このプロパティはホストアプリケーションの名前を指定します。
value フィールドの実際の値。
displayValue フィールドのこの値が表示されます。
screenReaderText スクリーンリーダーはこの値を使用して、フィールドについての情報を読み上げます。フォームは値を提供し、その値を上書きできます。
tabIndex フォームのタブシーケンスにおけるフィールドの位置フォームのデフォルトタブの順序を変更する場合にのみ、tabIndex を上書きします。
role 要素のロール、たとえば、見出しやテーブル。
height ウィジェットの高さ。高さはピクセルで指定されます。
width ウィジェットの幅。高さはピクセルで指定されます。
access サブフォームなど、コンテナオブジェクトのコンテンツにアクセスするために使用されるコントロール。
paraStyles ウィジェットへの XFA 要素のパラプロパティ。
dir テキストの方向。可能な値は ltr (左から右)と rtl (右から左)です。

これらのオプションとは別に、フィールドのタイプによって異なるいくつかの他のオプションがフレームワークによって提供されます。フィールド固有のオプションの詳細は、以下に記載されています。

フォームのフレームワークとのインタラクション

Forms のフレームワークとやりとりするために、ウィジェットはいくつかのイベントをトリガーし、フォームスクリプトが機能するように有効化します。ウィジェットがこれらのイベントをスローしない場合、そのフィールドのためにフォーム内に書かれたスクリプトの一部が機能していません。

ウィジェットによってトリガーされるイベント

イベント 説明
XFA_ENTER_EVENT このイベントはフィールドがフォーカスされるたびにトリガーされます。フィールドで「入力」スクリプトの実行を可能にします。イベントをトリガーするための構文は
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_ENTER_EVENT)
XFA_EXIT_EVENT このイベントはフィールドを離れるたびにトリガーされます。エンジンがフィールドの値を設定し、その「終了」スクリプトを実行することを可能にします。イベントをトリガーするための構文は
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_EXIT_EVENT)
XFA_CHANGE_EVENT このイベントがトリガーされ、エンジンがフィールドに書かれた「変更」スクリプトを実行することが可能になります。イベントをトリガーするための構文は
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CHANGE_EVENT)
XFA_CLICK_EVENT このイベントはフィールドがクリックされるたびにトリガーされます。エンジンがフィールドに書かれた「クリック」スクリプトを実行することが可能になります。イベントをトリガーするための構文は
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CLICK_EVENT)

ウィジェットで実装された API

外観フレームワークはカスタムウィジェットで実装されたウィジェットの関数をいくつか呼び出します。ウィジェットは次の関数を実装する必要があります。

Function 説明
focus : function() フォーカスをフィールドに移します。
click : function() フォーカスをフィールドに移し、XFA_CLICK_EVENT を呼び出します。

markError:function(errorMessage, errorType)

errorMessage: string representing the error
errorType: string ("warning"/"error")

注意:HTML5 フォームにのみ適用可能です。

エラーメッセージとエラータイプをウィジェットに送信します。ウィジェットはエラーを表示します。

clearError: function()

注意:HTML5 フォームにのみ適用可能です。

フィールドのエラーが修正された場合に呼び出されます。ウィジェットはエラーを非表示にします。

フィールドのタイプに固有のオプション

すべてのカスタムウィジェットは上記の仕様に準拠する必要があります。異なるフィールドの機能を使用するには、ウィジェットはその特定のフィールドのガイドラインに準拠する必要があります。

TextEdit: Text Field

オプション 説明
multiline フィールドが改行文字の入力をサポートする場合 true。
maxChars フィールドに入力できる最大文字数。

limitLengthToVisibleArea

注意:HTML5 フォームにのみ適用可能です

テキストのウィジェットがウィジェットの幅を超えたときの、テキストフィールドの動作を指定します。

ChoiceList: DropDownList, ListBox

オプション 説明
value
選択された値の配列。
item
オプションとして表示されるオブジェクトの配列。各オブジェクトには 2 つのプロパティがあります。
save:保存する値、display:表示される値。

編集可能な状態で

注意:HTML5 フォームにのみ適用可能です。

値が true の場合、ウィジェットでカスタムテキスト入力が有効。
displayValue
表示される値の配列。
multiselect
複数の選択が許可される場合は true。許可されない場合は false。

API

Function 説明

addItem: function(itemValues)
itemValues:display と save の値が含まれているオブジェクト
{sDisplayVal: <displayValue>, sSaveVal: <save Value>}

アイテムをリストに追加します。
deleteItem: function(nIndex)
nIndex:リストから削除する項目のインデックス


リストからオプションを削除します。
clearItems: function() リストからすべてのオプションを消去します。

NumericEdit: NumericField, DecimalField

オプション 説明
dataType フィールドのデータタイプ(整数/十進数)を示す文字列。
leadDigits 十進数で許可される小数点以上の最大桁数。
fracDigits 十進数で許可される小数点以下の最大桁数。
zero フィールドのロケールでのゼロの文字列表現。
decimal フィールドのロケールでの小数点の文字列表現。

CheckButton: RadioButton, CheckBox

オプション 説明
values

値の配列(オン/オフ/中間)。

これは、checkButton のさまざまなステートのための値の配列です。 values[0] はステートがオンのときの値です。values[1] はステートがオフのときの値です。
values[2] はステートが中間のときの値です。値配列の長さは、state オプションの値と同じです。

states

許可される状態の数。

アダプティブフォームの場合は 2 つ(オン、オフ)、HTML5 フォームの場合は 3 つ(オン、オフ、中間)です。

state

要素の現在の状態です。

アダプティブフォームの場合は 2 つ(オン、オフ)、HTML5 フォームの場合は 3 つ(オン、オフ、中間)です。

DateTimeEdit: (DateField)

オプション 説明
そのフィールドのローカライズされた曜日の名前。
months そのフィールドのローカライズされた月の名前。
zero 数字の 0 のローカライズされたテキスト。
clearText 「クリア」ボタンのローカライズされたテキスト。

このページ