اقدامات الحاقی

اکشن‌های افزونه، رفتار تعاملی را برای ویجت‌ها فراهم می‌کنند. با ایجاد یک اکشن، شما تعریف می‌کنید که وقتی کاربر یک ویجت را انتخاب یا به‌روزرسانی می‌کند، چه اتفاقی بیفتد.

در بیشتر موارد، می‌توانید با استفاده از اشیاء Action که توسط سرویس Apps Script Card ارائه می‌شوند، اقدامات افزونه‌ای تعریف کنید. هر Action هنگام ایجاد، با یک تابع فراخوانی مرتبط می‌شود. شما تابع فراخوانی را برای انجام مراحل انتخاب شده هنگام تعامل کاربر با ویجت پیاده‌سازی می‌کنید. همچنین باید Action را با استفاده از یک تابع کنترل‌کننده ویجت مناسب که نوع تعاملی که فراخوانی Action را فعال می‌کند، تعریف می‌کند، به ویجت پیوند دهید.

با استفاده از این فرآیند کلی، یک ویجت را با یک Action پیکربندی کنید:

  1. شیء Action را ایجاد کنید و تابع فراخوانی که باید اجرا شود را به همراه پارامترهای مورد نیاز آن مشخص کنید.
  2. با استفاده از شیء Action ، تابع مدیریت ویجت مناسب را روی ویجت فراخوانی کنید.
  3. تابع فراخوانی (callback) را برای اجرای رفتار مورد نیاز پیاده‌سازی کنید.

توابع مدیریت ویجت

برای پیوند دادن یک ویجت به یک Action خاص یا رفتار دیگر، از یک تابع کنترل‌کننده ویجت استفاده می‌کنید. تابع کنترل‌کننده تعیین می‌کند که چه نوع تعاملی (مثلاً کلیک روی ویجت یا ویرایش یک فیلد متنی) رفتار اقدام را فعال می‌کند. تابع کنترل‌کننده همچنین مشخص می‌کند که رابط کاربری پس از اتمام اقدام، در صورت وجود، چه مراحلی را طی کند.

جدول زیر انواع مختلف هندلر برای ویجت‌ها و ویجت‌هایی که با آنها استفاده می‌شوند را فهرست می‌کند:

تابع هندلر اقدام را آغاز می‌کند ابزارک‌های قابل اجرا توضیحات
setOnChangeAction() مقدار ویجت تغییر می‌کند DatePicker
DateTimePicker
SelectionInput
Switch
TimePicker TextInput		 یک Action تنظیم می‌کند که وقتی ویجت فوکوس را از دست می‌دهد، یک تابع Apps Script را اجرا می‌کند، مانند زمانی که کاربر متنی را در یک ورودی وارد می‌کند و Enter را فشار می‌دهد. هندلر به طور خودکار یک شیء رویداد را به تابعی که فراخوانی می‌کند، ارسال می‌کند. در صورت انتخاب، می‌توانید اطلاعات پارامتر اضافی را در این شیء رویداد وارد کنید.
setOnClickAction() کاربر روی ویجت کلیک می‌کند CardAction
Image
ImageButton
DecoratedText
TextButton		 یک Action تنظیم می‌کند که وقتی کاربر روی ویجت کلیک می‌کند، یک تابع Apps Script را اجرا می‌کند. این هندلر به طور خودکار یک شیء رویداد را به تابعی که فراخوانی می‌کند، ارسال می‌کند. می‌توانید اطلاعات پارامتر اختیاری را در این شیء رویداد وارد کنید.
setComposeAction() کاربر روی ویجت کلیک می‌کند CardAction
Image
ImageButton
DecoratedText
TextButton		 مخصوص جیمیل. Action را تنظیم می‌کند که یک پیش‌نویس ایمیل ایجاد می‌کند، سپس آن پیش‌نویس را در پنجره نوشتن رابط کاربری جیمیل به کاربر ارائه می‌دهد. می‌توانید پیش‌نویس را به عنوان یک پیام جدید یا پاسخی به پیام باز شده در جیمیل ایجاد کنید. وقتی کنترل‌کننده تابع فراخوانی پیش‌نویس‌ساز را فراخوانی می‌کند، یک شیء رویداد را به تابع فراخوانی ارسال می‌کند. برای جزئیات بیشتر به بخش «نوشتن پیام‌های پیش‌نویس» مراجعه کنید.
setOnClickOpenLinkAction() کاربر روی ویجت کلیک می‌کند CardAction
Image
ImageButton
DecoratedText
TextButton		 یک Action برای باز کردن یک URL هنگام کلیک کاربر روی ویجت تنظیم می‌کند. از این هندلر زمانی استفاده کنید که باید URL را بسازید یا اقدامات دیگری قبل از باز شدن لینک انجام شود؛ در غیر این صورت معمولاً استفاده setOpenLink() ساده‌تر است. فقط می‌توانید URL را در یک پنجره جدید باز کنید. وقتی بسته شد، می‌توانید باعث شوید که رابط کاربری افزونه را دوباره بارگذاری کند.
setOpenLink() کاربر روی ویجت کلیک می‌کند CardAction
Image
ImageButton
DecoratedText
TextButton		 وقتی کاربر روی ویجت کلیک می‌کند، مستقیماً یک URL را باز می‌کند. از این هندلر زمانی استفاده کنید که URL را می‌دانید و فقط نیاز به باز کردن آن دارید؛ در غیر این صورت از setOnClickOpenLinkAction() استفاده کنید. می‌توانید URL را در یک پنجره جدید یا در یک پوشش باز کنید. وقتی بسته شد، می‌توانید باعث شوید که رابط کاربری افزونه را مجدداً بارگذاری کند.
setSuggestionsAction() کاربر متنی را در یک ورودی وارد می‌کند TextInput یک Action تنظیم می‌کند که وقتی کاربر متنی را در ویجت ورودی متن وارد می‌کند، یک تابع Apps Script را اجرا می‌کند. این هندلر به طور خودکار یک شیء رویداد را به تابعی که فراخوانی می‌کند، ارسال می‌کند. برای جزئیات بیشتر به پیشنهادات تکمیل خودکار برای ورودی‌های متن مراجعه کنید.

توابع فراخوانی مجدد

توابع فراخوانی (callback functions) زمانی اجرا می‌شوند که یک Action فعال شود. از آنجایی که توابع فراخوانی، توابع اسکریپت برنامه‌ها (Apps Script functions) هستند، می‌توانید تقریباً هر کاری را که هر تابع اسکریپت دیگری می‌تواند انجام دهد، با آنها انجام دهید.

یک تابع فراخوانی گاهی اوقات یک شیء پاسخ خاص را برمی‌گرداند. این نوع پاسخ‌ها نشان‌دهنده عملیات اضافی هستند که باید پس از اتمام اجرای فراخوانی اتفاق بیفتند، مانند نمایش یک کارت جدید یا ارائه پیشنهادات تکمیل خودکار. هنگامی که تابع فراخوانی شما باید یک شیء پاسخ خاص را برگرداند، از یک کلاس سازنده در سرویس Card برای ساخت آن شیء استفاده می‌کنید.

جدول زیر نشان می‌دهد که چه زمانی توابع فراخوانی شما باید برای اقدامات خاص، یک شیء پاسخ خاص را برگردانند. این اقدامات همگی مستقل از برنامه میزبان خاصی هستند که افزونه آن را توسعه می‌دهد:

اقدام انجام شد تابع فراخوانی باید مقدار بازگشتی را برگرداند
بین کارت‌ها حرکت کنید ActionResponse
نمایش Notification ActionResponse
باز کردن یک لینک با استفاده از setOnClickOpenLinkAction() ActionResponse
نمایش پیشنهادات تکمیل خودکار SuggestionResponse
از یک اقدام جهانی استفاده کنید UniversalActionResponse
اقدامات دیگر هیچی

اقدامات مربوط به برنامه‌های میزبان Google Workspace

علاوه بر این اقدامات، هر برنامه میزبان مجموعه اقدامات خاص خود را دارد که فقط در آن میزبان قابل انجام است. برای جزئیات بیشتر، به راهنماهای زیر مراجعه کنید:

اشیاء رویداد اکشن

وقتی افزونه شما یک Action فعال می‌کند، رابط کاربری به طور خودکار یک شیء رویداد JSON می‌سازد و آن را به عنوان آرگومان به تابع فراخوانی Action ارسال می‌کند. این شیء رویداد حاوی اطلاعاتی در مورد زمینه فعلی سمت کلاینت کاربر، مانند مقادیر فعلی همه ویجت‌های تعاملی در کارت نمایش داده شده، است.

اشیاء رویداد اکشن یک ساختار JSON خاص دارند که اطلاعات موجود در آنها را سازماندهی می‌کند. همین ساختار زمانی استفاده می‌شود که یک تریگر صفحه اصلی برای ایجاد یک صفحه اصلی فعال می‌شود، یا زمانی که یک تریگر زمینه‌ای برای به‌روزرسانی نمایش افزونه فعال می‌شود.

برای توضیح کامل ساختار شیء رویداد، به اشیاء رویداد مراجعه کنید.