Check Box

CheckBoxレスポンシブ対応コンポーネント（AlexaCheckbox）は、ユーザーがチェック状態を切り替えられるチェックボックスを表示します。チェックボックスのサイズ、色、ユーザーがチェックボックスを操作したときに実行するコマンドを制御できます。

alexa-layoutsパッケージを読み込む

AlexaCheckboxを使用するには、alexa-layoutsパッケージを読み込みます。

alexa-layoutsパッケージの最新バージョンは1.2.0です。AlexaCheckboxはバージョン1.2.0で導入されました。

AlexaCheckboxのパラメーター

type以外のパラメーターはすべてオプションです。

名前	型	デフォルト	説明	追加または更新されたバージョン
`accessibilityLabel`	文字列	なし	チェックボックスを説明する文字列です。ユーザーがボックスを選択したときに、この文字列が読み上げられます。	1.2.0
`checkboxHeight`	ディメンション	viewportに基づく高さ	チェックボックスの高さです。	1.2.0
`checkboxWidth`	ディメンション	viewportに基づく幅	チェックボックスの幅です。	1.2.0
`entities`	配列	[]	このコンポーネントにバインドするentityデータの配列です。	1.2.0
`primaryAction`	コマンド	なし	ユーザーがチェックボックスを選択したときに実行されるアクションです。	1.2.0
`selectedColor`	色	青色。具体的な色調は指定した`theme`によって異なります。	チェックボックス選択時（`checked`が`true`）に塗りつぶしに使われる色です。	1.2.0
`theme`	文字列	dark	色のテーマをダークまたはライトに設定します。テーマを選択することでコンポーネントの色を制御します。	1.2.0
`type`	文字列	なし	常に`AlexaCheckbox`に設定されます。	1.2.0

checked（チェック）状態

AlexaCheckboxは、標準のcheckedコンポーネント状態を使って、コンポーネントをチェック済み、チェックなしのどちらで表示するかを判断します。ドキュメントにコンポーネントを配置したら、checkedをtrueかfalseに初期化します。

checkedをtrueに設定すると、チェックボックスは単色で塗りつぶされ、チェックマークが表示されます。
falseに設定すると、枠線と空のボックスが表示されます。コンポーネントのchecked状態のデフォルトはfalseです。

AlexaCheckboxには、indeterminateという3つ目の状態があります。この状態は、チェックボックスが「部分的に」選択されているというシナリオで使用します。たとえば、サブオプションのグループを表すチェックボックスの一部が選択され、一部が選択されていない場合などです。この状態の詳細については、isIndeterminateプロパティを参照してください。

ユーザーがチェックボックスを操作すると、コンポーネントは自動的にchecked状態を切り替えます。手動でchecked状態をトラッキングしたり、更新したりする必要はありません。

以下の例では、チェックボックスを2行にわたって表示しています。1行目のチェックボックスは、checkedをtrueに初期化しています。2行目は、checkedをデフォルトのfalseのままにしています。

disabled（無効）状態

AlexaCheckboxは、標準のdisabledコンポーネント状態を使って、コンポーネントを有効、無効のどちらとして表示するかを判断します。disabledがtrueの場合、チェックボックスはタッチやリモートなどのユーザー操作に一切反応しません。

disabled状態は、checked状態に依存しません。このため、無効のチェックボックスは、いずれのチェック状態でも表示できます。

以下の例では、disabledのチェックボックスを2列にわたって表示しています。1行目のチェックボックスは、checkedをtrueに設定しています。2行目は、checkedをデフォルトのfalseのままにしています。

isIndeterminate

AlexaCheckboxは、isIndeterminateプロパティを使って3つ目のチェックボックス状態を表します。isIndeterminateがtrueの場合、チェックボックスは単色で塗りつぶされ、チェックマークではなく横線が表示されます。

この状態を使って、「部分的に」選択されたチェックボックスを表します。たとえば、それぞれがチェックボックスを持つ、項目のリストを表示するとします。ヘッダーには、代表のチェックボックスを1つ表示し、リスト全体の状態を表します。項目の一部が選択されている場合、ヘッダーのチェックボックスを不確定状態として表示します。

ユーザーがチェックボックスをオン／オフすると、AlexaCheckboxはchecked状態を切り替え、isIndeterminateをデフォルトのfalseに設定します。チェックボックスの最終結果は、checkedを切り替えた結果によって異なります。たとえば、次のようになります。

checkedがtrueでisIndeterminateがtrue –
- チェックボックスは不確定状態です。
- ユーザーがチェックボックスをオンにすると、コンポーネントはcheckedとisIndeterminateの両方をfalseに更新します。チェックボックスはオフ状態に変わります。
checkedがfalseでisIndeterminateがtrue –
- チェックボックスは不確定状態です。
- ユーザーがチェックボックスをオンにすると、コンポーネントはcheckedをtrue、isIndeterminateをfalseに更新します。チェックボックスはオン状態に変わります。

どちらのシナリオでも、ユーザーがもう一度チェックボックスをオンにすると、コンポーネントはcheckedを更新しますが、isIndeterminateは変更しません。チェックボックスが自動的にisIndeterminate状態に戻ることはありません。ユーザーの操作中にisIndeterminateをtrueに設定するには、SetValueコマンドを使用します。

クリップボードにコピーされました。

オーサリングツールでAPLサンプルをテストする方法については、オーサリングツールでAPLサンプルをテストするを参照してください。

{
  "type": "APL",
  "version": "1.5",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.2.0"
    }
  ],
  "layouts": {
    "CheckboxRow": {
      "description": "左側にテキスト、右側に4つのチェックボックスを配置した行を表示します。4つのチェックボックスのchecked状態はすべて同じですが、テーマとdisabled状態は異なります。",
      "parameters": [
        "textToDisplay",
        "checked",
        "disabled",
        "isIndeterminate",
        "arrayOfCheckboxes"
      ],
      "item": {
        "type": "Container",
        "description": "チェックボックス行のメインコンテナです。",
        "direction": "row",
        "width": "100vw",
        "paddingLeft": "@marginHorizontal",
        "paddingRight": "@marginHorizontal",
        "items": [
          {
            "type": "Text",
            "description": "行の説明として渡されたテキストを表示します。",
            "text": "${textToDisplay}",
            "width": "75%",
            "textAlignVertical": "center",
            "shrink": 1,
            "style": "textStyleBody"
          },
          {
            "type": "Container",
            "description": "配列で指定されたdisabled状態とテーマのデータに基づいてチェックボックスを表示します。",
            "direction": "row",
            "data": "${arrayOfCheckboxes}",
            "items": [
              {
                "type": "AlexaCheckbox",
                "checked": "${checked}",
                "isIndeterminate": "${isIndeterminate}",
                "disabled": "${data.disabled}",
                "theme": "${data.theme}"
              }
            ]
          }
        ]
      }
    }
  },
  "mainTemplate": {
    "parameters": [
      "checkBoxStateData"
    ],
    "items": [
      {
        "type": "Container",
        "items": [
          {
            "type": "AlexaHeader",
            "headerTitle": "${checkBoxStateData.headerTitle}",
            "headerSubtitle": "${checkBoxStateData.headerSubtitle}"
          },
          {
            "type": "Sequence",
            "height": "100vh",
            "width": "100vw",
            "data": "${checkBoxStateData.arrayOfCheckboxRows}",
            "items": [
              {
                "type": "CheckboxRow",
                "textToDisplay": "${data.textToDisplay}",
                "checked": "${data.checked}",
                "isIndeterminate": "${data.isIndeterminate}",
                "arrayOfCheckboxes": "${checkBoxStateData.arrayOfCheckboxes}"
              }
            ]
          }
        ]
      }
    ]
  }
}

AlexaCheckboxの例

以下は、異なる色とサイズの複数のチェックボックスを表示するドキュメント全体とデータソースの例です。チェックボックスはデータソースで指定します。各行には、ダークとライトのテーマで同じチェックボックスを表示しています。チェックボックスをオンにすると、ユーザー定義のコマンドが実行され、ヘッダーのサブタイトルがオンにされたチェックボックスに関する情報で更新されます。コマンドは、AlexaCheckboxの現在のchecked状態をevent.source.checkedプロパティから取得します。