Eklenti işlemleri

Eklenti işlemleri, widget'lara etkileşimli davranışlar sağlar. Bir işlem oluşturarak kullanıcının bir widget'ı seçtiğinde veya güncellediğinde ne olacağını tanımlarsınız.

Çoğu durumda, Apps Komut Dosyası Card hizmeti tarafından sağlanan Action nesnelerini kullanarak eklenti işlemlerini tanımlayabilirsiniz. Her Action, oluşturulduğunda bir geri çağırma işleviyle ilişkilendirilir. Kullanıcı widget'la etkileşimde bulunduğunda belirli adımları uygulamak için geri çağırma işlevini uygularsınız. Ayrıca, Action öğesini, Action geri çağırmasını tetikleyen etkileşim türünü tanımlayan uygun bir widget işleyici işlevi kullanarak widget'a bağlamanız gerekir.

Action içeren bir widget'ı şu genel işlemi kullanarak yapılandırın:

1. Action nesnesini oluşturun. Bu nesnenin, gerektirdiği parametrelerle birlikte yürütmesi gereken geri çağırma işlevini belirtin.
2. Action nesnesini kullanarak widget'ta uygun widget işleyici işlevini çağırın.
3. Gerekli davranışı etkinleştirmek için geri çağırma işlevini uygulayın.

Not: Action nesnelerini CardAction nesneleriyle karıştırmayın. CardAction nesneleri kart üstbilgisi menü öğeleridir. Action nesneleri ise kullanıcı arayüzüyle etkileşimlere verilen yanıtları tanımlar.

Widget işleyici işlevleri

Bir widget'ı belirli bir Action veya başka bir davranışa bağlamak için widget işleyici işlevini kullanırsınız. İşleyici işlevi, hangi etkileşim türünün (örneğin, widget'ı tıklama veya metin alanını düzenleme) işlem davranışını tetiklediğini belirler. İşleyici işlevi, işlem tamamlandıktan sonra kullanıcı arayüzünün hangi adımları uygulayacağını da (varsa) tanımlar.

Aşağıdaki tabloda, widget'lar için farklı işleyici türleri ve hangi widget'larla kullanıldıkları listelenmiştir:

İşleyici işlevi	İşlemi tetikler	Geçerli widget'lar	Açıklama
setOnChangeAction()	Widget değeri değiştiğinde	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	Kullanıcı bir girişe metin girip Enter tuşuna bastığında olduğu gibi, widget odak kaybedince Apps Komut Dosyası işlevini yürüten bir Action ayarlar. İşleyici, çağırdığı işleve otomatik olarak bir etkinlik nesnesi iletir. Seçilirse bu etkinlik nesnesine ek parametre bilgileri ekleyebilirsiniz.
setOnClickAction()	Kullanıcı widget'ı tıkladığında	CardAction Image ImageButton DecoratedText TextButton	Kullanıcı widget'ı tıkladığında bir Apps Komut Dosyası işlevini yürüten Action ayarlar. İşleyici, çağırdığı işleve otomatik olarak bir etkinlik nesnesi iletir. Bu etkinlik nesnesine isteğe bağlı parametre bilgileri ekleyebilirsiniz.
setComposeAction()	Kullanıcı widget'ı tıkladığında	CardAction Image ImageButton DecoratedText TextButton	Gmail'e özel. Bir e-posta taslağı oluşturan ve bu taslağı Gmail kullanıcı arayüzü yazma penceresinde kullanıcıya sunan bir Action ayarlar. Taslağı yeni bir ileti olarak veya Gmail'de açık olan iletiye yanıt olarak oluşturabilirsiniz. İşleyici, taslak oluşturma geri çağırma işlevini çağırdığında geri çağırma işlevine bir event object (olay nesnesi) iletir. Daha fazla bilgi için Taslak mesaj oluşturma bölümüne bakın.
setOnClickOpenLinkAction()	Kullanıcı widget'ı tıkladığında	CardAction Image ImageButton DecoratedText TextButton	Kullanıcı widget'ı tıkladığında bir URL'nin açılması için Action ayarlar. URL'yi oluşturmanız gerektiğinde veya bağlantı açılmadan önce başka işlemlerin yapılması gerektiğinde bu işleyiciyi kullanın. Aksi takdirde, genellikle setOpenLink() öğesini kullanmak daha basittir. URL'yi yalnızca yeni bir pencerede açabilirsiniz. Kapatıldığında, kullanıcı arayüzünün eklentiyi yeniden yüklemesine neden olabilirsiniz.
setOpenLink()	Kullanıcı widget'ı tıkladığında	CardAction Image ImageButton DecoratedText TextButton	Kullanıcı widget'ı tıkladığında doğrudan bir URL açar. URL'yi biliyorsanız ve yalnızca açmanız gerekiyorsa bu işleyiciyi kullanın. Aksi takdirde setOnClickOpenLinkAction() işleyicisini kullanın. URL'yi yeni bir pencerede veya yer paylaşımında açabilirsiniz. Kapatıldığında, kullanıcı arayüzünün eklentiyi yeniden yüklemesine neden olabilirsiniz.
setSuggestionsAction()	Kullanıcı bir girişe metin girer	TextInput	Kullanıcı bir metin girişi widget'ına metin girdiğinde bir Apps Komut Dosyası işlevini yürüten Action ayarlar. İşleyici, çağırdığı işleve otomatik olarak bir etkinlik nesnesi iletir. Daha fazla bilgi için Metin girişleri için otomatik tamamlama önerileri başlıklı makaleyi inceleyin.

Geri çağırma işlevleri

Geri çağırma işlevleri, bir Action tetiklendiğinde yürütülür. Geri çağırma işlevleri Apps Komut Dosyası işlevleri olduğundan, diğer komut dosyası işlevlerinin yapabildiği hemen hemen her şeyi yapabilirler.

Uyarı: Apps Script Card hizmeti 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.

Geri çağırma işlevi bazen belirli bir yanıt nesnesi döndürür. Bu tür yanıtlar, geri çağırma işlemi tamamlandıktan sonra yapılması gereken ek işlemleri (ör. yeni bir kart görüntüleme veya otomatik tamamlama önerileri sunma) gösterir. Geri çağırma işlevinizin belirli bir yanıt nesnesi döndürmesi gerektiğinde, bu nesneyi oluşturmak için Card service içinde bir oluşturucu sınıfı kullanırsınız.

Aşağıdaki tabloda, geri çağırma işlevlerinizin belirli işlemler için ne zaman belirli bir yanıt nesnesi döndürmesi gerektiği gösterilmektedir. Bu işlemlerin tümü, eklentinin genişlettiği belirli ana makine uygulamasından bağımsızdır:

İşlem denendi	Geri çağırma işlevi döndürmelidir
Kartlar arasında gezinme	ActionResponse
Notification görüntüleme	ActionResponse
setOnClickOpenLinkAction() kullanarak bağlantı açma	ActionResponse
Otomatik tamamlama önerilerini görüntüleme	SuggestionResponse
Evrensel işlem kullanma	UniversalActionResponse
Diğer işlemler	Nothing

Google Workspace ana makine uygulamaları için işlemler

Bu işlemlere ek olarak, her ana makine uygulamasının yalnızca o ana makinede gerçekleştirilebilecek kendi işlem grubu vardır. Ayrıntılar için aşağıdaki kılavuzlara bakın:

• Takvim işlemleri
• Chat işlemleri
• İşlem yapmaya teşvik etme
• Gmail işlemleri
• Düzenleyici işlemleri

Not: Yanıt oluşturucu sınıflarını kullanırken yanıt nesnelerini oluşturmak için build() işlevini çağırdığınızdan emin olun. Aksi takdirde hata oluşur.

Not: Evrensel işlemler proje manifestinde tanımlanır ve Action nesnelerine ihtiyaç duymaz ancak geri çağırma işlevleri UniversalActionResponse döndürmelidir.

İşlem etkinliği nesneleri

Eklentiniz bir Action tetiklediğinde kullanıcı arayüzü, otomatik olarak bir JSON event object oluşturur ve bunu Action geri çağırma işlevine bağımsız değişken olarak iletir. Bu etkinlik nesnesi, kullanıcının mevcut istemci tarafı bağlamı hakkında bilgiler içerir. Örneğin, gösterilen karttaki tüm etkileşimli widget'ların mevcut değerleri gibi.

İşlem etkinliği nesneleri, içerdiği bilgileri düzenleyen belirli bir JSON yapısına sahiptir. Aynı yapı, bir ana sayfa oluşturmak için ana sayfa tetikleyicisi etkinleştiğinde veya eklenti ekranını güncellemek için bağlama dayalı tetikleyici etkinleştiğinde kullanılır.

Etkinlik nesnesi yapısıyla ilgili ayrıntılı açıklama için Etkinlik nesneleri bölümüne bakın.

Not: Gmail eklentileri, bu etkinlik nesnesi yapısının basitleştirilmiş bir sürümünü kullanıyordu. Bu sürüm artık kullanımdan kaldırıldı. Geriye dönük uyumluluk için orijinal Gmail eklentileri etkinlik nesnesi alanlarının tümü yeni etkinlik nesnesi yapısında yer almaya devam eder (bkz. etkinlik nesnesi yapısı). Ancak aynı bilgiler, ortak etkinlik ve Gmail etkinliği nesne alt yapılarında yeniden üretilir. Gmail eklentisini Google Workspace eklentisine yükseltiyorsanız güncellenen etkinlik nesnesi alanlarını kullanmak için kodunuzu ayarlamanız gerekir. Orijinal Gmail etkinlik nesnesi alanları sonunda kaldırılacaktır.