ほとんどのカードベースのアドオンは、 さまざまな「ページ」を表すカード できます。効果的なユーザーエクスペリエンスを提供するには アドオンのカード間はシンプルで自然なナビゲーションを使用する必要があります。
元々 Gmail アドオンでは、UI のカード間の移行が カードスタックへのプッシュやポップが Gmail によって表示されるスタックの一番上のカード。
Google Workspace アドオンで導入
ホームページと
表示されます。コンテキスト カードと非コンテキスト カードを表示するには、
Google Workspace アドオンには内部のカードスタックがある
あります。アドオンを開いたとき
対応する homepageTrigger が起動され、最初のインスタンスが作成されます。
スタック上にあるホームページ カード（下の図の濃い青色の「ホームページ」カード）。
homepageTrigger が定義されていない場合は、デフォルトのカードが作成され、表示されます。
非コンテキスト スタックにプッシュされます。最初のカードは、ルートカードです。
アドオンでは、コンテキストに依存しない追加のカードを作成して、 ユーザーが移動する際のスタック（図中の青色の「プッシュされたカード」） 追加します。アドオン UI にはスタックの一番上のカードが表示されるので、 カードがスタックに重なると表示が変わり、スタックからポップされたカードは戻ります 前のカードに戻ります。
アドオンに
コンテキストに基づくトリガー
ユーザーがそのコンテキストを入力するとトリガーが起動します。トリガー関数
コンテキスト カードが作成されますが、UI 表示は
DisplayStyle
確認します。
DisplayStyleREPLACE（デフォルト）、コンテキスト カード（濃いオレンジ） 「コンテキスト」が現在のカードに置き換えられるため、 表示されます。これにより、新しいコンテキスト カードスタックが効果的に開始される 非コンテキスト カードスタックのもので、このコンテキスト カードはルートです。 コンテキスト スタックのカードです。DisplayStylePEEKの場合、UI は代わりに 現在のカードに重ねて表示されます。ピークヘッダー 新しいカードのタイトルが表示され、ユーザーによる 新しいカードを表示するかどうかを指定できます。[View] をクリックすると、 ] ボタンを押すと、現在のカードが（前述のとおりREPLACE）。
追加のコンテキスト カードや スタックにプッシュします（図の黄色の「プッシュカード」）。更新中 カードスタックにより、アドオン UI が一番上のカードを表示するように変更されます。ユーザーが コンテキストが残ると、スタック上のコンテキスト カードが削除され、 一番上の非コンテキスト カードまたはホームページが更新されます。
ユーザーが入力したコンテキストがアドオンによって定義されていない場合、 新しいカードは作成されず 現在のカードは表示されたままになります。
Navigation のアクション
同じコンテキストのカードに対してのみ機能する（下記参照）。たとえば
popToRoot()
他のコンテキスト カードがすべて表示されます。
ホームページのカードには影響しません
一方、 ボタンは コンテキストカードから 表示されます。
ナビゲーション メソッド
カード間の切り替え効果を作成するには、
表示されます。Navigation
クラスは、スタックからカードのプッシュとポップを行う関数を提供します。ビルド
カード ナビゲーションを効果的なものにするには、
ウィジェット: ナビゲーションを使用
アクション。push またはポップできます
複数のカードを同時に表示できます。ただし、最初に作成したホームページ カードは削除できません。
開始時に最初にスタックにプッシュされます
ユーザーによるウィジェットの操作に応じて新しいカードに移動するには、次の操作を行います。 手順は次のとおりです。
Actionオブジェクトを作成する それを コールバック関数 使用できます。- ウィジェットの適切な
ウィジェット ハンドラ関数
そのウィジェットに
Actionを設定します。 - ナビゲーションを行うコールバック関数を実装します。この関数
アクション イベント オブジェクトが渡されている
引数として渡され、次の処理を行う必要があります。
<ph type="x-smartling-placeholder">
- </ph>
Navigationを作成する カードの変更を定義します。1 つのNavigationオブジェクトで、 複数のナビゲーション ステップが用意されており、 オブジェクトに追加されます。ActionResponseを作成する オブジェクトのActionResponseBuilderクラスとNavigation渡されます。- ビルドされた
ActionResponse。
ナビゲーション コントロールを作成する際は、以下を使用します。
Navigation オブジェクト関数:
| 関数 | 説明 |
|---|---|
Navigation.pushCard(Card) |
現在のスタックにカードをプッシュします。そのためには、まずカードを完全に作成する必要があります。 |
Navigation.popCard() |
グルーピングの最上部からカードを 1 枚削除します。アドオンのヘッダー行の戻る矢印をクリックする場合と同じです。ルートカードは削除されません。 |
Navigation.popToRoot() |
ルートカードを除くすべてのカードをスタックから削除します。基本的に、そのカードスタックはリセットされます。 |
Navigation.popToNamedCard(String) |
指定された名前またはスタックのルートカードに到達するまで、カードをスタックからポップします。CardBuilder.setName(String) 関数を使用してカードに名前を割り当てることができます。 |
Navigation.updateCard(Card) |
現在のカードのインプレース交換を行い、UI の表示を更新します。 |
ナビゲーションのベスト プラクティス
ユーザー操作やイベントによって同じ画面でカードが再レンダリングされるかどうか
使用する場合は、
Navigation.pushCard()
Navigation.popCard(),
および Navigation.updateCard()
メソッドを使って既存のカードを置き換えますユーザー操作やイベントが
異なるコンテキストでカードが再レンダリングされる場合は、
ActionResponseBuilder.setStateChanged()
必要な場合は、アドオンを強制的に再実行することができます。
以下に、ナビゲーションの例を示します。
- インタラクションまたはイベントによって現在のカードの状態が変更された場合（例:
タスクリストにタスクを追加するなど）は、
updateCard()。 - インタラクションやイベントが、ユーザーに詳細情報を提供する場合や、
その他のアクション（たとえば、アイテムのタイトルをクリックして詳細を表示する、または
ボタンを押して新しいカレンダーの予定を作成するなど）、
pushCard()を使用して新しいページを表示し、ユーザーは 戻るボタンです。 - インタラクションまたはイベントによって前のカードの状態が更新された場合（例:
「詳細ビュー」でアイテムのタイトルを更新する場合など）は、
popCard()popCard(),pushCard(previous), およびpushCard(current)前のカードと現在のカードを更新します。
カードの更新
Google Workspace アドオンを使用すると、 カードを更新するには、登録済みの Apps Script トリガー関数を再実行してください。 追加します。ユーザーはアドオンのメニュー項目からこの更新をトリガーします。
この操作は、homepageTrigger によって生成されたカードに自動的に追加されます。
アドオンのマニフェストで指定されている contextualTrigger トリガー関数
（コンテキスト カードスタックと非コンテキスト カードスタックの「ルート」）。
複数のカードを返却する
ホームページまたはコンテキスト トリガー関数を使用して、
単一の
Card オブジェクトまたは
対象の Card オブジェクト
UI を表示します。
カードが 1 つしかない場合は、非コンテキスト スタックまたはコンテキスト スタックに追加されます。 ホストアプリの UI に表示されます。
返された配列に、指定された複数の
Card
代わりにホスト アプリケーションは新しいカードを表示します。このカードには、
各カードのヘッダーのリストを返します。これらのヘッダーのいずれかをユーザーがクリックすると
対応するカードが表示されます。
ユーザーがリストからカードを選択すると、そのカードが ホスト アプリケーションがそれを表示します。「 ボタンを使用すると、ユーザーは カードヘッダーリスト。
この「フラット」アドオンが不要な場合は、カードの配置が適しています。 作成済みのカード間の移行などですただしほとんどの場合は カード遷移を直接定義する方法を学び、ホームページと コンテキスト トリガー関数は、単一のカード オブジェクトを返します。
例
ナビゲーションを使って複数のカードを作成する方法を示す例
ボタン間を行き来できます。これらのカードは
返されたカードをプッシュすることで
特定のコンテキストの内外で createNavigationCard() によって実行された場合です。
/**
* Create the top-level card, with buttons leading to each of three
* 'children' cards, as well as buttons to backtrack and return to the
* root card of the stack.
* @return {Card}
*/
function createNavigationCard() {
// Create a button set with actions to navigate to 3 different
// 'children' cards.
var buttonSet = CardService.newButtonSet();
for(var i = 1; i <= 3; i++) {
buttonSet.addButton(createToCardButton(i));
}
// Build the card with all the buttons (two rows)
var card = CardService.newCardBuilder()
.setHeader(CardService.newCardHeader().setTitle('Navigation'))
.addSection(CardService.newCardSection()
.addWidget(buttonSet)
.addWidget(buildPreviousAndRootButtonSet()));
return card.build();
}
/**
* Create a button that navigates to the specified child card.
* @return {TextButton}
*/
function createToCardButton(id) {
var action = CardService.newAction()
.setFunctionName('gotoChildCard')
.setParameters({'id': id.toString()});
var button = CardService.newTextButton()
.setText('Card ' + id)
.setOnClickAction(action);
return button;
}
/**
* Create a ButtonSet with two buttons: one that backtracks to the
* last card and another that returns to the original (root) card.
* @return {ButtonSet}
*/
function buildPreviousAndRootButtonSet() {
var previousButton = CardService.newTextButton()
.setText('Back')
.setOnClickAction(CardService.newAction()
.setFunctionName('gotoPreviousCard'));
var toRootButton = CardService.newTextButton()
.setText('To Root')
.setOnClickAction(CardService.newAction()
.setFunctionName('gotoRootCard'));
// Return a new ButtonSet containing these two buttons.
return CardService.newButtonSet()
.addButton(previousButton)
.addButton(toRootButton);
}
/**
* Create a child card, with buttons leading to each of the other
* child cards, and then navigate to it.
* @param {Object} e object containing the id of the card to build.
* @return {ActionResponse}
*/
function gotoChildCard(e) {
var id = parseInt(e.parameters.id); // Current card ID
var id2 = (id==3) ? 1 : id + 1; // 2nd card ID
var id3 = (id==1) ? 3 : id - 1; // 3rd card ID
var title = 'CARD ' + id;
// Create buttons that go to the other two child cards.
var buttonSet = CardService.newButtonSet()
.addButton(createToCardButton(id2))
.addButton(createToCardButton(id3));
// Build the child card.
var card = CardService.newCardBuilder()
.setHeader(CardService.newCardHeader().setTitle(title))
.addSection(CardService.newCardSection()
.addWidget(buttonSet)
.addWidget(buildPreviousAndRootButtonSet()))
.build();
// Create a Navigation object to push the card onto the stack.
// Return a built ActionResponse that uses the navigation object.
var nav = CardService.newNavigation().pushCard(card);
return CardService.newActionResponseBuilder()
.setNavigation(nav)
.build();
}
/**
* Pop a card from the stack.
* @return {ActionResponse}
*/
function gotoPreviousCard() {
var nav = CardService.newNavigation().popCard();
return CardService.newActionResponseBuilder()
.setNavigation(nav)
.build();
}
/**
* Return to the initial add-on card.
* @return {ActionResponse}
*/
function gotoRootCard() {
var nav = CardService.newNavigation().popToRoot();
return CardService.newActionResponseBuilder()
.setNavigation(nav)
.build();
}