lightning:input (ベータ)

lightning:input コンポーネントは HTML input 要素を作成します。このコンポーネントは��checkbox、date および datetime、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:input type="checkbox" label="Red" name="red" checked="true"/>
2<lightning:input type="checkbox" label="Blue" name="blue" />

チェックボックスボタンでは、代替ビジュアルデザインの 1 つ以上のオプションを選択できます。

1<lightning:input type="checkbox" label="Add pepperoni" name="addPepperoni" checked="true" value="pepperoni" />
2<lightning:input type="checkbox-button" label="Add salami" name="addSalami" value="salami" />

カラーピッカーを使用するかテキスト項目に色を入力して、色を指定できます。カラーピッカーは現在、Lightning Design System スタイル設定をサポートしていません。

1<lightning:input type="color" label="Color" name="color" value="#EEEEEE"/>

日付を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定をサポートしていません。日付形式は、onblur イベント時に自動的に検証されます。

1<lightning:input type="date" label="Birthday" name="date" />

日時を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定をサポートしていません。日時形式は、onblur イベント時に自動的に検証されます。

1<lightning:input type="datetime-local" label="Birthday" name="datetime" />

メールアドレスを入力するための入力項目。メールパターンは、onblur イベント時に自動的に検証されます。

1<lightning:input type="email" label="Email" name="email" value="abc@domain.com" />

[ファイルをアップロード] ボタンまたはドラッグアンドドロップゾーンを使用して、ファイルをアップロードするための入力項目。選択されたファイルのリストを取得するには、event.getSource().get("v.files"); を使用します。

1<lightning:input type="file" label="Attachment" name="file" multiple="true" accept="image/png, .zip" onchange="{! c.handleFilesChange }"/>

type="file" を使用してアップロードするファイルには、1 MB のサイズ制限が適用されます。チャンクを使用する場合はサイズ制限は 4 MB になります。ファイルアップロードを処理する Apex コントローラにコンポーネントを結び付ける必要があります。または、lightning:fileUpload コンポーネントを使用して、統合された方法でレコードにファイルをアップロードすることもできます。

月と年を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定を継承しません。月と年の形式は、onblur イベント時に自動的に検証されます。

1<lightning:input type="month" label="Birthday" name="month" />

数値を入力するための入力項目。数値入力を操作する場合は、max、min、step などの属性を使用できます。

1<lightning:input type="number" name="number" label="Number" value="12345"/>

数値入力をパーセントまたは通貨として書式設定するには、formatter をそれぞれ percent または currency に設定します。

1<lightning:input type="number" name="ItemPrice" 
2    label="Price" value="12345" formatter="currency"/>

パーセント入力と通貨入力の項目では、ネイティブ実装によって要求されるように、段階的な増分を 0.01 に指定する必要があります。

1<lightning:input type="number" name="decimal" label="Enter a decimal value" step="0.001"/>
2<lightning:input type="number" name="percentVal" label="Enter a percentage value" formatter="percent" step="0.01" />
3<lightning:input type="number" name="currencyVal" label="Enter a dollar amount" formatter="currency" step="0.01" />

パスワードを入力するための入力項目。入力した文字はマスクされます。

1<lightning:input type="password" label="Password" name="password" />

ラジオボタンでは、指定された数のオプションの 1 つのみを選択できます。lightning:input type="radio" は、単一ラジオボックスの作成に役立ちます。ラジオボタンのセットを操作している場合は、代わりに lightning:radioGroup を使用します。

1<lightning:input type="radio" label="Red" name="red" value="red" checked="true" />
2<lightning:input type="radio" label="Blue" name="blue" value="blue" />

数値を入力するためのスライダコントロール。数値入力を操作する場合は、max、min、step などの属性を使用できます。

1<lightning:input type="range" label="Number" name="number" min="0" max="10" />

検索文字列を入力するための入力項目。この項目には、Lightning Design System 検索ユーティリティアイコンが表示されます。

1<lightning:input type="search" label="Search" name="search" />

電話番号を入力するための入力項目。pattern 属性を使用して、項目検証のパターンを定義します。

1<lightning:input type="tel" label="Telephone" name="tel" value="343-343-3434" pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}"/>

テキストを入力するための入力項目。これはデフォルトの入力種別です。

1<lightning:input label="Name" name="myname" />

時間を入力するための入力項目。時間形式は、onblur イベント時に自動的に検証されます。

1<lightning:input type="time" label="Time" name="time" />

指定された 2 つの値の 1 つを選択するためのチェックボックスの切り替え。

1<lightning:input type="toggle" label="Toggle value" name="togglevalue" checked="true" />

URL を入力するための入力項目。この URL パターンは、onblur イベント時に自動的に検証されます。

1<lightning:input type="url" label="Website" name="website" />

週と年を入力するための入力項目。日付ピッカーは現在、Lightning Design System スタイル設定を継承しません。週と年の形式は、onblur イベント時に自動的に検証されます。

1<lightning:input type="week" label="Week" name="week" />

このコンポーネントでは、クライアント側で入力規則が使用できます。たとえば、url または email の入力種別に対して URL やメールアドレスを入力する必要がある場合にエラーメッセージが表示されます。

その他の項目要件を定義できます。たとえば、最大長を設定するには maxlength 属性を使用します。

1<lightning:input name="quantity" value="1234567890" label="Quantity" maxlength="10" />

入力の有効性状態を確認するには、ValidityState Web API に基づく validity 属性を使用します。項目が有効かどうかを判断するために、クライアント側コントローラの有効性状態にアクセスできます。たとえば、次の入力項目があるとします。

1<lightning:input name="input" aura:id="myinput" label="Enter some text" onblur="{! c.handleBlur }" />

valid プロパティは、すべての制約検証が満たされた場合に true を返します (この場合はなし)。

1handleBlur: function (cmp, event) {
2    var validity = cmp.find("myinput").get("v.validity");
3    console.log(validity.valid); //returns true
4    }

たとえば、数種類の項目とボタンが 1 つ設定された次のフォームがあるとします。無効な項目にエラーメッセージを表示するには、showHelpMessageIfInvalid() メソッドを使用します。

1<aura:component>
2        <lightning:input aura:id="field" label="First name" placeholder="First name" required="true" />
3        <lightning:input aura:id="field" label="Last name" placeholder="Last name" required="true" />        
4        <lightning:button aura:id="submit" type="submit" label="Submit" onclick="{! c.onClick }" />
5</aura:component>

クライアント側コントローラで項目を検証します。

1({
2    onClick: function (cmp, evt, helper) {
3        var allValid = cmp.find('field').reduce(function (validSoFar, inputCmp) {
4            inputCmp.showHelpMessageIfInvalid();
5            return validSoFar && inputCmp.get('v.validity').valid;
6         }, true);
7         if (allValid) {
8             alert('All form entries look valid. Ready to submit!');
9         } else {
10             alert('Please update the invalid form entries and try again.');
11         }
12     }
13})

この 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 文字未満の場合にカスタムエラーメッセージを表示します。

1<lightning:input name="firstname" label="First Name" minlength="5" 
2    messageWhenBadInput="Your entry must be at least 5 characters." />

maxlength は、入力できる文字数を制限します。許可されている文字数を超えて入力できないため、messageWhenTooLong エラーメッセージはトリガされません。ただし、messageWhenPatternMismatch と pattern を使用して同じ動作を実現できます。

1<lightning:input type="text" messageWhenPatternMismatch="Too many characters!" pattern=".{0,5}" name="input-name" label="Enter up to 5 characters" />

次の入力種別はサポートされていません。

• button
• hidden
• image
• reset
• submit

入力種別が button、reset、および submit の場合、代わりに lightning:button を使用します。

また、チェックボックス、ラジオボタン、トグルスイッチを操作するときは、aura:id を使用し、コンポーネントの配列をグループ化してトラバースします。get("v.checked") を使用して、どの要素がオンまたはオフになっているかを判断することができ、DOM にアクセスする必要がありません。name 属性と value 属性を使用し、反復中に各コンポーネントを識別することもできます。次の例では、aura:id を使用して 3 個のチェックボックスをグループ化しています。

1<aura:component>
2    <fieldset>
3        <legend>Select your favorite color:</legend>
4        <lightning:input type="checkbox" label="Red" 
5            name="color1" value="1" aura:id="colors"/>
6        <lightning:input type="checkbox" label="Blue" 
7            name="color2" value="2" aura:id="colors"/>
8        <lightning:input type="checkbox" label="Green" 
9            name="color3" value="3" aura:id="colors"/>
10    </fieldset>
11<lightning:button label="Submit" onclick="{!c.submitForm}"/>
12</aura:component>

アクセシビリティのためのテキスト表示ラベルを指定して、情報が支援技術で使用できるようにする必要があります。label 属性は、入力コンポーネントの HTML label 要素を作成します。表示ラベルをビューに表示させず、支援技術には使用できるようにするには、label-hidden バリエーションを使用します。

このコンポーネントは、次のメソッドをサポートします。

focus(): フォーカスを要素に設定します。

showHelpMessageIfInvalid(): フォームコントロールが無効な状態の場合、ヘルプメッセージを表示します。