日曆動作

Action 物件可讓您在 Google Workspace 外掛程式中建構互動式行為。可定義使用者與外掛程式 UI 中與小工具互動 (例如按鈕) 時會發生什麼事。

系統會使用小工具處理常式函式將動作附加至指定小工具，這個函式也會定義觸發動作的條件。觸發後，該動作就會執行指定的回呼函式。回呼函式會傳遞事件物件，其中含有使用者用戶端互動的相關資訊。您必須實作回呼函式，並讓函式傳回特定的回應物件。

舉例來說，假設您想要用於建構的按鈕，並在使用者點選該按鈕時顯示新資訊卡。為此，您必須建立新的按鈕小工具，並使用按鈕小工具處理常式函式 setOnClickAction(action) 來設定卡片建構 Action。您定義的 Action 會指定 Apps Script 回呼函式，在使用者按下按鈕時執行。在此情況下，您將實作回呼函式來建構所需卡片，並傳回 ActionResponse 物件。回應物件會指示外掛程式顯示建構的回呼函式的資訊卡。

本頁說明可加入外掛程式的日曆專屬小工具動作。

日曆互動情形

擴充 Google 日曆的 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(["[e-mail]", "[e-mail]"])
        .build();
  }

使用回呼函式設定會議資料

這項操作會設定開啟活動的會議資料。針對這個會議資料，必須指定會議解決方案 ID，因為使用者選取所需解決方案不會觸發動作。

以下範例說明如何建立按鈕，以便為正在編輯的活動設定會議資料：

  /**
   * 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': "[e-mail]"});
    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();
  }

設定附件圖示

附件圖示必須以 Google 的基礎架構代管。詳情請參閱「提供附件圖示」。