APL EditText
EditTextコンポーネントは、テキストを編集可能なボックス内に表示し、1行のテキストを編集できるようにします。
EditTextを使用するには、APL 1.4以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。プロパティ
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 | ◯ | ✕ | ユーザーがコンポーネントを選択したときに表示されるキーボードの種類です。 |
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に報告されます。
{
// EditText固有の値
"type": "EditText",
"text": String, // 表示されるテキスト（ ヒントのテキストではない）
"color": Color, // テキストの色
// 一般的なコンポーネントの値
"bind": Map, // コンポーネントのデータバインディングコンテキストへのアクセス
"checked": Boolean, // チェック済みの状態
"disabled": Boolean, // 無効化の状態
"focused": Boolean, // フォーカス状態
"height": Number, // コンポーネントのdp単位の高さ（パディングを含む）
"id": ID, // コンポーネントのID
"opacity": Number, // コンポーネントの不透明度[0～1]
"pressed": Boolean, // 押された状態
"uid": UID, // ランタイムで生成されたコンポーネントの固有ID
"width": Number // コンポーネントのdp単位の幅（パディングを含む）
}
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」を指定し、有効なフォントを確実に利用できるようにしてください。
{
"type": "Text",
"fontFamily", "times new roman, times, georgia, 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つ作成します。
{
"resources": [
{
"strings": {
"myMidFontWeight": "500",
"myLightFontWeight": "100"
}
}
]
}
highlightColor
選択したテキスト領域の背後に表示されるハイライトの色です。ダークテーマはデフォルトが#00CAFF4D、ライトテーマは#0070BA4Dです。
hint
表示するテキストがない場合にテキストブロックに表示するテキスト文字列です。hintは、textが設定されていないか、ユーザーがテキストブロックからテキストを削除した場合に表示されます。
hintColor
ヒントテキストの色です。指定しない場合、デフォルトはテーマおよびデバイスに応じて異なる値になります。
hintStyle
ヒントのフォントスタイルです。normalまたはitalicを指定します。
hintWeight
ヒントのフォントウェイトです。このプロパティの機能は、fontWeightプロパティと同じです。
keyboardType
コンポーネントに表示されるキーボードの種類を指定します。次のいずれかの値を指定できます。
| 型 | 説明 |
|---|---|
| decimalPad | 数字と小数点 |
| emailAddress | 「@」、「.」、およびスペースを含むメールアドレスに最適化されます。 |
| normal | デフォルトのキーボードです。 |
| numberPad | 数字のみ（PINコードに適しています）。 |
| phonePad | 数字、「*」、「#」。 |
| url | URLの入力に最適化されます。 |
APLランタイムがリクエストされたキーボードをサポートしていない場合、コンポーネントのデフォルトはnormal（デフォルト）キーボードとなります。
maxLength
テキスト編集コンポーネントに入力可能なテキストの最大長（文字数）です。0に設定すると、文字数制限なしとなります。一部の環境では、内部で最大長の制限が必要になる場合があります。少なくとも1024文字には対応できることをお勧めします。
onTextChange
ユーザーがコンポーネントに表示されたテキストを変更したときに実行されるコマンドです。このアクションでは、event.source.valueをEditTextコンポーネントのtextコンテンツに設定します。
このハンドラーは、次の形式のイベントを生成します。
"event": {
"source": {
"type": "EditText",
"handler": "TextChange",
... // コンポーネントのソースプロパティ
}
}
event.sourceの詳細についてはイベントソースを参照してください。
onSubmit
ユーザーが定義済みの送信キーを押したときに実行されるコマンドです。submitKeyTypeプロパティを使って「送信」を意味するキーを設定します。
このハンドラーは、次の形式のイベントを生成します。
"event": {
"source": {
"type": "EditText",
"handler": "Submit",
... // コンポーネントのソースプロパティ
}
}
event.sourceの詳細についてはイベントソースを参照してください。
secureInput
trueの場合、コンポーネントはユーザーの入力したすべての文字を非表示にします。このプロパティは、機密性の高いテキストに使用します。次の種類のキーボードで、secureInputがサポートされます。
decimalPadnormalnumberPad
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進数の文字に制限しています。
{
"type": "EditText",
"validCharacters": "0-9a-fA-F"
}
validCharactersプロパティは正規表現ではありません。validCharactersプロパティの目的は入力できる文字を制限することであり、最終的な表現の正しさを検証することではありません。次の表は、特殊文字のルールの一覧です。
| 文字 | 意味 |
|---|---|
- |
Unicodeコードポイントの範囲を指定します。ハイフン（-）を有効な文字に含めるには、文字列の前に配置します。 |
\uXXXX |
特定のUnicodeコードポイントを指定する4桁の16進数です。基本多言語面外のコードポイントは、UTF-16のサロゲートペアを使って記述する必要があります。 |
\" |
クォーテーションマークです。 |
\\ |
バックスラッシュです。 |
例：
"0-9" // PINパッドキーボード
"0-9." // 米国での金額（ATMに最適）
"-+a-zA-Z0-9_@." // 従来のメールアドレス
EditTextの高さおよび幅
コンポーネントの高さと幅のプロパティを設定します。高さと幅を設定しない場合、EditTextが高さと幅を計算します。
コンポーネントの高さは、指定したフォントの文字1行を表示できる高さに設定されます。コンポーネントの幅は、sizeプロパティを使って計算されます。
EditTextのフォーカス状態
EditTextコンポーネントは、フォーカス状態を自動で表示しません。APL Stylesと、borderWidthおよびborderColorプロパティを使って、フォーカスを取得したときにコンポーネントをハイライトします。
以下の例では、条件付きスタイルを使って、EditTextコンポーネントがフォーカスを取得したときに境界線の色と幅を変更します。
{
"type": "APL",
"version": "1.4",
"styles": {
"EditStyle": {
"values": [
{
"borderWidth": 2,
"borderStrokeWidth": 1,
"borderColor": "darkgrey",
"hintColor": "grey",
"hintWeight": "200",
"color": "black",
"fontSize": "20dp",
"size": 10
},
{
"when": "${state.focused}",
"borderColor": "green",
"borderStrokeWidth": 2
}
]
}
},
"mainTemplate": {
"items": {
"type": "EditText",
"style": "EditStyle",
"hint": "郵便番号",
"validCharacters": "-0-9"
}
}
}
