المهَام الشَائعة للبرمجة النصية للعميل

مكتمل

نموذج كائن واجهة API الخَاص بالعميل يعد شَاملاً وثريًا. عندمَا تتعرف عَلى البرمجة النصية للعميل، سوف تدرك أنه يمكنك ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام العديد مِن كائنَات وأسَاليب واجهة برمجة التطبيقَات (API) لتنفيذ المنطق الخَاص بك. فِي هذه الوحدة، يمكن أن نلقي نظرة عَلى بعض المهَام الشَائعة التي تقوم بهَا والتقنيَات التي يجب ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَامهَا لإنجَازهَا.

الوصول Dataverse إلى بيَانَات العمود

يتم تمثيل عمود Dataverse ككائن سمة فِي نموذج الكائن. يمكنك ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام طريقة getAttribute() لكائن formContext لتحديد موقع سمة محددة أو جَمِيع السمَات الموجودة فِي النموذج بسرعة. يتضمنُ كل كائن سَمة بعضَ الطًرق الشَائعَة المُتوفِّرة بغضِّ النَظر عَن نَوعِ البيَانَات. ثمَّة أيضًا طُرق أخرَى مُتَاحَة لأنوَاع بيَانَات سِمَاتٍ مُحدَّدةٍ (نصّ أو رَقم أو تَاريخ أو غير ذلك).

‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫ملاحظة

يفترض نموذج التعليمَات البرمجية هَذا وجود السمَات وعنَاصر التحكم ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِمة. تُرجع معظم الطرق قيمة فارغة إذَا لم تكن الكائنَات مُتَاحة ويجب ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام عمليَات التحقق الدفاعية المعتَادة عمليًا.

‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫نَصِيحة

تحتوي المجموعَات التي يتم إرجَاعهَا بواسطة أسَاليب Client API عَلى بعض الطرق المفيدة التي يمكنك ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَامهَا للتكرَار عبر العنَاصر. لمزيد مِن المَعلومَات، رَاجع المجموعَات (مرجع واجهة برمجة تطبيقَات العميل) فِي التطبيقَات التي تستند إلى النموذج - Power Apps.

المهمة	مثَال
الوصول عن طريق الاسم	javascript var nameAttribute = formContext.getAttribute("name"); يقوم بتعيين السمة للعمود اسم الحسَاب إلى المتغير nameAttribute. إذَا لم تكن السمة موجودة فِي النموذج، فستُرجع طريقة getAttribute قيمة فارغة.
الوصول إلى جَمِيع السمَات	javascript var allAttributes = formContext.getAttribute(); يقوم بتعيين صفيف مِن جَمِيع السمَات الموجودة فِي مجموعة formContext.data.entity.attributes إلى مُتغير allAttributes.

استخدم السمَات

المهمة	مثَال
الحصول عَلى قيمة السمة	javascript var nameValue = formContext.getAttribute("name").getValue(); يقوم بتعيين القيمة للعمود اسم الحسَاب إلى المتغير nameAttribute.
تعيين قيمة السمة	javascript formContext.getAttribute("name").setValue("new name"); يقوم بتَعيِين قيِمة عمود اسم الحسَاب إلى “new name”.
الحصول عَلى كائن الخيَار المحدد حَاليًا فِي سمة OptionSet (عمود Dataverse Choice)	javascript var addressTypeOption = formContext.getAttribute("address1_addresstypecode").getSelectedOption(); يقومُ بتعيين الخيَار المحدد فِي عمود نوع العنوان إلى متغير addressTypeOption.
تحديد مَا إذَا كانت قيمة السمة قد تغيرت فِي واجهة ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم منذ فتح النموذج	javascript var isNameChanged = formContext.getAttribute("name").getIsDirty(); يقوم بتعيين قيمة منطقية تشير إلى مَا إذَا كانت قيمة عمود اسم الحسَاب تتغير ويتم التعيين إلى المتغير isNameChanged‎.
تغيير مَا إذَا كانت البيَانَات مطلوبة فِي عمود مِن أجل حفظ سجل	javascript formContext.getAttribute("creditlimit").setRequiredLevel("required"); يجعلُ عمود حد الائتمَان مطلوبًا. javascript formContext.getAttribute("creditlimit").setRequiredLevel("none"); يجعلُ عمود حد الائتمَان اختيَاريًا.
تحديد مَا إذَا كان سيتم إرسَال البيَانَات الموجودة فِي إحدى السمَات عِندَ حفظ السجل	javascript var nameSubmitMode = formContext.getAttribute("name").getSubmitMode(); تكون قيمة المتغير nameSubmitMode إمَّا نص always أو never أو dirty لتمثيل submitMode لعمود اسم الحساب.
التحكم فِي مَا إذَا كان سيتم حفظ البيَانَات الموجودة فِي إحدى السمَات عِندَ حفظ السجل	javascript formContext.getAttribute("name").setSubmitMode("always"); يفرض المثَال حفظ قيمة عمود اسم الحسَاب دَائمًا حتى فِي حَالة عدم تغييرهَا.
عند تطبيق أمَان مستوى العمود عَلى سمة مَا، فحدد إذَا كان ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المستَخدِم لديه امتيَازَات لإجرَاء عمليَات الإنشَاء أو القرَاءة أو التحديث عَلى السمة.	javascript var canUpdateNameAttribute = formContext.getAttribute("name").getUserPrivilege().canUpdate; يقومُ بتعيين القيمة المنطقية التي تمثل امتيَاز ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫المُستَخدِم لتحديث عمود اسم الحسَاب إلى المتغير canUpdateNameAttribute.

عنَاصر التحكم فِي نموذج الوصول

المهمة	مثَال
الوصول إلى كافة عنَاصر التحكم لسمة معينة	javascript var nameControls = formContext.getAttribute("name").controls.get(); يقومُ بتعيين صفيف مِن جَمِيع عنَاصر التحكم الخَاصة بسِمة name إلى المتغير nameControls‎. يتم تمثيل معظم السمَات بعنصر تحكم واحد، ولكن قد يكون هنَاك أكثر مِن عمود واحد فِي حَالة ‏إضَافَة عمود إلى النموذج أكثر مِن مرة.
الوصول إلى عنصر التحكم بالاسم	javascript var nameControl = formContext.getControl("name"); عنصر التحكم الأول المضَاف إلى نموذج عمود له نفس اسم العمود. يحتوي كل مِن أسمَاء عنَاصر التحكم الأخرى عَلى رقم فهرس ملحق بالاسم. على سبيل المثَال، ثلاثة عنَاصر تحكم لعمود الاسم لهَا الأسمَاء: name وname1 وname2، عَلى التَوالي.
الوصول إلى كافة الضوابط	javascript var allControls = formContext.getControl(); يقومُ بتعيين صفيف مِن جَمِيع عنَاصر التحكم الموجودة فِي مجموعة formContext.ui.controls إلى متغير allControls‎.

‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام عنَاصر تحكم النمَاذج

مثل كائنَات السمَات تتضمن مجموعة شَائعة مِن الطرق بغض النظر عن النوع. كمَا أنهَا تتضمن طرقًا متخصصة استنَادًا إلى نوع عنصر التحكم.

المهمة	مثَال
تحديد مَا إذَا كان عنصر التحكم مرئيًا	javascript var isNameVisible = formContext.getControl("name").getVisible(); يقوم بتعيين قيمةٍ منطقية إلى متغير isNameVisible‎ الذي يمثل مَا إذَا كان عمود اسم الحسَاب مرئيًا أم لا.
إخفاء عنصر تحكم أو إظهَاره	javascript formContext.getControl("name").setVisible(false); يقومُ بإخفَاء عَمُود اسم الحسَاب.
الحصول عَلى مرجع إلى سمة عنصر التحكم	javascript var nameAttribute = formContext.getControl("name").getAttribute(); يقوم بتعيين السمة لعنصر التحكم لعمود اسم الحسَاب إلى المتغير nameAttribute.
تعطيل أو تمكين جَمِيع عنَاصر التحكم لإحدى السمَات	javascript formContext.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); }); تذكَّر أن أي سمة قد تتضمن عنَاصر تحكم متعددة.
تغيير تسمية عنصر تحكم	javascript formContext.getControl("name").setLabel("Company Name"); يقومُ بتعيين تسمية عمود اسم الحسَاب إلى نص Company Name.
الحصول عَلى أصل عنصر تحكم	javascript var parentSection = formContext.getControl("name").getParent(); يقومُ بتعيين عنصر التحكم الأصلي للعمود اسم الحسَاب إلى المتغير parentSection‎.
تعيين التركيز عَلى عنصر تحكم	javascript formContext.getControl("name").setFocus(); يقومُ بتعيين تركيز الإدخَال الحَالي إلى عمود اسم الحسَاب.

‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام علامَات التبويب والأقسَام

يحتوي كل نموذج عَلى مجموعة مِن علامَات التبويب. وتحتوي كل علامة تبويب عَلى مجموعة مِن الأقسَام. ويحتوي كل قسم عَلى مجموعة مِن عنَاصر التحكم. يمكنك برمجيًا الوصول إلى هذه العنَاصر و‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام الطرق الخَاصة بهَا.

المهمة	مثَال
إظهَار علامة تبويب أو إخفاؤهَا	javascript formContext.ui.tabs.get("general").setVisible(false); يقومُ بإخفاء علامة التبويب عَام.
تغيير تسمية علامة تبويب	javascript formContext.ui.tabs.get("general").setLabel("Major"); يقومُ بتعيين تسمية علامة تبويب general إلى نص Major.
إظهَار قسم أو إخفاؤه	javascript formContext.getControl("industrycode").getParent().setVisible(false); يقومُ بإظهَار قسم يحتوي عَلى عمود Industry Code.

‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَام بيَانَات الكيَان

يحتوي الجدول الآتي عَلى طرق يمكنك ‏‫‏‫‏‫‏‫‏‫‏‫‏‫‏‫استخدَامهَا للحصول عَلى معلومَات حول السجل الحَالي.

المهمة	مثَال
الحصول عَلى معرّف للسجل الحَالي	javascript var recordId = formContext.data.entity.getId(); يقومُ بتعيين معرف فريد للسجل الحَالي إلى متغير recordId‎. إذَا تم فتح النموذج لإنشَاء سجل جديد، يتم إرجَاع القيمة الخَالية.
حفظ السجل الحَالي	javascript formContext.data.entity.save(); استَخدِم saveandclose‎ أو saveandnew‎ لتنفيذ الإجرَاءَات المكافئة باستخدَام حفظ وإغلاق أو حفظ وجديد.
تحديد مَا إذَا كان قد تم تغيير أية بيَانَات فِي السجل الحَالي.	javascript var isDirty = formContext.data.entity.getIsDirty(); يقومً بتعيين قيمةٍ منطقيةٍ تشير إلى مَا إذَا كانت أي قيمة عمود فِي النموذج قد تغيرت إلى المُتغير isDirty.