Etkileşimli kartlar oluşturma

Çoğu eklenti, veri sunmaya ek olarak kullanıcının bilgi girmesini de gerektirir. Kart tabanlı bir eklenti derlediğinizde, 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 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ılı bilgi için eklenti işlemleri bölümünü inceleyin.

Çoğu durumda, bir widget'ı seçildiğinde veya güncellendiğinde belirli bir işlem gerçekleştirecek ş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ışı uygulamak için geri çağırma işlevini uygulayın.

Örnek

Aşağıdaki örnekte, tıklandıktan sonra bir kullanıcı bildirimi görüntüleyen bir düğme ayarlanmaktadır. Bu tıklama, bildirim metnini belirten bir bağımsız değişkenle notifyUser() geri çağırma işlevini tetikler. Yerleşik bir ActionResponse öğesinin döndürülmesi durumunda görüntülenen 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 tasarlayın

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

• Etkileşimli widget'lar, davranışlarını tanımlamak için genellikle en az bir işleyici yöntemine ihtiyaç duyar.

• URL'niz varsa ve URL'yi 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 adımlar gerçekleştirmeniz 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. Bu nesneyi OpenAs ve OnClose enum'larını 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. Kart hizmeti, eklentilerin çalışır durumda kalmasını sağlamak için geri çağırma işlevlerini maksimum 30 saniye yürütme süresiyle sınırlar. Yürütme işlemi bundan daha uzun sürerse eklentinizin kullanıcı arayüzü, Action komutuna yanıt olarak kart ekranını düzgün güncellemeyebilir .

• Üçüncü taraf arka ucundaki veri durumu, eklentinizin kullanıcı arayüzüyle kullanıcı etkileşimi sonucunda 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.