APL Sequence

Sequenceは、データセットを使用して複数のコンポーネントをインフレートし、長いスクロールリストに繰り返し表示します。デザインのガイダンスは、 AlexaデザインガイドのPagerとSequenceのセクションを参照してください。

SequenceはContainerに似ていますが、長いリストに対してはSequenceの方がパフォーマンスが良好です。ただし、Sequenceは柔軟性の低いレイアウトモデルです。

Sequenceを使うと、画面上で序数および照応に応じた項目を選択できます。詳細については、項目選択のためのAPLサポートを参照してください。

Sequenceを表示するプリビルドのレスポンシブ対応テンプレートについては、AlexaTextList、AlexaImageList、AlexaListsを参照してください。

プロパティ

Sequenceコンポーネントには、次のプロパティがあります。

プロパティ	型	デフォルト	スタイル設定	動的	説明
`numbered`	ブール値	`false`	✕	✕	`true`の場合、データバインディングコンテキストの子`Sequence`に序数を割り当てます。
`onScroll`	コマンド配列	`[]`	✕	✕	スクロール中に実行するコマンドです。
`preserve`	文字列の配列	`[]`	✕	✕	`Reinflate`コマンドでドキュメントを再インフレートする際に保存するプロパティです。
`scrollDirection`	`horizontal`、`vertical`のいずれか	`vertical`	✕	✕	この`Sequence`のスクロール方向です。
`snap`	`none`、`start`、`center`、`end`、`forceStart`、`forceCenter`、`forceEnd`のいずれか	`none`	◯	✕	スクロールを停止したときに子コンポーネントを止める配置です。

heightおよびwidth

表示エラーを最小限に抑えるため、垂直Sequenceのheightと水平Sequenceのwidthが指定されていない場合は100dpに初期化されます。heightやwidthにはautoを使用しないでください。Sequenceサイズには絶対または相対ディメンションを使用します。

高さの値を指定した垂直方向のSequence内でItemテンプレートを使用する場合、高さはパーセント値で設定せず、絶対ディメンションで設定してください。幅の値を指定した水平方向のSequence内でItemテンプレートを使用する場合、幅はパーセント値で設定せず、絶対ディメンションで設定してください。

numbered

trueに設定した場合、Sequence内の各項目にデータバインディングの順序数が設定されます。この順序数は「1」から始まり、子コンポーネントのnumberingプロパティがskipまたはresetの場合を除き、1ずつ増加します。firstItemとlastItemは順序には含まれません。

numberedプロパティでは、画面に数字が自動的に表示されません。データバインディングコンテキストでordinal値を使用して、Textコンポーネントに数値を表示できます。

onScroll

スクロール中に実行するコマンドです。ランタイムでは、スクロール中にフレームを描画するたびにこれらのコマンドの実行が1回試行されますが、正常に実行されない場合もあります。デバイスの処理速度が遅い場合、onScrollコマンドは断続的に実行される可能性があります。

コマンドで出力されるevent.source.positionは、現在のスクロール位置をSequenceの幅または高さで割ったパーセント値になります。たとえば、Sequenceの幅が200ピクセルであり、コンテンツを左方向に520ピクセル分スクロールした場合、event.source.positionの値は2.60になります。

生成されるイベントの形式は次のようになります。

"event": {
  "source": {
    "type": "Sequence",
    "handler": "Scroll",
    ...                     // コンポーネントのソースプロパティ
  }
}

event.sourceの詳細についてはイベントソースを参照してください。

onScrollイベントハンドラーは高速モードで実行されます。

preserve

Reinflateコマンドを使ってドキュメントを再インフレートする際に保存する動的なコンポーネントプロパティと、バインドされるプロパティの配列です。

Sequenceには以下のコンポーネント固有のプロパティ名があり、これらをpreserve配列に割り当てることができます。

centerId – シーケンスの中央に配置される子のIDです。
centerIndex – シーケンスの中央に配置される子のインデックスです。
firstId – シーケンス先頭に配置される子のIDです。
firstIndex – シーケンス先頭に配置される子のインデックスです。
scrollOffset – 絶対スクロール位置（dp単位）です。
scrollPercent – 相対スクロール位置（可視領域のパーセンテージ）です。

firstIndexオプションは、シーケンスの先頭に表示される現在の子のインデックスを使用し、（再インフレート後）シーケンス先頭のスクロール位置を同じ子（インデックスを指定）に配置するよう設定します。firstIdは、シーケンス先頭に表示される現在の子のidを使用し、（再インフレート後）シーケンス先頭のスクロール位置を同じ子（idを指定）に配置するよう設定します。

centerIndexオプションは、シーケンス中央に表示される現在の子のインデックスを使用し、（再インフレート後）シーケンス中央のスクロール位置を同じ子（インデックスを指定）に配置するよう設定します。centerIdオプションは、シーケンス中央に表示される現在の子のidを使用し、（再インフレート後）シーケンス中央のスクロール位置を同じ子（idを指定）に配置するよう設定します。

idで検索する場合（centerId、firstIdのいずれも）、idが再インフレート前にも後にも見つからなければ、シーケンスは先頭に配置されます。コンポーネントをindexで検索する場合（centerIndex、firstIndexのいずれも）、そのインデックスに子がなければ、シーケンスは先頭に配置されます。

scrollDirection

Sequence項目をレイアウトしてスクロールする方向です。scrollDirectionプロパティには以下のいずれかを設定できます。

vertical – 縦方向のリストに項目を表示します。リストは上下にスクロールします。
horizontal – 横方向のリストに項目を表示します。リストは左右にスクロールします。

snap

スクロールを停止したときに子コンポーネントを止める配置です。ユーザーがコンテンツをスクロールしてスクロールを停止すると、Sequenceは子項目を移動してSequenceコンテナの先頭、中央、末尾に「止め」ることができます。Sequenceは、止める位置に最も近い子項目に揃えられます。たとえば、snapがcenterの場合、Sequenceは中央に最も近い項目がコンテナの中央に止まる（スナップ）ように項目を移動させます。

Sequenceは、2種類のスナップ動作をサポートします。

スクロール速度が速い場合にスナップする – ユーザーがコンテンツをスクロールしてポインターを放し、シーケンスを停止できるよう速度を落とすと、Sequenceは子コンポーネントをリクエストされた配置、またはシーケンスの先頭か末尾に配置します。ユーザーがポインターを放したときにスクロールの速度がほぼ落ちているか、まったく出ていない場合、スナップは発生しません。この種類のスナップでは、snapをstart、center、endのいずれかに設定します。
常にスナップ（スナップの強制） – ユーザーがポインターを放した後、Sequenceは常に、子コンポーネントをリクエストされた配置、またはSequenceの先頭か末尾に配置します。スナップの強制動作には、スクロールの速度は関係ありません。この種類のスナップでは、snapをforceStart、forceCenter、forceEndのいずれかに設定します。

スナップがSequenceコンテナの先頭、中央、末尾を判断する際、paddingは除外されます。

snapプロパティは次の値を取ることができます。

none – （デフォルト）スナップは発生しません。
start – スクロール速度が速いとき、子コンポーネントの先頭側をコンテナの先頭に揃えます。
center – スクロール速度が速いとき、子コンポーネントの中央をコンテナの中央に揃えます。
end – スクロール速度が速いとき、子コンポーネントの末尾側をコンテナの末尾に揃えます。
forceStart – スクロール速度にかかわらず、子コンポーネントの先頭側をコンテナの先頭に揃えます。
forceCenter – スクロール速度にかかわらず、子コンポーネントの中央をコンテナの中央に揃えます。
forceEnd – スクロール速度にかかわらず、子コンポーネントの末尾側をコンテナの末尾に揃えます。

snapプロパティは、ユーザーがコンテンツをスクロールすると適用されます。スクロールコマンドには適用されません。コマンドによるスクロール中に項目を揃えるには、ScrollToComponentコマンドかScrollToIndexコマンドを使い、コマンドのalignプロパティを設定します。

多子プロパティ

Sequenceは多子プロパティです。Sequenceは、すべての多子プロパティを継承します。

アクション可能なプロパティ

Sequenceはアクション可能なコンポーネントです。Sequenceは、すべてのアクション可能なプロパティを継承します。

Sequenceイベントオブジェクト

Sequenceがイベントのソースまたはターゲットである場合、以下の値がevent.sourceまたはevent.targetに出力されます。

{
  // Sequence固有の値 
  "type": "Sequence",
  "position": Number,  // コンポーネントのスクロール位置（割合）       

  // 表示される子 
  "firstVisibleChild": Integer,       // 部分的に表示される最初の子のインデックス      
  "firstFullyVisibleChild": Integer,  // すべて表示される最初の子のインデックス      
  "lastFullyVisibleChild": Integer,   // すべて表示される最後の子のインデックス      
  "lastVisibleChild": Integer,        // 部分的に表示される最後の子のインデックス      

  // 一般的なコンポーネントの値  
  "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単位の幅（パディングを含む）        
}

コマンドで出力されるpositionは、現在のスクロール位置をシーケンスの幅または高さで割ったパーセント値になります。この値は、onScrollハンドラーで出力される位置と同じです。

イベントプロパティには、表示される子の範囲が含まれます。

子コンポーネントは、以下に該当する場合にすべて表示されます。

子コンポーネントの境界がSequenceの境界外に拡張されない。
子コンポーネントのdisplayプロパティが"normal"に設定されている。
子コンポーネントのopacityが1.0に設定されている。

子コンポーネントは、以下に該当する場合に表示されますが、すべては表示されません。

子コンポーネントの境界がSequenceの境界と交差している。
子コンポーネントのdisplayプロパティが"normal"に設定されている。
子コンポーネントのopacityが0以外に設定されている。

firstVisibleChildからlastVisibleChildまでの範囲には、シーケンスに一部でも表示される子コンポーネントがすべて含まれます。firstFullyVisibleChildからlastFullyVisibleChildまでに範囲には、シーケンスにすべてが表示される子コンポーネントがすべて含まれます。

firstVisibleChildプロパティとlastVisibleChildプロパティは、シーケンスに表示される子がない場合に–1を返します。firstFullyVisibleChildプロパティとlastFullyVisibleChildプロパティは、シーケンスに完全に表示される子がない場合に–1を返します。

表示されるかどうかの計算では、子のtransformプロパティやシーケンスにオーバーラップする可能性のあるコンポーネントからの遮蔽は考慮されません。

Sequenceの子項目

Sequenceの子は、連続した列として表示されます（左から右または上から下）。スクロール方向の子のディメンションは自動設定であり、デフォルトでは子のコンテンツを囲むように設定されます。

Sequenceの子では、次のプロパティを追加で使用できます。

プロパティ	型	デフォルト	スタイル設定	動的	説明
`numbering`	`normal`、`skip`、`reset`のいずれか	`normal`	✕	✕	次の子の順序数の付け方を指定します。
`spacing`	絶対ディメンション	0	✕	✕	レイアウト内でこのコンポーネントと前のコンポーネントの間に追加するスペースです。

numbering

Sequenceのnumberedがtrueの場合に適用されます。numberingプロパティは、Sequenceがシーケンス内の次の子のordinal値を更新する方法を制御します。

normal：次の子のordinalは、ordinal+1となります。
skip：次の子のordinalは、ordinalと同じになります。
reset：次の子のordinalは1になります。

spacing

Sequence内でこのコンポーネントと前のコンポーネントの間に追加するスペースの大きさです。Sequenceの最初の項目では無視されます。この値は絶対ディメンションで指定する必要があります。