विजेट

विजेट, यूज़र इंटरफ़ेस (यूआई) का एक एलिमेंट होता है. इसमें इनमें से एक या उससे ज़्यादा चीज़ें होती हैं:

• कार्ड और सेक्शन जैसे अन्य विजेट के लिए स्ट्रक्चर,
• उपयोगकर्ता के लिए जानकारी, जैसे कि टेक्स्ट और इमेज या
• कार्रवाई के लिए उपलब्ध विकल्प, जैसे कि बटन, टेक्स्ट इनपुट फ़ील्ड या चेकबॉक्स.

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

विजेट के टाइप

ऐड-ऑन विजेट को आम तौर पर तीन ग्रुप में बांटा जाता है: स्ट्रक्चरल विजेट, जानकारी देने वाले विजेट, और उपयोगकर्ता इंटरैक्शन विजेट.

स्ट्रक्चरल विजेट

स्ट्रक्चरल विजेट, यूज़र इंटरफ़ेस (यूआई) में इस्तेमाल किए जाने वाले अन्य विजेट के लिए कंटेनर और व्यवस्थित करने की सुविधा देते हैं.

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

स्ट्रक्चर के इन बुनियादी विजेट के अलावा, Google Workspace के ऐड-ऑन में, कार्ड सेवा का इस्तेमाल करके, मौजूदा कार्ड के ऊपर ओवरलैप होने वाले स्ट्रक्चर बनाए जा सकते हैं: फ़िक्स किए गए फ़ुटर और झलक दिखाने वाले कार्ड:

फ़िक्स्ड फ़ुटर

कार्ड के सबसे नीचे, बटन की एक फ़िक्स की गई लाइन जोड़ी जा सकती है. यह पंक्ति, कार्ड के बाकी कॉन्टेंट के साथ स्क्रीन पर नहीं दिखती या स्क्रोल नहीं होती.

यहां दिए गए कोड के उदाहरण में, फ़िक्स्ड फ़ुटर तय करने और उसे कार्ड में जोड़ने का तरीका बताया गया है:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("Primary")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("Secondary")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "secondaryCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

झलक दिखाने वाला कार्ड

जब कोई उपयोगकर्ता कोई कार्रवाई करता है, जैसे कि Gmail मैसेज खोलना, तो काम के हिसाब से कॉन्टेंट ट्रिगर हो जाता है. ऐसे में, आपके पास काम के हिसाब से कॉन्टेंट को तुरंत दिखाने (डिफ़ॉल्ट रूप से) या साइडबार में सबसे नीचे झलक दिखाने वाले कार्ड की सूचना दिखाने का विकल्प होता है. अगर कोई उपयोगकर्ता, संदर्भ के हिसाब से ट्रिगर चालू होने के दौरान, होम पेज पर वापस जाने के लिए, वापस जाएं arrow_back पर क्लिक करता है, तो उपयोगकर्ताओं को संदर्भ के हिसाब से कॉन्टेंट फिर से ढूंढने में मदद करने के लिए, एक झलक वाला कार्ड दिखता है.

अगर आपको संदर्भ के हिसाब से नया कॉन्टेंट उपलब्ध होने पर, उसे तुरंत दिखाने के बजाय, झलक वाला कार्ड दिखाना है, तो अपनी CardBuilder क्लास में .setDisplayStyle(CardService.DisplayStyle.PEEK) जोड़ें. झलक वाला कार्ड सिर्फ़ तब दिखता है, जब आपके संदर्भ के हिसाब से ट्रिगर होने पर, एक ही कार्ड ऑब्जेक्ट दिखता है. अगर ऐसा नहीं होता है, तो दिखने वाले कार्ड तुरंत मौजूदा कार्ड की जगह ले लेते हैं.

झलक वाले कार्ड के हेडर को पसंद के मुताबिक बनाने के लिए, संदर्भ के हिसाब से कार्ड बनाते समय, स्टैंडर्ड CardHeader ऑब्जेक्ट के साथ .setPeekCardHeader() तरीका जोड़ें. डिफ़ॉल्ट रूप से, झलक दिखाने वाले कार्ड के हेडर में सिर्फ़ आपके ऐड-ऑन का नाम होता है.

Cats Google Workspace ऐड-ऑन के शुरुआती सेटअप के आधार पर, यहां दिया गया कोड, उपयोगकर्ताओं को Peek कार्ड की मदद से, कॉन्टेक्स्ट के हिसाब से नए कॉन्टेंट के बारे में सूचना देता है. साथ ही, चुने गए Gmail मैसेज की थ्रेड का विषय दिखाने के लिए, Peek कार्ड के हेडर को पसंद के मुताबिक बनाता है.

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);

जानकारी देने वाले विजेट

जानकारी देने वाले विजेट, उपयोगकर्ता को जानकारी दिखाते हैं.

• इमेज—आपके दिए गए होस्ट किए गए और सार्वजनिक तौर पर ऐक्सेस किए जा सकने वाले यूआरएल से दिखाई गई इमेज.
• DecoratedText—यह एक टेक्स्ट कॉन्टेंट स्ट्रिंग है. इसे ऊपर और नीचे के टेक्स्ट लेबल, इमेज या आइकॉन जैसे अन्य एलिमेंट के साथ जोड़ा जा सकता है. DecoratedText विजेट में, बटन या स्विच विजेट भी शामिल हो सकते हैं. जोड़े गए स्विच, टॉगल या चेकबॉक्स हो सकते हैं. DecoratedText विजेट के कॉन्टेंट टेक्स्ट में, एचटीएमएल फ़ॉर्मैटिंग का इस्तेमाल किया जा सकता है. हालांकि, सबसे ऊपर और सबसे नीचे मौजूद लेबल में सादा टेक्स्ट का इस्तेमाल करना ज़रूरी है.
• टेक्स्ट पैराग्राफ़—एक ऐसा टेक्स्ट पैराग्राफ़ जिसमें एचटीएमएल फ़ॉर्मैट वाले एलिमेंट शामिल किए जा सकते हैं.

उपयोगकर्ता इंटरैक्शन विजेट

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

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

DecoratedText चेकबॉक्स

आपके पास बटन या बाइनरी टॉगल स्विच के बजाय, चेकबॉक्स वाला DecoratedText विजेट तय करने का विकल्प होता है. स्विच की तरह ही, चेकबॉक्स की वैल्यू को ऐक्शन इवेंट ऑब्जेक्ट में शामिल किया जाता है. इसे setOnClickAction(action) के तरीके से, DecoratedText से जुड़े Action को पास किया जाता है.

यहां दिए गए कोड के हिस्से में, चेकबॉक्स DecoratedText विजेट को तय करने का तरीका बताया गया है. इसके बाद, इसे कार्ड में जोड़ा जा सकता है:

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

तारीख और समय चुनने वाले टूल

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

यहां दिए गए कोड के कुछ हिस्से में, सिर्फ़ तारीख चुनने वाला पिकर, सिर्फ़ समय चुनने वाला पिकर, और तारीख और समय चुनने वाला पिकर तय करने का तरीका बताया गया है. इन पिकर को कार्ड में जोड़ा जा सकता है:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter a date")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter a time")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter a date and time")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));

यहां तारीख-समय चुनने वाले विजेट के हैंडलर फ़ंक्शन का उदाहरण दिया गया है. यह हैंडलर, "myDateTimePickerWidgetID" आईडी वाले तारीख-समय चुनने वाले विजेट में, उपयोगकर्ता की चुनी गई तारीख-समय की जानकारी देने वाली स्ट्रिंग को फ़ॉर्मैट करता है और उसे लॉग करता है:

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See https://developers.google.com/workspace/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

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

जब उपयोगकर्ता डेस्कटॉप डिवाइसों पर टाइम पिकर चुनता है, तो एक ड्रॉप-डाउन मेन्यू खुलता है. इसमें, 30 मिनट के अंतराल पर समय की सूची होती है. उपयोगकर्ता इस सूची से समय चुन सकता है. उपयोगकर्ता कोई खास समय भी टाइप कर सकता है. मोबाइल डिवाइसों पर, समय चुनने वाला टूल चुनने पर, डिवाइस में पहले से मौजूद "घड़ी" का समय चुनने वाला टूल खुल जाता है.

डेस्कटॉप	मोबाइल

ग्रिड

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

ग्रिड आइटम को किसी ऐसे आइडेंटिफ़ायर के साथ कॉन्फ़िगर किया जा सकता है जो ग्रिड पर तय किए गए ऐक्शन के लिए पैरामीटर के तौर पर दिखाया जाता है.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.RECTANGLE_4_3);

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

var grid = CardService.newGrid()
  .setTitle("Recently viewed")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));

टेक्स्ट का फ़ॉर्मैट

टेक्स्ट पर आधारित कुछ विजेट, टेक्स्ट के एचटीएमएल फ़ॉर्मैट को आसानी से इस्तेमाल कर सकते हैं. इन विजेट का टेक्स्ट कॉन्टेंट सेट करते समय, सिर्फ़ उससे जुड़े एचटीएमएल टैग शामिल करें.

इस्तेमाल किए जा सकने वाले टैग और उनका मकसद, नीचे दी गई टेबल में दिखाया गया है: