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リソースを使います。次の例では、resourcesブロックが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.textがEditTextコンポーネントのtextコンテンツに設定されます。

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

event.sourceの詳細については、eventプロパティを参照してください。

onTextChangeイベントハンドラーは、コンポーネントのデータバインディングコンテキストで通常モードで実行されます。

以下は、Textコンポーネントのtextプロパティを入力されたデータで更新する、onTextChangeハンドラーを含むEditTextコンポーネントの例です。onSubmitハンドラーは、結果が「最終」であることを示すようにコンポーネントを更新し、さらにSendEventコマンドも実行します。Echo Showなどのデバイスでは、EditTextコンポーネントをタップして画面上のキーボードを開きます。コードサンドボックスでフィールド内をクリックし、通常のキーボードを使用して入力してからEnterキーを押すと、onSubmitハンドラーの結果が表示されます。この例をスキルにコピーして、SendEventコマンドをテストしてください。

---

onSubmit

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

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

event.sourceの詳細については、eventプロパティを参照してください。

onSubmitイベントハンドラーは、コンポーネントのデータバインディングコンテキストで通常モードで実行されます。

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コンポーネントにフォーカスが当てられたときに境界線の色と幅を変更します。

Echo Showなどのデバイスでは、EditTextコンポーネントをタップして画面上のキーボードを開きます。コードサンドボックスでフィールド内をクリックし、通常のキーボードを使用して入力してからEnterキーを押すと、onSubmitハンドラーの結果が表示されます。Set FocusとClear Focusをクリックすると、定義されたスタイルの効果を確認できます。

---

関連トピック

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

---

---

最終更新日: 2025 年 12 月 02 日