حدث Form OnSave (مرجع واجهة برمجة تطبيقات العميل) في التطبيقات المستندة إلى النموذج

OnSave يحدث الحدث عندما:

• يحدد المستخدم الزر حفظ أو تحديث في شريط الأوامر، حتى في حالة عدم وجود بيانات تم تغييرها ليتم حفظها.
• تنفذ التعليمات البرمجية طريقة formContext.data.entity.save ، حتى في حالة عدم وجود بيانات تم تغييرها ليتم حفظها.
• ينتقل المستخدم بعيدا عن النموذج وهناك بيانات غير محفوظة في النموذج.
• يتم تمكين خيار الحفظ التلقائي، بعد 30 ثانية من تغيير البيانات، وهناك بيانات غير محفوظة في النموذج.
• تنفذ التعليمات البرمجية طريقة formContext.data.save وهناك بيانات غير محفوظة في النموذج.
• تنفذ التعليمات البرمجية طريقة formContext.data.refresh التي تمرر قيمة حقيقية كمعلمة أولى وهناك بيانات غير محفوظة في النموذج.

Note

OnSave سيؤدي الحدث الخاص بسجلات المواعيد أو المواعيد المتكررة أو نشاط الخدمة إلى إلغاء عملية الحفظ واستخدام Book الرسالة لاستمرار التغيير بدلا من Create أو Update. لهذا السبب، OnSavePostSave لن تعمل معالجات الأحداث لهذه الجداول.

لتحديد الزر الذي تم النقر فوقه لتنفيذ الحفظ، استخدم أسلوب getSaveMode .

يمكنك إلغاء إجراء الحفظ باستخدام الأسلوب preventDefault داخل كائن وسيطات الحدث. يمكن الوصول إلى الأسلوب preventDefault باستخدام أسلوب getEventArgs الذي يعد جزءا من سياق التنفيذ. يتم تمرير سياق التنفيذ تلقائيا إلى معالج أحداث النموذج.

دعم معالج الأحداث غير المتزامن

الحدث OnSave لديه القدرة على انتظار الوعود التي تم إرجاعها بواسطة معالجات الأحداث للتسوية قبل الحفظ، ما OnSave يسمح للحدث أن يكون غير متزامن ("غير متزامن").

OnSave يصبح الحدث غير متزامن عندما OnSave يقوم معالج الحدث بإرجاع وعد. يحدث حفظ السجل عند حل كل وعد يتم إرجاعه بواسطة معالج. بالنسبة لأي وعود يتم إرجاعها، هناك حد 10 ثوان لكل وعد، بعد ذلك تعتبر المنصة أن الوعود قد انتهت. يتم تطبيق هذه المهلة لكل وعد. على سبيل المثال، إذا تم إرجاع خمسة وعود، فإن إجمالي وقت الانتظار هو 50 ثانية.

إذا تم رفض الوعد أو انتهت مهلته، تستمر عملية الحفظ في التصرف بشكل مشابه لأخطاء البرنامج النصي الحالية. استخدم الأسلوب preventDefault داخل كائن وسيطات الحدث في هذا المعالج المعين إذا كنت تريد منع حدث الحفظ من الحدوث إذا كان هناك خطأ في البرنامج النصي/ وعد مرفوض أو مهلة معالج.

يمكنك أيضا إلغاء عملية الحفظ بغض النظر عن الخطأ في المعالج أو عدم استخدام الأسلوب preventDefault داخل كائن وسيطات الحدث. إذا تم استدعاء هذا الأسلوب، ينتظر الحدث Async OnSave جميع الوعود للتسوية، ولكن لن يحدث الحفظ. استدعاء هذا الأسلوب يعني أن المنطق داخل .then() سيتم .catch() تنفيذه.

OnSave ينتظر الحدث وعدا واحدا تم إرجاعه لكل معالج. إذا كانت هناك حاجة إلى وعود متعددة، فمن المستحسن التفاف جميع الوعود في Promise.all() الأسلوب وإرجاع الوعد الناتج الوحيد. بالنسبة لمعالجات متعددة تقوم جميعها بإرجاع وعد، نوصيك بإنشاء معالج واحد يستدعي جميع الأحداث وإرجاع وعد واحد يختتم جميع الوعود المطلوبة. هذه الممارسة هي تقليل أوقات الانتظار الناتجة عن المهلة.

سيناريو مثال حول وقت استخدام معالجات OnSave غير المتزامنة

ضع في اعتبارك إنشاء مهمة خدمة أمر عمل، تحتاج إلى التحقق من أن أصل العميل المحدد له نفس الحساب المدرج في أمر العمل. إحضار الحساب على أمر العمل وأصل العميل هي عمليات غير متزامنة وتحتاج إلى إكمالها قبل أن يحدث التحقق من الصحة.

في هذا السيناريو، نظرا لوجود عمليات غير متزامنة متعددة ويعيد كلا الاستدعاءين وعدا واحدا عن طريق التفاف كليهما في Promise.all() الأسلوب .

Note

preventDefault يمكن استخدام الأسلوب فقط بشكل متزامن.

على سبيل المثال:

 function myHandler() {
    return Promise.all([getWorkOrderPromise, getCustomerAssetPromise]).then((values) => {
        var workOrder = values[0];
        var customerAsset = values[1];
        // Perform validation
        if (isValid(workOrder, customerAsset)) {
            return Promise.resolve();
        }
        return Promise.reject(new Error("Validation failed for the work order and customer asset"));
   });
 }

تمكين Async OnSave باستخدام إعداد التطبيق

لاستخدام معالجات onSave غير المتزامنة، تحتاج إلى تمكينه من خلال إعداد تطبيق:

1. انتقل إلى https://make.powerapps.com.

2. تأكد من تحديد البيئة الصحيحة.

3. من جزء التنقل الأيسر، حدد التطبيقات.

4. حدد التطبيق ثم حدد ... (علامات الحذف). حدد تحرير.

5. حدد الإعدادات من شريط الأوامر.

6. عند فتح مربع الحوار، حدد الميزات.

7. قم بتشغيل معالج Async onSave.

8. حدد حفظ.

   

مهلات الحفظ غير المتزامن

عند استخدام معالج غير متزامن OnSave ، ينتظر النموذج تنفيذ الوعد الذي تم إرجاعه بواسطة المعالج. للتأكد من اكتمال حفظ النموذج في الوقت المناسب، سيطرح المعالج استثناء المهلة بعد 10 ثوان لإعلامك بضبط المعالج غير المتزامن OnSave للحصول على أداء أفضل.

هناك سيناريوهات حيث يلزم إيقاف OnSave المعالج مؤقتا لأكثر من 10 ثوان. مثال على ذلك هو فتح مربع حوار وانتظار إدخال المستخدم قبل متابعة الحفظ. للتأكد من أن العملية غير المتزامنة تنتظر الوعد بالحل، استخدم أسلوب disableAsyncTimeout .

Note

يجب عليك الاتصال disableAsyncTimeout قبل أي عبارات انتظار أو مكالمات غير متزامنة.

على سبيل المثال:

async function myHandler(context) {  
     context.getEventArgs().disableAsyncTimeout();
     // The 10000ms time out will not be disabled if the above line does not come before all async awaits
     await Xrm.Navigation.openConfirmDialog({ text: "Are you sure you want to save?" });
 }

عند استدعاء disableAsyncTimeout ، لا يتم تطبيق مهلة هذا المعالج. فإنه لا يزال ينتظر حتى يتم الوفاء بوعد هذا المعالج.

يجب استخدام هذا النمط بحذر لأنه قد يؤثر على أداء حفظ النموذج.

المقالات ذات الصلة

حدث حفظ الشبكة
الأحداث (مرجع واجهة برمجة تطبيقات العميل)
الأحداث في النماذج والشبكات في التطبيقات التي تستند إلى النموذج