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

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

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

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

  1. شی Action را ایجاد کنید، تابع callback را که باید به همراه هر پارامتری که نیاز دارد اجرا کند، مشخص کنید.
  2. با استفاده از شی Action ، تابع کنترل کننده ویجت مناسب روی ویجت را فراخوانی کنید.
  3. تابع 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 خاصی هستند که اطلاعاتی را که در خود دارند سازماندهی می کند. هنگامی که یک ماشه صفحه اصلی برای ایجاد یک صفحه اصلی فعال می شود، یا زمانی که یک ماشه متنی برای به روز رسانی صفحه نمایش افزودنی فعال می شود، از همین ساختار استفاده می شود.

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