Oluşturma işlemleriyle oluşturma kullanıcı arayüzünü genişletme

Gmail'i genişleten Google Workspace eklentileri, kullanıcı bir Gmail iletisini okurken kart tabanlı bir arayüz sağlamanın yanı sıra kullanıcı yeni iletiler oluştururken veya mevcut iletileri yanıtlarken başka bir arayüz de sağlayabilir. Bu sayede Google Workspace eklentileri, kullanıcı için e-posta oluşturma görevini otomatikleştirebilir.

Eklenti oluşturma kullanıcı arayüzüne erişme

Eklentilerin oluşturma kullanıcı arayüzünü görüntülemenin iki yolu vardır. İlk yöntem, eklenti açıkken yeni bir taslak veya yanıt oluşturmaya başlamaktır. İkinci yöntem, taslak oluştururken eklentiyi başlatmaktır.

Her iki durumda da eklenti, eklenti manifestinde tanımlanan ilgili kompozit tetikleyici işlevini yürütür. Oluşturma tetikleyici işlevi, ilgili oluşturma işlemi için oluşturma kullanıcı arayüzünü oluşturur. Gmail bu kullanıcı arayüzünü kullanıcıya gösterir.

Oluşturma eklentisi oluşturma

Aşağıdaki genel adımları uygulayarak bir eklentiye oluşturma işlevi ekleyebilirsiniz:

  1. gmail.composeTrigger alanını eklenti komut dosyası projesinin manifest dosyasına ekleyin ve oluşturma işlemleri için gerekenleri içerecek şekilde manifest kapsamlarını güncelleyin.
  2. Tetikleyici etkinleştiğinde bir oluşturma kullanıcı arayüzü oluşturan bir oluşturma tetikleyici işlevi uygulayın. Oluşturma tetikleyici işlevleri, tek bir Card nesnesi veya oluşturma işleminin oluşturma kullanıcı arayüzünü içeren bir Card nesnesi dizisi döndürür.
  3. Kullanıcının kullanıcı arayüzü etkileşimlerini oluşturmasına tepki vermek için gereken ilişkili geri çağırma işlevlerini uygulayın. Bu işlevler, oluşturma işleminin kendisi değildir (yalnızca oluşturma kullanıcı arayüzünün görünmesine neden olur). Bunun yerine, oluşturma kullanıcı arayüzünün farklı öğeleri seçildiğinde ne olacağını yöneten ayrı işlevlerdir. Örneğin, bir düğme içeren kullanıcı arayüzü kartında genellikle kullanıcı düğmeyi tıkladığında yürütülen ilişkili bir geri çağırma işlevi bulunur. Taslak ileti içeriğini güncelleyen widget'ların geri çağırma işlevi bir UpdateDraftActionResponse nesnesi döndürmelidir.

Tetikleyici işlevi oluşturma

Eklentinin oluşturma kullanıcı arayüzü, kartları oluşturmak ve widget'larla doldurmak için Apps Script kart hizmeti kullanılarak eklentinin mesaj kullanıcı arayüzüyle aynı şekilde oluşturulur.

Manifest dosyanızda tanımladığınız gmail.composeTrigger.selectActions[].runFunction değerini uygulamanız gerekir. Oluşturma tetikleyici işlevi, söz konusu işlem için oluşturma kullanıcı arayüzünü içeren tek bir Card nesnesi veya Card nesne dizisini döndürmelidir. Bu işlevler bağlamsal tetikleyici işlevlerine çok benzer ve kartları aynı şekilde oluşturmalıdır.

Tetikleyici etkinlik nesneleri oluşturma

Bir oluşturma işlemi seçildiğinde, ilgili oluşturma tetikleyici işlevi yürütülür ve işleve parametre olarak bir etkinlik nesnesi iletilir. Etkinlik nesnesi, eklenti bağlamı ve tetikleyici işlevinde oluşturulan taslak hakkında bilgi taşıyabilir.

Bilgilerin etkinlik nesnesinde nasıl düzenlendiğiyle ilgili ayrıntılar için Etkinlik nesnesi yapısı bölümüne bakın. Etkinlik nesnesinde bulunan bilgiler kısmen gmail.composeTrigger.draftAccess manifest alanının değeri tarafından kontrol edilir:

  • gmail.composeTrigger.draftAccess manifest alanı NONE ise veya dahil edilmemişse etkinlik nesnesi yalnızca minimum düzeyde bilgi içerir.

  • gmail.composeTrigger.draftAccess METADATA olarak ayarlanırsa, oluşturma tetikleyici işlevine iletilen etkinlik nesnesi, oluşturulmakta olan e-postanın alıcılarının listeleriyle doldurulur.

Etkin taslaklara içerik ekleme

Genellikle Google Workspace eklentisi oluşturma kullanıcı arayüzü, ileti oluşturmaya yardımcı olan kullanıcı seçeneklerini ve denetimlerini sağlar. Bu kullanım alanlarında, kullanıcı kullanıcı arayüzünde seçim yaptıktan sonra eklenti, seçimleri yorumlar ve mevcut çalışma e-posta taslağını buna göre günceller.

Mevcut taslak e-postayı güncellemeyi kolaylaştırmak için Kart hizmeti aşağıdaki sınıflarla genişletildi:

Eklenti oluşturma kullanıcı arayüzünde genellikle kullanıcının kullanıcı arayüzünde seçim yapmayı tamamladığını ve seçimlerinin oluşturmakta olduğu e-postaya eklenmesini istediğini belirtmek için tıklayabileceği bir "Kaydet" veya "Ekle" widget'ı bulunur. Bu etkileşimi eklemek için widget'ta, widget tıklandığında eklentiye belirli bir geri çağırma işlevi çalıştırması talimatını veren ilişkili bir Action nesnesi olmalıdır. Bu geri arama işlevlerini uygulamanız gerekir. Her geri çağırma işlevi, mevcut taslak e-postada yapılacak değişiklikleri ayrıntılı olarak açıklayan bir UpdateDraftActionResponse nesnesi döndürmelidir.

1. Örnek

Aşağıdaki kod snippet'inde, mevcut e-posta taslağının konusunu ve Alıcı, CC, BCC alıcılarını güncelleyen bir oluşturma kullanıcı arayüzünün nasıl oluşturulacağı gösterilmektedir.

    /**
     * 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. Örnek

Aşağıdaki kod snippet'inde, mevcut e-posta taslağına resim ekleyen bir oluşturma kullanıcı arayüzünün nasıl oluşturulacağı gösterilmektedir.

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