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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

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

إنشاء دالة التشغيل

تم إنشاء واجهة مستخدم لإنشاء الإضافات، بالطريقة نفسها التي تم بها إنشاء واجهة مستخدم رسائل الإضافات، وذلك باستخدام خدمة البطاقة في "برمجة تطبيقات Google" لإنشاء بطاقات وملئها بالأدوات.

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

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

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

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

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

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

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

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

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

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

عادةً ما تتضمّن واجهة مستخدم إنشاء الإضافة أداة 'Save' أو 'Insert' الأداة التي يمكن للمستخدم النقر عليها للإشارة إلى أنه تم اختياره في واجهة المستخدم ويريد أن تتم إضافة خياراته إلى الرسالة الإلكترونية التي ينشئها. لإضافة هذه التفاعل، يجب أن يكون للأداة "كائن" 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;
    }