ווידג'טים

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

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

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

סוגי ווידג'טים

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

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

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

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

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

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

הערה: כרטיסי הצצה לא מופיעים באפליקציות לנייד.

הקוד הבא, המבוסס על המדריך למתחילים של Google Workspace ל-Cats, מספק התראות למשתמשים על תוכן חדש לפי הקשר באמצעות כרטיס הצצה, ומתאים אישית את הכותרת של כרטיס ההצצה כך שהנושא של שרשור ההודעה שנבחר ב-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 – מחרוזת של תוכן טקסט, שאפשר להתאים לרכיבים אחרים, כמו תוויות של טקסט עליון או תחתון ותמונה או סמל. ווידג'טים מסוג DesignatedText יכולים לכלול גם ווידג'ט button או Switch. אפשר להוסיף מתגים או תיבות סימון. טקסט התוכן של הווידג'ט DesignatedText יכול להשתמש בעיצוב HTML. התוויות העליונה והתחתונה חייבות להשתמש בטקסט פשוט.
• פסקה בטקסט - פסקת טקסט, שיכולה לכלול רכיבים בפורמט HTML.

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

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

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

DecoratedText תיבות סימון

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

בקטע הקוד הבא מוסבר איך להגדיר בוחר של תאריכים בלבד, בוחר של שעה בלבד ובורר של תאריך ושעה, שאותם תוכלו להוסיף לכרטיס:

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 של ווידג'ט לבחירת תאריך ושעה. ה-handler הזה מעצב ומתעד מחרוזת שמייצגת את השעה שנבחרה על ידי המשתמש בווידג'ט של בוחר התאריכים, עם המזהה "myDateTime PickerWidgetID":

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/apps-script/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 דקות שמתוכם המשתמש יכול לבחור. המשתמש יכול גם להקליד שעה ספציפית. במכשירים ניידים, כשלוחצים על בורר השעה, נפתח בוחר השעה המובנה בנייד.

מחשב	נייד

מזהה GRid

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

אפשר להגדיר פריט ברשת עם מזהה שמוחזר כפרמטר לפעולה שהוגדרה ברשת.

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>."	זהו גופן אדום.
היפר-קישור	"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. אינץ'	זו השורה הראשונה. זוהי שורה חדשה.