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

Gmail'i genişleten Google Workspace Eklentileri, kullanıcılar Gmail iletilerini okurken kart tabanlı bir arayüz sağlamanın yanı sıra yeni mesajlar oluştururken veya mevcut mesajları yanıtlarken başka bir arayüz de sağlayabilir. Bu işlem, Google Workspace Eklentilerinin kullanıcı için e-posta oluşturma görevini otomatik hale getirmesini sağlar.

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

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

Her iki durum da eklentinin, eklenti manifest dosyasında tanımlanan ilgili oluşturma tetikleyici işlevini yürütmesine neden olur. Oluşturma tetikleyicisi işlevi, söz konusu oluşturma işlemi için oluşturma kullanıcı arayüzünü oluşturur ve Gmail'in bu arayüzü 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. Eklenti komut dosyası projesi manifest'ine gmail.composeTrigger alanını ekleyin ve manifest kapsamlarını, oluşturma işlemleri için gerekli olanları içerecek şekilde güncelleyin.
  2. Tetikleyici etkinleştiğinde oluşturma kullanıcı arayüzü oluşturan bir oluşturma tetikleyicisi işlevi uygulayın. Oluşturma tetikleyicisi işlevleri, tek bir Card nesnesi veya oluşturma işleminin oluşturma kullanıcı arayüzünü oluşturan bir Card nesne dizisi döndürür.
  3. Kullanıcının oluşturulan kullanıcı arayüzü etkileşimlerine 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). Bunlar, oluşturma kullanıcı arayüzünün farklı öğeleri seçildiğinde ne olacağını yöneten bağımsız işlevlerdir. Örneğin, bir düğme içeren kullanıcı arayüzü kartında genellikle bir kullanıcı bu düğmeyi tıkladığında yürütülen ilişkili bir geri çağırma işlevi bulunur. Taslak mesaj içeriğini güncelleyen widget'ların geri çağırma işlevi bir UpdateDraftActionResponse nesnesi döndürmelidir.

Tetikleyici işlevi oluştur

Eklentilerin oluşturma kullanıcı arayüzü, eklentinin mesaj kullanıcı arayüzüyle aynı şekilde oluşturulur. Bu arayüzde, kartlar oluşturmak ve bunları widget'larla doldurmak için Apps Komut Dosyası Kart hizmeti kullanılır.

Manifest'inizde tanımladığınız gmail.composeTrigger.selectActions[].runFunction öğesini uygulamanız gerekir. Oluşturma tetikleyicisi işlevi, tek bir Card nesnesi veya söz konusu işlemin oluşturma kullanıcı arayüzünü oluşturan bir Card nesne dizisi 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 tetikleyicisi işlevini yürütür ve işlevi parametre olarak bir etkinlik nesnesi iletir. Etkinlik nesnesi, eklenti bağlamı ve oluşturulan taslakla ilgili bilgileri tetikleyici işlevine taşıyabilir.

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

Etkin taslaklara içerik ekleme

Genellikle, Google Workspace eklentisi oluşturma kullanıcı arayüzü, mesaj oluşturmaya yardımcı olacak kullanıcı seçenekleri ve denetimleri 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ışan e-posta taslağını uygun şekilde günceller.

Mevcut taslak e-postayı güncellemeyi kolaylaştırmak için Kart hizmetinin kapsamı 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 işlemlerini tamamladığını belirtmek ve seçtiklerinin oluşturdukları e-postaya eklenmesini belirtmek üzere tıklayabilecekleri bir "Kaydet" veya "Ekle" widget'ı bulunur. Bu etkileşimi eklemek için widget'ın, eklenti tıklandığında belirli bir geri çağırma işlevini çalıştırmasını bildiren ilişkilendirilmiş bir Action nesnesinin olması gerekir. Bu geri çağırma işlevlerini uygulamanız gerekir. Her geri çağırma işlevi, mevcut taslak e-postada yapılacak değişiklikleri ayrıntılı olarak gösteren bir UpdateDraftActionResponse nesnesi döndürmelidir.

1. Örnek

Aşağıdaki kod snippet'inde, konuyu güncelleyen ve mevcut e-posta taslağının Cc, Bcc alıcılarını güncelleyen bir oluşturma 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 taslak e-postaya 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;
    }