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

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

मूल रूप से 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. ActionResponse बनाएं ऑब्जेक्ट को ActionResponseBuilder क्लास और Navigation ऑब्जेक्ट है.
   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 ट्रिगर फ़ंक्शन को फिर से चलाकर, अपने कार्ड को रीफ़्रेश करें मेनिफ़ेस्ट फ़ाइल में दी गई जानकारी शामिल न करें. उपयोगकर्ता इस रीफ़्रेश को किसी ऐड-ऑन मेन्यू आइटम के ज़रिए ट्रिगर करते हैं:

यह कार्रवाई 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();
  }