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

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

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

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

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

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

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

برای پیوند دادن یک ویجت به یک 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) هستند، می‌توانید تقریباً هر کاری را که هر تابع اسکریپت دیگری می‌تواند انجام دهد، از آنها بخواهید.

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

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

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

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

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

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

• اقدامات تقویم
• اقدامات چت
• اقدامات درایو
• اقدامات جیمیل
• اقدامات ویرایشگر

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

اکشن‌های یونیورسال در مانیفست پروژه تعریف شده‌اند و نیازی به اشیاء Action ندارند، اما توابع فراخوانی آنها باید یک UniversalActionResponse برگردانند.

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

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

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

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

افزونه‌های جیمیل از یک نسخه ساده‌شده از این ساختار شیء رویداد استفاده می‌کردند که اکنون منسوخ شده است. برای سازگاری با نسخه‌های قبلی، تمام فیلدهای شیء رویداد افزونه‌های اصلی جیمیل هنوز در ساختار شیء رویداد جدید قرار دارند (به ساختار شیء رویداد مراجعه کنید). با این حال، همان اطلاعات در زیرساختارهای commonEventObject و شیء رویداد جیمیل بازتولید می‌شوند. اگر در حال ارتقاء یک افزونه جیمیل به یک افزونه Google Workspace هستید، کد خود را طوری تنظیم کنید که از فیلدهای شیء رویداد به‌روزرسانی‌شده استفاده کند. در نهایت، فیلدهای شیء رویداد اصلی جیمیل حذف خواهند شد.