テキストフィールドウィジェット (テーマ指定可能)
テキストフィールドウィジェットは、フォーム内で一般的に使用される入力エレメントです。テキストフィールドを使用して、ユーザーがマッシュアップ内にテキストを入力できるように設定できます。Text プロパティを使用して、フィールド内のテキストを設定したり読み込んだりできます。テキスト領域ウィジェットとは異なり、テキストフィールドは 1 行に制限されています。共通のウィジェットプロパティに加えて、以下の方法でプロパティを使用してウィジェットを設定できます。
• 最大文字数を設定し、カウンタを追加します。
• データサービス、関数、およびその他のウィジェットの入力としてテキストを使用します。
• 値が設定されていない場合にヒントテキストを表示します。
• 「テキストをクリア」ボタンを追加します。
• 読み取り専用モードを有効にします。
• パスワードなどの機密情報の入力を非表示にします。
• 入力が特定のフォーマットに固定されるようにマスクパターンを定義します。
 |
テキストフィールドウィジェットは、プラットフォーム内の標準ウィジェットとして、および Web Part SDK からインポート可能な Web パーツとして使用できます。
|
次のウィジェットイベントを使用して、ランタイムでウィジェットの値が更新されたときにデータサービスまたは関数を実行できます。
• EnterKeyPressed - Enter キーを押すとトリガーされます。
• FocusLost - ウィジェットの外側の領域をクリックするか Tab キーを押すとトリガーされます。
イベントの操作
テキストフィールドウィジェットは、以下の 2 つのバインド可能なイベントをトリガーします。
• Changed - 文字が追加または除去されるとトリガーされます。
• EnterKeyPressed - ユーザーが Enter キーを押すとトリガーされます。
ウィジェットのイベントを使用して、ウィジェット内の関数、データサービス、またはサービスをトリガできます。たとえば、入力と同時に、または Enter キーを押したときに入力が検証されるようにするには、バリデータ関数にイベントをバインドします。
読み取り専用モードの有効化
ReadOnly プロパティを有効にして、ランタイムにテキストが変更されないように設定できます。たとえば、このプロパティを使用して、切り替えボタンが有効になるまで、またはマッシュアップでチェックボックスがオンになるまで、変更が行われないように設定できます。読み取り専用が有効になっている場合、テキストを選択してコピーすることはできますが、現在の値の編集、切り取り、および削除を行うことはできません。読み取り専用テキストフィールドのテキスト値を変更するには、デザインタイムに Text プロパティの値を入力します。また、データソースをプロパティにバインドして、ランタイムにテキスト値を変更することもできます。
文字数の制限の設定
以下のいずれかの方法によって、テキストフィールドからの入力を特定の文字数に制限できます。
• MaxNumberOfCharacters プロパティを任意の数値に設定します。デフォルトでは、テキストフィールドに入力できる文字数は最大 100 文字です。
• Mask プロパティを使用してマスクパターンを定義します。文字数制限を設定するために、パターン内の特殊文字の数が使用されます。
テキストフィールドへのカウンタの追加
テキストフィールドに文字数を示すカウンタを追加するには、Counter プロパティを True に設定します。空白を含む文字数制限を設定するには、MaxNumberOfCharacters プロパティが使用されます。次のイメージは、カウンタが表示されている最大文字数が 10 文字のテキストフィールドウィジェットを示しています。
文字数制限に達すると、カウンタの色が変わります。
「テキストをクリア」ボタンの追加
ShowClearText プロパティを有効にして、ウィジェットの入力ボックスにテキストボタンを追加できます。入力フィールドに値が含まれている場合、このボタンは自動的にウィジェットの右側に表示されます。これにより、ユーザーはウィジェット内の既存のテキストを素早く除去できます。
アイコンの追加
Icon プロパティを使用して、テキストフィールド内にアイコンを表示できます。アイコンはウィジェットの左側に自動的に表示されます。プラットフォームで使用可能な、提供済みの SVG アイコンからアイコンを選択できます。これらのアイコンの詳細については、SVG アイコンの使用を参照してください。
テキストフィールド入力パターンの設定
Mask プロパティを使用して、数値、英字、および英数字の入力パターンを指定できます。パターンを定義すると、プレースホルダーガイドが入力ボックスに追加されます。このガイドは線で表され、ユーザーがテキストフィールドに入力できるテキストパターンを示します。必要なパターンに加え、このプロパティはテキストフィールド内の文字数を設定します。以下の特殊文字を使用してパターンを作成できます。
• a - 英字
• 9 - 数値
• * - 英数字
パターンを作成するには、必要な入力を表す文字列に特殊文字を組み合わせます。たとえば、以下のパターンは異なるタイプの入力を表しています。
• 9999 - 4 桁の数字
• ***** - 5 文字の英数字
• 99–aa - 2 桁の数字、セパレータのダッシュ、2 文字のアルファベット。
次のイメージは、ランタイムに 4 つの 3 桁の数字が含まれる 999–999–999–999 数値パターンのガイドを示しています。
パターンは、桁数に加えて数字のフォーマットを設定するために使用されます。この例では、256120233234 のように任意の 12 桁の数字を入力できます。入力すると、アンダースコア (_) ガイドが数字に置き換えられます。
インジケータガイドは、デザインタイムにパターン内で設定した合計文字数に基づいて表示されます。パターンより桁数が少ない数字を入力すると、入力は不完全なままとなります。電話番号や郵便番号などの特定の文字数のパターンを定義する場合は、マスクを使用しなければなりません。入力が金額などの特定の文字数ではない場合は、マスクの使用を回避してください。
|
|
文字間のセパレータとして、ピリオド、ダッシュ、スラッシュなどのさまざまなタイプの記号を使用できます。
|
数値入力モードの有効化
入力を数値のみに制限するようにテキストフィールドウィジェットを設定できます。これにより、ユーザーが確実に有効な数値データを入力するようになり、検証を簡略化できます。テキストフィールドで数値入力を有効にするには、ウィジェットを選択し、「プロパティ」パネルで NumericInputMode プロパティを有効にします。このモードの追加のコンフィギュレーションプロパティが表示されます。
ユーザーが 10 進値を入力できるようにするには AllowDecimals を使用し、負の数を許可するには AllowNegativeValues を使用します。DecimalPlaces を設定して、小数点以下の桁数を定義します。値の範囲を制限するには、MinValue および MaxValue の検証プロパティを使用します。MinValueFailureMessage と MaxValueFailureMessage を使用して、ユーザーが範囲外の値を入力したときに表示されるメッセージをカスタマイズすることもできます。
数値フォーマットを制御するには、FormatToken プロパティを使用します。StepSize プロパティを設定して、ユーザーがキーボードショートカットを使用したときに値をどのくらい変化させるかを制御することもできます。NumericValue プロパティを使用すると、フィールドをデータソースにバインドして、値を動的に追跡または更新できます。
テキストフィールドウィジェットのサイズ変更
AllowResize プロパティを使用すると、ユーザーがテキストフィールドウィジェットのサイズを水平方向に変更できるようにするかどうかを制御できます。このプロパティを true に設定すると、ウィジェットに水平方向のサイズ変更ハンドルが表示され、ユーザーはマッシュアップインタフェースで幅を直接調整できます。これにより、入力領域の幅を柔軟に変更できるようになるため、ユーザビリティが向上します。
次の表に、テキストフィールドウィジェットのプロパティを示します。
|
プロパティ名
|
説明
|
ベースタイプ
|
デフォルト値
|
バインド可能か(Y/N)
|
ローカライズ可能か(Y/N)
|
||
|---|---|---|---|---|---|---|---|
|
Text
|
テキストフィールドに表示されるテキスト。
|
STRING
|
該当なし
|
Y
|
Y
|
||
|
Label
|
テキストフィールドのラベルに表示されるテキスト。
|
STRING
|
該当なし
|
Y
|
Y
|
||
|
AllowResize
|
ユーザーがランタイムにテキストフィールドのサイズを変更できるようにします。
|
BOOLEAN
|
False
|
N
|
N
|
||
|
Counter
|
テキストフィールドに入力された文字数をカウントして表示します。
|
BOOLEAN
|
False
|
N
|
N
|
||
|
MaxNumberOfCharacters
|
テキストフィールドの最大文字数を設定できます。
|
NUMBER
|
100
|
Y
|
N
|
||
|
NumericInputMode
|
ウィジェットの数値入力モードを有効にします。このモードでは、数値のみを入力できます。
|
ウィジェットを数値入力モードに設定します。このモードでは、数字のみを入力できます。
|
False
|
N
|
N
|
||
|
NumericValue
|
ウィジェットの数値を設定または取得します。
|
NUMBER
|
0
|
Y
|
N
|
||
|
AllowDecimals
|
数値入力モードを使用しているときには、小数を使用できます。
|
BOOLEAN
|
False
|
N
|
N
|
||
|
AllowNegativeValues
|
数値入力モードを使用している場合、負の値を使用できます。
|
BOOLEAN
|
False
|
N
|
N
|
||
|
DecimalPLaces
|
数値の許容小数桁数を設定します。
|
NUMBER
|
0
|
N
|
N
|
||
|
FormatToken
|
数値のフォーマットを指定するためのローカライズトークンを入力します。フォーマットトークンを設定すると、AllowDecimals、AllowNegativeValues、および DecimalPlaces プロパティがオーバーライドされます。サポートされているフォーマットの詳細については、https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat の Intl.NumberFormat オブジェクトを参照してください。
|
STRING
|
該当なし
|
N
|
N
|
||
|
StepSize
|
キーボードショートカットを使用しているときの数値のステップサイズを制御します。
|
NUMBER
|
1
|
N
|
N
|
||
|
HintText
|
このフィールドに何を入力すべきかを示すプレースホルダーテキストが表示されます。
|
STRING
|
該当なし
|
N
|
N
|
||
|
Disabled
|
このプロパティを使用して、マッシュアップ内のウィジェットを無効にします。ウィジェットはマッシュアップ内に表示されますが、クリックできません。
|
BOOLEAN
|
False
|
Y
|
N
|
||
|
ReadOnly
|
テキストフィールドを読み取り専用として設定でき、テキストをユーザーが編集できなくなります。
|
BOOLEAN
|
False
|
N
|
N
|
||
|
Password
|
テキストフィールドのエントリを非表示にできます。
|
BOOLEAN
|
False
|
N
|
N
|
||
|
ShowClearText
|
テキストフィールド内に「クリア」ボタンを追加し、ランタイムでそのボタンがクリックされたときにそのフィールド内のテキストをクリアできます。
|
BOOLEAN
|
True
|
N
|
N
|
||
|
LabelAlignment
|
ラベルを左、右、または中央に整列できます。
|
STRING
|
Left
|
N
|
N
|
||
|
TextAlignment
|
フィールド内のテキストを左または右に整列できます。
|
STRING
|
Left
|
N
|
N
|
||
|
Mask
|
テキストフィールド内の定義済み文字を設定できます。プロパティのコンフィギュレーションフィールドで、英字エントリを設定するには "a" を使用し、数字エントリを設定するには "9" を使用し、英数字エントリを設定するには "*" を使用します。
|
STRING
|
該当なし
|
N
|
N
|
||
|
TabSequence
|
ユーザーが Tab キーを押したときにウィジェットがハイライトされる順序。
|
NUMBER
|
該当なし
|
N
|
N
|
||
|
CustomClass
|
ウィジェットの最上位の div に CSS を定義できます。スペースで区切って、複数のクラスを入力できます。
|
STRING
|
該当なし
|
Y
|
N
|
||
|
EnterKeyPressed
|
テキスト値の編集中に Enter キーを押すとトリガーされるイベント。
|
該当なし
|
該当なし
|
Y
|
N
|
||
|
FocusLost
|
テキスト値の編集中に Tab キーを押すかウィジェットの外側の領域をクリックすることでフォーカスを切り替えたときにトリガーされるイベント。
|
該当なし
|
該当なし
|
Y
|
N
|
||
|
Changed
|
このウィジェットのデータが修正されたときにトリガーされるイベント。
|
該当なし
|
該当なし
|
Y
|
N
|
||
|
ResetToDefaultValue
|
このウィジェットの入力をそれぞれのデフォルト値にリセットします。
|
該当なし
|
該当なし
|
Y
|
N
|
||
|
Width
|
ウィジェットの幅。
|
NUMBER
|
273
|
N
|
N
|
||
|
Height
|
ウィジェットの高さ。デフォルトで自動的に計算されます。テキストフィールド内にラベルを含めた場合、より高くなります。
|
NUMBER
|
自動サイズ調整
|
N
|
N
|
||
|
TooltipField
|
ウィジェットにカーソルを合わせたときに表示されるツールヒントテキストを設定します。
|
STRING
|
該当なし
|
Y
|
Y
|
||
|
TooltipIcon
|
ウィジェットのツールヒントのアイコンイメージを設定します。
イメージを追加したり、イメージの URL パスを指定したりできます。
|
メディアエンティティ
|
該当なし
|
N
|
N
|
||
|
Icon
|
テキストボックス内に表示するアイコンを指定します。
|
SVG アイコンのリスト
|
該当なし
|
N
|
N
|
ウィジェットのデータの検証
共通のプロパティに加えて、検証プロパティ MaxLength および MinLength を使用して、テキストフィールドウィジェット内の文字数を検証できます。
プロパティ MaxLengthFailureMessage および MinLengthFailureMessage を使用して、デフォルトの失敗メッセージをカスタマイズできます。パラメータ ${value} を使用して最大値と最小値がメッセージ内に表示されます。
共通の検証プロパティの使用の詳細については、ウィジェットへの検証の適用を参照してください。
次の表に、「検証」パネルで使用可能な検証プロパティを示します。
|
プロパティ
|
説明
|
ベースタイプ
|
デフォルト値
|
バインド可能か (Y/N)
|
ローカライズ可能か (Y/N)
|
|---|---|---|---|---|---|
|
CriteriaMessage
|
検証に失敗したとき、および検証基準で表示されるメッセージ。
|
STRING
|
該当なし
|
Y
|
Y
|
|
CriteriaMessageDetails
|
検証基準および失敗のメッセージで表示される詳細。
|
STRING
|
該当なし
|
Y
|
Y
|
|
MaxLength
|
テキストフィールド値の最大長さ。
|
STRING
|
該当なし
|
Y
|
N
|
|
MaxLengthFailureMessage
|
現在の値が最大文字数を超えたときに表示されるメッセージ。
|
STRING
|
${value} characters is the maximum
|
Y
|
Y
|
|
MinLength
|
テキストフィールド値の最小長さ。
|
STRING
|
該当なし
|
Y
|
N
|
|
MinLengthFailureMessage
|
現在の値が最小文字数より小さい場合に表示されるメッセージ。
|
STRING
|
${value} characters is the minimum
|
Y
|
Y
|
|
MaxValue
|
ウィジェットの最大数値を設定します。
|
NUMBER
|
該当なし
|
Y
|
N
|
|
MaxValueFailureMessage
|
数値が最大値を超えている場合に表示されるメッセージ。
|
STRING
|
値が最大値を超えています
|
Y
|
Y
|
|
MinValue
|
ウィジェットの最小数値を設定します。
|
NUMBER
|
Y
|
N
|
|
|
MinValueFailureMessage
|
数値が最小値より小さい場合に表示されるメッセージ
|
STRING
|
Y
|
Y
|
|
|
RequiredMessage
|
ValueRequired が true に設定されているときにアイテムが選択されていない場合に表示されるメッセージ。
|
STRING
|
値は必須です
|
Y
|
Y
|
|
ShowValidationCriteria
|
テキストフィールドを編集しているときに、必須の入力に関するヒントメッセージを表示します。
|
BOOLEAN
|
False
|
Y
|
N
|
|
ShowValidationFailure
|
入力した値が検証に失敗したときに、失敗のメッセージを表示します。
|
BOOLEAN
|
False
|
Y
|
N
|
|
ShowValidationSuccess
|
入力した値が正しく検証されたときに、成功のメッセージを表示します。
|
BOOLEAN
|
False
|
Y
|
N
|
|
SuccessMessage
|
検証に成功したときに表示されるメッセージ。
|
STRING
|
該当なし
|
Y
|
Y
|
|
SuccessMessageDetails
|
検証成功のメッセージに関する詳細情報を表示するセカンダリメッセージ。
|
STRING
|
該当なし
|
Y
|
Y
|
|
Validate
|
ウィジェットの値が変更されたときにトリガーされるバインド可能なイベント。このイベントをサービスまたは関数にバインドして、検証のパターンまたは定義式を適用します。
|
イベント
|
該当なし
|
Y
|
N
|
|
ValidationCriteriaIcon
|
検証基準のヒントメッセージ内に表示する SVG アイコンを設定します。
|
IMAGELINK
|
info
|
N
|
N
|
|
ValidationFailureIcon
|
検証に失敗した場合にステータスメッセージ内に表示する SVG アイコンを設定します。
|
IMAGELINK
|
error
|
N
|
N
|
|
ValidationOutput
|
ウィジェット検証の出力を取得します。戻り値は Undefined、Unvalidated、Valid、または Invalid です。
|
STRING
|
該当なし
|
Y
|
N
|
|
ValidationState
|
検証状態を設定するバインド可能なプロパティ。このプロパティは Undefined、Unvalidated、Valid、または Invalid に設定できます。
|
STRING
|
Undefined
|
Y
|
N
|
|
ValidationSuccessIcon
|
検証に成功した場合にステータスメッセージ内に表示する SVG アイコンを選択します。
|
IMAGELINK
|
success
|
N
|
N
|
|
ValueRequired
|
リスト内のアイテムの選択は必須です。
|
BOOLEAN
|
False
|
Y
|
N
|