Eklenti işlemleri

Eklenti işlemleri, widget'lara etkileşimli davranış sağlar. İş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şlemlerini tanımlayabilirsiniz. Her Action, oluşturulduğunda 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, Action geri çağırma işlevini ne tür bir etkileşimin tetiklediğini tanımlayan uygun bir widget işleyici işlevi kullanarak Action öğesini widget'a bağlamanız gerekir.

Aşağıdaki genel süreci uygulayarak Action içeren bir widget yapılandırın:

1. Gereken tüm parametrelerle birlikte yürütmesi gereken geri çağırma işlevini belirterek Action nesnesini oluşturun.
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 üstbilgisi menü öğeleridir. Action nesneleri ise kullanıcının kullanıcı arayüzüyle 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, işlem davranışını ne tür bir etkileşimin (ör. widget'ı tıklama veya bir metin alanını düzenleme) tetiklediğini belirler. İşleyici işlevi, işlem tamamlandıktan sonra kullanıcı arayüzünün (varsa) hangi adımları uygulayacağını da tanımlar.

Aşağıdaki tabloda, widget'lar için farklı işleyici türleri ve bu işleyicilerin 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şir.	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	Widget'ın odağını kaybettiğinde (ör. kullanıcı bir girişe metin girip Enter tuşuna bastığında) bir Apps Script 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 bir Apps Komut Dosyası işlevini 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 özgüdür. E-posta taslağı oluşturan ve ardından bu taslağı Gmail kullanıcı arayüzü yazma penceresinde kullanıcıya sunan bir Action ayarlar. Taslağı yeni bir ileti 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 etkinlik nesnesi iletir. Daha fazla bilgi için Taslak ileti 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 açmak için Action ayarlanır. URL'yi oluşturmanız veya bağlantı açılmadan önce başka işlemlerin yapılması gerektiğinde bu işleyiciyi kullanın. Aksi takdirde genellikle setOpenLink() kullanmak daha basittir. URL'yi yalnızca yeni bir pencerede açabilirsiniz. Kapalıyken kullanıcı arayüzünün eklentiyi yeniden yüklemesine neden
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 bildiğiniz ve yalnızca açmanız gerektiğinde bu işleyiciyi kullanın. Aksi takdirde setOnClickOpenLinkAction() değerini kullanın. URL'yi yeni bir pencerede veya yer paylaşımında açabilirsiniz. Kapalıyken kullanıcı arayüzünün eklentiyi yeniden yüklemesine neden
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 belirler. İş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 yapabileceği hemen hemen her şeyi yapmalarını sağlayabilirsiniz.

Uyarı: Apps Script Kart hizmeti, geri çağırma işlevlerini en fazla 30 saniyelik yürütme süresiyle sınırlar. Yürütme bundan daha uzun sürerse eklenti kullanıcı arayüzünüz, Action değerine yanıt olarak kart görüntüsünü düzgün şekilde güncelleyemeyebilir.

Geri çağırma işlevi bazen belirli bir yanıt nesnesini döndürür. Bu tür yanıtlar, geri aramanın yürütülmesi 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 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 belirli bir yanıt nesnesi döndürmesi gerektiği durumlar gösterilmektedir. Bu işlemlerin tümü, eklentinin genişlettiği belirli ana uygulamadan bağımsızdır:

İşlem deneniyor	Geri çağırma işlevi şunu döndürmelidir:
Kartlar arasında gezinme	ActionResponse
Notification göster	ActionResponse
setOnClickOpenLinkAction() simgesini kullanarak bağlantı açma	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 o ana makinede yapılabilecek kendi işlem grubu vardır. Ayrıntılar için aşağıdaki kılavuzlara bakın:

• Takvim işlemleri
• Drive işlemleri
• 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 çağırdığınızdan emin olun. Aksi takdirde hata meydana gelir.

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

Eklentinizle bir Action tetiklendiğinde kullanıcı arayüzü otomatik olarak bir JSON etkinlik nesnesi 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 bilgi içerir (ör. görüntülenen karttaki tüm etkileşimli widget'ların mevcut değerleri).

İşlem etkinliği nesneleri, içerdikleri bilgileri düzenleyen belirli bir JSON yapısına sahiptir. Ana sayfa oluşturmak için bir ana sayfa tetikleyicisi etkinleştirildiğinde veya eklenti ekranını güncellemek için bir bağlamsal tetikleyici etkinleştirildiğinde 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 basitleştirilmiş bir sürümünü kullanıyordu. Bu sürümün desteği sonlandırıldı. Geriye dönük uyumluluk için orijinal Gmail eklentisi etkinlik nesnesi alanlarının tümü yeni etkinlik nesnesi yapısında yer almaya devam eder (etkinlik nesnesi yapısı bölümüne bakın). Ancak aynı bilgiler ortak etkinlik ve Gmail etkinliği obje alt yapılarında yeniden oluşturulur. Bir Gmail eklentisini Google Workspace eklentisine yükseltiyorsanız kodunuzu güncellenmiş etkinlik nesnesi alanlarını kullanacak şekilde ayarlamanız gerekir. Orijinal Gmail etkinlik nesnesi alanları zaman içinde kaldırılacaktır.