Eklenti işlemleri

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

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

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

1. Action nesnesini oluşturun ve gereken 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ışı uygulamak için geri çağırma işlevini uygulayın.

Not: Action nesnelerini CardAction nesneleriyle karıştırmayın. CardAction nesneleri kart başlığı menü öğeleridir, Action nesneleri ise kullanıcı arayüzüyle kullanıcı etkileşimlerine 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şlevi kullanırsınız. İşleyici işlevi, eylem davranışını ne tür bir etkileşimin (örneğin widget'ın tıklanması veya bir metin alanının düzenlenmesi) tetikleyeceğini belirler. İşleyici işlevi, işlem tamamlandıktan sonra kullanıcı arayüzünün hangi adımları atacağını da tanımlar.

Aşağıdaki tabloda, widget'lara ilişkin farklı işleyici türleri ve bunların hangi widget'larla birlikte kullanıldığı 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	Widget'ın odağı kaybolduğunda (örneğin, kullanıcı bir girişe metin girip Enter'a bastığında) Apps Komut Dosyası işlevini yürüten bir Action ayarlar. İşleyici, bir etkinlik nesnesini çağırdığı işleve otomatik olarak aktarır. İsterseniz bu etkinlik nesnesine ek parametre bilgileri ekleyebilirsiniz.
setOnClickAction()	Kullanıcı widget'ı tıklar	CardAction Image ImageButton DecoratedText TextButton	Kullanıcı widget'ı tıkladığında Apps Komut Dosyası işlevini yürüten bir Action ayarlar. İşleyici, bir etkinlik nesnesini çağırdığı işleve otomatik olarak aktarır. Bu etkinlik nesnesine isteğe bağlı parametre bilgileri ekleyebilirsiniz.
setComposeAction()	Kullanıcı widget'ı tıklar	CardAction Image ImageButton DecoratedText TextButton	Gmail'e özel. E-posta taslağı oluşturan bir Action ayarlar, ardından bu taslağı Gmail kullanıcı arayüzü oluşturma penceresinde kullanıcıya sunar. Taslağı yeni bir ileti veya Gmail'de açık bir iletiye yanıt olarak oluşturabilirsiniz. İşleyici taslak oluşturma geri çağırma işlevini çağırdığında, geri çağırma işlevine bir etkinlik nesnesi iletir. Daha fazla ayrıntı için Taslak iletiler oluşturma bölümüne bakın.
setOnClickOpenLinkAction()	Kullanıcı widget'ı tıklar	CardAction Image ImageButton DecoratedText TextButton	Kullanıcı widget'ı tıkladığında bir URL'yi açmak için Action ayarlar. Bu işleyiciyi, bağlantı açılmadan önce URL'yi oluşturmanız veya başka işlemlerin gerçekleşmesi gerektiğinde kullanın. Aksi takdirde, setOpenLink() kullanımı genellikle 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ıklar	CardAction Image ImageButton DecoratedText TextButton	Kullanıcı widget'ı tıkladığında doğrudan bir URL açar. Bu işleyiciyi, URL'yi bildiğinizde ve yalnızca açmanız gerektiğinde kullanın. Aksi takdirde setOnClickOpenLinkAction() kullanın. URL'yi yeni bir pencerede veya bir 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ş widget'ına metin girdiğinde Apps Komut Dosyası işlevini yürüten bir Action ayarlar. İşleyici, bir etkinlik nesnesini çağırdığı işleve otomatik olarak aktarır. Daha fazla ayrıntı için Metin girişleri için otomatik tamamlama önerileri bölümüne bakın.

Geri çağırma işlevleri

Geri çağırma işlevleri, bir Action tetiklendiğinde yürütülür. Geri çağırma işlevi Apps Komut Dosyası işlevleri olduğundan, bunların diğer herhangi bir komut dosyası işlevinin yapabileceği neredeyse her şeyi yapmasını sağlayabilirsiniz.

Uyarı: Apps Komut Dosyası 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.

Geri çağırma işlevi bazen belirli bir yanıt nesnesi döndürür. Bu tür yanıtlar, geri çağırmanın yürütülmesinden sonra gerçekleşmesi gereken ek işlemleri (ör. yeni bir kart görüntülemek veya otomatik tamamlama önerileri sunmak) belirtir. Geri çağırma işlevinizin belirli bir yanıt nesnesi döndürmesi gerektiğinde bu nesneyi oluşturmak için Kart hizmetinde 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 tamamı, eklentinin genişlettiği ana makine uygulamasından bağımsızdır:

İşlem yapılmaya çalışıldı	Geri çağırma işlevi şu sonucu döndürmelidir:
Kartlar arasında gezinme	ActionResponse
Notification görüntüle	ActionResponse
setOnClickOpenLinkAction() kullanarak bir bağlantı açın	ActionResponse
Otomatik tamamlama önerilerini görüntüleme	SuggestionResponse
Evrensel işlem kullanma	UniversalActionResponse
Diğer işlemler	Nothing

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

• Takvim işlemleri
• Harekete geçirme
• 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() yöntemini çağırdığınızdan emin olun. Aksi takdirde hata oluşur.

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

İşlem etkinliği nesneleri

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

İşlem etkinliği nesneleri, içerdikleri bilgileri düzenleyen belirli bir JSON yapısına sahiptir. Ana sayfa oluşturmak üzere bir ana sayfa tetikleyicisi veya eklenti ekranını güncellemek için içeriksel bir tetikleyici etkinleştiğinde de aynı yapı kullanılır.

Etkinlik nesnesi yapısının tam açıklaması için Etkinlik nesneleri bölümüne bakın.

Not: Gmail eklentileri, bu etkinlik nesnesi yapısının artık kullanımdan kaldırılan basitleştirilmiş bir sürümünü kullandı. Geriye dönük uyumluluk için tüm orijinal Gmail eklentileri etkinlik nesnesi alanları, yine de yeni etkinlik nesne yapısında yer alır (etkinlik nesnesi yapısı bölümüne bakın). Ancak aynı bilgiler ortak etkinlik ve Gmail etkinliği nesne alt yapılarında yeniden oluşturulur. Bir Gmail eklentisini bir Google Workspace eklentisine yükseltiyorsanız, kodunuzu güncellenmiş etkinlik nesnesi alanlarını kullanacak şekilde ayarlamanız gerekir. Bir süre sonra orijinal Gmail etkinlik nesnesi alanları kaldırılacaktır.