APL EditText



APL EditText

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

プロパティ

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"
    }
  }
}