Slider

Alexa Sliderレスポンシブ対応コンポーネント（AlexaSlider）は、対話型のプログレスバーを表示します。ユーザーは、コンテンツをスクラブしてバーをドラッグしたり、設定を変更したりできます。

重要： AlexaSliderにはAPL 1.4以降が必要です。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。

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

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

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

AlexaSliderのパラメーター

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

名前	型	デフォルト	説明	追加または更新されたバージョン
`accessibilityLabel`	文字列	[Total]のうち[Progress]経過しました。たとえば、[2分]のうち[20秒]経過しましたなど。	プログレスバーを説明する文字列です。ユーザーがコンポーネントを選択したときに、この文字列が読み上げられます。	1.2.0
`bufferValue`	数値	0	スライダーで経過したバッファー時間を表す値です。スライダーは、明るい色で塗りつぶすことによって、この値を表します。バッファーバーは、`bufferValue`が`progressValue`より大きい場合に表示されます。`isLoading`がfalseの場合に適用されます。	1.2.0
`entities`	配列	[]	このコンポーネントにバインドするentityデータの配列です。	1.2.0
`handleKeyDownCommand`	キーボードイベントハンドラーの配列		スライダーがキーボードまたはDパッドからのキー押下を受け取ると実行されるキーボードイベントハンドラーの配列です。ユーザーがスライダーを操作したときにコマンドを実行するを参照してください。	1.2.0
`iconLeftGraphicSource`	文字列	AlexaSliderVolumnOff	スライダーの左側に表示するベクターグラフィックスやアイコンのURLまたは直接参照です。`sliderType`が`icon`の場合に適用されます。	1.2.0
`iconRightGraphicSource`	文字列	AlexaSliderVolumn	スライダーの右側に表示するベクターグラフィックスやアイコンのURLまたは直接参照です。`sliderType`が`icon`の場合に適用されます。	1.2.0
`isLoading`	ブール値	false	trueの場合、スライダーの塗りつぶされていない部分にアニメーションを表示して、コンテンツがロード中であることを示します。	1.2.0
`layoutDirection`	文字列	`LTR`	スライダーのレイアウト方向を指定します。このプロパティを`LTR`（左から右）、`RTL`（右から左）のいずれかに設定します。このプロパティは、コンポーネントの親コンテナから`layoutDirection`を継承しません。このため、必要に応じて明示的にこのプロパティを設定してください。レスポンシブ対応コンポーネントでの右から左に記述する言語のサポートについて詳しくは、Support for Right-to-left Languagesを参照してください。	1.4.0
`metadataDisplayed`	ブール値	false	trueの場合、スライダーは現在の`progressValue`と、期間として`totalValue`を表示します。`sliderType`が`default`の場合に適用されます。スライダーの種類を参照してください。	1.2.0
`metadataPosition`	文字列	above_right	`default`スライダーのメタデータ位置を設定します。`sliderType`が`default`で`metaDataDisplayed`が`true`の場合に適用されます。`above_right`、`above_left_right`、`below_left_right`のいずれかを設定します。	1.2.0
`onBlurCommand`	コマンドの配列		スライダーがフォーカスを失ったときに実行されるコマンドの配列です。ユーザーがスライダーを操作したときにコマンドを実行するを参照してください。	1.2.0
`onDownCommand`	コマンドの配列		`onDown`イベントが発生したときに実行されるコマンドの配列です。`onDown`イベントは、ユーザーがスライダーにタッチしたり、選択したりしたときに発生します。ユーザーがスライダーを操作したときにコマンドを実行するを参照してください。	1.2.0
`onFocusCommand`	コマンドの配列		スライダーがフォーカスを受け取ったときに実行されるコマンドの配列です。ユーザーがスライダーを操作したときにコマンドを実行するを参照してください。	1.2.0
`onMoveCommand`	コマンド配列		`onMove`イベントが発生したときに実行されるコマンドの配列です。`onMove`イベントは、ユーザーがスライダーのつまみを移動させたときに発生します。ユーザーがスライダーを操作したときにコマンドを実行するを参照してください。	1.2.0
`onUpCommand`	コマンド配列		`onUp`イベントが発生したときに実行されるコマンドの配列です。`onUp`イベントは、ユーザーがスライダーから指を離したときに発生します。ユーザーがスライダーを操作したときにコマンドを実行するを参照してください。	1.2.0
`positionPropertyName`	文字列	Thumbposition	スライダーのつまみを現在の位置に戻すのに使用するプロパティの名前です。これをデータバインディングで使用して、ユーザーがスライダーを動かすたびに位置を判断できます。現在のつまみの位置を取得するを参照してください。	1.2.0
`progressFillColor`	色	@colorComponent	スライダーの進行状況を示すのに使用する塗りつぶしの色です。	1.2.0
`progressValue`	数値	0	スライダーの完了を表す値です。スライダーは、`progressFillColor`で指定した色で塗りつぶし、この位置にスライダーのつまみを表示することでこの値を表します。`progressValue`はミリ秒で指定します。ただし、`text`スライダーは値を割合で表します。	1.2.0
`sliderId`	文字列	Slider	（必須）`AlexaSlider`のこのインスタンスを表す一意の識別子です。`AlexaSlider`コンポーネントはこのIDを内部で使用します。ドキュメント内のほかのコンポーネントからこのコンポーネントを参照する必要がある場合、基本コンポーネントの`id`プロパティも設定する必要があります。	1.2.0
`sliderMoveMillisecond`	数値	10000	キーボードやDパッドを使用している場合にスライダーが動く時間をミリ秒で指定します。	1.2.0
`sliderSize`	文字列	small	スライダーの両端に表示されるインジケーターのサイズを設定します。`sliderType`が`icon`か`text`の場合に適用されます。`small`、`medium`、`large`のいずれかを設定します。	1.2.0
`sliderType`	文字列	default	スライダーが期間、アイコン（音量インジケーターなど）、割合のどれを表示するかを決定します。`default`、`icon`、`text`のいずれかを設定します。スライダーの種類を参照してください。	1.2.0
`theme`	文字列	dark	色のテーマをダークまたはライトに設定します。テーマを選択することでコンポーネントの色を制御します。	1.2.0
`thumbColor`	色	@colorComponent	スライダーのつまみアイコンの色です。	1.2.0
`thumbDisplayedAllStates`	ブール値	true	trueの場合、スライダーのつまみアイコンが常に表示されます。falseの場合、つまみアイコンはユーザーがスライダーを進めたり戻したりするまで表示されません。	1.2.0
`totalValue`	数値	0	スライダーが表す総時間を表す値をミリ秒で指定します。たとえば、`totalValue`を100,000に設定すると1分40秒を表すスライダーを作成できます。総時間によって画面に描画されるバーの幅が決定されることはありません。バーのサイズを決定するには、`AlexaSlider`か親`Container`上の標準の`width`プロパティを使用します。	1.2.0

スライダーの種類

sliderTypeによって、スライダーの全体的な外観が決まります。AlexaSliderは、次の3種類をサポートします。

default – スライダーは時間を示します。metadataDisplayedを設定すると、現在の進行状況と一緒にバーが表す全体時間を表示できます。
icon – スライダーは範囲の設定または値を表します。スライダーは、両端に特定の意味を表すアイコンを使用します。たとえば、音量設定を表すスライダーは、左端のアイコンで「音量オフ」、右端のアイコンで「音量フル」を表します。
text – スライダーは割合を表します。スライダーの左端に「0%」、右端に「100%」と表示されます。ユーザーがスライダーを動かすと、左端の値が更新され、現在の割合を反映して更新されます。

以下の画像は、スライダーの種類を表しています。最初の2つはdefaultスタイル、3つ目はデフォルトの音量アイコンを使ったiconスライダー、最後はtextスライダーです。

情報の表し方がそれぞれ違っていても、3種類のスライダーは、総時間とスライダーの現在の進行状況にはすべてミリ秒を使用します。

totalValueに総時間をミリ秒で指定します。
色で塗りつぶしてバーの進行状況を表す数値をprogressValueにミリ秒で指定します。この値によって、スライダーのつまみ位置も決まります。ユーザーがスライダーを動かすと、このプロパティの元の値が新しい値で上書きされます。
2番目の色で塗りつぶしてバッファーの進行状況を表す数値をbufferValueにミリ秒で指定します。

スライダーのサイズ

sliderSizeを使用すると、iconとtextの種類のスライダーにアイコンとテキストのサイズを設定できます。このプロパティにより、スライダーのどちらかの端に表示されるアイコンのサイズや割合が変更されます。

スライダーの長さを制御するには、基本コンポーネントのwidthプロパティを使用します。AlexaSliderコンポーネント自体、または親Container上のwidthを設定します。Viewportサイズでバーの高さや厚みが決まります。この値は変更できません。

以下の画像は、iconとtextのスライダーのsliderSizeのsmall、medium、large設定を示しています。

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

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

{
  "type": "APL",
  "version": "1.7",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.4.0"
    }
  ],
  "mainTemplate": {
    "items": {
      "type": "Container",
      "justifyContent": "center",
      "paddingLeft": "@marginHorizontal",
      "paddingRight": "@marginHorizontal",
      "items": [
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "icon",
          "sliderSize": "small"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "icon",
          "sliderSize": "medium"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "icon",
          "sliderSize": "large"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "text",
          "sliderSize": "small"
        },
        {
          "type": "AlexaSlider",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "text",
          "sliderSize": "medium"
        },
        {
          "type": "AlexaSlider",
          "theme": "${viewport.theme}",
          "progressValue": 20000,
          "bufferValue": 50000,
          "totalValue": 100000,
          "thumbDisplayedAllStates": false,
          "sliderType": "text",
          "sliderSize": "large"
        }
      ]
    }
  }
}

ユーザーがスライダーを操作したときにコマンドを実行する

AlexaSliderは、アクション可能なコンポーネントであり、タッチ可能なコンポーネントでもあります。つまり、onMoveハンドラーなど、ユーザーのアクションやタッチイベントを処理する追加のプロパティがあります。AlexaSliderは、これらのハンドラーを使ってスライダーを対話型にします。

オプションでこれらのハンドラーに実行する追加のコマンドを指定して、ユーザーがスライダーを操作したときに対応できるようにします。以下の各プロパティは、対応するイベントが発生すると実行されるコマンドの配列を取ります。

handleKeyDownCommand
onBlurCommand
onDownCommand
onFocusCommand
onMoveCommand
onUpCommand

スライダーを対話型にするためのコマンドに加えて、これらのプロパティに渡すコマンドが実行されます。

たとえば、以下のコマンドはユーザーがスライダーを動かしたときにhandlerNameというプロパティの値を"onMove"に設定します。

{
  "onMoveCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onMove"
  }
}

このコマンドを使用する例については、AlexaSliderの例を参照してください。

現在のつまみの位置を取得する

スライダーのつまみの初期位置は、progressValueプロパティを使って設定します。ユーザーがスライダーを操作すると、現在のつまみ位置が変更されます。定義したコマンド内でこの値にアクセスできます。

ユーザーがスライダーを動かしたときにつまみの現在位置を取得する

positionPropertyNameに、つまみの位置を表す名前を設定します。このプロパティのデフォルト名はThumbpositionです。
bindプロパティを使ってこのプロパティのバインディングを作成します。これにより、ドキュメントのほかのコンポーネントからプロパティにアクセスできるようになります。
コマンドで、データバインディング構文を使ってバインドされた変数を参照します。

たとえば、次のContainerは2つのバインディングを作成しています。1つはThumbposition用、もう1つは変数handlerName用です。

{
  "type": "Container",
  "bind": [
    {
      "name": "Thumbposition",
      "value": 0
    },
    {
      "name": "handlerName",
      "value": "none"
    }
  ],
  "items": []
}

次に、このContainerにはこれらの各値を表示するTextプロパティがあります。

{
  "type": "Text",
  "text": "Thumbposition = ${Thumbposition}, handlerName = ${handlerName}",
  "style": "textStyleDisplay6"
}

次に、AlexaSliderコンポーネントはpositionPropertyNameにThumbpositionを設定して、各ハンドラーにSetValueコマンドを定義します。ユーザーがスライダーを操作すると、Textコンポーネントは現在のThumbpositionとアクティブなハンドラー名を表示します。

{
  "type": "AlexaSlider",
  "sliderId": "Slider",
  "progressValue": 0,
  "totalValue": 100000,
  "sliderMoveMillisecond": 10000,
  "progressFillColor": "red",
  "thumbColor": "green",
  "positionPropertyName": "Thumbposition",
  "thumbDisplayedAllStates": true,
  "metadataDisplayed": true,
  "onMoveCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onMove"
  },
  "onUpCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onUp"
  },
  "onDownCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onDown"
  },
  "onFocusCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onFocus"
  },
  "onBlurCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "onBlur"
  },
  "handleKeyDownCommand": {
    "type": "SetValue",
    "property": "handlerName",
    "value": "handleKeyDown"
  }
}

このテクニックを使用するドキュメントの完全な例については、AlexaSliderの例を参照してください。

AlexaSliderの例

以下は、ユーザーがつまみを動かすとテキストが更新されるスライダーを使ったドキュメントの完全な例を示しています。ボタンはその後、スライダーを0にリセットします。