日历操作

借助 Action 对象，您可以为 Google Workspace 插件构建互动行为。它们定义了当用户与插件界面中的 widget（例如按钮）互动时会发生什么。

操作通过 widget 处理函数附加到给定的 widget，该函数还定义了触发操作的条件。触发后，操作会执行指定的回调函数。系统会向回调函数传递一个事件对象，其中包含有关用户客户端互动的信息。您必须实现回调函数，并让其返回特定的响应对象。

例如，假设您想要一个按钮，当点击该按钮时，系统会构建并显示一张新卡片。为此，您必须创建一个新的按钮微件，并使用按钮微件处理程序函数 setOnClickAction(action) 设置卡片构建器 Action。您定义的 Action 用于指定在点击按钮时执行的 Apps 脚本回调函数。在这种情况下，您需要实现回调函数来构建所需的卡片，并返回 ActionResponse 对象。响应对象会告知插件显示回调函数构建的卡片。

本页介绍了您可以在插件中添加的特定于日历的小部件操作。

Google 日历互动

扩展日历的 Google Workspace 加载项可以包含其他特定于日历的 widget 操作。这些操作要求关联的操作回调函数返回专门的响应对象：

尝试执行的操作 回调函数应返回
添加参加者 CalendarEventActionResponse
设置会议数据 CalendarEventActionResponse
添加附件 CalendarEventActionResponse

如需使用这些 widget 操作和响应对象，必须满足以下所有条件：

  • 当用户打开日历活动时，系统会触发该操作。
  • Google Workspace 加载项的 addOns.calendar.currentEventAccess 清单字段设置为 WRITE 或 READ_WRITE。
  • 该插件包含 https://www.googleapis.com/auth/calendar.addons.current.event.write 日历范围。

在用户保存日历活动之前，操作回调函数所做的更改不会保存。

使用回调函数添加参与者

以下示例展示了如何创建一个按钮，用于将特定参加者添加到正在修改的日历活动中。此示例使用基本卡片结构：

/**
 * Build a basic 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();
}

使用回调函数设置会议数据

此操作会在打开的活动中设置会议数据。对于此会议数据，需要指定会议解决方案 ID，因为该操作不是由用户选择所需解决方案触发的。

以下示例展示了如何创建一个按钮，用于为正在修改的活动设置会议数据：

/**
 * Build a basic 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 basic 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 的基础设施上。如需了解详情，请参阅提供附件图标。