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

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

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

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

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

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

توابع کنترل کننده ویجت

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

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

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

توابع پاسخ به تماس

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

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

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

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

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

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

• اقدامات تقویم
• اقدامات را هدایت کنید
• اقدامات Gmail
• اقدامات ویرایشگر

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

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

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

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

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

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

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