การนำทางการ์ด

ส่วนเสริมที่เป็นการ์ดส่วนใหญ่จะสร้างขึ้นโดยใช้ การ์ดที่แสดง "หน้าเว็บ" ต่างๆ ของ ของอินเทอร์เฟซเสริม หากต้องการมอบประสบการณ์ของผู้ใช้ที่มีประสิทธิภาพ คุณควรใช้การนำทางที่ง่ายและเป็นธรรมชาติระหว่างการ์ดต่างๆ ในส่วนเสริม

เดิมทีในส่วนเสริม Gmail การเปลี่ยนระหว่างการ์ดต่างๆ ของ UI โดยการดันและป็อปการ์ดไปยังและจากชุดการ์ดเดี่ยว การ์ดด้านบนของกองที่แสดงโดย Gmail

ขอแนะนำส่วนเสริมของ Google Workspace หน้าแรกและ การ์ดที่ไม่ใช่บริบท เพื่อรองรับการ์ดตามบริบท และการ์ดที่ไม่ใช่ตามบริบท ส่วนเสริมของ Google Workspace มีสแต็กการ์ดภายใน สำหรับแต่ละรายการ เมื่อมีการเปิดส่วนเสริม ในโฮสต์ homepageTrigger ที่เกี่ยวข้องจะเริ่มสร้างรายการแรก การ์ดหน้าแรกในกลุ่ม (การ์ด "หน้าแรก" สีน้ำเงินเข้มในแผนภาพด้านล่าง) หากไม่ได้กำหนด homepageTrigger ระบบจะสร้าง แสดงบัตรเริ่มต้น และพุชไปยังสแต็กที่ไม่ใช่บริบท การ์ดแรกนี้เป็นการ์ดรูท

ส่วนเสริมของคุณสามารถสร้างการ์ดที่ไม่ใช่บริบทเพิ่มเติมและพุชการ์ดดังกล่าวไปยัง ซ้อนกัน ("การ์ดที่ดึงไว้" สีน้ำเงินในแผนภาพ) ขณะที่ผู้ใช้ไปยังส่วนต่างๆ ส่วนเสริมของคุณ UI ของส่วนเสริมจะแสดงการ์ดบนสุดในกลุ่ม ดังนั้น การ์ดไปยังกองจะเปลี่ยนการแสดงผล และนำการ์ดออกจากกองกลับ การแสดงผลไปยังการ์ดก่อนหน้า

หากส่วนเสริมของคุณมีการกำหนด ทริกเกอร์ตามบริบท เมื่อผู้ใช้ป้อนบริบทดังกล่าว ทริกเกอร์จะเริ่มทำงาน ฟังก์ชันทริกเกอร์ สร้างการ์ดบริบท แต่การแสดงผล UI จะได้รับการอัปเดตตาม DisplayStyle ของบัตรใหม่ ได้แก่

• หาก DisplayStyle คือ REPLACE (ค่าเริ่มต้น), การ์ดตามบริบท (สีส้มเข้ม "บริบท" ในแผนภาพ) จะแทนที่ ที่แสดง การดำเนินการนี้จะเริ่มต้นสแต็กการ์ดใหม่ตามบริบทใหม่ไว้ด้านบนสุดอย่างมีประสิทธิภาพ ของสแต็กการ์ดที่ไม่ใช่ตามบริบท และการ์ดตามบริบทนี้คือราก ของสแต็กบริบท
• หาก DisplayStyle PEEK UI จะสร้างส่วนหัวที่โผล่ขึ้นมาปรากฏอยู่ที่ ด้านล่างของแถบด้านข้างส่วนเสริม ซ้อนทับการ์ดปัจจุบัน ส่วนหัวของ Peek แสดงชื่อการ์ดใหม่ และให้ปุ่มผู้ใช้ควบคุม เพื่อตัดสินใจว่าจะดูบัตรใหม่หรือไม่ หากผู้ใช้คลิกปุ่มดู ปุ่ม การ์ดดังกล่าวจะแทนที่บัตรปัจจุบัน (ตามที่อธิบายไว้ด้านบนด้วย REPLACE)

คุณสามารถสร้างการ์ดบริบทเพิ่มเติมและ ดันการ์ดเข้าไปในกองซ้อน ("การ์ดที่พุช" สีเหลืองในแผนภาพ) กำลังอัปเดต กลุ่มการ์ดจะเปลี่ยน UI ของส่วนเสริมเพื่อแสดงการ์ดบนสุด หากผู้ใช้ ออกจากบริบท ระบบจะนำการ์ดบริบทบนกองออกและการแสดงผล อัปเดตไปยังการ์ดหรือหน้าแรกที่ไม่ใช่ตามบริบทระดับบนสุด

หากผู้ใช้ป้อนบริบทที่ส่วนเสริมไม่ได้กำหนด ที่ไม่มีการสร้างการ์ดใหม่ บัตรปัจจุบันจะยังแสดงอยู่

การดำเนินการของ Navigation ที่อธิบายไว้ด้านล่างจะดำเนินการกับการ์ดจากบริบทเดียวกันเท่านั้น ตัวอย่างเช่น popToRoot() จากภายในการ์ดบริบทจะแสดงการ์ดบริบทอื่นๆ ทั้งหมดเท่านั้น และ จะไม่มีผลต่อการ์ดหน้าแรก

ในทางตรงกันข้าม ปุ่ม พร้อมใช้งานเสมอสำหรับให้ผู้ใช้นำทางจากการ์ดบริบทไปยัง การ์ดที่ไม่ใช่บริบท

วิธีไปยังส่วนต่างๆ

คุณสร้างการเปลี่ยนระหว่างการ์ดได้โดยการเพิ่มหรือนำการ์ดออกจาก สแต็กการ์ด Navigation มีฟังก์ชันสำหรับพุชและแสดงการ์ดจากกองซ้อน วิธีสร้าง การไปยังส่วนต่างๆ ในการ์ดได้อย่างมีประสิทธิภาพ คุณกำหนดค่า วิดเจ็ตสำหรับใช้การนำทาง การกระทำ คุณจะดันหรือป๊อปก็ได้ บัตรหลายใบพร้อมกันได้ แต่คุณนำการ์ดหน้าแรกเริ่มต้นออกไม่ได้ ที่จะพุชไปยังสแต็กเป็นอันดับแรกเมื่อส่วนเสริมเริ่มทำงาน

หากต้องการไปยังการ์ดใหม่เพื่อตอบกลับการโต้ตอบของผู้ใช้กับวิดเจ็ต ให้ทำตามขั้นตอนต่อไปนี้

1. สร้างออบเจ็กต์ Action และเชื่อมโยงกับ ฟังก์ชัน Callback ตามที่คุณนิยาม
2. เลือกใช้วิดเจ็ตตามที่เหมาะสม ฟังก์ชันเครื่องจัดการวิดเจ็ต เพื่อตั้งค่า Action ในวิดเจ็ตนั้น
3. ใช้ฟังก์ชัน Callback ที่ใช้ในการนำทาง ฟังก์ชันนี้ ได้รับออบเจ็กต์เหตุการณ์การดำเนินการ เป็นอาร์กิวเมนต์และต้องทำดังนี้
   1. สร้าง Navigation เพื่อกำหนดการเปลี่ยนแปลงการ์ด ออบเจ็กต์ Navigation รายการเดียวทำได้ ประกอบด้วยขั้นตอนการนําทางหลายขั้นตอน เรียงตามลำดับ จะเพิ่มลงในออบเจ็กต์
   2. สร้าง ActionResponse โดยใช้แอตทริบิวต์ ActionResponseBuilder และ Navigation ออบเจ็กต์
   3. ส่งคืนบิลด์ 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 ที่ลงทะเบียนไว้ใน ไฟล์ Manifest ผู้ใช้ทริกเกอร์การรีเฟรชนี้ผ่านรายการในเมนูส่วนเสริม

ระบบจะเพิ่มการดำเนินการนี้ลงในการ์ดที่สร้างโดย homepageTrigger โดยอัตโนมัติ contextualTrigger ทริกเกอร์ฟังก์ชัน ตามที่ระบุไว้ในไฟล์ Manifest ของส่วนเสริม ("ราก" ของสแต็กการ์ดตามบริบทและที่ไม่ใช่ตามบริบท)

การแสดงบัตรหลายใบ

ใช้ฟังก์ชันทริกเกอร์หน้าแรกหรือตามบริบทเพื่อสร้างและแสดงผล รายการเดียว Card ของออบเจ็กต์หรืออาร์เรย์ของ Card ระบุว่า การแสดง UI ของแอปพลิเคชัน

หากมีการ์ดเพียงใบเดียว ระบบจะเพิ่มการ์ดนั้นลงในสแต็กที่ไม่ใช่บริบทหรือบริบท ที่การ์ดรูทและ UI แอปพลิเคชันโฮสต์แสดงการ์ดดังกล่าว

ถ้าอาร์เรย์ที่แสดงผลมีบิลด์มากกว่า 1 รายการ Card แอปพลิเคชันโฮสต์จะแสดงการ์ดใหม่ซึ่งมี รายการส่วนหัวของการ์ดแต่ละใบ เมื่อผู้ใช้คลิกส่วนหัวเหล่านี้ UI แสดงการ์ดที่เกี่ยวข้อง

เมื่อผู้ใช้เลือกการ์ดจากรายการ การ์ดนั้นจะถูกพุชไปยัง สแต็กปัจจุบันและแอปพลิเคชันโฮสต์จะแสดงสแต็กปัจจุบัน ปุ่ม จะนำผู้ใช้กลับไปยัง รายการส่วนหัวของการ์ด

"แฟลต" นี้ การจัดเรียงบัตรจะได้ผลดีหากไม่จำเป็นต้องมีส่วนเสริม การเปลี่ยนระหว่างการ์ดที่คุณสร้างขึ้น อย่างไรก็ตาม ในกรณีส่วนใหญ่แล้ว ฝึกฝนเพื่อกำหนดการเปลี่ยนการ์ดโดยตรง และมีหน้าแรกและ ฟังก์ชันทริกเกอร์ตามบริบทจะแสดงออบเจ็กต์การ์ดรายการเดียว

ตัวอย่าง

นี่คือตัวอย่างที่แสดงวิธีสร้างการ์ดหลายใบด้วยการนำทาง ปุ่มที่ข้ามไปมาระหว่างส่วนต่างๆ ได้ การ์ดเหล่านี้สามารถเพิ่มลงใน สแต็กตามบริบทหรือไม่ใช่บริบทด้วยการพุชการ์ดที่แสดงผล โดย 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();
  }