Etkileşimli kartlar oluşturma

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

Widget'lara işlem ekleme

Çoğunlukla, widget'ları belirli işlemlere bağlayarak ve gerekli davranışı bir geri çağırma işlevinde 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şlemi gerçekleştirecek şekilde yapılandırmak için şu genel prosedürü uygulayabilirsiniz:

1. Gerekli parametrelerle birlikte yürütülmesi 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örüntüleyen bir düğme ayarlanmaktadır. Tıklama, bildirim metnini belirten bir bağımsız değişkenle notifyUser() geri çağırma işlevini tetikler. Yerleşik bir ActionResponse döndürüldüğünde bir 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 ihtiyaç 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, Action nesnesi ve geri çağırma işlevi tanımlama ihtiyacını önler. Önce URL'yi oluşturmanız veya URL'yi açmadan önce başka ek adımlar atmanız gerekiyorsa bunun yerine bir Action tanımlayın ve 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 numaralandırmalarını kullanarak açılış ve kapanış davranışını belirtmek için de kullanabilirsiniz.

• Aynı Action nesnesini birden fazla widget kullanabilir. Ancak geri çağırma işlevi için farklı parametreler sağlamak isterseniz 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 maksimum 30 saniyelik yürütme süresiyle sınırlandırır. Yürütme işlemi daha uzun sürerse eklenti kullanıcı arayüzünüz Action'e yanıt olarak kart görüntüsünü düzgün bir şekilde güncellemeyebilir .

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