اقدامات تقویم

اشیاء Action به شما امکان می‌دهند رفتار تعاملی را در افزونه‌های Google Workspace ایجاد کنید. آن‌ها تعریف می‌کنند که وقتی کاربر با یک ویجت (مثلاً یک دکمه) در رابط کاربری افزونه تعامل می‌کند، چه اتفاقی می‌افتد.

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

برای مثال، فرض کنید می‌خواهید دکمه‌ای داشته باشید که با کلیک روی آن، یک کارت جدید ساخته و نمایش داده شود. برای این کار، باید یک ویجت دکمه جدید ایجاد کنید و از تابع setOnClickAction(action) برای مدیریت ویجت دکمه استفاده کنید تا یک Action ساخت کارت تنظیم کنید. Action که تعریف می‌کنید، یک تابع فراخوانی Apps Script را مشخص می‌کند که هنگام کلیک روی دکمه اجرا می‌شود. در این حالت، شما تابع فراخوانی را برای ساخت کارت مورد نظر خود پیاده‌سازی می‌کنید و یک شیء ActionResponse برمی‌گردانید. شیء response به افزونه می‌گوید که کارتی را که تابع فراخوانی ساخته است، نمایش دهد.

این صفحه، اقدامات ویجت مخصوص تقویم را که می‌توانید در افزونه خود بگنجانید، شرح می‌دهد.

تعاملات تقویم

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

اقدام انجام شد تابع فراخوانی باید مقدار بازگشتی را برگرداند
اضافه کردن شرکت‌کنندگان CalendarEventActionResponse
تنظیم داده‌های کنفرانس CalendarEventActionResponse
افزودن پیوست‌ها CalendarEventActionResponse

برای استفاده از این اکشن‌های ویجت و اشیاء پاسخ، همه موارد زیر باید صحیح باشند:

  • این عمل زمانی آغاز می‌شود که کاربر یک رویداد تقویم را باز کرده باشد.
  • فیلد مانیفست addOns.calendar.currentEventAccess افزونه روی WRITE یا READ_WRITE تنظیم شده است.
  • این افزونه شامل محدوده تقویم https://www.googleapis.com/auth/calendar.addons.current.event.write می‌شود.

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

اضافه کردن شرکت‌کنندگان با قابلیت فراخوانی مجدد

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

  /**
   * Build a simple card with a button that sends a notification.
   * This function is called as part of the eventOpenTrigger that builds
   * a UI when the user opens an event.
   *
   * @param e The event object passed to eventOpenTrigger function.
   * @return {Card}
   */
  function buildSimpleCard(e) {
    var buttonAction = CardService.newAction()
        .setFunctionName('onAddAttendeesButtonClicked');
    var button = CardService.newTextButton()
        .setText('Add new attendee')
        .setOnClickAction(buttonAction);

    // Check the event object to determine if the user can add
    // attendees and disable the button if not.
    if (!e.calendar.capabilities.canAddAttendees) {
      button.setDisabled(true);
    }

    // ...continue creating card sections and widgets, then create a Card
    // object to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Adds attendees to the
   * Calendar event being edited.
   *
   * @param {Object} e The action event object.
   * @return {CalendarEventActionResponse}
   */
  function onAddAttendeesButtonClicked (e) {
    return CardService.newCalendarEventActionResponseBuilder()
        .addAttendees(["aiko@example.com", "malcom@example.com"])
        .build();
  }

تنظیم داده‌های کنفرانس با یک تابع فراخوانی مجدد

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

مثال زیر نحوه ایجاد دکمه‌ای را نشان می‌دهد که داده‌های کنفرانس را برای رویدادی که در حال ویرایش است، تنظیم می‌کند:

  /**
   * Build a simple card with a button that sends a notification.
   * This function is called as part of the eventOpenTrigger that builds
   * a UI when the user opens a Calendar event.
   *
   * @param e The event object passed to eventOpenTrigger function.
   * @return {Card}
   */
  function buildSimpleCard(e) {
    var buttonAction = CardService.newAction()
        .setFunctionName('onSaveConferenceOptionsButtonClicked')
        .setParameters(
          {'phone': "1555123467", 'adminEmail': "joyce@example.com"});
    var button = CardService.newTextButton()
        .setText('Add new attendee')
        .setOnClickAction(buttonAction);

    // Check the event object to determine if the user can set
    // conference data and disable the button if not.
    if (!e.calendar.capabilities.canSetConferenceData) {
      button.setDisabled(true);
    }

    // ...continue creating card sections and widgets, then create a Card
    // object to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Sets conference data for the
   * Calendar event being edited.
   *
   * @param {Object} e The action event object.
   * @return {CalendarEventActionResponse}
   */
  function onSaveConferenceOptionsButtonClicked(e) {
    var parameters = e.commonEventObject.parameters;

    // Create an entry point and a conference parameter.
    var phoneEntryPoint = ConferenceDataService.newEntryPoint()
      .setEntryPointType(ConferenceDataService.EntryPointType.PHONE)
      .setUri('tel:' + parameters['phone']);

    var adminEmailParameter = ConferenceDataService.newConferenceParameter()
        .setKey('adminEmail')
        .setValue(parameters['adminEmail']);

    // Create a conference data object to set to this Calendar event.
    var conferenceData = ConferenceDataService.newConferenceDataBuilder()
        .addEntryPoint(phoneEntryPoint)
        .addConferenceParameter(adminEmailParameter)
        .setConferenceSolutionId('myWebScheduledMeeting')
        .build();

    return CardService.newCalendarEventActionResponseBuilder()
        .setConferenceData(conferenceData)
        .build();
  }

اضافه کردن پیوست‌ها با یک تابع فراخوانی

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

  /**
   * Build a simple card with a button that creates a new attachment.
   * This function is called as part of the eventAttachmentTrigger that
   * builds a UI when the user goes through the add-attachments flow.
   *
   * @param e The event object passed to eventAttachmentTrigger function.
   * @return {Card}
   */
  function buildSimpleCard(e) {
    var buttonAction = CardService.newAction()
        .setFunctionName('onAddAttachmentButtonClicked');
    var button = CardService.newTextButton()
        .setText('Add a custom attachment')
        .setOnClickAction(buttonAction);

    // Check the event object to determine if the user can add
    // attachments and disable the button if not.
    if (!e.calendar.capabilities.canAddAttachments) {
      button.setDisabled(true);
    }

    // ...continue creating card sections and widgets, then create a Card
    // object to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Adds attachments to the Calendar
   * event being edited.
   *
   * @param {Object} e The action event object.
   * @return {CalendarEventActionResponse}
   */
  function onAddAttachmentButtonClicked(e) {
    return CardService.newCalendarEventActionResponseBuilder()
             .addAttachments([
               CardService.newAttachment()
                 .setResourceUrl("https://example.com/test")
                 .setTitle("Custom attachment")
                 .setMimeType("text/html")
                 .setIconUrl("https://example.com/test.png")
             ])
        .build();
  }

تنظیم آیکون پیوست

نماد پیوست باید در زیرساخت گوگل میزبانی شود. برای جزئیات بیشتر به «ارائه نمادهای پیوست» مراجعه کنید.