APLバックスタック拡張機能

APLバックスタック拡張機能

バックスタック拡張機能を使用すると、以前に表示したAPLドキュメントに戻る機能をユーザーに提供できます。これはHTML_Historyオブジェクトに似た機能です。

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

拡張機能の詳細については、APL拡張機能を参照してください。

拡張機能の概要

サポートされるAPLの最小バージョン APL 1.3
拡張機能のURI aplext:backstack:10
設定 backstackId
環境プロパティ
コマンド
イベントハンドラー なし
画像フィルター なし
スキルマニフェストへの追加 不要
設定の自動初期化 なし

バックスタック拡張機能の概要

バックスタック拡張機能を使用すると、HTML_Historyオブジェクトのように、前に表示したドキュメントの状態を保持しながら、暗黙的にそれらのドキュメントに順番に戻るナビゲーションを提供できます。バックスタック拡張機能によって新しいコマンドが追加され、ドキュメントで直接バックスタックを操作して前のドキュメントに戻ることも可能になります。

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

バックスタックについて

バックスタック拡張機能を使用するには、ドキュメントのextensionsプロパティで拡張機能をリクエストします。

バックスタック拡張機能のURIは、「aplext:backstack:10」です。

次の例では、バックスタック拡張機能をリクエストし、「Back」という名前を割り当てます。

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

ユーザーのデバイスがバックスタック拡張機能をサポートしているかどうかを確認するには、environment.extension変数を使用します。

{ "type": "Text", "text": "バックスタック拡張機能が${environment.extension.Back ? 'インストールされています' : 'インストールされていません'}" }

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

ドキュメントをバックスタックに追加する

デフォルトでは、APLドキュメントは（バックスタック拡張機能をリクエストしていても）、APLクライアントのバックスタックに追加されません。

ドキュメントをバックスタックに含めるには、ドキュメントのsettingsプロパティにbackstackIdプロパティを設定します。

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

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

バックスタックに追加したドキュメントに移動するには、次の2つの方法があります。

  1. 暗黙的な戻るナビゲーション（システムイベント）
  2. 明示的な戻るナビゲーション（コマンドベース）

バックスタックのナビゲーションを行うと、ナビゲーション方法（暗黙的または明示的）にかかわらず、戻った先のドキュメントと、そこから進んだ後続のすべてのドキュメントがバックスタックから暗黙的に消去されます。

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

システムイベントの戻るナビゲーション

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

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

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

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

コマンドベースの戻るナビゲーション

バックスタック拡張機能では、GoBackコマンドによるバックスタックの明示的なナビゲーションがサポートされます。任意のイベントハンドラーからGoBackコマンドを実行して、バックスタックを逆順に移動できます。バックスタック拡張機能が「Back」として登録されている場合、次のようにGoBackコマンドを送信します。

{
  "type": "Back:GoBack"
}

コマンドベースの戻るナビゲーションでは、GoBackコマンドのbackTypeプロパティを使用して、バックスタックを非シーケンシャルに移動することも可能です。

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

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

たとえば、バックスタックを使用するAPLドキュメントでは、システムレベルの「戻る」入力が提供されない場合、次のように独自の「戻る」ボタンを画面に描画できます。

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

バックスタックを消去する

Clearコマンドを使用すると、明示的にバックスタックを消去できます。任意のAPLイベントハンドラーからClearコマンドを実行します。

{
   "type": "TouchWrapper",
   "items": {
     "type": "Text",
     "text": “バックスタックを消去”
   },
   "onPress": {
     "type": "Backstack:Clear"
   }
 }

バックスタックからドキュメントの状態を復元する

バックスタック内の任意のドキュメントに戻ると、そのドキュメントは、前回終了してバックスタックに追加されたときのアクティブな状態に復元されます。ドキュメントのインフレート時の標準ルールに加えて、次のルールが適用されます。

  • すべての動的なコンポーネントプロパティは、最後にアクティブだった値に復元されます。
  • すべてのコンポーネント状態プロパティは、最後にアクティブだった値に復元されます。
  • フォーカスは、最後にフォーカスのあったコンポーネントに戻ります。

  • すべてのナビゲーション可能なコンポーネントは、最後にアクティブだった「位置」に復元されます。

    • GridSequence - 最後のスクロール位置。
    • ScrollView - 最後のスクロール位置。
    • Sequence - 最後のスクロール位置。
    • Pager - 最後のアクティブページ。
  • すべてのメディアコンポーネントは、最後にアクティブだった状態に復元されます。
    • Video - すべてのビデオ状態プロパティが復元されます。
  • onMountハンドラーは、バックスタックによるドキュメントの復元時には実行されません。

ドキュメントの終了時にアクティブだったコマンドは復元されないことに注意してください。

設定

バックスタック拡張機能には、次の設定があります。

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

backstackId

backstackIdプロパティは、ドキュメントがバックスタックに追加されるかどうかを決定します。

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

  1. APLがドキュメントAを初期化して表示します。このドキュメントにはbackstackIdが設定されています。
  2. バックスタックの長さは0です。
  3. デバイスがドキュメントBを受け取り、表示します。
  4. ドキュメントAがスタックに追加され、バックスタックの長さが1になります。

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

backstackIdの値は一意である必要はありません。バックスタック内ではbackstackIdの重複が許容されます。ただし、重複がある場合にGoBackコマンドで戻ることができる先は、バックスタック内で最も新しいドキュメントのみになることに注意してください。

たとえば、ドキュメントをバックスタックに追加する必要があることを示すには、次のように設定します。

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

settingsプロパティの名前は、extensionsプロパティでバックスタック拡張機能に割り当てた名前と同じにする必要があります。

環境

バックスタック拡張機能により、割り当てられた名前空間に次の環境プロパティが追加されます。

名前 型 説明
backstack 配列 バックスタック内の各ドキュメントのIDを含む配列です。
responsibleForBackButton ブール値 ドキュメントで戻るボタンを描画する必要がある場合はtrueです。

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

次の例では、nameを「Back」として拡張機能をリクエストします。このため、環境プロパティはenvironment.extension.Backとして提供されます。

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

backstack

backstack配列には、以前に表示され、空でないbackstackId値が設定されていたすべてのドキュメントのIDが含まれます。配列は表示された順番に並んでいます。最初に表示されたドキュメントのインデックスは0で、最後のドキュメントのインデックスは長さ-1になります。配列が空の場合は、バックスタックにドキュメントがないことを示します。

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

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

responsibleForBackButton

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

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

コマンド

バックスタック拡張機能により、次の2つの新しいコマンドが追加されます。

  • GoBack
  • Clear

GoBack

GoBackコマンドは、バックスタックの前のドキュメントに戻ります。次のプロパティがあります。

プロパティ 型 デフォルト 説明
backType count | index | id count 使用する戻るナビゲーションの種類です。
backValue 文字列または数値 1 バックスタック内の戻る先のドキュメントを表す値です。

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

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "Back",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "data": "${environment.extension.Back.backstack}",
      "item": {
        "type": "TouchWrapper",
        "item": {
          "type": "Text",
          "text": "ドキュメントID ${data}に移動"
        },
        "onPress": {
          "type": "Back:GoBack",
          "backType": "id",
          "backValue": "${data}"
        }
      }
    }
  }
}

backType

使用する戻るナビゲーションの種類です。backTypeプロパティは、次のオプションのいずれかを表す列挙値です。

名前 説明
count バックスタック内の現在のドキュメントから、指定した数だけ前のドキュメントに戻ります。
index バックスタック内の指定したインデックスを持つドキュメントに戻ります。
id バックスタック内の指定したbackstackIdを持つドキュメントに戻ります。

backTypeをbackValueプロパティと組み合わせて使用すると、count、index、idによるバックスタックのナビゲーションが可能になります。

backValue

backValueプロパティは、指定されたbackTypeに応じて、バックスタック内で戻る先のドキュメントの値を示します。

backTypeがcountまたはindexの場合、backValueは、backstack配列のナビゲーションに使用する整数値を受け取ります。

たとえば、バックスタックにドキュメント[ "A", "B", "C" ]があり、ドキュメント"D"が現在アクティブであるとします。次の例のTouchWrapperコンポーネントは、どちらもドキュメント"A"に戻ります。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "Backstack",
      "uri": "aplext:backstack:10"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "items": [
        {
          "type": "TouchWrapper",
          "item": {
            "type": "Text",
            "text": "3つ前のドキュメントに戻る"
          },
          "onPress": {
            "type": "Backstack:GoBack",
            "backType": "count",
            "backValue": 3
          }
        },
        {
          "type": "TouchWrapper",
          "item": {
            "type": "Text",
            "text": "バックスタック内の最初のドキュメントに戻る"
          },
          "onPress": {
            "type": "Backstack:GoBack",
            "backType": "index",
            "backValue": 0
          }
        }
      ]
    }
  }
}

backTypeがidの場合、backValueは文字列を受け取ります。指定されたbackValueのドキュメントがバックスタック内に複数ある場合は、一致する最新のドキュメント（インデックスが最も小さいドキュメント）が使用されます。

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

Clear

Clearコマンドを使用すると、バックスタックからすべての項目が削除されます。Clearコマンドに追加のプロパティはありません。以下は、Clearコマンドの例です。

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

イベントハンドラー

バックスタック拡張機能によって追加されるイベントハンドラーはありません。

画像フィルター

バックスタック拡張機能によって追加される新しい画像フィルターはありません。

このページは役に立ちましたか？

最終更新日: 2025 年 12 月 04 日