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

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

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

הקוד הבא, שמבוסס על המדריך למתחילים בנושא התוסף Cats ל-Google Workspace, מאפשר להודיע למשתמשים על תוכן חדש שמבוסס על ההקשר באמצעות כרטיס Peek, ולהתאים אישית את הכותרת של כרטיס ה-Peek כך שתציג את הנושא של שרשור ההודעות שנבחר ב-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);

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

ווידג'טים מידעיים מציגים מידע למשתמש.

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

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

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

• פעולה בכרטיס – פריט תפריט שמופיע בתפריט של סרגל הכותרת של התוסף. התפריט בסרגל הכותרת יכול לכלול גם פריטים שמוגדרים כפעולות אוניברסליות, שמופיעים בכל כרטיס שהתוסף מגדיר.
• בוררי DateTime – ווידג'טים שמאפשרים למשתמשים לבחור תאריך, שעה או את שניהם. מידע נוסף זמין בקטע בוררי תאריך ושעה שבהמשך.
• לחצן תמונה – לחצן עם תמונה במקום טקסט. אפשר להשתמש באחד מכמה סמלים מוגדרים מראש או בתמונה שמתארחת באופן ציבורי, שמצוינת באמצעות כתובת ה-URL שלה.
• Selection input – שדה קלט שמייצג אוסף של אפשרויות. ווידג'טים של קלט בחירה מופיעים בתור תיבות סימון, לחצני בחירה או תיבות בחירה נפתחות.
• Switch – ווידג'ט החלפת מצב. אפשר להשתמש במתגים רק בשילוב עם ווידג'ט DecoratedText. כברירת מחדל, האפשרויות האלה מוצגות כמתג החלפת מצב, אבל אפשר להציג אותן כתיבת סימון במקום זאת.
• לחצן טקסט – לחצן עם תווית טקסט. אפשר לציין מילוי של צבע רקע ללחצני טקסט (ברירת המחדל היא שקוף). אפשר גם להשבית את הלחצן לפי הצורך.
• קלט טקסט – שדה קלט טקסט. הווידג'ט יכול לכלול טקסט של כותרת, טקסט של רמז וטקסט עם כמה שורות. הווידג'ט יכול להפעיל פעולות כשערך הטקסט משתנה.
• Grid – פריסה עם כמה עמודות שמייצגת אוסף של פריטים. אתם יכולים לייצג פריטים באמצעות תמונה, כותרת, כותרת משנה ומגוון אפשרויות התאמה אישית, כמו סגנונות של גבולות וחיתוך.

DecoratedText תיבות סימון

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

עיצוב טקסט

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

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