APL GridSequence
GridSequence
コンポーネントは、データセットを使用して、単一方向にスクロールする固定グリッドレイアウトに、コンポーネントのセットを繰り返し表示します。
GridSequence
とContainer
コンポーネントの違いは、GridSequence
は長いリストでより高いパフォーマンスが得られるかわりに、柔軟なレイアウトモデルでのパフォーマンスでは劣るという点です。GridSequence
と通常のSequence
の違いは、GridSequence
が行と列で子コンポーネントを調整するという点です。
GridSequence
を表示するプリビルドのレスポンシブ対応テンプレートについては、AlexaGridListを参照してください。
GridSequence
を使用するには、APL1.4以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。プロパティ
GridSequenceコンポーネントには、次のプロパティがあります。
- すべてのアクション可能なコンポーネントのプロパティ
- すべての多子コンポーネントのプロパティ
- すべての基本コンポーネントのプロパティ
- 以下の表は、
GridSequence
プロパティの一覧です。列の意味を参照してください。
プロパティ | 型 | デフォルト | スタイル設定 | 動的 | 説明 |
---|---|---|---|---|---|
|
ディメンションまたはディメンションの配列 |
必須 |
✕ |
◯ |
子の高さです。 |
|
ディメンションまたはディメンションの配列 |
必須 |
✕ |
◯ |
子の幅です。 |
|
ブール値 |
false |
✕ |
✕ |
|
|
コマンドの配列 |
|
✕ |
✕ |
スクロール中に実行するコマンドです。 |
|
文字列の配列 |
|
✕ |
✕ |
|
|
|
|
✕ |
✕ |
この |
|
|
|
◯ |
✕ |
スクロールを停止したときに子コンポーネントを止める配置です。 |
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
の子は左上から配置され、次の行に進む前に各行が埋まります。以下はレイアウト図です。
