APL EditText

APL EditText

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

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

プロパティ

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に報告されます。

{
  // 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単位の幅(パディングを含む)        
}

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

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

  • LTREditTextコンポーネントのカーソルは左から右に移動します。
  • RTLEditTextコンポーネントのカーソルは右から左に移動します。

borderColor

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

borderStrokeWidth

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

親コンポーネント内でコンポーネントの位置を再レイアウトせずに、描画された境界線の幅を変更する場合は、このプロパティをborderWidthとは別に設定します。たとえば、borderWidth2に設定し、borderStrokeWidth1に設定したとします。コンポーネントは1ピクセルの境界線で表示されますが、viewport上には2ピクセルの境界線分のスペースが確保されます。borderStrokeWidth2に変更すると、コンポーネントは確保するスペースを変更することなく、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です。normalboldがランタイムに割り当てられています。100から900までの整数値がフォントバリエーションに対応しており、数字が大きくなると太くなります。ほとんどのフォントは、これほど多くのバリエーションはサポートしていません。たとえば、Amazon Ember Displayには5種類の太さ(Thin、Light、Regular、Medium、Bold)があり、それぞれ100、300、500、700、900が割り当てられています。

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

fontWeightのリソースを作成する場合、stringリソースを使います。次の例では、resourceブロックがmyMidFontWeightmyLightFontWeightという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(デフォルト)キーボードとなります。

lang

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

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

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

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

{
    "type": "APL",
    "version": "1.9",
    "mainTemplate": {
        "item": {
            "type": "EditText",
            "lang": "ja-JP",
            "fontFamily": "Noto Sans CJK"
        }
    }
}

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

maxLength

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

onTextChange

ユーザーがコンポーネントに表示されたテキストを変更したときに実行されるコマンドです。このアクションでは、event.source.valueEditTextコンポーネントの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.9",
  "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"
    }
  }
}