APL Backstack Extension

backstack extensionを使用すると、ユーザーは以前に表示したAPLドキュメントに戻ることができます。HTML_Historyオブジェクトに似た機能です。

backstack extensionは、Amazonデバイスで使用できます。ただし、デバイスによっては、APLをサポートしていても利用できない場合があります。APLドキュメントのwhenプロパティを使用すると、backstackをサポートしていないデバイスでも代替のエクスペリエンスを提供できます。

extensionsのしくみについては、APL Extensionsを参照してください。

Extensionの概要

サポートされるAPLの最小バージョン	APL 1.3
Extension URI	`aplext:backstack:10`
設定	`backstackId`
環境プロパティ	`backstack` `responsibleForBackButton`
コマンド	`GoBack` `Clear`
イベントハンドラー	なし
スキルマニフェストで必要か	いいえ
設定は自動的に初期化されるか	いいえ

Backstack extensionの概要

HTML_Historyオブジェクトと同様、backstack extensionを使うと、暗黙的に前のドキュメントに順に戻ることができます。同時に、これらのドキュメントの状態も保存されます。backstack extensionでは新しいコマンドが追加され、ドキュメントが直接backstackを処理して、前のドキュメントに戻ることができます。

backstack extensionはオプション機能であり、APLをサポートするすべてのデバイスで利用できるわけではありません。
backstack extensionは、APLクライアントの単一インスタンスに対して相対的です。これは、ブラウザの個々のタブに相対的なHTML_Historyと同様です。
ドキュメントは、ドキュメントのsettingsにbackstackIdを指定することにより、オプトインベースでbackstackに追加されます。
backstackを使ってスタック内の前のドキュメントに戻ることはできますが、次のドキュメントに進むことはできません。
backstackの長さは、environmentプロパティのbackstackプロパティを使って照会できます。
backstack内のドキュメントは、暗黙的に逆順で返されます。それらは、backstackIdを明示的に使うことで、非シーケンシャルに返すこともできます。
backstackは、ドキュメントの状態を保存し、復元して戻る操作に返します。
backstackは、スタック内の前のドキュメントに戻る際、暗黙的にすべての後続ドキュメントを消去します。
backstackは、Clearコマンドを使用して、明示的に消去できます。

backstackとは

backstack extensionを使用するには、ドキュメントのextensionsプロパティでextensionをリクエストします。

backstack extensionのURIは、"aplext:backstack:10"です。

この例では、backstack extensionをリクエストして、「Back」という名前を割り当てています。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ]
}

environment.extension変数を使用して、ユーザーのデバイスがbackstack extensionをサポートするかどうかをチェックします。

{ "type": "Text", "text": "backstack extensionは${environment.extension.Back ? 'インストール済み' : 'インストールされていません'}" }

ドキュメントでbackstackを参照する際は、必ずwhen句とenvironment.extension変数を使用して、extensionがユーザーのデバイスでサポートされていることを確認します。

backstackにドキュメントを追加する

デフォルトでは、APLドキュメントはAPLクライアントのbackstackに追加されません（backstack extensionをリクエストする場合でも）。

ドキュメントをbackstackに追加するには、ドキュメントのsettingsプロパティにbackstackIdプロパティを設定します。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "settings": {
    "Back": {
      "backstackId": "myDocument"
    }
  }
}

backstackのドキュメントをターゲットにする要件については、GoBackコマンドを参照してください。

backstackを操作する

backstackに追加したドキュメントの操作方法は2つあります。

暗黙的な戻る操作（システムイベント）
明示的な戻る操作（コマンドベース）

backstack操作を行うと、戻る先のドキュメントおよびbackstackの後続のドキュメントがすべて暗黙的に消去されます。これは、操作方法（暗黙的または明示的）にかかわらず共通です。

たとえば、backstackに、ドキュメントA、B、C、Dが追加されたとします。ユーザーがドキュメントBに戻ると、backstackからB、C、Dが削除され、Aのみが残ります。

システムの戻る操作は、ユーザーが入力した「戻る」操作への応答としてデバイスによって実行されるイベントとみなされます。たとえば、次のような入力です。

デバイス上やペアリングされたリモコンの実際の「戻る」ボタンを押した場合。
システムレベルUIの「戻る」ボタンを押した場合（Androidシステムトレイ）。
ユーザーが「戻って」や「前に戻る」などと発話した場合。

システムの戻るイベントを処理する場合、APLクライアントは以下のルールに従います。

backstackプロパティの長さが0より大きい場合、現在のドキュメントは終了し、スタック内の前のドキュメントが復元されます。これは、GoBackを実行する場合と同じです。
backstackプロパティの長さが0の場合、現在のドキュメントおよびクライアントが終了します。これは、[Finish]コマンドを実行する場合と同じです。

backstack extensionは、GoBackコマンドによる明示的なbackstack操作をサポートします。任意のイベントハンドラーからGoBackコマンドを実行して、逆順にbackstackを操作します。ここでは、backstack extensionが「Back」として登録されていると仮定し、次のようにGoBackコマンドを送信します。

{
  "type": "Back:GoBack"
}

コマンドベースの戻る操作では、GoBackコマンドのbackTypeプロパティを使用して、非シーケンシャルのbackstack操作をすることも可能です。

{
  "type": "Back:GoBack",
  "backType": "id",
  "backValue": "myDocument"
}

デバイスのユースケースによっては、システムレベルの「戻る」入力ができない場合もあります。backstack環境プロパティであるresponsibleForBackButtonを照会し、APLドキュメントがbackstackへの入力を提供できるかどうかを判断します（システムが提供していないため）。trueの場合、GoBackコマンドを使用して戻る操作ができます。

たとえば、システムレベルの「戻る」入力ができなくても、backstackを使用するAPLドキュメントが独自の「戻る」ボタンを画面に描画できます。

{ "when": "${environment.extension.Back.responsibleForBackButton}", "type": "TouchWrapper", "items": { "type": "Text", "text": "前に戻るにはここを押してください" }, "onPress": { "type": "Back:GoBack" } }

Backstackを消去する

Clearコマンドを使うと、明示的にbackstackを消去できます。APLイベントハンドラーからClearコマンドを実行します。

{
   "type": "TouchWrapper",
   "items": {
     "type": "Text",
     "text": “backstackを消去する”
   },
   "onPress": {
     "type": "Backstack:Clear"
   }
 }

backstackからドキュメント状態を復元する

backstackの任意のドキュメントに戻る場合、ドキュメントは前回終了してbackstackに追加されたときのアクティブ状態を復元します。ドキュメントインフレーションの標準ルールに加え、次のルールが適用されます。

すべての動的なプロパティが、最後のアクティブ値に復元されます。
すべてのコンポーネント状態が、最後のアクティブ値に復元されます。
フォーカスが、最後にフォーカスのあったコンポーネントに戻ります。
操作可能なコンポーネントがすべて、最後のアクティブな位置に復元されます。
- GridSequence – 最後のスクロール位置。
- ScrollView – 最後のスクロール位置。
- Sequence – 最後のスクロール位置。
- Pager – 最後のアクティブページ。
すべてのメディアコンポーネントが、最後のアクティブ状態に復元されます。
- Video – すべてのビデオ状態プロパティが復元されます。
onMountハンドラーは、backstackがドキュメントを復元する際には実行されません。

ドキュメント終了時にアクティブだったすべてのコマンドが復元されるわけではありませんので、注意してください。

設定

backstack extensionには、次の設定があります。

名前	型	デフォルト	説明
`backstackId`	文字列	""	コマンドで使用されるこのドキュメントの参照名です。

backstackId

backstackIdプロパティにより、ドキュメントがbackstackに追加されるかどうかが決まります。

ドキュメントがbackstackに追加されるのは、新しいドキュメントに置き換えられた時点です。ドキュメントが最初に画面に表示された時点ではありません。次に例を示します。

APLが開始し、backstackIdが設定されたドキュメントAを表示します。
Backstackの長さは0です。
デバイスが、ドキュメントBを受け取り、表示します。
ドキュメントAがスタックに追加されたため、Backstackの長さは1になります。

backstackIdが存在しないか空の場合、ドキュメントはbackstackに追加されません。存在する場合、ドキュメントはbackstackに追加されます。

backstackId値が一意である必要はありません。backstack内でbackstackIdが重複することもできます。重複している場合、GoBackコマンドが取得できるのは、最新のドキュメントのみになりますので注意してください。

たとえば、ドキュメントをbackstackに追加する必要がある場合、次のように指定します。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "settings": {
    "Back": {
      "backstackId": "myDocument"
    }
  }
}

settingsプロパティが、backstack extensionのextensionsプロパティに割り当てられた名前と一致しています。

環境

backstack extensionは、割り当てられた名前空間に次の環境プロパティを追加します。

名前	型	説明
`backstack`	配列	backstack内の各ドキュメントのIDを含む配列です。
`responsibleForBackButton`	ブール値	ドキュメントが戻るボタンを描画する場合はTrueです。

これらのプロパティは、environment.extensionの環境プロパティに追加されます。

次の例では、nameが「Back」のextensionをリクエストしています。このため、環境プロパティは、environment.extension.Backに設定されています。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "bind": {
        "name": "Responsible",
        "value": "${environment.extension.Back.responsibleForBackButton}"
      },
      "firstItem": {
        "type": "Text",
        "text": "backstackには、${environment.extension.Back.backstack.length}件の項目があります"
      },
      "data": "${environment.extension.Back.backstack}",
      "items": {
        "type": "Text",
        "text": "Backstack ${index}: '${data}'"
      },
      "lastItem": {
        "type": "Text",
        "text": "戻るボタンを${Responsible ? '描画する' : '描画しない'}"
      }
    }
  }
}

backstack

backstack配列には、既に表示されたドキュメントのうち、backstackId値が空でないものすべてのIDが含まれます。配列は順に並んでいます。最初に表示したドキュメントがインデックス0で、最後のドキュメントが（長さ-1）のインデックスに配置されます。空の配列は、backstackにドキュメントがないことを示します。

これは、カスタムの戻るボタンの表示に対する条件ロジックで、backstackの長さを照会する場合に使用できます。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "TouchWrapper",
      "when": "${environment.extension.Back.backstack.length > 0}",
      "item": {
        "type": "Text",
        "text": "Go Back!"
      },
      "onPress": {
        "type": "Back:GoBack"
      }
    }
  }
}

responsibleForBackButton

標準でシステムの戻るボタンがないデバイスは、responsibleForBackButtonプロパティがtrueです。ほとんどのデバイスにはシステムで定義された共通の「戻る」操作方法があります。たとえば、キーボードやリモコンのボタンを押す、システム定義の標準ジェスチャー（画面スワイプなど）、ステータスバーに戻るボタンを表示するなどといった方法です。一部のデバイス（当初のEcho Showなど）は、表示されたAPLアプリで、必要に応じて適切な戻るボタンを表示します。こうした場合、適切な視覚エクスペリエンスを表示するために、APLドキュメントを準備する必要があります。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "TouchWrapper",
      "when": "${environment.extension.Back.responsibleForBackButton}",
      "item": {
        "type": "Text",
        "text": "Go Back!"
      },
      "onPress": {
        "type": "Back:GoBack"
      }
    }
  }
}

コマンド

backstack extensionは、2つの新しいコマンドを追加します。

GoBack
Clear

GoBack

GoBackコマンドは、backstackの前のドキュメントに戻ります。次のプロパティがあります：

プロパティ	型	デフォルト	説明
`backType`	`count` \| `index` \| `id`	`count`	使用する戻る操作の種類です。
`backValue`	文字列または数値	1	backstackで戻るドキュメントを示す値です。

以下は、backstack内の任意のドキュメントに戻るGoBackコマンドの例です。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "data": "${environment.extension.Back.backstack}",
      "item": {
        "type": "TouchWrapper",
        "item": {
          "type": "Text",
          "text": "Go to document id ${data}"
        },
        "onPress": {
          "type": "Back:GoBack",
          "backType": "id",
          "backValue": "${data}"
        }
      }
    }
  }
}

backType

使用する戻る操作の種類です。backTypeプロパティの列挙値には次のオプションがあります。

名前	説明
`count`	backstackの現在のドキュメントから指定する数の分、後ろにあるドキュメントに戻ります。
`index`	backstack内の指定したインデックスを持つドキュメントに戻ります。
`id`	backstack内の指定した`backstackId`を持つドキュメントに戻ります。

backValueプロパティと組み合わせて使用すると、backTypeで、count、index、idを指定したbackstack操作が可能になります。

backValue

backValueプロパティは、指定されたbackTypeに応じて、backstack内の戻り先のドキュメントを指定する値です。

backTypeがcountまたはindexの場合、backValueにはbackstack配列操作に使う数値が入ります。

たとえば、backstackにドキュメント[ "A", "B", "C" ]があり、ドキュメント"D"が現在アクティブだとします。以下の例のTouchWrapperコンポーネントは、いずれもドキュメント"A"に戻ります。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Backstack",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "items": [
        {
          "type": "TouchWrapper",
          "item": {
            "type": "Text",
            "text": "Go back 3 documents"
          },
          "onPress": {
            "type": "Backstack:GoBack",
            "backType": "count",
            "backValue": 3
          }
        },
        {
          "type": "TouchWrapper",
          "item": {
            "type": "Text",
            "text": "Go to the first document in the backstack"
          },
          "onPress": {
            "type": "Backstack:GoBack",
            "backType": "index",
            "backValue": 0
          }
        }
      ]
    }
  }
}

backTypeがidの場合、backValueには文字列が入ります。backstackに指定されたbackValueのドキュメントが複数ある場合、一致した最新のドキュメントが使用されます（indexが最も小さいドキュメントなど）。

範囲外の数値や存在しない文字列が指定されたためにbackstack配列の既存のドキュメントにbackValueが一致しない場合、GoBackコマンドは無視されます。

Clear

Clearコマンドを使用すると、backstackのすべての項目を消去できます。Clearコマンドに追加のプロパティはありません。以下は、Clearコマンドの例です。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Backstack",
      "uri": "aplext:backstack:10"
    }
  ],
  "onMount": {
    "type": "Backstack:Clear",
    "description": “このドキュメントの読み込み時にバックスタックをクリア”
  },
  ...
}

イベントハンドラー

backstack extensionでは、イベントハンドラーは追加されません。