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
がサポートされます。
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進数の文字に制限しています。
{
"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"
}
}
}