Di chuyển thẻ

Hầu hết tiện ích bổ sung dựa trên thẻ được xây dựng bằng cách sử dụng nhiều thẻ đại diện cho các "trang" khác nhau của giao diện tiện ích bổ sung. Để có trải nghiệm người dùng hiệu quả, bạn nên sử dụng cách di chuyển đơn giản và tự nhiên giữa các thẻ trong tiện ích bổ sung của mình.

Ban đầu, trong tiện ích bổ sung của Gmail, hiệu ứng chuyển đổi giữa các thẻ khác nhau của giao diện người dùng bao gồm được xử lý bằng cách đẩy và đẩy thẻ vào và ra khỏi một ngăn xếp thẻ, với thẻ trên cùng của ngăn xếp được Gmail hiển thị.

Ra mắt các tiện ích bổ sung của Google Workspace trang chủ và thẻ không theo ngữ cảnh. Để phù hợp với thẻ theo ngữ cảnh và không theo ngữ cảnh, Tiện ích bổ sung của Google Workspace có ngăn xếp thẻ bên trong cho mỗi chiến dịch. Khi mở tiện ích bổ sung trong một máy chủ lưu trữ, homepageTrigger tương ứng sẽ kích hoạt để tạo mã đầu tiên thẻ trang chủ trên ngăn xếp (thẻ "trang chủ" màu xanh dương đậm trong sơ đồ bên dưới). Nếu bạn không xác định homepageTrigger, thì thẻ mặc định sẽ được tạo, hiển thị và được đẩy lên ngăn xếp không theo ngữ cảnh. Thẻ đầu tiên này là thẻ gốc.

Tiện ích bổ sung của bạn có thể tạo thêm thẻ không theo ngữ cảnh và đẩy các thẻ đó vào ngăn xếp ("thẻ được đẩy" màu xanh dương trong biểu đồ) khi người dùng di chuyển qua tiện ích bổ sung của mình. Giao diện người dùng của tiện ích bổ sung hiển thị thẻ trên cùng trong ngăn xếp, do đó, việc đẩy thẻ vào ngăn xếp sẽ thay đổi chế độ hiển thị, còn thẻ bật ra khỏi ngăn xếp sẽ xuất hiện trở lại màn hình hiển thị đến các thẻ trước đó.

Nếu tiện ích bổ sung của bạn có kích hoạt theo ngữ cảnh, khi người dùng nhập bối cảnh đó, thì điều kiện kích hoạt sẽ kích hoạt. Hàm kích hoạt tạo thẻ ngữ cảnh, nhưng màn hình giao diện người dùng được cập nhật dựa trên DisplayStyle của thẻ mới:

• Nếu DisplayStyle là REPLACE (mặc định), thẻ ngữ cảnh (màu cam đậm) "theo ngữ cảnh" trong biểu đồ) sẽ thay thế thẻ thẻ hiển thị. Thao tác này sẽ khởi động một cách hiệu quả ngăn xếp thẻ mới theo bối cảnh ở trên cùng của ngăn xếp thẻ không theo ngữ cảnh và thẻ ngữ cảnh này là gốc thẻ ngăn xếp theo bối cảnh.
• Nếu DisplayStyle là PEEK thì giao diện người dùng sẽ tạo một tiêu đề xem nhanh xuất hiện ở cuối thanh bên của tiện ích bổ sung, phủ lên thẻ hiện tại. Tiêu đề xem trước hiển thị tiêu đề của thẻ mới và cung cấp các nút điều khiển người dùng cho phép họ quyết định có xem thẻ mới hay không. Nếu họ nhấp vào Chế độ xem , thẻ này sẽ thay thế thẻ hiện tại (như được mô tả ở trên bằng REPLACE).

Bạn có thể tạo thêm thẻ ngữ cảnh và đẩy chúng vào ngăn xếp ("thẻ được đẩy" màu vàng trong sơ đồ). Đang cập nhật ngăn xếp thẻ sẽ thay đổi giao diện người dùng của tiện ích bổ sung để cho thấy thẻ ở trên cùng. Nếu người dùng để lại bối cảnh, các thẻ bối cảnh trong ngăn xếp sẽ bị xoá và màn hình các bản cập nhật cho thẻ hoặc trang chủ không theo ngữ cảnh ở trên cùng.

Nếu người dùng nhập bối cảnh mà tiện ích bổ sung của bạn không xác định trình kích hoạt theo ngữ cảnh cho, không có thẻ mới nào được tạo và thẻ hiện tại vẫn được hiển thị.

Hành động Navigation được mô tả dưới đây chỉ hành động trên các thẻ trong cùng một ngữ cảnh; ví dụ: popToRoot() từ trong thẻ ngữ cảnh chỉ bật tất cả các thẻ ngữ cảnh khác và sẽ không ảnh hưởng đến các thẻ trên trang chủ.

Ngược lại, nút arrow_back lại luôn có sẵn để người dùng chuyển từ thẻ ngữ cảnh đến thẻ không theo ngữ cảnh.

Phương thức điều hướng

Bạn có thể tạo hiệu ứng chuyển đổi giữa các thẻ bằng cách thêm hoặc xoá thẻ khỏi ngăn xếp thẻ. Navigation lớp cung cấp các chức năng đẩy và đẩy thẻ từ ngăn xếp. Xây dựng điều hướng thẻ hiệu quả, bạn định cấu hình tiện ích để sử dụng tính năng điều hướng hành động. Bạn có thể đẩy hoặc đẩy nhiều thẻ cùng lúc, nhưng bạn không thể xoá thẻ trang chủ ban đầu được đẩy lần đầu tiên vào ngăn xếp khi tiện ích bổ sung khởi động.

Để điều hướng đến một thẻ mới tương ứng với tương tác của người dùng với một tiện ích, hãy làm theo các bước sau:

1. Tạo một đối tượng Action và liên kết tài khoản đó với một gọi lại hàm bạn xác định.
2. Gọi bộ phận thích hợp của tiện ích hàm trình xử lý tiện ích để đặt Action trên tiện ích đó.
3. Triển khai hàm callback tiến hành việc điều hướng. Hàm này được cung cấp một đối tượng sự kiện hành động làm đối số và phải thực hiện những việc sau:
   1. Tạo một Navigation để xác định thay đổi thẻ. Một đối tượng Navigation có thể chứa nhiều bước điều hướng được tiến hành theo thứ tự chúng sẽ được thêm vào đối tượng.
   2. Tạo ActionResponse bằng cách sử dụng ActionResponseBuilder lớp và Navigation .
   3. Trả về ActionResponse.

Khi tạo các thành phần điều khiển điều hướng, bạn sử dụng Hàm đối tượng Navigation:

Các phương pháp hay nhất về tính năng điều hướng

Nếu một sự tương tác hoặc sự kiện của người dùng dẫn đến việc các thẻ hiển thị lại trong cùng một sự kiện ngữ cảnh, sử dụng Navigation.pushCard()! Navigation.popCard(), và Navigation.updateCard() để thay thế các thẻ hiện có. Nếu một sự kiện hoặc lượt tương tác của người dùng dẫn đến thẻ hiển thị lại trong ngữ cảnh khác, hãy sử dụng ActionResponseBuilder.setStateChanged() để buộc thực thi lại tiện ích bổ sung của bạn trong những ngữ cảnh đó.

Sau đây là các ví dụ điều hướng:

• Nếu một lượt tương tác hoặc sự kiện thay đổi trạng thái của thẻ hiện tại (ví dụ: thêm một công việc vào một danh sách công việc), hãy sử dụng updateCard().
• Nếu một lượt tương tác hoặc sự kiện cung cấp thêm thông tin chi tiết hoặc nhắc người dùng hành động khác (ví dụ: nhấp vào tiêu đề của một mặt hàng để xem thêm chi tiết hoặc nhấn một nút để tạo sự kiện mới trên Lịch), sử dụng pushCard() để hiển thị trang mới đồng thời cho phép người dùng thoát khỏi trang mới bằng cách sử dụng nút quay lại.
• Nếu một lượt tương tác hoặc sự kiện cập nhật trạng thái trong một thẻ trước đó (ví dụ: cập nhật tiêu đề của mục từ chế độ xem chi tiết), hãy sử dụng các lệnh như popCard()! popCard(), pushCard(previous), và pushCard(current) để cập nhật thẻ trước đó và thẻ hiện tại.

Đang làm mới thẻ

Tiện ích bổ sung của Google Workspace giúp người dùng có thể làm mới thẻ của bạn bằng cách chạy lại chức năng kích hoạt Apps Script đã đăng ký trong tệp kê khai của bạn. Người dùng kích hoạt quá trình làm mới này thông qua một mục trong trình đơn tiện ích bổ sung:

Hành động này sẽ tự động được thêm vào thẻ do homepageTrigger tạo hoặc Hàm kích hoạt contextualTrigger, như chỉ định trong tệp kê khai của tiện ích bổ sung ('gốc' của ngăn xếp thẻ theo ngữ cảnh và không theo ngữ cảnh).

Trả lại nhiều thẻ

Các hàm kích hoạt trang chủ hoặc ngữ cảnh được dùng để tạo và trả về hoặc một đơn vị đối tượng Card hoặc một mảng Card mà giao diện người dùng của ứng dụng.

Nếu chỉ có một thẻ, thẻ đó sẽ được thêm vào ngăn xếp không theo ngữ cảnh hoặc theo ngữ cảnh làm thẻ gốc và giao diện người dùng của ứng dụng lưu trữ sẽ hiển thị thẻ đó.

Nếu mảng được trả về bao gồm nhiều hơn một dữ liệu đã tạo Card thì ứng dụng lưu trữ sẽ hiển thị một thẻ mới, trong đó chứa danh sách tiêu đề của từng thẻ. Khi người dùng nhấp vào bất kỳ tiêu đề nào trong số đó, giao diện người dùng sẽ hiện thẻ tương ứng.

Khi người dùng chọn một thẻ trong danh sách, thẻ đó sẽ được đẩy lên ngăn xếp hiện tại và ứng dụng lưu trữ hiển thị ngăn xếp đó. Chiến lược phát hành đĩa đơn Nút arrow_back đưa người dùng trở lại danh sách tiêu đề thẻ.

"flat" này Tính năng sắp xếp thẻ có thể hoạt động hiệu quả nếu tiện ích bổ sung của bạn không cần bất kỳ hiệu ứng chuyển đổi giữa các thẻ mà bạn tạo. Tuy nhiên, trong hầu hết các trường hợp, tốt hơn thực hành trực tiếp xác định hiệu ứng chuyển đổi thẻ, đồng thời đặt trang chủ và hàm kích hoạt theo ngữ cảnh trả về một đối tượng thẻ duy nhất.

Ví dụ:

Dưới đây là ví dụ cho thấy cách tạo một số thẻ bằng tính năng điều hướng chuyển giữa các nút. Bạn có thể thêm các thẻ này vào ngăn xếp theo ngữ cảnh hoặc không theo ngữ cảnh bằng cách đẩy thẻ được trả về bởi createNavigationCard() trong hoặc bên ngoài ngữ cảnh cụ thể.

  /**
   *  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();
  }