إجراءات الإضافات

توفر إجراءات "الإضافة" سلوكًا تفاعليًا لـ الأدوات. عند إنشاء إجراء، يمكنك تحديد ما يحدث عندما يختار المستخدم أداة أو يحدّثها.

في معظم الحالات، يمكنك تحديد إجراءات "الإضافة" باستخدام Action الكائنات التي توفّرها خدمة البطاقات في "برمجة تطبيقات Google". يرتبط كل Action بـ دالّة رد اتصال عند إنشائه. عليك تنفيذ دالّة رد الاتصال لاتخاذ خطوات محدّدة عندما يتفاعل المستخدم مع الأداة. يجب أيضًا ربط Action بالأداة باستخدام دالّة معالجة مناسبة للأداة تحدّد نوع التفاعل الذي يؤدي إلى تشغيل Action رد الاتصال.

لضبط أداة باستخدام Action ، اتّبِع الخطوات التالية:

1. أنشئ الكائن Action ، وحدِّد دالّة رد الاتصال التي يجب تنفيذها بالإضافة إلى أي مَعلمات مطلوبة.
2. استدعِ دالّة معالجة الأداة المناسبة على الأداة باستخدام الكائن Action.
3. نفِّذ دالّة رد الاتصال لتفعيل السلوك المطلوب.

لا تخلط بين كائنات Action وكائنات CardAction. CardAction الكائنات هي عناصر قائمة رأس البطاقة، بينما Action الكائنات تحدّد الردود على تفاعلات المستخدم مع واجهة المستخدم.

دوال معالجة الأدوات

لربط أداة بـ Action أو سلوك آخر، استخدِم دالّة معالجة الأداة. تحدّد دالّة المعالجة نوع التفاعل (على سبيل المثال، النقر على الأداة أو تعديل حقل نص) الذي يؤدي إلى تشغيل سلوك الإجراء. تحدّد دالّة المعالجة أيضًا الخطوات التي تتخذها واجهة المستخدم، إن وُجدت، بعد اكتمال الإجراء.

يسرد الجدول التالي أنواع المعالجات المختلفة للأدوات والأدوات التي يتم استخدامها معها:

دالّة المعالجة	يؤدي إلى تشغيل الإجراء	الأدوات القابلة للتطبيق	الوصف
setOnChangeAction	تتغيّر قيمة الأداة	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	يضبط Action ينفّذ دالّة في "برمجة تطبيقات Google" عندما تفقد الأداة التركيز، مثلاً عندما يُدخِل المستخدم نصًا في حقل إدخال ويضغط على مفتاح Enter. يمرِّر المعالج تلقائيًا كائن حدث إلى الدالّة التي يستدعيها. يمكنك إدراج معلومات إضافية عن المَعلمات في كائن الحدث هذا إذا تم اختيارها.
setOnClickAction	ينقر المستخدم على الأداة	CardAction Image ImageButton DecoratedText TextButton	يضبط Action ينفّذ دالّة في "برمجة تطبيقات Google" عندما ينقر المستخدم على الأداة. يمرِّر المعالج تلقائيًا كائن حدث إلى الدالّة التي يستدعيها. يمكنك إدراج معلومات اختيارية عن المَعلمات في كائن الحدث هذا.
setComposeAction	ينقر المستخدم على الأداة	CardAction Image ImageButton DecoratedText TextButton	خاص بـ Gmail يضبط Action ينشئ مسودة رسالة إلكترونية، ثم يعرض هذه المسودة للمستخدم في نافذة إنشاء واجهة مستخدم Gmail. يمكنك إنشاء المسودة كرسالة جديدة أو رد على الرسالة المفتوحة في Gmail. عندما يستدعي المعالج دالّة رد الاتصال لإنشاء المسودة، يمرِّر كائن حدث إلى دالّة رد الاتصال. لمزيد من التفاصيل، اطّلِع على إنشاء رسائل مسودة.
setOnClickOpenLinkAction	ينقر المستخدم على الأداة	CardAction Image ImageButton DecoratedText TextButton	يضبط Action لفتح عنوان URL عندما ينقر المستخدم على الأداة. استخدِم هذا المعالج عندما يكون عليك إنشاء عنوان URL أو يجب تنفيذ إجراءات أخرى قبل فتح الرابط. بخلاف ذلك، يكون استخدام setOpenLink أسهل عادةً. لا يمكنك فتح عنوان URL إلا في نافذة جديدة. عند إغلاق النافذة، يمكنك إعادة تحميل واجهة مستخدم "الإضافة" .
setOpenLink	ينقر المستخدم على الأداة	CardAction Image ImageButton DecoratedText TextButton	يفتح عنوان URL مباشرةً عندما ينقر المستخدم على الأداة. استخدِم هذا المعالج عندما تعرف عنوان URL وتحتاج فقط إلى فتحه. بخلاف ذلك، استخدِم setOnClickOpenLinkAction. يمكنك فتح عنوان URL في نافذة جديدة أو في تراكب. عند إغلاق النافذة، يمكنك إعادة تحميل واجهة مستخدم "الإضافة".
setSuggestionsAction	يُدخِل المستخدم نصًا في حقل إدخال	TextInput	يضبط Action ينفّذ دالّة في "برمجة تطبيقات Google" عندما يُدخِل المستخدم نصًا في أداة إدخال نص. يمرِّر المعالج تلقائيًا كائن حدث إلى الدالّة التي يستدعيها. لمزيد من التفاصيل، اطّلِع على اقتراحات الإكمال التلقائي لحقول إدخال النص.

دوال رد الاتصال

يتم تنفيذ دوال رد الاتصال عندما يتم تشغيل Action. بما أنّ دوال رد الاتصال هي دوال في "برمجة تطبيقات Google"، يمكنك تنفيذ أي إجراء تقريبًا يمكن أن تنفّذه أي دالّة نص برمجي أخرى.

**تحذير:** تحدّ خدمة البطاقات في "برمجة تطبيقات Google" دوال رد الاتصال بحد أقصى 30 ثانية من وقت التنفيذ. إذا استغرق التنفيذ وقتًا أطول من ذلك، قد لا يتم تحديث واجهة مستخدم "الإضافة" لعرض البطاقة بشكل صحيح استجابةً لـ Action.

تعرض دالّة رد الاتصال أحيانًا كائن رد معيّنًا. تشير هذه الأنواع من الردود إلى عمليات إضافية يجب تنفيذها بعد اكتمال دالّة رد الاتصال، مثل عرض بطاقة جديدة أو عرض اقتراحات الإكمال التلقائي. عندما يجب أن تعرض دالّة رد الاتصال كائن رد معيّنًا ، استخدِم فئة إنشاء في خدمة البطاقات لإنشاء هذا الكائن.

يوضِّح الجدول التالي الحالات التي يجب فيها أن تعرض دوال رد الاتصال كائن رد معيّنًا لإجراءات معيّنة. تكون هذه الإجراءات مستقلة عن تطبيق المضيف المحدّد الذي توسّعه "الإضافة":

الإجراء الذي تمت محاولته	يجب أن تعرض دالّة رد الاتصال
التنقّل	ActionResponse
عرض Notification	ActionResponse
فتح رابط باستخدام setOnClickOpenLinkAction	ActionResponse
عرض اقتراحات الإكمال التلقائي	SuggestionResponse
استخدام إجراء عام	UniversalActionResponse
الإجراءات الأخرى	Nothing

إجراءات تطبيقات المضيف في Google Workspace

بالإضافة إلى هذه الإجراءات، يتضمّن كل تطبيق مضيف مجموعة الإجراءات الخاصة به التي لا يمكن تنفيذها إلا في هذا المضيف. لمزيد من التفاصيل، اطّلِع على الأدلة التالية:

• إجراءات "تقويم Google"
• إجراءات Hangouts Chat
• إجراءات Google Drive
• إجراءات Gmail
• إجراءات "محرّر المستندات"

عند استخدام فئات إنشاء الردود، استدعِ طريقة build لإنشاء كائنات الردود. سيؤدي عدم إجراء ذلك إلى ظهور خطأ.

يتم تحديد الإجراءات العامة في بيان المشروع ولا تحتاج إلى Action كائنات، ولكن يجب أن تعرض دوال رد الاتصال الخاصة بها UniversalActionResponse.

كائنات أحداث الإجراءات

عندما تشغّل "الإضافة" Action، تنشئ واجهة المستخدم تلقائيًا _كائن حدث_ بتنسيق JSON وتمرِّره كمعلَمة إلى دالّة رد الاتصال Action. يحتوي كائن الحدث هذا على معلومات عن السياق الحالي من جهة العميل للمستخدم، مثل القيم الحالية لجميع الأدوات التفاعلية في البطاقة المعروضة.

تتّخذ كائنات أحداث الإجراءات بنية JSON معيّنة تنظّم المعلومات التي تحتوي عليها. يتم استخدام البنية نفسها عندما يتم تشغيل مشغّل الصفحة الرئيسية لإنشاء صفحة رئيسية، أو عندما يتم تشغيل مشغّل سياقي لتعديل عرض "الإضافة".

للحصول على شرح كامل لبنية كائن الحدث، اطّلِع على كائنات الأحداث.

استخدمت إضافات Gmail إصدارًا مبسطًا من بنية كائن الحدث هذه، والتي تم إيقافها الآن. لضمان التوافق مع الإصدارات السابقة، لا تزال جميع حقول كائن الحدث الأصلية لإضافات Gmail مضمّنة في بنية كائن الحدث الجديد (اطّلِع على بنية كائن الحدث). ومع ذلك، يتم إعادة إنتاج المعلومات نفسها في الـ commonEventObject و Gmail event object البنيتَين الفرعيتَين. إذا كنت بصدد ترقية إضافة Gmail إلى إضافة Google Workspace، عدِّل الرمز البرمجي لاستخدام حقول كائن الحدث المعدّلة. في النهاية، ستتم إزالة حقول كائن الحدث الأصلية في Gmail.