APL Sequence

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

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

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

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

プロパティ

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

• すべてのアクション可能なコンポーネントのプロパティ
• すべての複数子コンポーネントのプロパティ
• すべての基本コンポーネントのプロパティ
• 次の表に示す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テンプレートを使用する場合、幅はパーセント値で設定せず、絶対ディメンションで設定してください。

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

コンポーネントのlayoutDirectionプロパティは、scrollDirectionプロパティがhorizontal（水平）の場合に項目を表示する方向を決定します。

• 左から右（LTR） – Sequenceは、左側から順に項目を配置します。項目は右からスクロールして表示します。
• 右から左（RTL） – Sequence は、右側から順に項目を配置します。項目は左からスクロールして表示します。

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の詳細についてはイベントソースを参照してください。

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に出力されます。

コマンドで出力される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は、項目を水平方向または垂直方向に配置します。

• 水平 – 項目は、layoutDirectionプロパティの値に応じて、左から右、または右から左の方向に表示されます。ユーザーはコンポーネントを左右にスワイプして、項目をスクロールします。
• 垂直 – 項目は上から下に並べて表示されます。ユーザーはコンポーネントを上下にスワイプして、項目をスクロールします。

スクロール方向の子のディメンションは自動設定であり、デフォルトでは子のコンテンツを囲むように設定されます。

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の最初の項目では無視されます。この値は絶対ディメンションで指定する必要があります。

関連トピック

• アクション可能なコンポーネントのプロパティ
• 複数子コンポーネントのプロパティ
• GridSequence