日历操作

借助 Action 对象,您可以将互动行为内置到 Google Workspace 插件中。它们定义了用户与插件界面中的微件(例如按钮)互动时发生的情况。

使用微件处理程序函数将操作附加到给定微件,该函数还定义了触发操作的条件。触发后,操作会执行指定的回调函数。系统会向回调函数传递一个对象对象,该对象包含用户的客户端互动的相关信息。您必须实现该回调函数,并使其返回特定的响应对象。

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

本页介绍了您可以在插件中包含的 Google 日历专用微件操作。

日历互动

用于扩展 Google 日历的 Google Workspace 插件还可以包含一些专门针对 Google 日历的微件操作。以下操作需要关联的操作回调函数来返回专用响应对象:

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

如需使用这些微件操作和响应对象,必须满足以下所有条件:

  • 系统会在用户打开日历活动时触发操作。
  • 插件的 addOns.calendar.currentEventAccess 清单字段设置为 WRITEREAD_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();
  }

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

此操作会针对未处理的活动设置会议数据。对于此会议数据,需要指定会议解决方案 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': "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();
  }

设置附件图标

附件图标必须托管在 Google 的基础架构上。如需了解详情,请参阅提供附件图标