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ştururken kullanıcıdan eklentinizin ihtiyaç duyduğu verileri 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 bölümüne bakın.

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

1. Gerekli tüm parametrelerle birlikte çalıştırılması gereken geri çağırma işlevini belirterek bir Action nesnesi oluşturun.
2. Uygun widget işleyici işlevini çağırarak widget'ı Action öğesine bağlayın.
3. Gerekli davranışı uygulamak 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 ayarlanmıştır. Tıklama, bildirim metnini belirten bir bağımsız değişkenle notifyUser() geri çağırma işlevini tetikler. Oluşturulan bir ActionResponse döndürüldüğünde bildirim 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öntemine ihtiyacı vardır.

• Bir URL'niz varsa ve bunu yalnızca bir sekmede açmak istiyorsanız setOpenLink() widget işleyici işlevini kullanın. Bu sayede Action nesnesi ve geri çağırma işlevi tanımlama ihtiyacı ortadan kalkar. Önce URL'yi oluşturmanız veya URL'yi açmadan önce başka ek adımlar uygulamanız gerekiyorsa bir 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. OpenAs ve OnClose enum'larını kullanarak açma ve kapama davranışını belirtmek için de bu nesneyi 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 duyarlı kalmasını sağlamak için Kart hizmeti, geri çağırma işlevlerini en fazla 30 saniyelik yürütme süresiyle sınırlandırır. Yürütme işlemi bundan daha uzun sürerse eklenti kullanıcı arayüzünüz, Action yanıtına göre kart görüntüsünü düzgün şekilde güncelleyemeyebilir .

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