APL GridSequence

GridSequenceコンポーネントは、データセットを使用して、単一方向にスクロールする固定グリッドレイアウトに、コンポーネントのセットを繰り返し表示します。

GridSequenceとContainerコンポーネントの違いは、GridSequenceは長いリストでより高いパフォーマンスが得られるかわりに、柔軟なレイアウトモデルでのパフォーマンスでは劣るという点です。GridSequenceと通常のSequenceの違いは、GridSequenceが行と列で子コンポーネントを調整するという点です。

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

プロパティ

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

• すべてのアクション可能なコンポーネントのプロパティ
• すべての多子コンポーネントのプロパティ
• すべての基本コンポーネントのプロパティ
• 以下の表は、GridSequenceプロパティの一覧です。列の意味を参照してください。

heightおよびwidth

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

childHeight

GridSequenceの各行の高さを決める配列です。

垂直スクロールするGridSequenceはchildHeightの最初の値を使用します。この値は絶対ディメンション、相対ディメンションのいずれかで指定する必要があります。childHeightをautoにすることはできません。

水平スクロールするGridSequenceには、複数のchildHeight値を指定できます。列と行の高さと幅の計算に記載されたレイアウトアルゴリズムにより、各子項目が配置されます。

childWidth

GridSequenceの各列の幅を決める配列です。

水平スクロールするGridSequenceはchildWidthの最初の値を使用します。この値は絶対ディメンション、相対ディメンションのいずれかで指定する必要があります。childWidthをautoにすることはできません。

垂直スクロールするGridSequenceには、複数のchildWidth値を指定できます。列と行の高さと幅の計算に記載されたレイアウトアルゴリズムにより、各子項目が配置されます。

numbered

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

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

onScroll

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

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

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

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

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

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

preserve

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

GridSequenceには以下のコンポーネント固有のプロパティ名があり、これらを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

scrollDirectionには、verticalまたはhorizontalを指定します。

snap

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

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

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

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

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

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

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

多子プロパティ

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

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

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

GridSequenceの子項目

GridSequenceの子は、子の幅、高さ、スクロール方向に基づいて固定サイズで表示されます。

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

numbering

GridSequenceのnumberedプロパティがtrueの場合に適用されます。GridSequenceがGridSequenceの次の子のordinal値を更新する方法を制御します。

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

GridSequenceと動的データソース

GridSequenceは、dynamicIndexListなどの動的データソースにバインドできます。動的データソースの前または途中に項目を追加すると、GridSequenceが想定外のスクロール動作をする場合があります。これを回避するには、前または途中に追加する項目の数を、交差軸の項目数の倍数にします。GridSequenceのscrollDirectionがverticalに設定されている場合、交差軸はchildWidthによって決まります。逆に、GridSequenceのscrollDirectionがhorizontalに設定されている場合、交差軸はchildHeightによって決まります。

列と行の高さと幅の計算

垂直スクロールのGridSequenceは、次のアルゴリズムを使って列の幅を計算します。

固定GridSequenceWidth + 単一のChildWidth

GridSequenceの幅のディメンションがわかっていてchildWidthの値が1つの場合、作成される列の数は100%をchildWidthで割った数（端数は切り捨て）となります。

たとえば、子の幅が「23%」の場合は4列作成され、右側にはほとんどスペースが残りません。同様に、GridSequenceの幅が300dpでchildWidthが50dpの場合、子の列は6列作成されます。

固定GridSequenceWidth + 複数のChildWidth

GridSequenceの幅のディメンションがわかっていてchildWidthに複数の値がある場合、GridSequenceには次のルールが適用されます。

• 絶対ディメンションの列は割り当てられた値を使用します。
• 相対ディメンション（パーセンテージ）の列はGridSequenceにそのパーセンテージをかけた幅を使用します。
• スペースが残っている場合、autoディメンションの各列にスペースが均等に分配されます。スペースが残っていない場合、auto列の幅は0となります。

自動GridSequenceWidth

GridSequenceの幅がautoの場合、GridSequenceには次のルールが適用されます。

• 絶対ディメンションの列は割り当てられた値を使用します。
• 相対ディメンションの列は幅0を使用します。
• autoディメンションの列は幅0を使用します。
• GridSequence全体の幅は、列幅の合計となります。

水平スクロールGridSequenceの行の高さを割り当てるアルゴリズムは同じルールに従いますが、childWidthではなくchildHeightを使用します。

GridSequenceは、子項目がGridSequenceよりも大きい場合に子項目を切り取ります。たとえば、[ auto, 30%, 50%, 30%, auto ]のchildWidth配列は4番目の要素を切り取って、最初の要素と5番目の要素にサイズ0を割り当てます。

サイズいっぱいの幅を取る場合はchildWidthにautoを設定します。サイズが同じ子を3つ定義する場合、[auto, auto, auto]式を使うことで数字の切り捨てエラーを回避し、子のサイズを均等にできます。

GridSequenceイベントオブジェクト

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

{
  // GridSequence固有の値  
  "type": "GridSequence",
  "position": Number,       // コンポーネントのスクロール位置（割合）       
  "itemsPerCourse": 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ハンドラーで出力される位置と同じです。

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

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

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

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

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

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

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

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

GridSequenceの例

水平グリッドの例

高さが同じ2つの行を持つ水平グリッドの例

{
  "type": "GridSequence",
  "height": "300dp",
  "scrollDirection": "horizontal",
  "childWidth": "200dp",
  "childHeight": "50%"
}

水平スクロールグリッドの例のため、ここでは子が縦に並んで表示されます。GridSequenceの高さは300dpで、childHeightは50%です。このため、GridSequenceは子項目の2行分を埋めます。各行の高さは150dpです。

childWidthに指定されたとおり、各列の幅は200dpです。GridSequenceの子は左上から配置され、次の列に進む前に各列が埋まります。以下はレイアウト図です。

垂直グリッドの例

幅が等しくない3列の垂直グリッドの例

{
  "type": "GridSequence",
  "width": "1000dp",
  "scrollDirection": "vertical",
  "childWidths": [ "20%", "30%", "auto" ],
  "childHeight": "100dp"
}

垂直スクロールグリッドの例のため、ここでは各列の幅がchildWidth配列によって決まります。autoディメンションが拡張されて残りのスペースが埋まります。このため、列の幅は、200dp、300dp、500dpと計算されます。GridSequenceの子は左上から配置され、次の行に進む前に各行が埋まります。以下はレイアウト図です。

関連トピック

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