این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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