إجراءات التقويم

تتيح لك عناصر Action إنشاء سلوك تفاعلي في إضافات Google Workspace. وهي تحدّد الإجراءات التي تحدث عندما يتفاعل المستخدم مع أداة (مثل زر) في واجهة المستخدم الخاصة بالإضافة.

يتم ربط إجراء بأداة معيّنة باستخدام دالة معالجة الأدوات، والتي تحدّد أيضًا الشرط الذي يؤدي إلى تنفيذ الإجراء. عندما يتم تشغيل الإجراء، ينفّذ دالّة ردّ اتصال معيّنة. يتم تمرير عنصر حدث إلى دالة معاودة الاتصال، ويحمل هذا العنصر معلومات حول تفاعلات المستخدم من جهة العميل. يجب تنفيذ دالة معالجة النتائج وإرجاع عنصر استجابة محدّد.

على سبيل المثال، لنفترض أنّك تريد زرًا ينشئ بطاقة جديدة ويعرضها عند النقر عليه. لإجراء ذلك، عليك إنشاء أداة زر جديدة واستخدام دالة معالج أداة الزر setOnClickAction(action) لضبط Action لإنشاء البطاقات. يحدّد Action الذي تحدّده دالة رد اتصال Apps Script يتم تنفيذها عند النقر على الزر. في هذه الحالة، عليك تنفيذ دالة رد الاتصال لإنشاء البطاقة التي تريدها وعرض كائن ActionResponse. يطلب عنصر الاستجابة من الإضافة عرض البطاقة التي أنشأتها دالة رد الاتصال.

توضّح هذه الصفحة إجراءات الأدوات الخاصة بـ "تقويم Google" التي يمكنك تضمينها في الإضافة.

التفاعلات مع التقويم

يمكن أن تتضمّن إضافات Google Workspace التي توسّع نطاق "تقويم Google" بعض الإجراءات الإضافية الخاصة بأدوات "تقويم Google". تتطلّب هذه الإجراءات أن تعرض دالّة ردّ الاتصال المرتبطة بالإجراء عناصر ردّ مخصّصة:

الإجراء الذي تمت محاولة تنفيذه يجب أن تعرض دالة رد الاتصال
إضافة ضيوف CalendarEventActionResponse
ضبط بيانات المؤتمر CalendarEventActionResponse
إضافة مرفقات CalendarEventActionResponse

للاستفادة من إجراءات التطبيق المصغّر وعناصر الرد، يجب استيفاء جميع الشروط التالية:

  • يتم تفعيل الإجراء عندما يكون حدث تقويم مفتوحًا للمستخدم.
  • تم ضبط حقل addOns.calendar.currentEventAccess في ملف البيان الخاص بالإضافة على WRITE أو READ_WRITE.
  • تتضمّن الإضافة https://www.googleapis.com/auth/calendar.addons.current.event.write نطاق "تقويم Google".

بالإضافة إلى ذلك، لا يتم حفظ أي تغييرات أجرتها دالة معاودة الاتصال الخاصة بالإجراء إلا بعد أن يحفظ المستخدم حدث "تقويم Google".

إضافة ضيوف باستخدام دالة رد الاتصال

يوضّح المثال التالي كيفية إنشاء زر يضيف ضيفًا معيّنًا إلى حدث في "تقويم Google" يتم تعديله:

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

إضافة مرفقات باستخدام دالة ردّ الاتصال

يوضّح المثال التالي كيفية إنشاء زر يضيف مرفقًا إلى حدث في "تقويم Google" يتم تعديله:

  /**
   * 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 الأساسية. لمزيد من التفاصيل، يمكنك الاطّلاع على توفير رموز المرفقات.