アダプティブフォームおよび HTML5 フォームの外観フレームワーク appearance-framework-for-adaptive-and-html-forms

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

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

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

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

一般的なオプション common-options

グローバルオプションは次のとおりです。これらのオプションはすべてのフィールドで使用できます。

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

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

フォームのフレームワークとのインタラクション interaction-with-forms-framework

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

ウィジェットによってトリガーされるイベント events-triggered-by-widget

イベント
説明
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 apis-implemented-by-widget

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

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 フォームにのみ適用可能です。

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

フィールドのタイプに固有のオプション options-specific-to-type-of-field

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

TextEdit:テキストフィールド textedit-text-field

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

limitLengthToVisibleArea

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

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

ChoiceList: DropDownList,、ListBox choicelist-dropdownlist-listbox

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

編集可能な状態で

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

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

API api

Function
説明
addItem: function(itemValues)
itemValues:display と save の値が含まれているオブジェクト
{sDisplayVal: <displayValue>, sSaveVal: <save Value>}
アイテムをリストに追加します。
deleteItem : function(nIndex)
nIndex:リストから削除する項目のインデックス
リストからオプションを削除します。
clearItems: function()
リストからすべてのオプションを消去します。

NumericEdit、NumericField、DecimalField numericedit-numericfield-decimalfield

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

CheckButton: RadioButton, CheckBox checkbutton-radiobutton-checkbox

オプション
説明
values

値の配列(on/off/neutral))。

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

states

許可される状態の数。

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

state

要素の現在の状態です。

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

DateTimeEdit: (DateField) datetimeedit-datefield

オプション
説明
そのフィールドのローカライズされた曜日の名前。
そのフィールドのローカライズされた月の名前。
zero
数字の 0 のローカライズされたテキスト。
clearText
「クリア」ボタンのローカライズされたテキスト。
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2