大多数基于卡片的插件都是使用多个卡片构建的，这些卡片代表插件界面的不同“页面”。为了提供良好的用户体验，您应在插件中使用简单自然的卡片导航方式。
最初，在 Gmail 插件中，界面中不同卡片之间的转换是通过将卡片推送和弹出到单个卡片堆叠来处理的，堆叠顶部的卡片由 Gmail 显示。
Google Workspace 插件引入了首页和非情境卡片。为了适应情境卡片和非情境卡片，Google Workspace 插件为每种卡片都提供了内部卡片堆叠。在宿主中打开某个插件时，系统会触发相应的 homepageTrigger 以创建堆栈上的第一个首页卡片（下图中的深蓝色“首页”卡片）。如果未定义 homepageTrigger，系统会创建、显示默认卡片，并将其推送到非情境堆栈。这张第一张卡片是根卡片。
当用户浏览您的插件时，您的插件可以创建其他非情境卡片，并将其推送到堆叠（图表中的蓝色“推送的卡片”）。插件界面会显示堆栈中的顶部卡片，因此将新卡片推送到堆栈会更改显示内容，从堆栈中弹出卡片会将显示内容返回到之前的卡片。
如果您的插件定义了上下文触发器，当用户进入相应上下文时，该触发器就会触发。触发器函数会构建情境卡片，但界面显示会根据新卡片的 DisplayStyle 进行更新：
- 如果
DisplayStyle为REPLACE（默认值），情境卡片（图表中的深橙色“情境”卡片）会取代当前显示的卡片。这实际上会在非情境卡片堆叠上启动新的情境卡片堆叠，并且此情境卡片是情境堆叠的根卡片。 - 如果
DisplayStyle为PEEK，界面将改为创建一个在插件边栏底部显示的 peek 标题，并叠加在当前卡片上。预览标题会显示新卡片的标题，并提供用户按钮控件，以便用户决定是否查看新卡片。如果用户点击查看按钮，该卡片会替换当前卡片（如上文中所述的REPLACE）。
您可以创建其他情境卡片并将其推送到堆叠（图表中的黄色“推送的卡片”）。更新卡片堆叠会更改插件界面，以显示最上面的卡片。如果用户离开某个情境，堆叠中的情境卡片会被移除，显示内容会更新为顶部的非情境卡片或首页。
如果用户进入您的插件未定义上下文触发器的上下文，系统不会创建新卡片，并会继续显示当前卡片。
下面介绍的 Navigation 操作仅适用于同一情境中的卡片；例如，在情境卡片中执行 popToRoot() 只会弹出所有其他情境卡片，而不会影响首页卡片。
与之相反，用户可以随时使用 按钮从内容相关卡片导航到非内容相关卡片。
导航方法
您可以通过向卡片堆叠中添加或移除卡片，在卡片之间创建转场效果。Navigation 类提供了用于从堆栈中推送和弹出卡片的函数。如需构建有效的卡片导航，您需要配置微件以使用导航操作。您可以同时推送或弹出多个卡片，但无法移除在插件启动时首先推送到堆栈上的初始首页卡片。
如需在用户与 widget 互动时导航到新卡片，请按以下步骤操作：
- 创建一个
Action对象，并将其与您定义的回调函数相关联。 - 调用微件的适当微件处理程序函数，以在该微件上设置
Action。 - 实现用于执行导航的回调函数。此函数会作为参数接受一个操作事件对象，并且必须执行以下操作：
- 创建一个
Navigation对象来定义卡片更改。单个Navigation对象可以包含多个导航步骤，这些步骤会按照添加到对象的顺序执行。 - 使用
ActionResponseBuilder类和Navigation对象构建ActionResponse对象。 - 返回构建的
ActionResponse。
- 创建一个
构建导航控件时，您可以使用以下 Navigation 对象函数：
| 函数 | 说明 |
|---|---|
Navigation.pushCard(Card) |
将卡片推送到当前堆栈。这需要先完全构建卡片。 |
Navigation.popCard() |
从堆叠顶部移除一张卡片。相当于点击插件标题行中的返回箭头。这不会移除根卡片。 |
Navigation.popToRoot() |
移除堆叠中除根卡片之外的所有卡片。本质上会重置该卡片堆叠。 |
Navigation.popToNamedCard(String) |
从堆栈中弹出卡片，直到找到具有给定名称的卡片或堆栈的根卡片。您可以使用 CardBuilder.setName(String) 函数为卡片分配名称。 |
Navigation.updateCard(Card) |
对当前卡片进行原位替换，刷新界面中的显示。 |
Navigation 最佳实践
如果用户互动或事件应导致在同一上下文中重新渲染卡片，请使用 Navigation.pushCard()、Navigation.popCard() 和 Navigation.updateCard() 方法替换现有卡片。如果用户互动或事件应导致在其他情境中重新渲染卡片，请使用 ActionResponseBuilder.setStateChanged() 在这些情境中强制重新执行您的插件。
以下是导航示例：
- 如果互动或事件更改了当前卡片的状态（例如，向任务列表添加任务），请使用
updateCard()。 - 如果互动或事件提供更多详细信息或提示用户执行进一步操作（例如，点击某个项的标题以查看更多详细信息，或按按钮以创建新的日历活动），请使用
pushCard()显示新页面，同时允许用户使用返回按钮退出新页面。 - 如果互动或事件更新了上一个卡片中的状态（例如，通过详情视图更新商品的标题），请使用
popCard()、popCard()、pushCard(previous)和pushCard(current)等方法更新上一个卡片和当前卡片。
刷新卡片
借助 Google Workspace 插件，用户可以通过重新运行清单中注册的 Apps 脚本触发器函数来刷新您的卡片。用户通过插件菜单项触发此刷新：
此操作会自动添加到由 homepageTrigger 或 contextualTrigger 触发器函数生成的卡片中，如您的插件清单文件（情境相关卡片堆叠和非情境相关卡片堆叠的“根”）中所指定。
退回多张卡
首页或情境触发器函数用于构建并返回单个 Card 对象或应用界面显示的 Card 对象数组。
如果只有一张卡片，系统会将其添加到非情境堆叠或情境堆叠中作为根卡片，并在托管应用界面中显示该卡片。
如果返回的数组包含多个内置 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();
}