कार्ड नेविगेशन

ज़्यादातर कार्ड-आधारित ऐड-ऑन को ऐसे कई कार्ड का इस्तेमाल करके बनाया जाता है जो ऐड-ऑन इंटरफ़ेस के अलग-अलग 'पेज' को दिखाते हैं. असरदार उपयोगकर्ता अनुभव पाने के लिए, आपको अपने ऐड-ऑन में कार्ड के बीच आसान और नैचुरल नेविगेशन का इस्तेमाल करना चाहिए.

मूल रूप से, Gmail ऐड-ऑन में, यूज़र इंटरफ़ेस (यूआई) के अलग-अलग कार्ड के बीच ट्रांज़िशन को कार्ड को एक कार्ड स्टैक में पुश और पॉप-अप करके, और Gmail से दिखाए गए स्टैक के टॉप कार्ड से हैंडल किया जाता है.

होम पेज कार्ड नेविगेशन

Google Workspace ऐड-ऑन की मदद से, होम पेज और ऐसे कार्ड दिखाए जाते हैं जो काम के नहीं हैं. संदर्भ के हिसाब से और काम के नहीं होने वाले कार्ड को शामिल करने के लिए, Google Workspace ऐड-ऑन में हर कार्ड के लिए अंदरूनी कार्ड स्टैक होता है. जब किसी ऐड-ऑन को होस्ट में खोला जाता है, तो उससे जुड़े homepageTrigger, स्टैक पर पहला होम पेज कार्ड बनाने के लिए सक्रिय होते हैं (नीचे दिए गए डायग्राम में गहरा नीला "होम पेज" कार्ड). अगर homepageTrigger तय नहीं किया गया है, तो डिफ़ॉल्ट कार्ड बनाया जाता है, दिखाया जाता है, और बिना काम के स्टैक में डाला जाता है. यह पहला कार्ड रूट कार्ड है.

जैसे ही उपयोगकर्ता आपके ऐड-ऑन में नेविगेट करता है, आपका ऐड-ऑन अतिरिक्त गैर-संदर्भ कार्ड बना सकता है और उन्हें स्टैक पर नीले रंग के "पुश किए गए कार्ड" में भेज सकता है. ऐड-ऑन यूज़र इंटरफ़ेस (यूआई) स्टैक में सबसे ऊपर का कार्ड दिखाता है, इसलिए नए कार्ड स्टैक पर पुश करने से डिसप्ले बदल जाता है और स्टैक से पॉप कार्ड हटने पर डिसप्ले, पिछले कार्ड पर चला जाता है.

अगर आपके ऐड-ऑन के पास पहले से तय संदर्भ ट्रिगर है, तो जब उपयोगकर्ता उस संदर्भ को डालता है तब ट्रिगर सक्रिय हो जाता है. ट्रिगर फ़ंक्शन संदर्भ कार्ड बनाता है, लेकिन यूज़र इंटरफ़ेस (यूआई) डिसप्ले को नए कार्ड के DisplayStyle के आधार पर अपडेट किया जाता है:

  • अगर DisplayStyle REPLACE (डिफ़ॉल्ट) है, तो कॉन्टेक्स्ट में मौजूद कार्ड (मौजूदा डायग्राम में गहरे रंग का नारंगी "कीवर्ड" कार्ड) दिखाए गए कार्ड की जगह ले लेता है. इससे गैर-संदर्भ कार्ड स्टैक के ऊपर एक नया प्रासंगिक कार्ड स्टैक शुरू हो जाता है और यह प्रासंगिक कार्ड प्रासंगिक स्टैक का रूट कार्ड होता है.
  • अगर DisplayStyle PEEK है, तो यूज़र इंटरफ़ेस (यूआई) एक झलक वाला हेडर बनाता है. यह ऐड-ऑन साइडबार के सबसे नीचे, मौजूदा कार्ड को ओवरले करता है. पीक हेडर से, नए कार्ड का शीर्षक दिखता है. साथ ही, यह उपयोगकर्ता बटन के लिए ऐसे कंट्रोल उपलब्ध कराता है जिनसे यह तय किया जा सकता है कि नया कार्ड देखना है या नहीं. अगर वे देखें बटन पर क्लिक करते हैं, तो कार्ड मौजूदा कार्ड की जगह ले लेता है (जैसा कि ऊपर REPLACE में बताया गया है).

अतिरिक्त प्रासंगिक कार्ड बनाकर उन्हें स्टैक में पीले रंग के "पुश किए गए कार्ड" में पुश किया जा सकता है. कार्ड स्टैक को अपडेट करने से, सबसे ऊपर वाला कार्ड दिखाने के लिए ऐड-ऑन यूज़र इंटरफ़ेस (यूआई) बदल जाता है. अगर उपयोगकर्ता किसी संदर्भ को छोड़ देते हैं, तो स्टैक से मिलते-जुलते कार्ड को हटा दिया जाता है और डिसप्ले सबसे ऊपर के सबसे काम के नहीं कार्ड या होम पेज पर अपडेट हो जाता है.

अगर उपयोगकर्ता कोई ऐसा कॉन्टेक्स्ट डालता है जिसके लिए ऐड-ऑन के लिए, ट्रिगर ट्रिगर तय नहीं किया जाता है, तो कोई नया कार्ड नहीं बनाया जाता है और मौजूदा कार्ड दिखता रहता है.

Navigation के बारे में नीचे बताई गई कार्रवाइयां, सिर्फ़ एक ही संदर्भ वाले कार्ड पर काम करती हैं. उदाहरण के लिए, संदर्भ वाले कार्ड में से popToRoot(), सिर्फ़ दूसरे सभी संदर्भ कार्ड को पॉप करती हैं और इससे होम पेज कार्ड पर असर नहीं पड़ता.

इसके उलट, बटन हमेशा उपयोगकर्ताओं के लिए उपलब्ध होता है. यहां वे अपने काम के कार्ड से, काम न करने वाले कार्ड पर नेविगेट कर सकते हैं.

आप कार्ड स्टैक में कार्ड जोड़कर या हटाकर कार्ड के बीच ट्रांज़िशन बना सकते हैं. Navigation क्लास से, स्टैक से कार्ड को पुश और पॉप करने के फ़ंक्शन मिलते हैं. बेहतर कार्ड नेविगेशन बनाने के लिए, आप अपने विजेट कॉन्फ़िगर करके नेविगेशन कार्रवाई का इस्तेमाल करें. एक साथ कई कार्ड को पुश या पॉप किया जा सकता है, लेकिन ऐड-ऑन के शुरू होने पर स्टैक में पुश किए जाने वाले शुरुआती होम पेज कार्ड को हटाया नहीं जा सकता.

विजेट के साथ उपयोगकर्ता के इंटरैक्शन के जवाब में नए कार्ड पर जाने के लिए, यह तरीका अपनाएं:

  1. एक Action ऑब्जेक्ट बनाएं और उसे अपने तय किए गए कॉलबैक फ़ंक्शन से जोड़ें.
  2. विजेट पर Action सेट करने के लिए, विजेट के सही विजेट हैंडलर फ़ंक्शन को कॉल करें.
  3. नेविगेशन करने वाले कॉलबैक फ़ंक्शन को लागू करें. इस फ़ंक्शन को आर्ग्युमेंट के तौर पर ऐक्शन इवेंट ऑब्जेक्ट दिया जाता है और यह नीचे दिया गया होना चाहिए:
    1. कार्ड में बदलाव तय करने के लिए Navigation ऑब्जेक्ट बनाएं. एक ही Navigation ऑब्जेक्ट में कई नेविगेशन चरण हो सकते हैं, जो उसी क्रम में होते हैं जिस क्रम में उन्हें ऑब्जेक्ट में जोड़ा गया है.
    2. ActionResponseBuilder क्लास और Navigation ऑब्जेक्ट का इस्तेमाल करके, ActionResponse ऑब्जेक्ट बनाएं.
    3. बनाया गया ActionResponse दिखाएं.

नेविगेशन कंट्रोल बनाते समय, ये Navigation ऑब्जेक्ट फ़ंक्शन इस्तेमाल किए जा सकते हैं:

फ़ंक्शन जानकारी
Navigation.pushCard(Card) कार्ड को मौजूदा स्टैक पर पुश करता है. इसके लिए, पहले आपको पूरा कार्ड बनाना होगा.
Navigation.popCard() स्टैक के ऊपर से एक कार्ड निकालता है. ऐड-ऑन हेडर की पंक्ति में वापस जाएं ऐरो पर क्लिक करने के बराबर. इससे रूट कार्ड नहीं हटते.
Navigation.popToRoot() रूट कार्ड को छोड़कर, स्टैक से सभी कार्ड हटा देता है. इससे, कार्ड का स्टैक रीसेट हो जाता है.
Navigation.popToNamedCard(String) स्टैक से कार्ड को तब तक पॉप करता है जब तक कि दिए गए नाम या स्टैक के रूट कार्ड के कार्ड तक नहीं पहुंच जाता. CardBuilder.setName(String) फ़ंक्शन का इस्तेमाल करके, कार्ड को नाम दिए जा सकते हैं.
Navigation.updateCard(Card) मौजूदा कार्ड को बदलने की सुविधा, यूज़र इंटरफ़ेस (यूआई) में दिखने पर, इसे बदलने की सुविधा देती है.

अगर किसी उपयोगकर्ता के इंटरैक्शन या इवेंट की वजह से, कार्ड उसी संदर्भ में फिर से रेंडर हो रहे हैं, तो मौजूदा कार्ड की जगह Navigation.pushCard(), Navigation.popCard(), और Navigation.updateCard() तरीका इस्तेमाल करें. अगर उपयोगकर्ता के किसी इंटरैक्शन या इवेंट की वजह से, कार्ड अलग तरह से रेंडर होते हैं, तो उन परिस्थितियों में अपने ऐड-ऑन को हर हाल में फिर से लागू करने के लिए, ActionResponseBuilder.setStateChanged() का इस्तेमाल करें.

नेविगेशन के ये उदाहरण हैं:

  • अगर कोई इंटरैक्शन या इवेंट, मौजूदा कार्ड की स्थिति (उदाहरण के लिए, किसी टास्क की सूची में कोई टास्क जोड़ना) बदलता है, तो updateCard() का इस्तेमाल करें.
  • अगर किसी इंटरैक्शन या इवेंट से, आगे की जानकारी मिलती है या उपयोगकर्ता को आगे की कार्रवाई के लिए कहा जाता है. उदाहरण के लिए, ज़्यादा जानकारी देखने के लिए आइटम के शीर्षक पर क्लिक करना या नया कैलेंडर इवेंट बनाने के लिए बटन दबाना, तो नए पेज को दिखाने के लिए pushCard() का इस्तेमाल करें. साथ ही, 'वापस जाएं' बटन का इस्तेमाल करके उपयोगकर्ता को नए पेज से बाहर निकलने का विकल्प दें.
  • अगर पिछले कार्ड में कोई इंटरैक्शन या इवेंट अपडेट होता है (उदाहरण के लिए, जानकारी वाले व्यू के साथ किसी आइटम का शीर्षक अपडेट करना), तो पिछले कार्ड और मौजूदा कार्ड को अपडेट करने के लिए popCard(), popCard(), pushCard(previous), और pushCard(current) का इस्तेमाल करें.

कार्ड रीफ़्रेश किए जा रहे हैं

Google Workspace ऐड-ऑन, आपके कार्ड में रीफ़्रेश करने की सुविधा देते हैं. इसके लिए, आपके मेनिफ़ेस्ट में रजिस्टर किए गए Apps Script ट्रिगर फ़ंक्शन को फिर से चलाया जाता है. उपयोगकर्ता इस रीफ़्रेश को किसी ऐड-ऑन मेन्यू आइटम के ज़रिए ट्रिगर करते हैं:

Google Workspace ऐड-ऑन साइडबार Google Workspace ऐड-ऑन साइडबार





यह कार्रवाई, आपके ऐड-ऑन की मेनिफ़ेस्ट फ़ाइल में मौजूद, 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();
  }