רכיבי Widget

ווידג'ט הוא רכיב בממשק המשתמש שמספק אחת או יותר מהאפשרויות הבאות:

מבנה לווידג'טים אחרים כמו כרטיסים וקטעים,
מידע למשתמש כמו טקסט ותמונות, או
אפשרויות לפעולה כמו לחצנים, שדות להזנת טקסט או תיבות סימון.

הווידג'טים שמוסיפים לקטעי הכרטיסים מגדירים את ממשק המשתמש הכולל של התוסף. הווידג'טים נראים ומתפקדים באותו אופן גם באתרים וגם במכשירים ניידים. במאמרי העזרה מוסברות כמה שיטות ליצירת ערכות של ווידג'טים.

באופן כללי, יש שלוש קטגוריות של ווידג'טים של תוספים: ווידג'טים מבניים, ווידג'טים של מידע ווידג'טים של אינטראקציית משתמש.

ווידג'טים של מבנים

ווידג'טים מבניים מספקים מאגרי מידע וארגון לווידג'טים אחרים שמשמשים בממשק המשתמש.

קבוצת לחצנים: אוסף של לחצן אחד או יותר של טקסט או תמונה, שמקובצים בשורה אופקית.
כרטיס: כרטיס יחיד של הקשר שמכיל קטע אחד או יותר של כרטיס. כדי להגדיר איך המשתמשים עוברים בין הכרטיסים, צריך להגדיר את הניווט בין הכרטיסים.
כותרת הכרטיס: הכותרת של כרטיס מסוים. בכותרות של כרטיסים אפשר להוסיף כותרות, כותרות משנה ותמונה. פעולות בכרטיס ופעולות אוניברסליות מופיעות בכותרת של הכרטיס אם משתמשים בהן.
קטע כרטיסים: קבוצה של ווידג'טים, מופרדת מקטעים אחרים של כרטיסים על ידי קו אופקי, ויכולה לכלול כותרת. כל כרטיס צריך לכלול לפחות קטע אחד. אי אפשר להוסיף כרטיסים או כותרות של כרטיסים לקטע של כרטיסים.

דוגמה לכרטיס שמוצגים בו ווידג'טים מבניים

כשמוסיפים ווידג'ט לאחד מהקונטיינרים, נוצר עותק של הווידג'ט הזה והוא מתווסף לקונטיינר. אם משנים את הווידג'ט אחרי שמוסיפים אותו, השינוי לא משתקף בממשק. חשוב לוודא שהווידג'ט הושלם לפני שמוסיפים אותו. אם צריך לשנות ווידג'ט אחרי שמוסיפים אותו, צריך לבנות מחדש את כל קטע הכרטיס או את הכרטיס. פרטים נוספים זמינים במאמר בנושא יצירת כרטיסים.

בנוסף לווידג'טים המבניים הבסיסיים האלה, בתוסף 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, אפשר להציג את התוכן החדש לפי הקשר באופן מיידי (התנהגות ברירת המחדל) או להציג התראה בכרטיס הצצה בתחתית סרגל הצד. אם משתמש לוחץ על 'הקודם' כדי לחזור אל דף הבית בזמן שהפעלה לפי הקשר פעילה, מופיע כרטיס הצצה כדי לעזור למשתמשים למצוא שוב את התוכן ההקשרי.

כדי להציג כרטיס הצצה כשתוכן הקשרי חדש זמין, מוסיפים את .setDisplayStyle(CardService.DisplayStyle.PEEK) לכיתה CardBuilder. כרטיס הצצה מופיע רק אם מוחזר אובייקט כרטיס יחיד עם הטריגר ההקשרי. אחרת, הכרטיסים שמוחזרים מחליפים את הכרטיס הנוכחי.

כדי להתאים אישית את הכותרת של כרטיס התצוגה המקדימה, מוסיפים את השיטה .setPeekCardHeader עם אובייקט CardHeader רגיל כשיוצרים את הכרטיס ההקשרי. כברירת מחדל, הכותרת של כרטיס הצצה כוללת רק את השם של התוסף. דוגמה לכרטיס הצצה בהתאמה אישית

על סמך ההפעלה המהירה של התוסף Cats ל-Google Workspace, הקוד הבא שולח למשתמשים הודעה על תוכן חדש בהקשר באמצעות כרטיס הצצה, ומתאים אישית את הכותרת של כרטיס ההצצה כדי להציג את הנושא של שרשור ההודעות שנבחר ב-Gmail.

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);

ווידג'טים עם מידע

ווידג'טים אינפורמטיביים מציגים מידע למשתמש.

‫[Image]: תמונה שמצוינת באמצעות כתובת URL מתארחת שזמינה לכולם.
‫DecoratedText: מחרוזת של תוכן טקסט שאפשר לשלב עם רכיבים אחרים, כמו תוויות עליונות ותחתונות, תמונה או סמל. ווידג'טים מסוג DecoratedText יכולים לכלול גם ווידג'טים מסוג Button או Switch. המתגים שמוסיפים יכולים להיות מתגים רגילים או תיבות סימון. בטקסט של התוכן אפשר להשתמש בפורמט HTML, אבל בתוויות העליונה והתחתונה צריך להשתמש בטקסט פשוט.
פסקה עם טקסט: פסקה עם טקסט, שיכולה לכלול רכיבים בפורמט HTML.

דוגמאות לווידג'טים של מידע בכרטיס

ווידג'טים של אינטראקציות משתמשים

ווידג'טים של אינטראקציית משתמש מאפשרים לתוסף להגיב לפעולות של משתמשים. אפשר להגדיר את הווידג'טים האלה עם תגובות לפעולות כדי להציג כרטיסים שונים, לפתוח כתובות URL, להציג התראות, לכתוב טיוטות של אימיילים או להפעיל פונקציות אחרות של Apps Script. פרטים נוספים זמינים במדריך בנושא יצירת כרטיסים אינטראקטיביים.

‫Card action: פריט בתפריט שמוצב בסרגל הכותרת של התוסף. תפריט סרגל הכותרת יכול להכיל גם פריטים שמוגדרים כפעולות אוניברסליות, שמופיעים בכל כרטיס שהתוסף מגדיר.
רכיבי בחירת תאריך ושעה: ווידג'טים שמאפשרים למשתמשים לבחור תאריך, שעה או את שניהם. מידע נוסף זמין במאמר בנושא בחירת תאריך ושעה.
לחצן תמונה: לחצן שמוצגת בו תמונה במקום טקסט. אפשר להשתמש באחד מכמה סמלים מוגדרים מראש או בתמונה שמתארחת באופן ציבורי.
Selection input: שדה להזנת קלט שמייצג אוסף של אפשרויות. ווידג'טים של קלט בחירה מוצגים כתיבות סימון, כפתורי בחירה או תיבות בחירה בתפריט נפתח.
מתג: ווידג'ט של מתג הפעלה/השבתה שמשמש עם ווידג'ט DecoratedText. כברירת מחדל, הן מוצגות כמתג, אבל אפשר להציג אותן כתיבת סימון.
כפתור טקסט: כפתור עם תווית טקסט. מציינים צבע מילוי לרקע של לחצני טקסט (ברירת המחדל היא שקוף). אפשר גם להשבית את הלחצן לפי הצורך.
הזנת טקסט: שדה להזנת טקסט. לווידג'ט יכולים להיות טקסט של כותרת, טקסט של רמז וטקסט עם כמה שורות. הווידג'ט יכול להפעיל פעולות כשהערך של הטקסט משתנה.
רשת: פריסה עם כמה עמודות. הצגת פריטים עם תמונה, שם, כותרת משנה ואפשרויות התאמה אישית כמו סגנונות של מסגרת וחיתוך.

דוגמאות לווידג'טים של אינטראקציות משתמשים בכרטיס

תיבות סימון `DecoratedText`

אפשר להגדיר ווידג'ט DecoratedText עם תיבת סימון, במקום לחצן או מתג בינארי. בדומה למתגי הפעלה/השבתה, הערך של תיבת הסימון נכלל באובייקט של אירוע הפעולה שמועבר אל Action שמצורף אל DecoratedText באמצעות השיטה setOnClickAction.

דוגמה לווידג'ט של תיבת סימון עם טקסט מעוצב

קטע הקוד הבא מראה איך להגדיר את הווידג'ט של תיבת הסימון 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"));

הדוגמה הבאה היא של פונקציית handler של ווידג'ט לבחירת תאריך ושעה. ‫This handler formats and logs a string representing the date-time chosen by the user in a date-time picker widget with the ID 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"));

עיצוב טקסט

חלק מהווידג'טים מבוססי-הטקסט תומכים בעיצוב בסיסי של טקסט HTML. כשמגדירים את תוכן הטקסט של הווידג'טים האלה, צריך לכלול את תגי ה-HTML המתאימים.

בטבלה הבאה מוצגים התגים הנתמכים והמטרה שלהם:

פורמט	דוגמה	תוצאה שעברה עיבוד
מודגש	`"This is <b>bold</b>."`	זה מודגש.
כתב נטוי	`"This is <i>italics</i>."`	זה נטוי.
קו תחתון	`"This is <u>underline</u>."`	זה קו תחתון.
קו חוצה	`"This is <s>strikethrough</s>."`	זה ~~קו חוצה~~.
צבע גופן	`"This is <font color=\"#FF0000\">red font</font>."`	זה גופן אדום.
Hyperlink	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	זהו היפר-קישור.
שעה	`"This is a time format: <time>2023-02-16 15:00</time>."`	זהו פורמט של שעה: 2023-02-16 15:00.
שורה חדשה	`"This is the first line. <br> This is a new line.`"	זו השורה הראשונה. זו שורה חדשה.