APL EditText

EditTextコンポーネントは、テキストを編集可能なボックス内に表示し、1行のテキストを編集できるようにします。

環境によっては、編集可能なテキストを使えない場合があります。環境プロパティのdisallowEditTextを使って、現在のデバイスと設定が、編集可能なテキストをサポートしているかどうかを判断します。

プロパティ

EditTextコンポーネントには、次のプロパティがあります。

• すべてのアクション可能なコンポーネントのプロパティ
• すべての基本コンポーネントのプロパティ
• 次の表は、EditTextプロパティの一覧です。列の意味はこちらを参照してください。

プロパティ	型	デフォルト	スタイル設定	動的	説明
borderColor	色	<none>	◯	◯	テキストボックスの周りの境界線の色です。
borderStrokeWidth	負でない絶対ディメンション	<borderWidth>	◯	◯	テキストボックスを囲む境界線の幅です。
borderWidth	負でない絶対ディメンション	0	◯	◯	境界線の幅です。
color	色	テーマによって異なります	◯	◯	ユーザーが入力したテキスト、またはtextプロパティに指定したテキストの色です。
fontFamily	文字列	sans-serif	◯	◯	フォントファミリーの名前です。
fontSize	正の絶対ディメンション	40dp	◯	◯	テキストのサイズです。
fontStyle	normal, italic	normal	◯	◯	フォントのスタイルです。
fontWeight	normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900	normal	◯	◯	フォントの太さです。
highlightColor	色	テーマによって異なります	◯	◯	選択したテキストの後ろに表示するハイライト色です。
hint	文字列	""	◯	◯	テキストが入力されていないときに表示されるヒントテキストです。textプロパティに値がある場合は表示されません。
hintColor	色	テーマによって異なります	◯	◯	ヒントテキストの色です。
hintStyle	normal, italic	normal	◯	◯	ヒントのフォントスタイルです。
hintWeight	normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900	normal	◯	◯	ヒントのフォントの太さです。
keyboardType	KeyboardType	normal	◯	✕	ユーザーがコンポーネントを選択したときに表示されるキーボードの種類です。
lang	文字列	""	◯	◯	テキストの言語です。指定すると、APLはテキスト表示の際、fontFamilyの言語固有のバージョンを探します。
maxLength	負でない数値	0	◯	✕	ユーザーが編集ボックスに入力できる最大文字数です。
onTextChange	コマンドの配列	[]	✕	✕	テキストがユーザーイベントで変更されたときに実行するコマンドです。
onSubmit	コマンドの配列	[]	✕	✕	ユーザーが指定した送信キー（submitKeyType）を押して変更を送信したときに実行するコマンドです。
secureInput	ブール値	false	◯	◯	trueの場合、入力された文字を非表示にします。
selectOnFocus	ブール値	false	◯	✕	trueの場合、EditTextコンポーネントがフォーカスを取得したときにテキストを選択します。
size	正の整数	8	◯	✕	表示するおおよその文字数を指定します。
submitKeyType	SubmitKeyType	done	◯	✕	リターンキーの種類です。指定されたキーがonSubmitイベントを送信します。
text	文字列	""	✕	◯	表示するテキストを指定します。
validCharacters	文字列	""	◯	✕	入力できる文字を制限します。

EditTextがイベントのソースまたはターゲットの場合、以下の値がevent.sourceまたはevent.targetに報告されます。

layoutDirectionコンポーネントプロパティ

コンポーネントのlayoutDirectionプロパティにより、編集するテキストのカーソルの開始ポイントと方向が決まります。

• LTR：EditTextコンポーネントのカーソルは左から右に移動します。
• RTL：EditTextコンポーネントのカーソルは右から左に移動します。

borderColor

EditTextボックスを囲む境界線の色です。

borderStrokeWidth

テキストボックスの周りに「描画された」境界線の幅です。指定しない場合、borderStrokeWidthは既定のborderWidthに設定されます。指定すると、描画される境界線の実際の幅は、borderStrokeWidthとborderWidthのより小さい値になります。境界線を境界線の幅の外側に描画することはできません。

親コンポーネント内でコンポーネントの位置を再レイアウトせずに、描画された境界線の幅を変更する場合は、このプロパティをborderWidthとは別に設定します。たとえば、borderWidthを2に設定し、borderStrokeWidthを1に設定したとします。コンポーネントは1ピクセルの境界線で表示されますが、viewport上には2ピクセルの境界線分のスペースが確保されます。borderStrokeWidthを2に変更すると、コンポーネントは確保するスペースを変更することなく、2ピクセルの境界線で表示されます。

これに対し、borderWidth を単独で使用して1から2に変更すると、画面に表示されるコンポーネントが幅の広い境界線に合わせて変動します。

borderWidth

テキストボックスの周りの境界線の幅です。borderWidthは絶対ディメンションで指定します。相対ディメンションは使用できません。境界線の幅はEditTextコンポーネントのパディングには影響しません。

color

表示されるテキストの色です。ダークテーマはデフォルトを#FAFAFAに、ライトテーマは#1E2222に設定してください。

fontFamily

表示されるテキストのフォントを指定します。fontFamilyプロパティには、単一のフォント名、またはコンマ区切りのフォント名リストを含む文字列を指定できます。APLランタイムによって、デバイスにインストールされている最初の名前付きフォントのリストが検索されます。有効なフォントが見つからない場合は、デフォルトのsans-serifフォントに設定されます。

フォント名にはスペースを使用できます。APLでは、次の2種類のフォント名がサポートされています。

• インストールされているフォントの固有名（「amazon-ember」、「times」、「times new roman」など）
• 総称（「serif」または「sans-serif」）

Alexaデバイスでは、特定のフォントセットは保証されません。fontFamilyリストの最後には、「serif」または「sans-serif」を指定し、有効なフォントを確実に利用できるようにしてください。

多くのAlexaデバイスでは、「sans-serif」のデフォルトは「Amazon Ember Display」、「serif」のデフォルトは「Bookerly」です。アジアの一部のマーケットでは、これらのデフォルトは「Noto Sans CJK」です。

alexa-stylesパッケージで利用可能なフォントスタイルの詳細については、フォントファミリーを参照してください。

fontSize

フォントのサイズです。デフォルトは40dpです。フォントサイズは、相対ディメンションではなく、絶対ディメンションで指定します。

fontStyle

normalまたはitalicのフォントスタイルです。デフォルトはnormalです。

fontWeight

表示されるテキストのフォントウェイトです。デフォルトはnormalです。normalとboldがランタイムに割り当てられています。100から900までの整数値がフォントバリエーションに対応しており、数字が大きくなると太くなります。ほとんどのフォントは、これほど多くのバリエーションはサポートしていません。たとえば、Amazon Ember Displayには5種類の太さ（Thin、Light、Regular、Medium、Bold）があり、それぞれ100、300、500、700、900が割り当てられています。

fontWeightは、整数や文字列としてではなく、列挙セットを表すことに注意してください。たとえば、750という値は無効であり、フォントのウェイトは700～800の間には設定されません。

fontWeightのリソースを作成する場合、stringリソースを使います。次の例では、resourceブロックがmyMidFontWeightとmyLightFontWeightというfontWeightのリソースを2つ作成します。

highlightColor

選択したテキスト領域の背後に表示されるハイライトの色です。ダークテーマはデフォルトが#00CAFF4D、ライトテーマは#0070BA4Dです。

hint

表示するテキストがない場合にテキストブロックに表示するテキスト文字列です。hintは、textが設定されていないか、ユーザーがテキストブロックからテキストを削除した場合に表示されます。

hintColor

ヒントテキストの色です。指定しない場合、デフォルトはテーマおよびデバイスに応じて異なる値になります。

hintStyle

ヒントのフォントスタイルです。normalまたはitalicを指定します。

hintWeight

ヒントのフォントウェイトです。このプロパティの機能は、fontWeightプロパティと同じです。

keyboardType

コンポーネントに表示されるキーボードの種類を指定します。次のいずれかの値を指定できます。

型	説明
decimalPad	数字と小数点が表示されます。
emailAddress	「@」、「.」、およびスペースを含むメールアドレスの入力に最適化されます。
normal	デフォルトのキーボードです。
numberPad	数字のみです（PINコードに適しています）。
phonePad	数字と「*」と「#」が表示されます。
url	URLの入力に最適化されます。

APLランタイムがリクエストされたキーボードをサポートしていない場合、コンポーネントのデフォルトはnormal（デフォルト）キーボードとなります。

lang

テキストの言語です。指定すると、APLはテキスト表示の際、fontFamilyの言語固有のバージョンを探します。

有効なフォントが見つからない場合、APLはこのプロパティを無視し、指定されたfontFamilyを使用します。

langプロパティにBCP-47文字列を設定します（例："ja-JP"）。

以下の例は、NotoSans-CJKフォントの日本語スタイルバージョンを使ってEditTextコンポーネントを表示しています。

注： Alexaデバイスには特定の言語のフォントがインストールされていない場合があります。さまざまなデバイスで正常に動作するかどうかエクスペリエンスをテストしてください。

maxLength

テキスト編集コンポーネントに入力可能なテキストの最大長（文字数）です。0に設定すると、文字数制限なしとなります。一部の環境では、内部で最大長の制限が必要になる場合があります。少なくとも1024文字には対応できることをお勧めします。

onTextChange

ユーザーがコンポーネントに表示されたテキストを変更したときに実行されるコマンドです。このアクションでは、event.source.valueをEditTextコンポーネントのtextコンテンツに設定します。

このハンドラーは、次の形式のイベントを生成します。

event.sourceの詳細についてはイベントソースを参照してください。

onSubmit

ユーザーが定義済みの送信キーを押したときに実行されるコマンドです。submitKeyTypeプロパティを使って「送信」を意味するキーを設定します。

このハンドラーは、次の形式のイベントを生成します。

event.sourceの詳細についてはイベントソースを参照してください。

secureInput

trueの場合、コンポーネントはユーザーの入力したすべての文字を非表示にします。このプロパティは、機密性の高いテキストに使用します。次の種類のキーボードで、secureInputがサポートされます。

• decimalPad
• normal
• numberPad

selectOnFocus

trueの場合、コンポーネントはフォーカスのあるテキストブロックをハイライトします。ユーザーは、1回のバックスペースキーで、コンポーネント内の既存テキストをすべて削除できます。falseの場合、カーソル挿入ポイントはテキストの末尾に表示されます。このプロパティのデフォルトはfalseです。

size

現在のフォントで「normal-width」幅の文字がsize個ある想定で、EditTextコンポーネントのデフォルト幅を指定します。EditTextコンポーネントに合う実際の文字数は、実際の文字の幅によって異なります。

submitKeyType

送信キーの種類を指定します。キーのラベルは、基盤となるプラットフォームによって異なります。次の種類を指定できます。

型	Echo Showデバイスのラベルサンプル（英語（米国））
done	Done
go	Go
next	Next
search	Search
send	Send

送信キーのlabelにかかわらず、ユーザーがキーを押すとonSubmitイベントが実行されます。

text

テキストブロックに表示するテキスト文字列です。文字列を空にすると、テキストは表示されません。nullに設定すると、文字列を空（""）にした場合と同じ結果になります。

textが空またはnullの場合、EditTextコンポーネントはhintTextを表示します。表示されているtextは、ユーザーが入力したテキストで置き換えられます。

validCharactersに設定された文字制限は、textプロパティに適用されます。たとえば、validCharactersでユーザーが入力できる文字セットを制限する場合、textにも同じ制限を満たす値を設定する必要があります。

validCharacters

設定すると、ユーザーがEditTextコンポーネントに入力できる文字が、指定した文字に制限されます。空白または設定されない場合、入力できる文字は制限されません。

この制限は、textプロパティに適用されます。これには、textプロパティを設定または変更する、次のようなすべてのシナリオが含まれます。

• APLドキュメント内のtextプロパティに初期値を設定する場合
• SetValueコマンドを使用して、textプロパティの値を設定または変更する場合
• ユーザーがEditTextコンポーネントを選択して値を入力する場合

validCharactersプロパティは、hintTextプロパティには適用されません。

以下の例では、コンポーネントを16進数の文字に制限しています。

validCharactersプロパティは正規表現ではありません。validCharactersプロパティの目的は入力できる文字を制限することであり、最終的な表現の正しさを検証することではありません。次の表は、特殊文字のルールの一覧です。

文字	意味
-	Unicodeコードポイントの範囲を指定します。ハイフン（-）を有効な文字に含めるには、文字列の前に配置します。
\uXXXX	特定のUnicodeコードポイントを指定する4桁の16進数です。基本多言語面外のコードポイントは、UTF-16のサロゲートペアを使って記述する必要があります。
\"	クォーテーションマークです。
\\	バックスラッシュです。

例：

EditTextの高さおよび幅

コンポーネントの高さと幅のプロパティを設定します。高さと幅を設定しない場合、EditTextが高さと幅を計算します。

コンポーネントの高さは、指定したフォントの文字1行を表示できる高さに設定されます。コンポーネントの幅は、sizeプロパティを使って計算されます。

EditTextのフォーカス状態

EditTextコンポーネントは、フォーカス状態を自動で表示しません。APL Stylesと、borderWidthおよびborderColorプロパティを使って、フォーカスを取得したときにコンポーネントをハイライトします。

以下の例では、条件付きスタイルを使って、EditTextコンポーネントがフォーカスを取得したときに境界線の色と幅を変更します。

関連トピック

• 基本コンポーネントのプロパティ
• アクション可能なコンポーネントのプロパティ
• APL Text