APL Sequence



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

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

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

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

プロパティ

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

• すべてのアクション可能なコンポーネントのプロパティ
• すべての複数子コンポーネントのプロパティ
• すべての基本コンポーネントのプロパティ
• 次の表に示すSequenceプロパティ列の意味を参照してください。

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": {
    "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は、項目を水平方向または垂直方向に配置します。

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

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

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

numbering

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

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

spacing

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

関連トピック

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