گسترش رابط کاربری نوشتن با اقدامات نوشتن

افزونه‌های Google Workspace که Gmail را گسترش می‌دهند، علاوه بر ارائه یک رابط مبتنی بر کارت زمانی که کاربر در حال خواندن پیام Gmail است، می‌تواند هنگام نوشتن پیام‌های جدید یا پاسخ دادن به پیام‌های موجود، رابط دیگری ارائه دهد. این به افزونه‌های Google Workspace اجازه می‌دهد تا کار نوشتن ایمیل برای کاربر را خودکار کند.

دسترسی به واسط نوشتن افزونه

دو راه برای مشاهده رابط کاربری نوشتن افزونه وجود دارد. راه اول این است که در حالی که افزونه از قبل باز است شروع به نوشتن یک پیش نویس یا پاسخ دهید. راه دوم این است که هنگام نوشتن پیش نویس، افزونه را شروع کنید.

در هر صورت باعث می شود که افزونه تابع آغازگر نوشتن مربوطه را که در مانیفست افزودنی تعریف شده است، اجرا کند. تابع راه‌اندازی نوشتن، رابط کاربری نوشتن را برای آن اقدام نوشتن می‌سازد، که Gmail سپس آن را به کاربر نمایش می‌دهد.

ساخت افزونه نوشتن

با دنبال کردن این مراحل کلی می‌توانید قابلیت نوشتن را به یک افزونه اضافه کنید:

  1. فیلد gmail.composeTrigger را به مانیفست پروژه اسکریپت افزودنی اضافه کنید و دامنه‌های مانیفست را به‌روزرسانی کنید تا شامل موارد مورد نیاز برای اقدامات نوشتن شود.
  2. یک تابع راه‌انداز نوشتن را پیاده‌سازی کنید که وقتی تریگر فعال می‌شود، یک رابط کاربری نوشتن ایجاد می‌کند. توابع راه‌اندازی نوشتن یا یک شی Card یا آرایه‌ای از اشیاء Card را برمی‌گرداند که شامل رابط کاربری نوشتن برای اقدام نوشتن است.
  3. توابع مربوط به پاسخ به تماس مورد نیاز برای واکنش به تعاملات نوشتن رابط کاربر را اجرا کنید. این توابع خود عمل نوشتن نیستند (که فقط باعث ظاهر شدن رابط کاربری نوشتن می شود). بلکه، اینها توابع فردی هستند که هنگام انتخاب عناصر مختلف UI compose چه اتفاقی می‌افتد را کنترل می‌کنند. به عنوان مثال، یک کارت UI حاوی یک دکمه معمولاً دارای یک تابع تماس مرتبط است که زمانی که کاربر روی آن دکمه کلیک می‌کند، اجرا می‌شود. تابع تماس برای ویجت هایی که محتوای پیام پیش نویس را به روز می کنند باید یک شی UpdateDraftActionResponse برگرداند.

نوشتن تابع ماشه

رابط کاربری نوشتن یک افزونه به همان روشی ساخته می‌شود که رابط کاربری پیام آن افزودنی است—با استفاده از سرویس Apps Script Card برای ساخت کارت‌ها و پر کردن آنها با ویجت‌ها .

شما باید gmail.composeTrigger.selectActions[].runFunction را که در مانیفست خود تعریف می کنید، پیاده سازی کنید. تابع راه‌اندازی نوشتن باید یک شی Card یا آرایه‌ای از اشیاء Card را برگرداند که شامل رابط کاربری نوشتن برای آن عملکرد است. این توابع بسیار شبیه به توابع ماشه متنی هستند و باید کارت‌ها را به همان روش بسازند.

اشیاء رویداد ماشه را بنویسید

هنگامی که یک اقدام نوشتن انتخاب می‌شود، تابع آغازگر نوشتن مربوطه را اجرا می‌کند و تابع یک شی رویداد را به عنوان پارامتر ارسال می‌کند. شی رویداد می تواند اطلاعاتی در مورد زمینه افزودنی و پیش نویسی که برای تابع ماشه ایجاد می شود، حمل کند.

برای جزئیات در مورد نحوه چیدمان اطلاعات در شی رویداد، به ساختار شی رویداد رجوع کنید. اطلاعات موجود در شی رویداد تا حدی توسط مقدار فیلد مانیفست gmail.composeTrigger.draftAccess کنترل می شود:

  • اگر فیلد مانیفست gmail.composeTrigger.draftAccess NONE باشد یا در آن گنجانده نشده باشد، شی رویداد فقط اطلاعات حداقلی دارد.

  • اگر gmail.composeTrigger.draftAccess روی METADATA تنظیم شده باشد، شی رویدادی که به تابع آغازگر نوشتن ارسال می‌شود با لیست‌هایی از گیرندگان ایمیل در حال ایجاد پر می‌شود.

درج محتوا در پیش نویس های فعال

معمولاً یک رابط کاربری افزودنی Google Workspace گزینه‌ها و کنترل‌هایی را برای کاربر فراهم می‌کند که به نوشتن پیام کمک می‌کند. برای این موارد استفاده، هنگامی که کاربر در UI انتخاب کرد، افزونه انتخاب‌ها را تفسیر می‌کند و پیش‌نویس ایمیل کاری فعلی را بر این اساس به‌روزرسانی می‌کند.

برای آسان‌تر کردن به‌روزرسانی پیش‌نویس ایمیل فعلی، سرویس کارت با کلاس‌های زیر گسترش یافته است:

  • ContentType - فهرستی که تعیین می کند HTML قابل تغییر، HTML غیرقابل تغییر (که کاربران جیمیل نمی توانند آن را ویرایش کنند) یا محتوای متن ساده اضافه شود.
  • UpdateDraftActionResponse — نشان دهنده پاسخی به اقدامی است که پیش نویس ایمیل فعلی را به روز می کند.
  • UpdateDraftActionResponseBuilder - سازنده برای اشیاء UpdateDraftActionResponse .
  • UpdateDraftBodyAction —عملی را نشان می دهد که متن پیش نویس ایمیل فعلی را به روز می کند.
  • UpdateDraftBodyType - شماره ای که نحوه تغییر بدنه را مشخص می کند.
  • UpdateDraftSubjectAction —عملی را نشان می دهد که فیلد موضوع پیش نویس ایمیل فعلی را به روز می کند.
  • UpdateDraftToRecipientsAction —عملی را نشان می دهد که به گیرندگان ایمیل پیش نویس فعلی را به روز می کند.
  • UpdateDraftCcRecipientsAction —عملی را نشان می دهد که گیرندگان رونوشت پیش نویس ایمیل فعلی را به روز می کند.
  • UpdateDraftBccRecipientsAction —عملی را نشان می دهد که گیرندگان Bcc پیش نویس ایمیل فعلی را به روز می کند.

معمولاً یک واسط نوشتن افزودنی شامل ویجت «ذخیره» یا «درج» است که کاربر می‌تواند روی آن کلیک کند تا نشان دهد که انتخاب‌ها در رابط کاربری تمام شده است و می‌خواهد انتخاب‌هایش به ایمیلی که در حال نوشتن است اضافه شود. برای افزودن این تعامل ، ویجت باید یک شی Action مرتبط داشته باشد که به افزونه دستور می‌دهد تا وقتی روی ویجت کلیک می‌شود، یک تابع تماس خاص را اجرا کند. شما باید این توابع برگشت تماس را پیاده سازی کنید. هر تابع فراخوانی باید یک شیء ساخته شده UpdateDraftActionResponse را برگرداند که تغییراتی را که باید در پیش نویس ایمیل فعلی ایجاد شود، جزئیات می دهد.

مثال 1

قطعه کد زیر نشان می‌دهد که چگونه می‌توان یک رابط کاربری نوشتاری ایجاد کرد که موضوع را به‌روزرسانی می‌کند، و گیرندگان To، Cc، Bcc پیش‌نویس ایمیل فعلی را به‌روزرسانی می‌کند.

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