APL Sequence



APL Sequence

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

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

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

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

プロパティ

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

プロパティ デフォルト スタイル設定 動的 説明

numbered

ブール値

false

trueの場合、データバインディングコンテキストの子Sequenceに序数を割り当てます。

onScroll

コマンド配列

[]

スクロール中に実行するコマンドです。

preserve

文字列の配列

[]

Reinflateコマンドでドキュメントを再インフレートする際に保存するプロパティです。

scrollDirection

horizontalverticalのいずれか

vertical

このSequenceのスクロール方向です。

snap

nonestartcenterendforceStartforceCenterforceEndのいずれか

none

スクロールを停止したときに子コンポーネントを止める配置です。

heightおよびwidth

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

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

numbered

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

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で検索する場合(centerIdfirstIdのいずれも)、idが再インフレート前にも後にも見つからなければ、シーケンスは先頭に配置されます。コンポーネントをindexで検索する場合(centerIndexfirstIndexのいずれも)、そのインデックスに子がなければ、シーケンスは先頭に配置されます。

scrollDirection

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

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

snap

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

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

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

スナップが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

normalskipresetのいずれか

normal

次の子の順序数の付け方を指定します。

spacing

絶対ディメンション

0

レイアウト内でこのコンポーネントと前のコンポーネントの間に追加するスペースです。

numbering

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

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

spacing

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