APL Pager

Pagerは、一連のコンポーネントを1つずつ表示します。通常、Pagerは、時系列に並べられたデータ項目を表示するために使用します。PagerとSequenceとの違いは、Pagerが長い連続した形ではなくページ単位に分割して項目を表示する点です。

Pagerは、左から右に順番に並べられた一連のページとして表示されます。ユーザーは、Pagerを左右にスワイプしてページを切り替えます。デバイスにタッチパネルが搭載されていない場合、Pagerはキーボードの入力（左右の矢印キーまたはTabキー）に応じて移動します。

Pagerは、Sequenceとは異なります。Sequenceは、連続した項目のリストとして表示されます。小型のスクリーンではゆっくりスワイプするとSequenceは1つの項目を表示しますが、Sequenceはコンテンツを速く進める高速スワイプモードにも対応しています。Sequenceの項目が小さい場合、Sequenceは「高速スクロールモード」で小さいバージョンのコンテンツを複数表示できます。個々の項目は隣り合って表示されます。一方、Pagerでは、前後のページのいずれかの方向に少しスワイプするだけで、それまで見ていたページから新しいページへとコンテンツが切り替わります。

プロパティ

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

プロパティ	型	デフォルト	スタイル設定	動的	説明
`handlePageMove`	ページ移動ハンドラーの配列	`[]`	✕	✕	`Pager`がページを切り替えたときに実行するハンドラーです。カスタムのページ遷移を視覚化する際に使用します。
`initialPage`	整数	0	✕	✕	最初のページの（0から始まる）インデックスです。デフォルトは0です。
`navigation`	`normal`、`none`、`wrap`、`forward-only`のいずれか	`wrap`	✕	✕	移動可能な方向を指定します。
`onPageChanged`	コマンド配列	`[]`	✕	✕	ページを切り替える場合に実行するコマンドです。
`pageDirection`	`horizontal`、`vertical`のいずれか	horizontal	✕	✕	ページ移動の方向です。
`preserve`	文字列の配列	[]	✕	✕	`Reinflate`コマンドでドキュメントを再インフレートする際に保存するプロパティです。

指定されない場合、Pagerコンポーネントのheightとwidthのデフォルトは100dpです。Pagerのheightとwidthは、絶対ディメンションまたは相対ディメンションのいずれかである必要があります。autoは使用できません。Pagerの子のheightとwidthは常に100%です。つまり、Pagerの子項目は常にPager自体と同じサイズになります。

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

{
  // Pager固有の値
  "type": "Pager",
  "page": 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単位の幅（パディングを含む）
}

handlePageMove

ページ移動ハンドラーの配列を指定します。これらのハンドラーは、Pagerが次のページに移動すると実行されます。handlePageMoveに値が含まれる場合、ハンドラーは通常のページ変更動作の表示を上書きします。

handlePageMoveハンドラーによって生成されるイベントは、次のような形式になります。

"event": {
  "source": {
    "type": "Pager",
    "handler": "Move",
    ...                   // コンポーネントのソースプロパティ
  },
  "direction": STRING,    // 動きの方向。 'left'、'right'、'up'、'down'のいずれかになります。
  "amount": NUMBER,       // 0～1の間の数値です。
  "currentChild": {       // 現在画面に表示されているコンポーネントのプロパティ
    "id": ID,
    "uid": UID
  },
  "nextChild": {          // 画面に移動されるコンポーネントのプロパティ
    "id": ID,
    "uid": UID
  }
}

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

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

イベントのdirectionプロパティは、ジェスチャーの動きの方向を表します。leftとupの方向値は、現在のページからこのリスト内の次のページに変更されます。rightとdownの方向値は、現在のページからこのリスト内の前のページに変更されます。ページ間を遷移するカスタムアニメーションを作成する場合、アニメーションがジェスチャーの動きと一致する必要はありません。

amountフィールドは、ジェスチャーで移動する距離です。amountが0の場合、現在のページがすべて画面に表示され、次のページが表示されないことを意味します。amountが1の場合、現在のページが完全に削除され、次のページが適切に画面内に配置されることを意味します。ユーザーのジェスチャーに一致するアニメーションを作成するには、amountの値をopacityやtransformなどのプロパティに設定します。

単一のページ移動ハンドラーは、以下の表のプロパティを持つオブジェクトです。

プロパティ	型	デフォルト	説明
`commands`	コマンド配列	`[]`	`Pager`がこのハンドラーを呼び出した場合に実行するコマンドです。
`description`	文字列	""	ハンドラーの任意の説明です。
`drawOrder`	`nextAbove`、`nextBelow`、`higherAbove`、`higherBelow`、`higherAbove`のいずれか	`higherAbove`	ページのスタック順序です。
`when`	ブール値	`true`	`true`の場合、このハンドラーが呼び出されます。

Alexaは、移動ハンドラーの配列を順番にチェックし、when句がtrueの最初の移動ハンドラーを呼び出します。ハンドラーを呼び出すと、そのハンドラーに定義されたcommandsが実行されます。when句がtrueの移動ハンドラーがない場合、Alexaはシステムのデフォルト移動ハンドラーを実行します。

drawOrderプロパティは、遷移中に一番上に表示するページを制御します。このプロパティは、カスタム遷移でページがオーバーラップする場合に使用します。以下の表は、特定の移動方向とdrawOrderでどのページが一番上に表示されるか（「現在」または「次」）を示しています。

移動の方向	nextAbove	nextBelow	higherAbove	higherBelow
左または上（リスト内前方に進む）	次	現在	次	現在
右または下（リスト内後方に進む）	次	現在	現在	次

ハンドラーの呼び出し中、現在および次のコンポーネントのベース位置はPagerの境界に設定され、それぞれの不透明度は1に設定されます。handlePageMoveハンドラーは適切な変換と不透明度の変化を適用して、現在のページと次のページを視覚的に配置する必要があります。

以下の例は、標準的なPager動作をシミュレートしたものです。ページを切り替えると、現在のページがビューの外にスライドアウトし、新しいページがビュー内にスライドインします。

{
  "handlePageMove": [
    {
      "when": "${event.direction == 'left' || event.direction == 'right'}",
      "drawOrder": "higherAbove",
      "commands": [
        {
          "type": "SetValue",
          "componentId": "${event.currentChild.uid}",
          "property": "transform",
          "value": [
            {
              "translateX": "${100 ` event.amount ` (event.direction == 'left' ? -1 : 1)}%"
            }
          ]
        },
        {
          "type": "SetValue",
          "componentId": "${event.nextChild.uid}",
          "property": "transform",
          "value": [
            {
              "translateX": "${100 ` (1.0 - event.amount) ` (event.direction == 'left' ? 1 : -1)}%"
            }
          ]
        }
      ]
    }
  ]
}

カスタムのページ遷移アニメーションを作成する場合、次の点に注意してください。

event.directionプロパティを使用して、ユーザーがPagerをドラッグした方向を判断します。
drawOrderを設定してほかのページの上または下にページを配置します。ページがオーバーラップしない場合、このプロパティは無視して構いません。
SetValueを呼び出し、event.amountの現在の値に基づいて使用する各視覚プロパティを変更します。たとえば、opacityを変更してページのフェードインとフェードアウトを行ったり、transformを変更してページを画面の内外にスライド移動させたりします。
ページ移動の最後に視覚値が適切に設定されることを確認します。
- すべてが表示されるように、event.nextChildのopacityを1に設定する必要があります。
- event.nextChildのtransformプロパティをnormalに戻す必要があります。

以下は、opacityとtransformを使用するhandlePageMoveの例です。Pagerを進める場合、新しいページのtransformプロパティが変更されるとページが右から画面内にスライドインします。古いページのtransformおよびopacityプロパティが変更されると、新しいページが画面にスライドインするにつれて古いページの表示が縮小されます。デバッグのため、viewportの一番上のTextコンポーネントはevent.amountの値を表示します。

クリップボードにコピーされました。

オーサリングツールでAPLサンプルをテストする方法については、オーサリングツールでAPLサンプルをテストするを参照してください。

{
  "type": "APL",
  "version": "1.6",
  "import": [
    {
      "name": "alexa-styles",
      "version": "1.1.0"
    }
  ],
  "mainTemplate": {
    "items": {
      "type": "Container",
      "width": "100%",
      "bind": [
        {
          "name": "AMOUNT",
          "value": 0
        }
      ],
      "items": [
        {
          "type": "Text",
          "text": "Amountの値：${AMOUNT}"
        },
        {
          "type": "Pager",
          "width": "300",
          "height": 300,
          "items": {
            "type": "Frame",
            "borderWidth": 25,
            "borderColor": "${data.border}",
            "backgroundColor": "@colorYellow800",
            "borderRadius": "@shapeRoundedRect",
            "item": {
              "type": "Text",
              "color": "@colorText",
              "text": "${data.text}"
            }
          },
          "data": [
            {
              "border": "@colorBlue800",
              "text": "これはPagerの最初のページです。"
            },
            {
              "border": "@colorTeal800",
              "text": "これはPagerの2ページ目です。"
            },
            {
              "border": "@colorGreen800",
              "text": "これはPagerの3ページ目です。"
            }
          ],
          "handlePageMove": [
            {
              "when": "${event.direction == 'left'}",
              "drawOrder": "nextAbove",
              "commands": [
                {
                  "type": "SetValue",
                  "componentId": "${event.nextChild.uid}",
                  "property": "transform",
                  "value": [
                    {
                      "translateX": "${(1.0-event.amount) * 300}"
                    }
                  ]
                },
                {
                  "type": "SetValue",
                  "componentId": "${event.currentChild.uid}",
                  "property": "opacity",
                  "value": "${(1.0 - event.amount)}"
                },
                {
                  "type": "SetValue",
                  "componentId": "${event.currentChild.uid}",
                  "property": "transform",
                  "value": [
                    {
                      "scale": "${(1.0 - 0.3 * event.amount)}"
                    }
                  ]
                },
                {
                  "type": "SetValue",
                  "property": "AMOUNT",
                  "value": "${event.amount}"
                }
              ]
            },
            {
              "when": "${event.direction == 'right'}",
              "drawOrder": "nextBelow",
              "commands": [
                {
                  "type": "SetValue",
                  "componentId": "${event.currentChild.uid}",
                  "property": "transform",
                  "value": [
                    {
                      "translateX": "${event.amount * 300}"
                    }
                  ]
                },
                {
                  "type": "SetValue",
                  "componentId": "${event.nextChild.uid}",
                  "property": "opacity",
                  "value": "${event.amount}"
                },
                {
                  "type": "SetValue",
                  "componentId": "${event.nextChild.uid}",
                  "property": "transform",
                  "value": [
                    {
                      "scale": "${(0.7 + 0.3 * event.amount)}"
                    }
                  ]
                },
                {
                  "type": "SetValue",
                  "property": "AMOUNT",
                  "value": "${event.amount}"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

handlePageMoveハンドラーのコマンドは、Pagerが2つのページ間で遷移すると実行されます。以下のシナリオではコマンドは実行されません。

Pagerにページがないか、1ページのみの場合。
navigationプロパティがnoneで、ユーザーがページをドラッグしようとした場合。
ユーザーがnavigationプロパティでサポートされていない方向にページをドラッグしようとした場合。たとえば、navigationがforward-onlyの場合、右や下にスワイプしてもページは切り替わりません。
ユーザーがpageDirectionに指定されていない方向にページをドラッグしようとした場合。たとえば、pageDirectionがhorizontalの場合、上や下にスワイプしてもページは切り替わりません。

initialPage

表示する最初のページのインデックスです。インデックスは0から始まり、デフォルトは0です。firstItemに値が設定されている場合、firstItem項目のインデックスは0になります。

navigationプロパティは、ユーザーがコンテンツ内を移動する方法を制御します。

normal – ユーザーはPagerで前後に自由に移動することができます。
none – ユーザーはPagerを移動できません。コマンドを使用してプログラムでPagerを移動します。たとえば、AutoPageコマンドやSetPageコマンドを使用します。
wrap – ユーザーは前後に自由に移動することができます。ユーザーが最後のページでスワイプすると、Pagerは最初のページに戻ります。
forward-only – ユーザーは前には移動できますが、後ろには移動できません。

SetPageコマンドとAutoPageコマンドは常にPagerを移動できます。navigationプロパティは、画面上のスワイプによるユーザー操作を制限します。

onPageChanged

onPageChangedハンドラーは、Pagerが新しいページに完全に切り替わったときに実行されます。生成されるイベントの形式は次のようになります。

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

event.sourceの詳細についてはイベントソースを参照してください。event.source.valueプロパティは、新しいページのインデックス（0から始まるインデックス）を含みます。

pageDirection

ページが切り替わるときのアニメーションの方向を決定します。pageDirectionは、ユーザーが画面をスワイプしてPagerを操作する方向も決定します。

pageDirectionには、horizontal、verticalのいずれかを指定できます。

horizontal – （デフォルト）ユーザーは左か右にスワイプしてページを操作します。左にスワイプすると、インデックスの大きいページに進みます。右にスワイプすると、インデックスの小さいページに戻ります。デフォルトのアニメーションは、ページを左か右にスライドしてページを切り替えます。
vertical – ユーザーは上か下にスワイプしてページを操作します。上にスワイプすると、インデックスの大きいページに進みます。下にスワイプすると、インデックスの小さいページに戻ります。デフォルトのページ切り替えアニメーションは、ページを上か下にスライドしてページを切り替えます。

preserve

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

Pagerには以下のコンポーネント固有のプロパティ名があり、これらをpreserve配列に割り当てることができます。

pageId – 開始ページを現在のページのIDと一致するよう設定します。
pageIndex – 開始ページを現在のページのインデックスに設定します。

これらの値がいずれも指定されていない場合、ドキュメント再インフレート後の開始ページはinitialPageになります。

preserveをpageIdに設定したにもかかわらず、Pagerの現在表示されているページにidが設定されていない場合、ドキュメント再インフレート後の開始ページはinitialPageになります。同様に、指定されたpageIndexが存在しない場合（ページ数が変更された場合など）、initialPageインデックスが使用されます。

以下の例では、ドキュメントの再インフレート後にPagerの現在のページを復元しています。

{
  "type": "Pager",
  "id": "MyPager",
  "preserve": ["pageIndex"]
}

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

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

複数子プロパティ

Pagerは、複数子コンポーネントです。Pagerは、すべての複数子プロパティを継承します。

{
  "type": "Pager",
  "items": [
    {
      "type": "Text"
      "text": "ページ#1で表示されるテキストコンテンツ"
    },
    {
      "type": "Text"
      "text": "ページ#2で表示されるテキストコンテンツ"
    }
  ]
}