مقدمة إلى استخدام React فِي مكون Power Apps

  • 10 دقائق

إن React عبارة عن إطار عمل عميل قياسي لبناء واجهات المستخدم. وهو يوفر طريقة تعريفية لإنشاء واجهات مستخدم تفاعلية ويوفر آلية لتغليف المكونات لإنشاء واجهات مستخدم معقدة تدير حالات المكونات وشديدة التفاعل. نظراً لكتابة React فِي JavaScript، يمكنك استخدام إطار العمل هذا ضمن مكون Power Apps.

إذا لم تكن ملماً باستخدام React، فانتقل إلى React، الذي يوفر مجموعة كبيرة من الموارد التعليمية والموارد حول كيفية بناء مكونات React.

إعداد جهاز الكمبيوتر الخاص بك لمكونات التعليمات البرمجية

لإعداد الكمبيوتر لإنشاء مكونات التعليمات البرمجية، اتبع الخطوات التالية:

  1. ثبّت Npm (يأتي مع Node.js) أو Node.js (يأتي مع npm). نوصي باستخدام إصدار (LTS) (دعم طويل الأمد).

  2. ثبّت Visual Studio Code.

  3. ثبّت ملحق Power Platform Tools.

  4. قم بتثبيت Build Tools لـ Visual Studio من تنزيلات Visual Studio.

Fluent UI

لقد كان تنفيذ Fluent UI، وهو عبارة عن مجموعة من أطر عمل UX التي يمكنك استخدامها لبناء تجارب سهلة تتناسب بسلاسة مع مجموعة واسعة من منتجات Microsoft، أحد التطورات الهامة التي حققتها Microsoft. يمكن استخدام Fluent UI فِي مكون التعليمات البرمجية لـ Power Apps بطريقة بسيطة كالإشارة إلى مكتباته، وهذا يوفر إصداراً خاصاً بـ React يمكنك استخدامه. لمزيد من المعلومات، راجع Fluent UI.

تطبيق عينة مكون FacePile

هام

قم بتنزيل الملف المضغوط باسم FacePileComponent.zip لاستخدامه مع هذا التمرين. قم بفك ملف zip.

في هذا المثال، ستقوم ببناء مكون يستخدم مكون FacePile Fluent UI. يُظهر FacePile قائمة بالوجوه أو الأحرف الأولى من الأسماء فِي بحث أفقي، حيث كل دائرة تمثل شخصاً.

هناك مثال عملي عن استخدام هذا البحث وهو سرد المساهمين فِي مقال أو سجل، مثل ما قد تراه فِي Microsoft Learn، كما يظهر فِي الصورة التالية.

لقطة شاشة لمكون FacePile Fluent UI

إنشاء مشروع مكون جديد

لإنشاء مشروع مكون، اتبع هذه الخطوات:

  1. أنشئ دليلاً ستنشئ فيه مكوناً خاصاً بك. في هذه العينة، ستضع المكون فِي C:\users\username\source\face-pile؛ ومع ذلك، يمكنك إنشاء دليلك الخاص. لإنشاء دليلك الخاص، تستخدم Visual Studio Code.

  2. ابدأ تشغيل Visual Studio Code.

  3. حدّد الجهاز الطرفي، وحدّد الجهاز الطرفي الجديد، وقم بتبديل Terminal shell إلى موجه الأوامر.

    ملاحظة

    إذا لم تكن معتادًا على الجهاز الطرفي فِي Visual Studio Code، فانتقل إلى أساسيات الجهاز الطرفي لمعرفة المزيد.

  4. قم بإنشاء مجلد المصدر الخاص بك.

    md \source

  5. قم بتغيير الدليل إلى المجلد المصدر.

    cd \source

  6. من الدليل المصدر، أنشئ دليلاً باسم face-pile.

    md face-pile

  7. قم بتغيير الدليل إلى الدليل الذي قمت بإنشائه.

     cd face-pile

  8. من المفترض أن تكون الآن فِي الدليل الجديد الذي أنشأته.

  9. قم بتهيئة مشروع المكون باستخدام Power Platform CLI بواسطة الأمر التالي.

    pac pcf init --namespace Learn --name ReactFacePile --template field --framework React

  10. ثبّت أدوات بناء المشروع باستخدام الأمرnpm install. قد تظهر بعض التحذيرات المعروضة؛ ولكن، يمكنك تجاهلها بأمان.

    npm install

  11. قم بتشغيل الأمر التالي لفتح المشروع فِي Visual Studio Code.

    code -a .

  12. يجب أن يظهر المشروع كما فِي الصورة التالية.

    لقطة شاشة لـ Facepile UI فِي Visual Studio Code.

تنفيذ منطق مكون التعليمات البرمجية

لتنفيذ منطق مكون التعليمات البرمجية، اتبع الخطوات التالية:

  1. وسّع المجلد ReactFacePile وافتح الملف ControlManifest.Input.xml.

  2. حدّد موقع عقدة الخاصية واستبدلها بـ XML التالي.

    <property name="numberOfFaces" display-name-key="numberOfFaces_Display_Key" description-key="numberOfFaces_Desc_Key" of-type="Whole.None" usage="bound" required="false" />

  3. حدّد موقع الموارد وقم بإلغاء تعليقات css وresx.

    لقطة شاشة لإزالة تعليق css فِي Visual Studio Code.

  4. تأكد من تحديد الملف ControlManifest.Input.xml ثم حدّد New Folder.

  5. قم بتسمية المجلد الجديد components.

  6. انتقل إلى المجلد حيث قمت باستخراج ملف FacePileComponent.zip الذي تم تنزيله وافتح مجلد FacePileComponent.

  7. اسحب الملفات إلى داخل المجلد FacePileComponents، ثم قم بإفلاتها فِي مجلد components الذي أنشأته.

  8. يجب أن يحتوي مجلد components الآن على ملفين.

    لقطة شاشة لإزالة مجلدي Facepile.

  9. افتح الملف Index.ts.

  10. استبدل الاستيراد { HelloWorld, IHelloWorldProps } من "./HelloWorld"; مع جزء التعليمة البرمجية المتكررة هذا.

    import { FacepileBasicExample, IFacepileBasicExampleProps } from "./components/Facepile" ;

  11. بعد الاستيراد، أضف الثابت التالي.

    const DEFAULT_NUMBER_OF_FACES = 3;

  12. أضف جزء التعليمة البرمجية المتكررة قبل الدالة الإنشائية.

    private props: IFacepileBasicExampleProps = {
    numberFacesChanged: this.numberFacesChanged.bind(this),
};

  13. يجب أن تبدو التغييرات التي أجريتها مثل الصورة التالية.

    لقطة شاشة لتغيير التعليمات البرمجية فِي الملف index.ts.

  14. حدّد موقع الأسلوب init وأضف جزء التعليمة البرمجية المتكررة التالية بعد السطر this.notifyOutputChanged = notifyOutputChanged;

    this.props.numberOfFaces = context.parameters.numberOfFaces.raw || DEFAULT_NUMBER_OF_FACES;

  15. استبدل الأسلوب updateView بالأسلوب التالي.

    public updateView(context: ComponentFramework.Context<IInputs>): React.ReactElement {
    if (context.updatedProperties.indexOf("numberOfFaces") > -1) {
        this.props.numberOfFaces = context.parameters.numberOfFaces.raw || DEFAULT_NUMBER_OF_FACES;
    }
    return React.createElement(FacepileBasicExample, this.props);
}

  16. يجب أن يبدو الأسلوبين init وupdateView الآن مثل الصورة التالية.

    لقطة شاشة لطريقة العرض المحدثة للتعليمات البرمجية فِي الملف index.ts.

  17. استبدل الأسلوب getOutputs‎ بالأسلوب التالي.

    public getOutputs(): IOutputs {
    return {
        numberOfFaces: this.props.numberOfFaces,
    };
}

  18. أضف الأسلوب التالي بعد أسلوب destroy.

    private numberFacesChanged(newValue: number) {
    if (this.props.numberOfFaces !== newValue) {
        this.props.numberOfFaces = newValue;
        this.notifyOutputChanged();
    }
}

  19. حدّد ملف وحفظ كل تغييراتك.

إضافة تصميم إلى مكون التعليمات البرمجية‬

لإضافة تصميم إلى مكون التعليمات البرمجية‬، اتبع الخطوات الآتية:

  1. حدّد الملف ControlManifest.Input.xml ثم حدّد New Folder.

  2. قم بتسمية المجلد الجديد css.

  3. حدّد المجلد css الذي أنشأته وحدّد ملف جديد.

  4. قم بتسمية الملف الجديد ReactFacePile.css.

  5. افتح ملف ReactFacePile.css الجديد الذي أنشأته، والصق الجزء التعليمة البرمجية المتكررة لـ CSS التالية.

    msFacepileExample {
max-width: 300px;
}
.msFacepileExample .control {
 padding-top: 20px;
}
.msFacepileExample .ms-Dropdown-container, .msFacepileExample.ms-Slider {
margin: 10px 0 10px 0;
}
.msFacepileExample .ms-Dropdown-container .ms-Label {
padding-top: 0;
}
.msFacepileExample .ms-Checkbox {
padding-top: 15px;
}
.exampleCheckbox {
margin: 10px 0;
}
.exampleLabel {
margin: 10px 0;
}

  6. حدّد ملف واحفظ تغييراتك.

  7. حدّد الملف ControlManifest.Input.xml وحدّد New Folder.

  8. قم بتسمية المجلد الجديد strings.

  9. انتقل إلى المجلد حيث قمت باستخراج ملف FacePileComponent.zip الذي تم تنزيله وافتح مجلد FacePileStrings.

  10. اسحب ملف ReactFacePile.1033.resx ثم قم بإفلاته فِي مجلد strings الذي أنشأته.

  11. يجب أن يحتوي مجلد strings الآن على الملف resx.

    لقطة شاشة لإظهار إضافة ملف Facepile.

  12. حدّد ملف واحفظ تغييراتك.

  13. انتقل إلى الوحدة الطرفية وقم بتشغيل أمر البناء هذا.

    npm run build

    ملاحظة

    إذا تلقيت خطأ يفيد بأن JSX لم يتم تعريفه، فافتح الملف .eslintrc.json. في السطر 11: "ComponentFramework": trueأضف فاصلة ثم سطراً جديداً بـ "JSX": true. في السطر 41: قم بتغيير JSX.Element إلى React.JSX.Element. احفظ التغييرات وكرر الأمر npm run build.

  14. يجب أن تكتمل عملية البناء بنجاح.

  15. اختبر المكونات عن طريق تشغيل الأمر التالي.

    npm start

  16. من المفترض أن يفتح مفعّل الاختبار فِي نافذة متصفح جديدة.

  17. يجب أن يبدو المكون الآن مثل الصورة التالية.

    لقطة شاشة لصورة المكون الجديد.

  18. غيّر حجم الحاوية إلى 500 x 220 وانقل شريط التمرير إلى 5.

  19. يجب أن يبدو المكون الآن مثل الصورة التالية. أغلق نافذة متصفح مفعّل الاختبار.

    لقطة شاشة لصورة المكون الجديد مع بعض التسويات.

  20. أغلق نافذة متصفح مفعّل الاختبار.

  21. عد إلى الوحدة الطرفية وأوقف المراقب عن طريق الضغط على [CONTROL] + C.

  22. اكتب Y ثم اضغط على [ENTER].

لمزيد من المعلومات، انتقل إلى تنفيذ مكون FacePile.