این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ابزارک ها

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

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

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

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

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

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

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

نمونه‌ای از کارت که ویجت‌های ساختاری را نشان می‌دهد

وقتی یک ویجت را به یکی از کانتینرها اضافه می‌کنید، یک کپی از آن ویجت ایجاد و اضافه می‌کنید. اگر ویجت را پس از افزودن تغییر دهید، این تغییر در رابط کاربری منعکس نمی‌شود. قبل از افزودن ویجت، مطمئن شوید که کامل است. اگر پس از افزودن ویجت نیاز به تغییر آن دارید، کل بخش کارت یا کارت را از نو بسازید. برای جزئیات بیشتر به Construct cards مراجعه کنید.

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

نمونه‌هایی از ویجت‌های اطلاعاتی در یک کارت

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

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

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

مثالی از منویی که عملکردهای کارت را نشان می‌دهد

نمونه‌هایی از ویجت‌های تعامل کاربر در یک کارت

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

شما می‌توانید یک ویجت DecoratedText تعریف کنید که به جای یک دکمه یا کلید دوتایی، یک چک‌باکس به آن متصل باشد. مشابه کلیدهای دوتایی، مقدار چک‌باکس در شیء رویداد action که توسط متد setOnClickAction به 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.` »	این سطر اول است. این یک خط جدید است.