توسيع واجهة مستخدم الإنشاء باستخدام إجراءات الإنشاء

بالإضافة إلى توفير واجهة تستنِد إلى البطاقة عند قراءة المستخدِم لرسالة Gmail أو إضافات Google Workspace التي توسِّع Gmail توفير واجهة أخرى عند إنشاء المستخدم لرسائل جديدة أو الرد على التعليقات الحالية. يتيح ذلك لإضافات Google Workspace تنفيذ مهمة إنشاء الرسائل الإلكترونية للمستخدم تلقائيًا.

الوصول إلى واجهة مستخدم إنشاء الإضافة

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

تتسبب أي من الحالتين في تنفيذ الإضافة للإجراء إنشاء دالة المشغِّل، المحددة في الإضافة البيان. تقوم دالة مشغل الإنشاء بإنشاء واجهة مستخدم الإنشاء لهذا الإنشاء الإجراء، الذي يعرضه Gmail بعد ذلك للمستخدم.

إنشاء إضافة إنشاء

يمكنك إضافة وظيفة إنشاء إلى إضافة من خلال اتباع الخطوات العامة التالية:

1. إضافة gmail.composeTrigger إلى مشروع النص البرمجي للإضافة البيان وتعديل البيان النطاقات لتضمينها تلك المطلوبة لإجراءات الإنشاء.
2. يمكنك تنفيذ دالة تشغيل الإنشاء التي تنشئ واجهة مستخدم للإنشاء عند حرائق الغابات. ترجع دوال مشغل الإنشاء إما قيمة Card أو مصفوفة من كائنات Card التي تضم واجهة مستخدم الإنشاء لإجراء الإنشاء.
3. تنفيذ وظائف معاودة الاتصال المرتبطة اللازمة للتفاعل مع طلبات المستخدمين لإنشاء تفاعلات واجهة المستخدم. هذه الدوال ليست إجراء الإنشاء نفسه (مما يؤدي فقط إلى ظهور واجهة مستخدم الإنشاء)؛ بل هي الدوال الفردية التي تحكم ما يحدث عندما تكون هناك عناصر مختلفة إنشاء واجهة المستخدم. على سبيل المثال، بطاقة واجهة مستخدم تحتوي على زر عادةً ما تتضمن وظيفة استدعاء مرتبطة يتم تنفيذها عندما ينقر المستخدم على هذا الزر. وظيفة معاودة الاتصال للتطبيقات المصغّرة التي تعدِّل مسودة الرسالة يجب أن يعرض المحتوى UpdateDraftActionResponse الخاص بك.

إنشاء دالة المشغِّل

تم إنشاء واجهة مستخدم إنشاء الإضافة بنفس طريقة إنشاء رسالة الإضافة واجهة المستخدم - باستخدام خدمة بطاقة برمجة التطبيقات لإنشاء البطاقات واملأها التطبيقات المصغّرة:

يجب تنفيذ gmail.composeTrigger.selectActions[].runFunction التي تحددها في بيانك. يجب أن يتم إرجاع دالة إنشاء إما كائن Card واحد أو مصفوفة من عناصر Card التي تشكل واجهة المستخدم الخاصة بالإنشاء لهذا الإجراء. هذه الدوال متشابهة جدًا إلى دوال التشغيل السياقية ويجب إنشاء بطاقات بنفس الطريقة.

تحذير: لأسباب أمنية، يمكن للإضافات لا يمكن تغيير Google Workspace أو جهة خارجية تلقائيًا أذونات الوصول إلى الملفات. على سبيل المثال، لا يمكن لإحدى الإضافات أن يتم كتم صوتها إضافة مستلمي البريد الإلكتروني إلى مجموعة الحسابات التي يمكنها عرض ملف Dropbox. وبدلاً من ذلك، يجب أن تُعلِم الإضافة المستخدمين بأنّ تغيير الإذن قيد الحدوث. لا يمكن للإضافات التي لا تُعلم المستخدمين بمثل هذه التغييرات أن تمر مراجعة الإضافات

إنشاء كائنات أحداث المشغل

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

الاطّلاع على بنية كائن الحدث للحصول على تفاصيل حول كيفية ترتيب المعلومات في كائن الحدث. المعلومات الموجودة في كائن الحدث يتم التحكم فيها جزئيًا من خلال قيمة gmail.composeTrigger.draftAccess حقل البيان:

• إذا كانت gmail.composeTrigger.draftAccess حقل البيان هو NONE أو لم يتم تضمينه، فكائن الحدث يحتوي على الحد الأدنى من المعلومات.

• في حال gmail.composeTrigger.draftAccess يتم ضبطه على METADATA، وهو كائن الحدث الذي تم تمريره إلى دالة مشغِّل الإنشاء تتم تعبئته بقوائم مستلمي الرسالة الإلكترونية التي يتم إنشاؤها.

ملاحظة: لاستخدام إذن الوصول إلى مسودة METADATA، يجب أن يتضمن بيان الإضافة https://www.googleapis.com/auth/gmail.addons.current.message.metadata نطاق Gmail

إدراج المحتوى في المسودات النشطة

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

لتسهيل تعديل مسودة الرسالة الإلكترونية الحالية، تستخدم خدمة البطاقات. تم توسيعها لتشمل الفئات التالية:

• ContentType— تعداد يحدد ما إذا كان سيتم إضافة HTML قابل للتغيير وHTML غير قابل للتغيير (التي لا يمكن للمستخدمين تعديله)، أو محتوى بنص عادي.
• UpdateDraftActionResponse: لتمثيل ردّ على إجراء يعدِّل مسودة الرسالة الإلكترونية الحالية.
• UpdateDraftActionResponseBuilder: أ أداة إنشاء UpdateDraftActionResponse الأخرى.
• UpdateDraftBodyAction: لتمثيل إجراء يعدّل نص مسودة الرسالة الإلكترونية الحالية.
• UpdateDraftBodyType— التعداد الذي يحدد كيفية تغير الجسم.
• UpdateDraftSubjectAction: لتمثيل إجراء يعدِّل حقل الموضوع لمسودة الرسالة الإلكترونية الحالية.
• UpdateDraftToRecipientsAction: لتمثيل إجراء يؤدي إلى تعديل الحقل "إلى" في مسودة الرسالة الإلكترونية الحالية.
• UpdateDraftCcRecipientsAction: لتمثيل إجراء يعدِّل مستلمي "نسخة إلى" لمسودة الرسالة الإلكترونية الحالية.
• UpdateDraftBccRecipientsAction: لتمثيل إجراء يعدِّل مستلمي "نسخة مخفية الوجهة" لمسودة الرسالة الإلكترونية الحالية.

عادةً ما تتضمن واجهة مستخدم إنشاء الإضافة الزر "حفظ" أو "إدراج" أداة يمكن للمستخدم النقر للإشارة إلى أنهم قد اتخذوا التحديدات في واجهة المستخدم ويريدون الخيارات لإضافتها إلى رسالة البريد الإلكتروني التي ينشئونها. لإضافة هذا interactivity، يجب أن يعرض التطبيق المصغّر كائن Action مرتبط يوجه الإضافة إلى تشغيل دالة رد اتصال محددة عندما يتم النقر عليه. يجب تنفيذ دوال معاودة الاتصال هذه. يجب أن تكون كل دالة استدعاء وإرجاع UpdateDraftActionResponse يوضح بالتفصيل التغييرات التي يجب إجراؤها على مسودة الرسالة الإلكترونية الحالية.

مثال 1

يوضح مقتطف الرمز التالي كيفية إنشاء واجهة مستخدم إنشاء تعمل على تحديث الموضوع، ومستلمي "إلى: نسخة مخفية الوجهة" من مسودة الرسالة الإلكترونية الحالية.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

مثال 2

يوضح مقتطف الرمز التالي كيفية إنشاء واجهة مستخدم للإنشاء تُدرِج صورًا. في مسودة رسالة البريد الإلكتروني الحالية.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }