Thao tác trên lịch

Các đối tượng Action cho phép bạn tạo hành vi tương tác vào tiện ích bổ sung của Google Workspace. Các hành động này xác định điều gì sẽ xảy ra khi người dùng tương tác với một tiện ích (ví dụ: nút) trong giao diện người dùng của tiện ích bổ sung.

Một thao tác được đính kèm vào một tiện ích nhất định bằng cách sử dụng hàm trình xử lý tiện ích. Hàm này cũng xác định điều kiện kích hoạt thao tác. Khi được kích hoạt, thao tác sẽ thực thi một hàm gọi lại được chỉ định. Hàm gọi lại được truyền một đối tượng sự kiện chứa thông tin về các hoạt động tương tác phía máy khách của người dùng. Bạn phải triển khai hàm gọi lại và yêu cầu hàm này trả về một đối tượng phản hồi cụ thể.

Ví dụ: giả sử bạn muốn một nút tạo và hiển thị một thẻ mới khi được nhấp vào. Để làm được điều này, bạn phải tạo một tiện ích nút mới và sử dụng hàm trình xử lý tiện ích nút setOnClickAction(action) để đặt Action tạo thẻ. Action mà bạn xác định sẽ chỉ định một hàm gọi lại Apps Script thực thi khi người dùng nhấp vào nút. Trong trường hợp này, bạn triển khai hàm gọi lại để tạo thẻ mà bạn muốn và trả về đối tượng ActionResponse. Đối tượng phản hồi sẽ yêu cầu tiện ích bổ sung hiển thị thẻ mà hàm gọi lại đã tạo.

Trang này mô tả các thao tác của tiện ích dành riêng cho Lịch mà bạn có thể đưa vào tiện ích bổ sung.

Hoạt động tương tác với Lịch

Các tiện ích bổ sung của Google Workspace mở rộng Lịch có thể bao gồm một số thao tác bổ sung dành riêng cho tiện ích Lịch. Các thao tác này yêu cầu hàm gọi lại của thao tác liên kết để trả về các đối tượng phản hồi chuyên biệt:

Đã thử thực hiện hành động Hàm gọi lại phải trả về
Thêm người tham dự CalendarEventActionResponse
Thiết lập dữ liệu hội nghị CalendarEventActionResponse
Thêm tệp đính kèm CalendarEventActionResponse

Để sử dụng các thao tác tiện ích và đối tượng phản hồi này, tất cả các điều kiện sau đây đều phải đúng:

  • Thao tác này được kích hoạt khi người dùng mở một sự kiện trên Lịch.
  • Trường tệp kê khai addOns.calendar.currentEventAccess của tiện ích bổ sung được đặt thành WRITE hoặc READ_WRITE.
  • Tiện ích bổ sung này bao gồm phạm vi Lịch https://www.googleapis.com/auth/calendar.addons.current.event.write.

Ngoài ra, mọi thay đổi do hàm gọi lại hành động thực hiện sẽ không được lưu cho đến khi người dùng lưu sự kiện Lịch.

Thêm người tham dự bằng hàm gọi lại

Ví dụ sau đây cho biết cách tạo một nút để thêm một người tham dự cụ thể vào một sự kiện trên Lịch đang được chỉnh sửa:

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

Thiết lập dữ liệu hội nghị bằng hàm gọi lại

Thao tác này sẽ đặt dữ liệu hội nghị trên sự kiện đang mở. Đối với dữ liệu hội nghị này, bạn cần chỉ định mã giải pháp hội nghị vì hành động này không phải do người dùng kích hoạt bằng cách chọn giải pháp mong muốn.

Ví dụ sau đây cho biết cách tạo một nút thiết lập dữ liệu hội nghị cho một sự kiện đang được chỉnh sửa:

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

Thêm tệp đính kèm bằng hàm gọi lại

Ví dụ sau đây cho biết cách tạo một nút để thêm tệp đính kèm vào một sự kiện Lịch đang được chỉnh sửa:

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

Đặt biểu tượng tệp đính kèm

Biểu tượng tệp đính kèm phải được lưu trữ trên cơ sở hạ tầng của Google. Hãy xem phần Cung cấp biểu tượng tệp đính kèm để biết thông tin chi tiết.