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, Apps Komut Dosyası Kart hizmeti tarafından sağlanan Action nesnelerini kullanarak eklenti işlemleri tanımlayabilirsiniz. Her Action, onu oluşturduğunuzda bir geri çağırma işleviyle ilişkilendirilir. Kullanıcı widget'la etkileşimde bulunduğunda istenen adımları atmak için geri çağırma işlevini uygularsınız. Ayrıca, ne tür bir etkileşimin Action geri çağırmasını 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 widget'ı Action ile yapılandırın:

1. Action nesnesini oluşturun. Nesnenin, gerekli tüm parametrelerle birlikte yürütmesi gereken geri çağırma işlevini belirtin.
2. Action nesnesini kullanarak widget'taki 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 girdikleri etkileşimlere verilen yanıtları tanımlar.

Widget işleyici işlevleri

Bir widget'ı belirli bir Actionya veya başka bir davranışa bağlamak için widget işleyici işlevi kullanabilirsiniz. İşleyici işlevi, ne tür bir etkileşimin (örneğin, widget'ı tıklama veya bir metin alanını düzenleme) işlem davranışını tetikleyeceğini belirler. İşleyici işlevi, işlem tamamlandıktan sonra kullanıcı arayüzünün hangi adımları attığını da tanımlar.

Aşağıdaki tabloda, widget'ların farklı işleyici türleri ve bunların hangi widget'larla birlikte kullanıldığı listelenmektedir:

İşleyici işlevi	İşlemi tetikler	Geçerli widget'lar	Açıklama
setOnChangeAction()	Widget değeri değişir	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	Kullanıcının bir girişe metin girip Enter tuşuna basması gibi widget odağı kaybettiğinde Apps Komut Dosyası işlevi yürüten bir Action ayarlar. İşleyici, çağırdığı işleve otomatik olarak bir etkinlik nesnesi iletir. İ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şlevi yürüten bir 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ıklar	CardAction Image ImageButton DecoratedText TextButton	Gmail'e özel. E-posta taslağı oluşturan bir Action ayarlar ve ardından bu taslağı, bir Gmail kullanıcı arayüzü oluşturma penceresinde kullanıcıya sunar. Taslağı yeni bir ileti olarak veya Gmail'de açık olan iletinin 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 bilgi için Taslak iletiler oluşturma sayfasına göz atın.
setOnClickOpenLinkAction()	Kullanıcı widget'ı tıklar	CardAction Image ImageButton DecoratedText TextButton	Kullanıcı widget'ı tıkladığında bir URL'nin açılması için Action gönderir. URL'yi oluşturmanız veya bağlantı açılmadan önce başka işlemlerin gerçekleştirilmesi gerektiğinde bu işleyiciyi kullanın. Aksi takdirde, setOpenLink() kullanımı genellikle daha basit olur. URL'yi yalnızca yeni bir pencerede açabilirsiniz. Kapatıldığında kullanıcı arayüzünün eklentiyi yeniden 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. URL'yi biliyorsanız ve yalnızca açmanız gerekiyorsa bu işleyiciyi kullanın. Aksi takdirde setOnClickOpenLinkAction() 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ı, metin girişi widget'ına metin girdiğinde Apps Komut Dosyası işlevini yürüten bir Action ayarlar. İşleyici, çağırdığı işleve otomatik olarak bir etkinlik nesnesini iletir. 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, diğer komut dosyası işlevlerinin hemen hemen 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ırlar. Yürütme işlemi bundan daha uzun sürerse eklentinizin kullanıcı arayüzü, Action

yanıtına göre kart görüntüsünü düzgün bir şekilde güncellemeyebilir.

Geri çağırma işlevi bazen belirli bir yanıt nesnesini döndürür. Bu yanıt türleri, geri çağırmanın yürütülmesi bittikten 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 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 tümü, eklentinin genişlettiği belirli ana makine uygulamasından bağımsızdır:

Yapılmak istenen işlem	Geri çağırma işlevi şunu döndürmelidir:
Kartlar arasında gezinme	ActionResponse
Notification gösterin	ActionResponse
Bir bağlantıyı setOnClickOpenLinkAction() kullanarak açın	ActionResponse
Otomatik tamamlama önerilerini görüntüleme	SuggestionResponse
Genel işlem kullanma	UniversalActionResponse
Diğer işlemler	Nothing

Bu işlemlere ek olarak, her ana makine uygulamasının yalnızca ilgili ana makinede yapılabilecek kendi işlemleri vardır. Ayrıntılar için aşağıdaki kılavuzlara bakın:

• Takvim işlemleri
• İşlemleri artırma
• 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 nesneleri gerektirmez 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, Action geri çağırma işlevine bir bağımsız değişken olarak iletir. Bu etkinlik nesnesi, kullanıcının mevcut istemci tarafı bağlamı hakkında, görüntülenen karttaki tüm etkileşimli widget'ların geçerli değerleri gibi bilgileri içerir.

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

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

Not: Gmail eklentileri, bu etkinlik nesne yapısının artık kullanımdan kaldırılmış olan basitleştirilmiş bir sürümünü kullandı. Geriye dönük uyumluluk için orijinal Gmail eklentileri etkinlik nesnesi alanlarının tümü, yeni etkinlik nesne yapısı içinde yer almaya devam eder (etkinlik nesne yapısına bakın). Ancak aynı bilgiler ortak etkinlik ve Gmail etkinliği nesne alt yapılarında yeniden oluşturulur. Bir Gmail eklentisini Google Workspace eklentisine yükseltiyorsanız kodunuzu güncellenen etkinlik nesnesi alanlarını kullanacak şekilde ayarlamanız gerekir. Bu durumda, orijinal Gmail etkinlik nesnesi alanları sonunda kaldırılır.