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

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

Google Workspace eklentisi oluşturma kullanıcı arayüzüne erişme

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

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

E-posta oluşturma eklentisi oluşturma

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

  1. gmail.composeTrigger alanını eklenti komut dosyası projesinin manifest dosyasına ekleyin ve manifest kapsamlarını, oluşturma işlemleri için gerekenleri içerecek şekilde güncelleyin.
  2. Tetikleyici tetiklendiğinde oluşturma kullanıcı arayüzü oluşturan bir oluşturma tetikleyici işlevi uygulayın. Oluşturma tetikleyici işlevleri, oluşturma işlemi için oluşturma kullanıcı arayüzünü oluşturan tek bir Card nesnesi veya Card nesneleri dizisi döndürür.
  3. Kullanıcının Compose kullanıcı arayüzü etkileşimlerine yanıt vermek için gereken ilişkili geri çağırma işlevlerini uygulayın. Bu işlevler, yalnızca oluşturma kullanıcı arayüzünün görünmesine neden olan oluşturma işlemi değildir. 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, düğme içeren bir kullanıcı arayüzü kartında genellikle kullanıcı bu 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

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

Manifest dosyanızda tanımladığınız gmail.composeTrigger.selectActions[].runFunction uygulamanız gerekir. Oluşturma tetikleyici işlevi, söz konusu işlem için oluşturma kullanıcı arayüzünü oluşturan tek bir Card nesnesi veya Card nesneleri dizisi döndürmelidir. Bu işlevler, bağlamsal tetikleyici işlevlere ç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şlev, parametre olarak bir etkinlik nesnesi geçirir. Etkinlik nesnesi, eklenti bağlamı ve oluşturulan taslakla ilgili bilgileri tetikleyici işleve taşıyabilir.

Bilgilerin etkinlik nesnesinde nasıl düzenlendiğiyle ilgili ayrıntılar için Etkinlik nesnesi yapısı başlıklı makaleyi inceleyin. Etkinlik nesnesinde yer alan bilgiler, gmail.composeTrigger.draftAccess manifest alanı değerine göre kısmen kontrol edilir:

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

  • gmail.composeTrigger.draftAccess METADATA olarak ayarlanırsa oluşturma tetikleyici işlevine iletilen etkinlik nesnesi, oluşturulan e-postanın alıcılarının listeleriyle doldurulur. METADATA taslak erişiminin kullanılması için eklenti manifestinin https://www.googleapis.com/auth/gmail.addons.current.message.metadata Gmail kapsamını içermesi gerekir.

Etkin taslaklara içerik ekleme

Genellikle bir eklenti oluşturma kullanıcı arayüzü, kullanıcılara mesaj oluşturmaya yardımcı olan seçenekler ve kontrol sunar. Bu kullanım alanlarında, kullanıcı arayüzünde seçim yaptıktan sonra eklenti bu seçimleri yorumlar ve mevcut e-posta taslağını buna göre günceller.

Mevcut taslak e-postanın güncellenmesini kolaylaştırmak için Card service aşağıdaki sınıflarla genişletildi:

Genellikle bir eklenti oluşturma kullanıcı arayüzünde, kullanıcının kullanıcı arayüzünde seçim yapmayı bitirdiğini ve seçimlerinin oluşturduğ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 eklentinin belirli bir geri çağırma işlevini çalıştırmasını sağlayan 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 yerleşik bir UpdateDraftActionResponse nesnesi döndürmelidir.

1. Örnek

Aşağıdaki kod snippet'inde, mevcut e-posta taslağının konusunu, alıcılarını (Kime, Cc ve Bcc) güncelleyen bir Compose 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 taslak e-postaya resim ekleyen bir Compose 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;
}