ابزارک ها

ویجت یک عنصر رابط کاربری است که یک یا چند مورد از موارد زیر را ارائه می‌دهد:

  • ساختار برای سایر ابزارک‌ها مانند کارت‌ها و بخش‌ها،
  • اطلاعاتی برای کاربر مانند متن و تصاویر، یا
  • امکاناتی برای انجام عملیات مانند دکمه‌ها، فیلدهای ورودی متن یا چک‌باکس‌ها.

مجموعه ویجت‌های اضافه شده به بخش‌های کارت، رابط کاربری کلی افزونه را تعریف می‌کنند. ویجت‌ها ظاهر و عملکرد یکسانی در دستگاه‌های وب و موبایل دارند. مستندات مرجع، روش‌های مختلفی را برای ساخت مجموعه ویجت‌ها شرح می‌دهد.

انواع ویجت

ویجت‌های افزونه عموماً به سه گروه دسته‌بندی می‌شوند: ویجت‌های ساختاری، ویجت‌های اطلاعاتی و ویجت‌های تعامل با کاربر.

ابزارک‌های ساختاری

ویجت‌های ساختاری، برای سایر ویجت‌های مورد استفاده در رابط کاربری، فضا و سازماندهی فراهم می‌کنند.

  • مجموعه دکمه‌ها - مجموعه‌ای از یک یا چند دکمه متنی یا تصویری که در یک ردیف افقی گروه‌بندی شده‌اند.
  • کارت — یک کارت زمینه واحد که شامل یک یا چند بخش کارت است. شما با پیکربندی پیمایش کارت، نحوه حرکت کاربران بین کارت‌ها را تعریف می‌کنید.
  • سربرگ کارت — سربرگ یک کارت مشخص. سربرگ‌های کارت می‌توانند عنوان، زیرعنوان و تصویر داشته باشند. اگر افزونه از اقدامات کارت و اقدامات عمومی استفاده کند، در سربرگ کارت ظاهر می‌شوند.
  • بخش کارت — گروهی از ویجت‌ها که توسط یک خط‌کش افقی از سایر بخش‌های کارت جدا شده‌اند و به صورت اختیاری دارای یک سربرگ بخش هستند. هر کارت باید حداقل یک بخش کارت داشته باشد. شما نمی‌توانید کارت یا سربرگ کارت را به یک بخش کارت اضافه کنید.

ابزارک‌های ساختاری

علاوه بر این ویجت‌های ساختاری پایه، در افزونه‌ی Google Workspace می‌توانید از سرویس Card برای ایجاد ساختارهایی که با کارت فعلی همپوشانی دارند استفاده کنید: پاورقی‌های ثابت و کارت‌های Peek :

می‌توانید یک ردیف ثابت از دکمه‌ها را به پایین کارت خود اضافه کنید. این ردیف با بقیه محتوای کارت حرکت نمی‌کند یا اسکرول نمی‌شود.

مثال ابزارک پاورقی ثابت

قطعه کد زیر نحوه تعریف یک نمونه پاورقی ثابت و افزودن آن به یک کارت را نشان می‌دهد:

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

کارت پیک

مثال کارت Peek

وقتی محتوای متنی جدید توسط یک اقدام کاربر، مانند باز کردن یک پیام Gmail، فعال می‌شود، می‌توانید محتوای متنی جدید را فوراً نمایش دهید (رفتار پیش‌فرض) یا یک اعلان کارت Peek در پایین نوار کناری نمایش دهید. اگر کاربر در حالی که یک محرک متنی فعال است، روی Back کلیک کند تا به صفحه اصلی شما بازگردد، یک کارت Peek ظاهر می‌شود تا به کاربران کمک کند محتوای متنی را دوباره پیدا کنند.

برای نمایش یک کارت peek هنگام وجود محتوای متنی جدید، به جای نمایش فوری محتوای متنی جدید، .setDisplayStyle(CardService.DisplayStyle.PEEK) را به کلاس CardBuilder خود اضافه کنید. یک کارت peek فقط در صورتی ظاهر می‌شود که یک شیء کارت واحد با تریگر متنی شما برگردانده شود. در غیر این صورت، کارت‌های برگردانده شده بلافاصله جایگزین کارت فعلی می‌شوند.

برای سفارشی‌سازی هدر کارت peek، هنگام ساخت کارت متنی خود، متد .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 همچنین می‌توانند شامل یک ویجت دکمه یا سوئیچ باشند. سوئیچ‌های اضافه شده می‌توانند ضامن یا کادر انتخاب باشند. متن محتوای ویجت DecoratedText می‌تواند از قالب‌بندی HTML استفاده کند؛ برچسب‌های بالا و پایین باید از متن ساده استفاده کنند.
  • پاراگراف متنی - یک پاراگراف متنی که می‌تواند شامل عناصر قالب‌بندی شده HTML باشد.

ابزارک‌های اطلاعاتی

ابزارک‌های تعامل با کاربر

ویجت‌های تعامل کاربر به افزونه اجازه می‌دهند تا به اقدامات انجام شده توسط کاربران پاسخ دهد. می‌توانید این ویجت‌ها را با پاسخ‌های عملی پیکربندی کنید تا کارت‌های مختلف را نمایش دهند، URLها را باز کنند، اعلان‌ها را نشان دهند، پیش‌نویس ایمیل‌ها را بنویسند یا سایر عملکردهای اسکریپت برنامه‌ها را اجرا کنند. برای جزئیات بیشتر به راهنمای ساخت کارت‌های تعاملی مراجعه کنید.

  • اقدام کارت — یک آیتم منو که در منوی نوار سربرگ افزونه قرار می‌گیرد. منوی نوار سربرگ همچنین می‌تواند شامل آیتم‌هایی باشد که به عنوان اقدامات جهانی تعریف شده‌اند و در هر کارتی که افزونه تعریف می‌کند، ظاهر می‌شوند.
  • انتخابگرهای تاریخ و زمان - ویجت‌هایی که به کاربران امکان انتخاب تاریخ، زمان یا هر دو را می‌دهند. برای اطلاعات بیشتر به انتخابگرهای تاریخ و زمان در زیر مراجعه کنید.
  • دکمه تصویری — دکمه‌ای که به جای متن از تصویر استفاده می‌کند. می‌توانید از یکی از چندین آیکون از پیش تعریف شده یا یک تصویر عمومی که توسط URL آن مشخص شده است، استفاده کنید.
  • ورودی انتخاب - یک فیلد ورودی که مجموعه‌ای از گزینه‌ها را نشان می‌دهد. ویجت‌های ورودی انتخاب به صورت کادرهای انتخاب، دکمه‌های رادیویی یا کادرهای انتخاب کشویی ارائه می‌شوند.
  • سوئیچ - یک ویجت تغییر وضعیت. شما فقط می‌توانید از سوئیچ‌ها در رابطه با ویجت DecoratedText استفاده کنید. به طور پیش‌فرض، این سوئیچ‌ها به عنوان یک سوئیچ تغییر وضعیت نمایش داده می‌شوند، اما می‌توانید آنها را به عنوان یک کادر انتخاب نمایش دهید.
  • دکمه متنی — دکمه‌ای با برچسب متنی. می‌توانید برای دکمه‌های متنی، رنگ پس‌زمینه تعیین کنید (پیش‌فرض شفاف است). همچنین می‌توانید در صورت نیاز، دکمه را غیرفعال کنید.
  • ورودی متن — یک فیلد ورودی متن. ویجت می‌تواند متن عنوان، متن راهنما و متن چندخطی داشته باشد. ویجت می‌تواند هنگام تغییر مقدار متن، اقداماتی را انجام دهد.
  • شبکه‌ای - یک طرح چند ستونی که مجموعه‌ای از موارد را نشان می‌دهد. می‌توانید موارد را با تصویر، عنوان، زیرعنوان و طیف وسیعی از گزینه‌های سفارشی‌سازی مانند حاشیه و سبک‌های برش نمایش دهید.
ویجت عملکرد کارتابزارک‌های تعامل با کاربر

کادرهای انتخاب DecoratedText

شما می‌توانید یک ویجت DecoratedText تعریف کنید که به جای یک دکمه یا کلید دوتایی، یک چک‌باکس به آن متصل باشد. مانند کلیدها، مقدار چک‌باکس در شیء رویداد action قرار می‌گیرد که توسط متد setOnClickAction(action) به Action متصل به این DecoratedText ارسال می‌شود.

مثال ویجت کادر انتخاب با متن تزئین‌شده

قطعه کد زیر نحوه تعریف یک ویجت 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);
  }
}

جدول زیر نمونه‌هایی از رابط‌های کاربری انتخاب‌گر تاریخ را در دستگاه‌های دسکتاپ و موبایل نشان می‌دهد. وقتی انتخاب‌گر تاریخ را انتخاب می‌کنید، یک رابط کاربری تقویم مبتنی بر ماه باز می‌شود تا کاربر بتواند به سرعت تاریخ جدیدی را انتخاب کند.

وقتی کاربر در دستگاه‌های رومیزی، انتخابگر زمان را انتخاب می‌کند، یک منوی کشویی با لیستی از زمان‌ها که با فواصل ۳۰ دقیقه‌ای از هم جدا شده‌اند، باز می‌شود که کاربر می‌تواند از بین آنها انتخاب کند. کاربر همچنین می‌تواند یک زمان خاص را تایپ کند. در دستگاه‌های تلفن همراه، انتخابگر زمان، انتخابگر زمان «ساعت» داخلی موبایل را باز می‌کند.

دسکتاپ موبایل
مثال انتخاب انتخابگر تاریخمثال انتخاب انتخابگر تاریخ موبایل
مثال انتخاب انتخابگر زمانمثال انتخاب زمان سنج موبایل

شبکه

نمایش آیتم‌ها در یک طرح چند ستونی با ویجت شبکه. هر آیتم می‌تواند یک تصویر، عنوان و زیرنویس را نمایش دهد. از گزینه‌های پیکربندی اضافی برای تنظیم موقعیت متن نسبت به تصویر در یک آیتم شبکه‌ای استفاده کنید.

می‌توانید یک آیتم شبکه را با شناسه‌ای پیکربندی کنید که به عنوان پارامتری به اکشن تعریف شده در شبکه برگردانده می‌شود.

مثال ویجت شبکه‌ای

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>." این یک قالب زمانی است: .
نیولاین "This is the first line. <br> This is a new line. » این سطر اول است.
این یک خط جدید است.