Class Action

الإجراء

إجراء يتيح التفاعل داخل عناصر واجهة المستخدم لا يتم تنفيذ الإجراء مباشرةً على العميل، بل يتم استدعاء دالّة رد الاتصال في "برمجة التطبيقات" مع مَعلمات اختيارية.

متاحة لإضافات Google Workspace وتطبيقات Google Chat.

const image = CardService.newImage().setOnClickAction(
    CardService.newAction().setFunctionName('handleImageClick').setParameters({
      imageSrc: 'carImage'
    }),
);

الطُرق

الطريقة	نوع القيمة التي تم إرجاعها	وصف قصير
addRequiredWidget(requiredWidget)	Action	تضيف هذه السمة أسماء الأدوات التي يحتاجها هذا الإجراء لإرسال نموذج صالح.
setAllWidgetsAreRequired(allWidgetsAreRequired)	Action	تشير هذه السمة إلى ما إذا كان هذا الإجراء يتطلّب إدخالات من جميع التطبيقات المصغّرة.
setFunctionName(functionName)	Action	تضبط هذه السمة اسم دالة ردّ الاتصال التي سيتم استدعاؤها.
setInteraction(interaction)	Action	تضبط هذه السمة التفاعل مع المستخدم، وهي مطلوبة فقط عند فتح مربّع حوار.
setLoadIndicator(loadIndicator)	Action	تضبط هذه السمة مؤشر التحميل الذي يظهر أثناء تنفيذ الإجراء.
setParameters(parameters)	Action	تسمح بتمرير مَعلمات مخصّصة إلى دالة رد الاتصال.
setPersistValues(persistValues)	Action	توضّح ما إذا كانت قيم النموذج يتم تحديدها من خلال قيم العميل أو قيم الخادم بعد أن تعدّل استجابة الإجراء Card النموذج.

الطرق المتوقّفة

الطريقة	نوع القيمة التي تم إرجاعها	وصف قصير
setMethodName(functionName)	Action

مستندات تفصيلية

addRequiredWidget(requiredWidget)

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

متاحة لإضافات Google Workspace وتطبيقات Google Chat.

const textInput = CardService.newTextInput()
                      .setFieldName('text_input_1')
                      .setTitle('Text input title');

// Creates a footer button that requires an input from the above TextInput
// Widget.
const action = CardService.newAction()
                   .setFunctionName('notificationCallback')
                   .addRequiredWidget('text_input_1');
const fixedFooter = CardService.newFixedFooter().setPrimaryButton(
    CardService.newTextButton().setText('help').setOnClickAction(action),
);

المَعلمات

الاسم	النوع	الوصف
requiredWidget	String	اسم الأداة المطلوبة لهذا الإجراء

الإرجاع

Action: هذا العنصر، للتسلسل

---

setAllWidgetsAreRequired(allWidgetsAreRequired)

تشير هذه السمة إلى ما إذا كان هذا الإجراء يتطلّب إدخالات من جميع التطبيقات المصغّرة.

متاحة لإضافات Google Workspace وتطبيقات Google Chat.

// Creates a button with an action that requires inputs from all widgets.
const button = CardService.newTextButton()
                   .setText('Create notification')
                   .setOnClickAction(
                       CardService.newAction().setAllWidgetsAreRequired(true));

المَعلمات

الاسم	النوع	الوصف
allWidgetsAreRequired	Boolean	تُستخدَم لتحديد ما إذا كان الإجراء يتطلّب إدخالات من جميع التطبيقات المصغّرة. القيمة التلقائية هي false.

الإرجاع

Action: هذا العنصر، للتسلسل

---

setFunctionName(functionName)

تضبط هذه السمة اسم دالة ردّ الاتصال التي سيتم استدعاؤها. الحقل مطلوب.

المَعلمات

الاسم	النوع	الوصف
functionName	String	اسم الدالة يمكنك استخدام دوال من المكتبات المضمّنة، مثل Library.libFunction1.

الإرجاع

Action: هذا العنصر، للتسلسل

---

setInteraction(interaction)

تضبط هذه السمة التفاعل مع المستخدم، وهي مطلوبة فقط عند فتح مربّع حوار. في حال عدم تحديد نوع الاستجابة، يستجيب التطبيق بتنفيذ Action، مثل فتح رابط أو تنفيذ وظيفة، كالمعتاد.

لا تتوفّر هذه الميزة إلا لتطبيقات Google Chat. لا يتوفّر هذا الخيار لإضافات Google Workspace.

const action = CardService.newAction()
                   .setFunctionName('handleDialog')
                   .setInteraction(CardService.Interaction.OPEN_DIALOG);

المَعلمات

الاسم	النوع	الوصف
interaction	Interaction	التفاعل المطلوب تحديده

الإرجاع

Action: هذا العنصر، للتسلسل

---

setLoadIndicator(loadIndicator)

تضبط هذه السمة مؤشر التحميل الذي يظهر أثناء تنفيذ الإجراء.

المَعلمات

الاسم	النوع	الوصف
loadIndicator	LoadIndicator	المؤشر المطلوب عرضه.

الإرجاع

Action: هذا العنصر، للتسلسل

---

setParameters(parameters)

تسمح بتمرير مَعلمات مخصّصة إلى دالة رد الاتصال. اختياريّ.

المَعلمات

الاسم	النوع	الوصف
parameters	Object	يجب أن تكون المفاتيح والقيم سلاسل.

الإرجاع

Action: هذا العنصر، للتسلسل

---

setPersistValues(persistValues)

توضّح ما إذا كانت قيم النموذج يتم تحديدها من خلال قيم العميل أو قيم الخادم بعد أن تعدّل استجابة الإجراء Card النموذج. عند ضبطها على true، تظل قيم العميل محفوظة بعد استجابة الخادم. عند ضبطها على false، تستبدل قيم الخادم قيم النموذج. القيمة التلقائية هي false.

يساعد الاحتفاظ بقيم العميل في تجنُّب الحالات التي يتغيّر فيها النموذج بشكل غير متوقّع بعد أن يجري المستخدم تعديلاً. على سبيل المثال، إذا أجرى مستخدم تعديلاً على TextInput بعد إرسال نموذج، ولكن قبل أن يستجيب الخادم. إذا تم الاحتفاظ بالقيم، سيظل التعديل الذي أجراه المستخدم متاحًا بعد أن يعدّل رد الخادم Card، وإلا ستعود قيمة النموذج إلى القيمة التي أرسلها المستخدم في الأصل إلى النموذج.

يمكن أن يؤدي الاحتفاظ بقيم العميل إلى تعطيل قدرة البرنامج النصي على محو حقول النموذج أو إلغاء قيم النموذج، لذا تجنَّب تفعيل الاحتفاظ بهذا النوع من الوظائف. في حال عدم توفّر الثبات، ننصحك باستخدام LoadIndicator.SPINNER للأحداث، لأنّ ذلك يؤدي إلى قفل واجهة المستخدم ويمنع المستخدم من إجراء تعديلات قبل أن يستجيب الخادم. بدلاً من ذلك، يمكنك استخدام LoadIndicator.NONE والتأكّد من أنّ كل عنصر في النموذج يتضمّن إجراء onChange.

// Creates a button with an action that persists the client's values as the
// on-click action.
const button =
    CardService.newTextButton()
        .setText('Create notification')
        .setOnClickAction(
            CardService.newAction().setPersistValues(true).setFunctionName(
                'functionName'),
        );

المَعلمات

الاسم	النوع	الوصف
persistValues	Boolean	تحديد ما إذا كان سيتم الاحتفاظ بالقيم. القيمة التلقائية هي false.

الإرجاع

Action: هذا العنصر، للتسلسل

الطرق المتوقّفة

setMethodName(functionName)

تمّت إزالة هذا العمود. الاسم المستعار القديم لـ setFunctionName(functionName)

المَعلمات

الاسم	النوع	الوصف
functionName	String	اسم الدالة يمكنك استخدام دوال من المكتبات المضمّنة، مثل Library.libFunction1.

الإرجاع

Action: هذا العنصر، للتسلسل