Etkileşimli kartlar oluşturma

Çoğu eklenti, verileri sunmanın yanı sıra kullanıcının bilgi girmesini de gerektirir. Kart tabanlı bir eklenti oluşturduğunuzda, eklentinizin ihtiyaç duyduğu verileri kullanıcıdan istemek veya başka etkileşim kontrolleri sağlamak için düğmeler, araç çubuğu menü öğeleri ya da onay kutuları gibi etkileşimli widget'lar kullanabilirsiniz.

Widget'lara işlem ekleme

Çoğu durumda, widget'ları belirli işlemlere bağlayarak ve geri çağırma işlevinde gerekli davranışı uygulayarak etkileşimli hale getirirsiniz. Ayrıntılar için eklenti işlemleri başlıklı makaleyi inceleyin.

Çoğu durumda, bir widget'ı seçildiğinde veya güncellendiğinde belirli bir işlemi yapacak şekilde yapılandırmak için şu genel prosedürü uygulayabilirsiniz:

  1. Yürütülmesi gereken geri çağırma işlevini ve gerekli parametreleri belirten bir Action nesnesi oluşturun.
  2. Uygun widget işleyici işlevini çağırarak widget'ı Action öğesine bağlayın.
  3. Gerekli davranışı etkinleştirmek için geri çağırma işlevini uygulayın.

Örnek

Aşağıdaki örnekte, tıklandıktan sonra kullanıcı bildirimi gösteren bir düğme ayarlanmaktadır. Tıklama, bildirim metnini belirten bir bağımsız değişkenle notifyUser() geri çağırma işlevini tetikler. Birleştirilmiş birim iade edildiğinde ActionResponse bildirimi gösterilir.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText))
        .build();      // Don't forget to build the response!
  }

Etkili etkileşimler tasarlama

Etkileşimli kartlar tasarlarken aşağıdakileri göz önünde bulundurun:

  • Etkileşimli widget'ların davranışlarını tanımlamak için genellikle en az bir işleyici yöntemi gerekir.

  • Bir URL'niz varsa ve bunu yalnızca sekmede açmak istiyorsanız setOpenLink() widget işleyici işlevini kullanın. Bu sayede bir Action nesnesi ve geri çağırma işlevi tanımlamanıza gerek kalmaz. Önce URL'yi oluşturmanız veya URL'yi açmadan önce başka ek adımlar atmanız gerekiyorsa Action tanımlayın ve bunun yerine setOnClickOpenLinkAction() kullanın.

  • setOpenLink() veya setOnClickOpenLinkAction() widget işleyici işlevlerini kullanırken hangi URL'nin açılacağını tanımlamak için bir OpenLink nesnesi sağlamanız gerekir. Bu nesneyi, OpenAs ve OnClose sabit listelerini kullanarak açma ve kapatma davranışını belirtmek için de kullanabilirsiniz.

  • Birden fazla widget'ın aynı Action nesnesini kullanması mümkündür. Ancak geri çağırma işlevine farklı parametreler sağlamak istiyorsanız farklı Action nesneleri tanımlamanız gerekir.

  • Geri çağırma işlevlerinizi basit tutun. Eklentilerin yanıt vermeye devam etmesini sağlamak için Card service, geri çağırma işlevlerinin yürütme süresini en fazla 30 saniye ile sınırlar. Yürütme bu süreden uzun sürerse eklenti kullanıcı arayüzünüz, Action yanıtı olarak kart gösterimini düzgün şekilde güncelleyemeyebilir .

  • Bir kullanıcının eklenti kullanıcı arayüzünüzle etkileşimi sonucunda üçüncü taraf arka uçtaki bir veri durumu değişirse mevcut istemci tarafı önbelleğin temizlenmesi için eklentinin "durum değişti" bitini true olarak ayarlaması önerilir. Daha fazla bilgi için ActionResponseBuilder.setStateChanged() yöntem açıklamasını inceleyin.