Lightning コンポーネント開発者ガイド
jlightning:input (ベータ)
lightning:input コンポーネントは HTML input 要素を作成します。このコンポーネントは、checkbox、date および datetime-local、email、file、password、search、tel、url、number、radio、toggle など、HTML5 の入力種別をサポートします。デフォルトは text です。
onblur、onfocus、onchange などの入力イベントに対してクライアント側のコントローラを定義できます。たとえば、コンポーネントの値が変���された場合にコンポーネントの変更イベントを処理するには、onchange 属性を使用します。
このコンポーネントは、Lightning Design System の入力からスタイル設定を継承します。
チェックボックスチェックボックスでは、1 つ以上のオプションを選択できます。lightning:input type="checkbox" は、単一チェックボックスの作成に役立ちます。チェックボックスのグループを操作する場合は、代わりに lightning:checkboxGroup を使用します。
チェックボックスボタンでは、代替ビジュアルデザインの 1 つ以上のオプションを選択できます。
カラーピッカーを使用するかテキスト項目に色を入力して、色を指定できます。ネイティブのカラーピッカーが使用されます。
日付を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定をサポートしていません。日付形式は、onblur イベント時に自動的に検証されます。
日時を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定をサポートしていません。日時形式は、onblur イベント時に自動的に検証されます。
メールアドレスを入力するための入力項目。メールパターンは、onblur イベント時に自動的に検証されます。
[ファイルをアップロード] ボタンまたはドラッグアンドドロップゾーンを使用して、ファイルをアップロードするための入力項目。選択されたファイルのリストを取得するには、event.getSource().get("v.files"); を使用します。
月と年を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定を継承しません。月と年の形式は、onblur イベント時に自動的に検証されます。
数値を入力するための入力項目。数値入力を操作する場合は、max、min、step などの属性を使用できます。
数値入力をパーセントまたは通貨として書式設定するには、formatter をそれぞれ percent または currency に設定します。
パーセント入力と通貨入力の項目では、ネイティブ実装によって要求されるように、段階的な増分を 0.01 に指定する必要があります。
パスワードを入力するための入力項目。入力した文字はマスクされます。
ラジオボタンでは、指定された数のオプションの 1 つのみを選択できます。lightning:input type="radio" は、単一ラジオボックスの作成に役立ちます。ラジオボタンのセットを操作している場合は、代わりに lightning:radioGroup を使用します。
数値を入力するためのスライダコントロール。数値入力を操作する場合は、max、min、step などの属性を使用できます。
検索文字列を入力するための入力項目。この項目には、Lightning Design System 検索ユーティリティアイコンが表示されます。
電話番号を入力するための入力項目。pattern 属性を使用して、項目検証のパターンを定義します。
テキストを入力するための入力項目。これはデフォルトの入力種別です。
時間を入力するための入力項目。時間形式は、onblur イベント時に自動的に検証されます。
指定された 2 つの値の 1 つを選択するためのチェックボックスの切り替え。
URL を入力するための入力項目。この URL パターンは、onblur イベント時に自動的に検証されます。
週と年を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定を継承しません。週と年の形式は、onblur イベント時に自動的に検証されます。
このコンポーネントでは、クライアント側で入力規則が使用できます。たとえば、url または email の入力種別に対して URL やメールアドレスを入力する必要がある場合にエラーメッセージが表示されます。
その他の項目要件を定義できます。たとえば、最大長を設定するには maxlength 属性を使用します。
入力の有効性状態を確認するには、ValidityState Web API に基づく validity 属性を使用します。項目が有効かどうかを判断するために、クライアント側コントローラの有効性状態にアクセスできます。たとえば、次の入力項目があるとします。
valid プロパティは、すべての制約検証が満たされた場合に true を返します (この場合はなし)。
たとえば、数種類の項目とボタンが 1 つ設定された次のフォームがあるとします。無効な項目にエラーメッセージを表示するには、showHelpMessageIfInvalid() メソッドを使用します。
クライアント側コントローラで項目を検証します。
この validity 属性は、次の boolean プロパティがあるオブジェクトを返します。
- badInput: 値が無効であることを示します
- patternMismatch: 値が指定されたパターンに一致していないことを示します。
- rangeOverflow: 値が指定された max 属性よりも大きいことを示します。
- rangeUnderflow: 値が指定された min 属性よりも小さいことを示します。
- stepMismatch: 値が指定された step 属性に一致していないことを示します。
- tooLong: 値が指定された maxlength 属性を超えていることを示します。
- typeMismatch: 値がメールまたは url 入力種別の所定の構文に一致していないことを示します。
- valid: 値が有効であることを示します。
- valueMissing: required 属性が true に設定されている場合に、空の値が指定されたことを示します。
入力規則の検証に失敗した場合、デフォルトで次のメッセージが表示されます。
- badInput: 有効な値を入力してください。
- patternMismatch: エントリは許可されているパターンと一致しません。
- rangeOverflow: 数値が高すぎます。
- rangeUnderflow: 数値が低すぎます。
- stepMismatch: エントリは有効な増分ではありません。
- tooLong: エントリが長すぎます。
- typeMismatch: 無効な形式を入力しました。
- valueMissing: この項目を入力してください。
次の属性に独自の値を指定することでデフォルトのメッセージを上書きできます: messageWhenBadInput、messageWhenPatternMismatch、messageWhenTypeMismatch、messageWhenValueMissing、messageWhenRangeOverflow、messageWhenRangeUnderflow、messageWhenStepMismatch、messageWhenTooLong。
たとえば、入力が 5 文字未満の場合にカスタムエラーメッセージを表示します。
maxlength は、入力できる文字数を制限します。許可されている文字数を超えて入力できないため、messageWhenTooLong エラーメッセージはトリガされません。ただし、messageWhenPatternMismatch と pattern を使用して同じ動作を実現できます。
次の入力種別はサポートされていません。
- button
- hidden
- image
- reset
- submit
入力種別が button、reset、および submit の場合、代わりに lightning:button を使用します。
また、チェックボックス、ラジオボタン、トグルスイッチを操作するときは、aura:id を使用し、コンポーネントの配列をグループ化してトラバースします。get("v.checked") を使用して、どの要素がオンまたはオフになっているかを判断することができ、DOM にアクセスする必要がありません。name 属性と value 属性を使用し、反復中に各コンポーネントを識別することもできます。次の例では、aura:id を使用して 3 個のチェックボックスをグループ化しています。
アクセシビリティのためのテキスト表示ラベルを指定して、情報が支援技術で使用できるようにする必要があります。label 属性は、入力コンポーネントの HTML label 要素を作成します。表示ラベルをビューに表示させず、支援技術には使用できるようにするには、label-hidden バリエーションを使用します。
メソッドこのコンポーネントは、次のメソッドをサポートします。
focus(): フォーカスを要素に設定します。
showHelpMessageIfInvalid(): フォームコントロールが無効な状態の場合、ヘルプメッセージを表示します。
属性
| 属性名 | 属性型 | 説明 | 必須項目 |
|---|---|---|---|
| accept | String | サーバが受け入れるファイルの種類を指定します。この属性は、type='file' の場合のみ使用できます。 | |
| accesskey | String | 要素の有効化またはフォーカス設定のためのショートカットキーを指定します。 | |
| body | Component[] | コンポーネントのボディ。マークアップでは、これはタグのボディに含まれるすべてを指します。 | |
| checked | Boolean | チェックボックスをオンにするかどうかを指定します。この値のデフォルトは false です。 | |
| class | String | コンポーネントの基本クラスに加え、外部要素の CSS クラス。 | |
| disabled | Boolean | 入力要素を無効にするかどうかを指定します。この値のデフォルトは false です。 | |
| files | Object | 選択されたファイルが含まれる FileList。この属性は、type='file' の場合のみ使用できます。 | |
| formatter | String | 使用するフォーマッタを伴う文字列値。 | |
| isLoading | Boolean | データが読み込み中であることを示すスピナーを表示するかどうかを指定します。この値のデフォルトは false です。 | |
| label | String | 入力のテキスト表示ラベル。 | はい |
| max | decimal | 浮動小数点数の値の上限。 | |
| maxlength | Integer | 項目内で使用できる最大文字数。 | |
| messageToggleActive | String | 切り替えの有効状態を示すテキスト。デフォルトは「Active」(有効) です。 | |
| messageToggleInactive | String | 切り替えの無効状態を示すテキスト。デフォルトは「Inactive」(無効) です。 | |
| messageWhenBadInput | String | 不正な入力が検出された場合に表示されるエラーメッセージ。 | |
| messageWhenPatternMismatch | String | パターンの不一致が検出された場合に表示されるエラーメッセージ。 | |
| messageWhenRangeOverflow | String | 範囲を超えたことが検出された場合に表示されるエラーメッセージ。 | |
| messageWhenRangeUnderflow | String | 範囲を下回ったことが検出された場合に表示されるエラーメッセージ。 | |
| messageWhenStepMismatch | String | ステップの不一致が検出された場合に表示されるエラーメッセージ。 | |
| messageWhenTooLong | String | 値が長すぎる場合に表示されるエラーメッセージ。 | |
| messageWhenTypeMismatch | String | 種別の不一致が検出された場合に表示されるエラーメッセージ。 | |
| messageWhenValueMissing | String | 値がない場合に表示されるエラーメッセージ。 | |
| min | decimal | 浮動小数点数の値の下限。 | |
| minlength | Integer | 項目内で使用できる最小文字数。 | |
| multiple | Boolean | ユーザが複数の値を入力できることを指定します。この属性は、type='file' または type='email' の場合のみ使用できます。 | |
| name | String | 入力要素の名前を指定します。 | はい |
| onblur | Action | 要素がフォーカスを解放したときにトリガされるアクション。 | |
| onchange | Action | 値属性が変更された場合にトリガされるアクション。 | |
| onfocus | Action | 要素にフォーカスが設定されたときにトリガされるアクション。 | |
| pattern | String | 入力値をチェックする正規表現を指定します。この属性は、text、date、search、url、tel、email、password の種別でサポートされます。 | |
| placeholder | String | 項目が空の場合に、ユーザに有効な入力を求めるためのテキスト。 | |
| readonly | Boolean | 入力項目が参照のみであることを指定します。この値のデフォルトは false です。 | |
| required | Boolean | フォームを送信する前に入力項目が入力されている必要があることを指定します。この値のデフォルトは false です。 | |
| step | Object | 正の浮動小数点の値の粒度。粒度が重要でない場合は、「any」を使用します。 | |
| tabindex | Integer | 要素のタブ順序を指定します (タブボタンがナビゲーションに使用される場合)。 | |
| type | String | 入力の種別。この値のデフォルトは text です。 | |
| validity | Object | 制約検証に対して要素が取ることのできる有効性状態を表します。 | |
| value | Object | 入力要素の値を指定します。 | |
| variant | String | バリエーションは入力項目の外観を変更します。使用できるバリエーションは standard と label-hidden です。この値のデフォルトは standard です。 |