APL GridSequence

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

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

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

重要： GridSequenceを使用するには、APL1.4以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。

プロパティ

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

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

プロパティ	型	デフォルト	スタイル設定	動的	説明
`childHeight`, `childHeights`	ディメンションまたはディメンションの配列	必須	◯	✕	子の高さです。
`childWidth`, `childWidths`	ディメンションまたはディメンションの配列	必須	◯	✕	子の幅です。
`numbered`	ブール値	false	✕	✕	trueを指定した場合、子に番号が順番に割り当てられます。
`onScroll`	コマンドの配列	[]	✕	✕	スクロール中に実行するコマンドです。
`scrollDirection`	horizontal, vertical	vertical	✕	✕	この`GridSequence`のスクロール方向です。

GridSequenceの子は、子の幅、高さ、スクロール方向に基づいて固定サイズでレイアウトされます。表示エラーを最小限に抑えるために、縦GridSequenceの高さと横GridSequenceの幅が、指定されていない場合は100dpに初期化されます。

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

{
  // GridSequence固有の値  
  "type": "GridSequence",
  "position": Number,       // コンポーネントのスクロール位置（割合）       
  "itemsPerCourse": Number, // 各行（縦スクロール）または各列（横スクロール）の子の数           

  // 一般的なコンポーネントの値  
  "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を参照してください。

childHeight

子のheightプロパティは、GridSequenceの各行の高さを決める配列です。縦スクロールのGridSequenceでは、最初の子のheight値のみが使用されます。値は、絶対ディメンションまたは相対ディメンションで指定する必要があります（"auto"は指定できません）。横スクロールのGridSequenceでは、1つ以上の子のheight値を指定でき、以前に指定したレイアウトアルゴリズムを使って各子項目を配置します。

childWidth

子のwidthプロパティは、GridSequenceの各列の幅を決める配列です。横スクロールのGridSequenceでは、最初の子のwidth値のみが使用されます。値は、絶対ディメンションまたは相対ディメンションで指定する必要があります（"auto"は指定できません）。縦スクロールのGridSequenceでは、1つ以上の子のwidth値を指定でき、以前に指定したレイアウトアルゴリズムを使って各子項目を配置します。

numbered

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

onScroll

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

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

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

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

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

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

scrollDirection

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

多子プロパティ

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

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

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

子プロパティ

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

プロパティ	型	デフォルト	スタイル設定	動的	説明
`numbering`	`normal` \| `skip` \| `reset` \| `normal`	✕	✕	次の子の順序数の付け方を指定します。

numbering

親でnumberedが設定されている場合に、順序数の値を制御します。このプロパティは、GridSequenceの現在の子ではなく、GridSequenceの次の子について順序数の値の指定方法を制御するものです。

normal：次の子の順序数は、現在の順序数に1を足したものになります。
skip：次の子の順序数は、現在の順序数と同じになります。
reset：次の子の順序数は1になります。

GridSequenceと動的データソース

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

列の高さと幅の計算

縦スクロールのGridSequenceで列の幅を計算するには、次のアルゴリズムを使用します。

固定GridSequenceWidth + 単一のChildWidth

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

たとえば、子の幅が"23%"の場合は4列作成され、右側にはほとんどスペースが残りません。同様に、幅が300dpで幅50dpの子が1つ割り当てられているGridSequenceの場合、子の列は6列になります。

固定GridSequenceWidth + 複数のChildWidth

GridSequence幅のディメンションがわかっており、子の幅が複数割り当てられている場合は、次のようになります。

絶対ディメンションの列にはその値が割り当てられます。
相対ディメンションの列（割合）には、全体のGridSequenceに割合をかけた幅が割り当てられます。
スペースが残っている場合（割り当てられた列の幅の合計が全体の列幅より小さい場合）、「auto」ディメンションの各列にスペースが均等に分配されます。スペースが残っていない場合、「auto」列には幅0が割り当てられます。

自動GridSequenceWidth

GridSequenceの幅が「auto」の場合は次のようになります。

絶対ディメンションの列にはその値が割り当てられます。
相対ディメンションの列には、幅0が割り当てられます。
「auto」ディメンションの列には、幅0が割り当てられます。
GridSequence全体の幅には、列幅の合計が割り当てられます。

横スクロールGridSequenceの行の高さを割り当てるアルゴリズムは、同じルールに従います。

GridSequenceより大きくなるように、子のサイズを変更できます。たとえば、子の幅配列が[ auto, 30%, 50%, 30%, auto ]の場合、4つ目の要素が切り落とされ、1つ目と5つ目の要素にサイズ0を割り当てます。

「auto」プロパティは、すべてにサイズを設定する場合に適しています。サイズが同じ子を3つ定義する場合、[auto, auto, auto]式を使うことで数字の切り捨てエラーを回避し、子のサイズを均等にできます。

GridSequenceの例

水平グリッドの例

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

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

これは、垂直列に子を配置する横スクロールグリッドの例です。GridSequenceの高さは300dpで、子の高さは50%です。このため、子の2行にはそれぞれ150dpの高さの行が入ります。子の幅に指定されたとおり、各列の幅は200dpです。GridSequenceの子は左上から配置され、次の列に進む前に各列が埋まります。以下は、レイアウト図です。

垂直グリッドの例

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

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

これは、縦スクロールのグリッドを示しています。このため、子の幅配列によって、各列の幅が決まります。「auto」ディメンションは拡大して残りのスペースを埋めます。このため、グリッドセルの幅はそれぞれ、200、300、500 dpと計算されます。GridSequenceの子は、右上から配置され、次の行に進む前に各行が埋まります。以下は、レイアウト図です。