عرض مصدر Cordova/platforms electron

<noinclude>{{DISPLAYTITLE:المكون دليل استخدام منصة إلكترون (Electron) في React}}</noinclude>
إلكترون (Electron) هو إطار عمل يستخدم تقنيات الويب (مثل HTML وCSS وJS) لبناء تطبيقات حاسوب عابرة للمنصات (أي تعمل على منصّات مختلفة).
__toc__
== متطلبات النظام لتشغيل إطار عمل إلكترون ==

=== نظام لينكس ===

* الإصدار 2.7 أو أعلى من بايثون (Python). ويُنصح بتفقًّد إصدار بايثون الذي تستخدمه خاصةً أنّ بعض توزيعات لينكس (مثل الإصدار 6 من توزيعة CentOS) لا تزال تستخدم الإصدار 2.6 من بايثون  افتراضيًّا.

=== نظام ماك ===

* الإصدار 2.7 أو أعلى من بايثون (Python) بالإضافة إلى دعم بروتوكول طبقة المنافذ الآمنة TLS 1.2.
* الإصدار 8.2.1 أو أعلى من بيئة تطوير Xcode الخاصة بنظام ماك. تتضمن هذه الحزمة جميع الأدوات الضرورية لتوقيع وتفسير التعليمات البرمجية الخاصة بنظام ماك.
* دعم أدوات توزيعة RedHat التالية:
** Homebrew: وهو أحد مديري الحزم المتاحين لنظام ماك ويُستخدم لتثبيت الأدوات والمصادر الإضافية. ستحتاج إلى أداة Homebrew أيضًا لتثبيت متطلبات مدير حزم RPM. راجع [https://brew.sh/ دليل تثبيت Brew] لمزيد من الإرشادات حول هذه النقطة.
** مدير حزم RPM: يُعَدّ RPM مدير الحزم الافتراضي للعديد من توزيعات لينكس ويُستخدم أيضًا لإنشاء حزم RPM لنظام لينكس. ستحتاج إلى استخدام أمر Homebrew التالي لتثبيت هذه الأداة:

<syntaxhighlight class="" lang="bash">
brew install rpm
</syntaxhighlight>
=== نظام تشغيل ويندوز ===

* الإصدار 2.7.10 أو أعلى من بايثون.
* واجهة سطر أوامر PowerShell. لكن إذا كنت تستخدم نظام تشغيل Windows 7، فستحتاج إلى الإصدار 3.0 على الأقل لتتمكن من توقيع التطبيقات.
* [https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/ أدوات استكشاف وإصلاح المشاكل] لنظام ويندوز. وهي حزمة أدوات لتعزيز قدرات استكشاف الأخطاء ويُنصح بتثبيتها مع الإصدار 10.0.15063.468 من حزمة أدوات تطوير ويندوز (Windows SDK).

== نظرة سريعة ==

=== إنشاء مشروع كوردوفا ===

استخدم الأمر التالي بعد التحقق من تلبية متطلبات نظام التشغيل سابقة الذكر للبدء بإنشاء مشروع كوردوفا:

<syntaxhighlight class="" lang="bash">npm i -g cordova
cordova create sampleApp
cd  sampleApp
cordova platform add electron</syntaxhighlight>
'''ملاحظة''': إذا كنت تستخدم واجهة سطر أوامر كوردوفا أقدم من الإصدار 9، فستحتاج إلى استخدام دالّة <code>cordova-electron</code> عوضًا عن دالّة <code>electron</code> لأيّ تعليمة تتطلّب ذكر اسم المنصّة. مثال على ذلك:

<syntaxhighlight class="" lang="bash">cordova platform add cordova-electron
cordova run cordova-electron</syntaxhighlight>
=== استعراض مشروع كوردوفا ===

ليس من الضروري تجميع تطبيق إلكترون قيد الإنشاء بهدف استعراضه ومراجعته نسبةً لبطء عملية التجميع. لذلك يُنصح بإضافة راية <code>nobuild--</code> لتعطيل عملية التجميع أثناء استعراض سير العمل.

<syntaxhighlight class="" lang="bash">cordova run electron --nobuild</syntaxhighlight>
=== بناء مشروع كوردوفا ===

'''الإصدار التجريبي'''

<syntaxhighlight class="" lang="bash">cordova build electron
cordova build electron --debug</syntaxhighlight>
'''الإصدار المستقر'''

<syntaxhighlight class="" lang="bash">cordova build electron --release</syntaxhighlight>
== تخصيص خيارات نافذة التطبيق ==

يوفر إطار عمل إلكترون خيارات متعدِّدة للتحكم بنافذة المُستعرض وسيُغطي هذا القسم كيفية إعداد بعض الخيارات الأساسية. راجع قسم [https://electronjs.org/docs/api/browser-window#new-browserwindowoptions خيارات نافذة العرض] من توثيق إلكترون لرؤية كامل قائمة الخيارات.

يُنصح بإنشاء ملف خاص بإعدادات إلكترون في جذر مسار مشروع كوردوفا وإدراج المسار المتعلق به في خيار <code>ElectronSettingsFilePath</code> الموجود بملف <code>config.xml</code> كما في المثال التالي:

<syntaxhighlight class="" lang="xml"><platform name="electron">
    <preference name="ElectronSettingsFilePath" value="res/electron/settings.json" />
</platform></syntaxhighlight>
إذا أردت تغيير أيٍّ من خيارات نافذة المُستعرض (<code>BrowserWindow</code>) الافتراضية، فستحتاج إلى إضافة تلك الخيارات إلى مُكوِّن <code>browserWindow</code> الموجود في ملف <code>res/electron/settings.json</code> كما هو موضَّح أدناه:

<syntaxhighlight class="" lang="json">{
    "browserWindow": { ... }
}</syntaxhighlight>
=== كيفية تحديد حجم النافذة الافتراضي ===

أبعاد نافذة المُستعرض الافتراضية هي 800 للعرض و600 للطول، لكنها قابلة للتخصيص عبر تعديل خصائص العرض والطول كما في المثال التالي:

<syntaxhighlight class="" lang="json">{
    "browserWindow": {
        "width": 1024,
        "height": 768
    }
}</syntaxhighlight>
=== كيفية منع تغيير حجم نافذة المستعرض ===

يمكنك تعطيل إمكانية تغيير أبعاد نافذة المُستعرض من قبل المستخدم عبر استخدام خاصية <code>resizable</code> كما هو موضح أدناه:

<syntaxhighlight class="" lang="json">{
    "browserWindow": {
        "resizable": false
    }
}</syntaxhighlight>
=== كيفية استخدام العرض الكامل لنافذة المستعرض ===

يمكنك فرض عرض التطبيق بوضع الشاشة الكاملة عبر استخدام خاصية <code>fullscreen</code> كما في المثال التالي:

<syntaxhighlight class="" lang="json">{
    "browserWindow": {
        "fullscreen": true
    }
}</syntaxhighlight>
=== كيفية دعم نظام برامج Node.js وواجهة برمجة تطبيقات إلكترون (Electron APIs) ===

حدد قيمة خاصية <code>nodeIntegration</code> إلى <code>true</code> لدعم مكتبات [[Node.js]] واستخدام الرموز التي يتشاركها <code>Node.js</code> وإلكترون كما هو موضح في المثال التالي. افتراضيًّا تًعَدّ  قيمة هذه الخاصية هي <code>false</code> ويمكنك قراءة المزيد من التفاصيل حول [https://electronjs.org/docs/faq#i-can-not-use-jqueryrequirejsmeteorangularjs-in-electron دعم مكتبات  - RequireJS - Meteor - AngularJS] و [[jQuery]] في توثيق إلكترون. 

<syntaxhighlight class="" lang="json">{
    "browserWindow": {
        "webPreferences": {
            "nodeIntegration": false
        }
    }
}</syntaxhighlight>
== تخصيص عملية إلكترون الرئيسية ==

إذا احتجت إلى تخصيص عملية إلكترون الرئيسية بما يتخطى ما تُتيحه إعدادات إطار العمل فيُمكنك تغيير تعليمات ملف <code>cdv-electron-main.js</code> الموجود في مسار <code>‎{PROJECT_ROOT_DIR}/platform/electron/platform_www/‎</code> والخاص بعملية التطبيق الرئيسية.

لكن يجدر بنا تحذيركم من تعديل هذا الملف فعملية تحديث إطار <code>cordova-electron</code> تتضمن حذف المنصّة القديمة قبل تثبيت الإصدار الجديد.

== أدوات المطورين (DevTools) ==

تتحكم رايتي <code>release--</code> و<code>debug--</code> بإمكانية عرض أدوات المطورين والتي تظهر افتراضيًّا في إصدارات الاختبار (Debug Builds). قد تتضمن تلك الإصدارات راية <code>debug--</code> أو قد لا تستخدم أيّ راية. لذا فإن أردت إخفاء أدوات المطورين في تلك الإصدارات، فعليك إضافة راية <code>release--</code> عند بناء أو تشغيل التطبيق.

'''ملاحظة''': يمكن فتح أو إغلاق أدوات المطورين يدويًا في إصدارات الاختبار.

== إعدادات الإصدار ==

=== إعدادات الإصدار الافتراضية ===

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

'''لينكس'''

{| class="wikitable"
! '''الحزمة'''
! '''المعمارية'''
|-
| <code>tar.gz</code>
| x64
|}

'''ماك'''

{| class="wikitable"
! '''الحزمة'''
! '''المعمارية'''
|-
| <code>dmg</code>
| x64
|-
| <code>zip</code>
| x64
|}'''ويندوز'''

{| class="wikitable"
! '''الحزمة'''
! '''المعمارية'''
|-
| <code>nsis</code>
| x64
|}

=== تخصيص إعدادات الإصدار ===

إذا رغبت بتخصيص إعدادات الإصدار لأيّ سبب، فستحتاج إلى تضمينها في ملف <code>build.json</code> والموجود في جذر مسار المشروع (مثل <code>‎{PROJECT_ROOT_DIR}/build.json</code>). يحتوي هذا الملفّ على جميع إعدادات الإصدار لجميع المنصّات (مثل: أندرويد، وإلكترون، وiOS، وويندوز). ستبدو بنية إعدادات إلكترون كما في المثال التالي:

<syntaxhighlight class="" lang="json">{
    "electron": {}
}</syntaxhighlight>
بما أنّ إطار عمل إلكترون يُستخدم لإنشاء تطبيقات عابرة للمنصات (أي تعمل على أنظمة تشغيل مختلفة)، فستحتاج إلى تخصيص إعدادات منفصلة لكلّ منصّة على حدة. يتضمن مكوّن إلكترون الموجود في ملفّ <code>build.json</code> ثلاث خصائص تفصِل بين إعدادات الإصدار لكلّ نظام تشغيل كما هو موضّح في المثال التالي:

<syntaxhighlight class="" lang="json">{
    "electron": {
        "linux": {},
        "mac": {},
        "windows": {}
    }
}</syntaxhighlight>
يحتوي كلّ مكوِّن على الخصائص اللازمة لتحديد أيّ حزمة يجب توليدها وكيف تُوقّع.

'''خصائص أنظمة التشغيل'''

* '''الحزمة (<code>package</code>)''': وهي مصفوفة تضمّ ترميز الإصدارات التي ستوَلّد لاحقًا.
* '''المعمارية (<code>arch</code>)''': وهي مصفوفة من المعماريات التي تستهدفها كلّ حزمة منفصلة.
* '''التوقيع (<code>signing</code>)''': وهو مُكوِّن يحتوي معلومات التوقيع. راجع صفحة [https://cordova.apache.org/docs/en/latest/guide/platforms/electron/index.html#signing-configurations إعدادات التوقيع] لمزيد من المعلومات عن هذه النقطة.

سيستخدم إلكترون الإعدادات الافتراضية في حالة وجود أيّ خصائص غير محددة القيمة في ملف <code>build.json</code>.

=== إضافة حزمة ===

تتضمن خاصية الحزمة (<code>package</code>) مصفوفةً من ترميز الحزم التي ستُجمّع لاحقًا، فإذا حدّدت تلك الخصائص، فلن يستخدم إلكترون الحزم الافتراضية ما لم تُضفها بنفسك. كما لن يهمّ ترتيب عناصر الحزمة الذي أدخلتها.

على سبيل المثال ستُولّد الإعدادات التالية حزم <code>tar.gz</code> و<code>dmg</code> و<code>zip</code> لمنصة ماك:

<syntaxhighlight class="" lang="json">{
    "electron": {
        "mac": {
            "package": [
                "dmg",
                "tar.gz",
                "zip"
            ]
        }
    }
}</syntaxhighlight>
'''الحزم المتاحة لكل نظام تشغيل''':

{| class="wikitable"
! '''نوع الحزمة'''
! '''لينكس'''
! '''ماك'''
! '''ويندوز'''
|-
| <code>default</code>
| -
| <code>dmg - zip</code>
| -
|-
| <code>dmg</code>
| -
| ✅
| -
|-
| <code>mas</code>
| -
| ✅
| -
|-
| <code>mas-dev</code>
| ✅
| -
| -
|-
| <code>pkg</code>
| -
| ✅
| -
|-
| <code>7z</code>
| ✅
| ✅
| ✅
|-
| <code>zip</code>
| ✅
| ✅
| ✅
|-
| <code>tar.xz</code>
| ✅
| ✅
| ✅
|-
| <code>tar.lz</code>
| ✅
| ✅
| ✅
|-
| <code>tar.gz</code>
| ✅
| ✅
| ✅
|-
| <code>tar.bz2</code>
| ✅
| ✅
| ✅
|-
| <code>dir</code>
| ✅
| ✅
| ✅
|-
| <code>nsis</code>
| -
| -
| ✅
|-
| <code>nsis-web</code>
| -
| -
| ✅
|-
| <code>portable</code>
| -
| -
| ✅
|-
| <code>appx</code>
| -
| -
| ¹ ✅
|-
| <code>msi</code>
| -
| -
| ✅
|-
| <code>AppImage</code>
| ✅
| -
| -
|-
| <code>snap</code>
| ✅
| -
| -
|-
| <code>deb</code>
| ✅
| -
| -
|-
| <code>rpm</code>
| ✅
| -
| -
|-
| <code>freebsd</code>
| ✅
| -
| -
|-
| <code>pacman</code>
| ✅
| -
| -
|-
| <code>p5p</code>
| ✅
| -
| -
|-
| <code>apk</code>
| ✅
| -
| -
|}
* ¹ يجدر بنا التنويه إلى أنّ الإصدار 10 فقط من نظام تشغيل ويندوز يمكنه إنشاء حزمة <code>AppX</code>.

=== إعداد معمارية الحزمة ===

تضم خاصية المعمارية (<code>arch</code>) مصفوفة من المعماريات التي تستهدفها كل حزمة. إذا حدّدت قيمة هذه الخاصية فلن يستخدم إلكترون المعمارية الافتراضية عند تجميع تلك الحزمة.

'''ملاحظة''': الخيارات المتاحة لأيّ نظام تشغيل قد لا تتضمن جميع المعماريات. يمكنك مراجعة [https://github.com/electron/electron/releases/ صفحة إصدارات إلكترون] لمعرفة الخيارات المتاحة لنظام التشغيل الذي تستهدفه.  فنظام ماك (داروين) على سبيل المثال لا يدعم سوى معمارية <code>x64</code> فقط

'''المعماريات المتاحة''':

* <code>ia32</code>
* <code>x64</code>
* <code>armv7l</code>
* <code>arm64</code>

لتوضيح ذلك فإن الإعدادات التالية ستُولّد حزمة <code>dmg</code> لمعمارية <code>x64</code>:

<syntaxhighlight class="" lang="json">{
    "electron": {
        "mac": {
            "package": [ "dmg" ],
            "arch": [ "x64" ]
        }
    }
}</syntaxhighlight>
=== كيفية دعم إصدار متعدد المنصّات ===

'''ملاحظة''': لا تدعم جميع المنصّات هذه الميزة وقد يتضمن استخدامها قيودًا على منصات أخرى.

من الممكن إنشاء تطبيق يعمل على منصات متعددة باستخدام نظام تشغيل واحد لكن ذلك قد يتضمن قيودًا ما. لذلك يُنصح باستخدام نظام التشغيل المستهدف لإنشاء تطبيق يعمل على نفس النظام. يعرض الجدول التالي التطبيقات متعددة المنصّات التي يمكن لكلّ نظام تشغيل إنشاءها:

{| class="wikitable"
! '''الخادم ¹'''
! '''لينكس'''
! '''ماك'''
! '''ويندوز'''
|-
| لينكس
| ✅
| -
| ²❗
|-
| ماك ³
| ✅
| ✅
| ²❗
|-
| ويندوز
| -
| -
| ✅
|}'''القيود''':

* ¹ : إذا كان التطبيق يحتوي أيّ مكتبات تستخدم تعليمات لغة الآلة الأصلية لنظام التشغيل المُستهدف، فلن يمكن تفسير التعليمات البرمجية إلّا على نظام التشغيل المُستهدف.
* ² : لا يمكن لنظامي ماك ولينكس إنشاء حزم <code>Appx</code> التي تستهدف متجر تطبيقات ويندوز.
* ³ : ستُحمّل جميع متطلّبات النظام تلقائيًا عند الطلب ما عدا مدير حزم <code>RPM</code> والذي ستحتاج إلى تحميله باستخدام أداة <code>brew</code> (متاحة لإصدار ماك Sierra 10.12 أو أعلى).

سيُفعّل الضبط التالي ميزة إنشاء إصدار متعدِّد المنصّات لجميع أنظمة التشغيل المُدرَجة باستخدام الإعدادات الافتراضية:

<syntaxhighlight class="" lang="json">{
    "electron": {
        "linux": {},
        "mac": {},
        "windows": {}
    }
}</syntaxhighlight>
== إعدادات التوقيع ==

=== التوقيع لنظام ماك ===

هناك ثلاثة أنواع من أهداف التوقيع (signing) هي <code>debug</code> و<code>release</code> و<code>store</code>. يحتوي كلّ منها على الخصائص التالية:

{| class="wikitable"
! '''مفتاح الكائن'''
! '''الوصف'''
|-
| <code>entitlements</code>
| قيمة المسار إلى ملف الاستحقاقات (entitlements file)
|-
| <code>entitlementsInherit</code>
| قيمة المسار إلى ملف الاستحقاقات الذي يرث إعدادات الأمان
|-
| <code>identity</code>
| نص يحتوي على اسم الشهادة
|-
| <code>requirements</code>
| قيمة المسار إلى ملف المتطلبات -❗لاحظ أن هذا المفتاح غير متاح في إعدادات توقيع إصدار المتجر (mas)
|-
| <code>provisioningProfile</code>
| قيمة المسار إلى ملف التزويد (provisioning profile)
|}

مثال على ذلك:

<syntaxhighlight class="" lang="json">{
    "electron": {
        "mac": {
            "package": [
                "dmg",
                "mas",
                "mas-dev"
            ],
            "signing": {
                "release": {
                    "identity": "APACHE CORDOVA (TEAMID)",
                    "provisioningProfile": "release.mobileprovision"
                }
            }
        }
    }
}</syntaxhighlight>
هناك بعض الاستثناءات لكيفية استخدام توقيع المعلومات في نظام ماك. لكن تستخدم جميع إصدرات الحزم إعدادات توقيع <code>debug</code> و <code>release</code> افتراضيًّا،  ما عدا <code>mas</code> و<code>mas-dev</code>.

لنستخدم المثال سابق الذكر لمراجعة بعض الحالات لتعميق فهمنا لتلك الاستثناءات.

'''الحالة الأولى''':

<syntaxhighlight class="" lang="bash">cordova build electron --debug</syntaxhighlight>
يهدف الأمر أعلاه إلى:

* توليد إصداري <code>dmg</code> و<code>mas-dev</code> باستخدام إعدادات توقيع <code>debug</code>.
* تجاهل توليد حزمة <code>mas</code> التي تستهدف نظام تشغيل ماك.

'''الحالة الثانية''':

<syntaxhighlight class="" lang="bash">cordova build electron --release</syntaxhighlight>
ينتج عن الأمر السابق:

* توليد إصدار <code>dmg</code> باستخدام إعدادات <code>release</code>.
* توليد إصدار <code>mas</code> باستخدام إعدادات <code>store</code>.
* تجاهل توليد حزمة <code>mas-dev</code>.

=== التوقيع لنظام ويندوز ===

تتضمن معلومات التوقيع الخاصة بنظام ويندوز نوعين من الوسوم هما <code>debug</code> و<code>release</code>، ويحتوي كلّ قسم منهما على الخصائص التالية:

{| class="wikitable"
! '''مفتاح الكائن'''
! '''الوصف'''
|-
| <code>certificateFile</code>
| نص يُمثل قيمة المسار إلى ملف الشهادة
|-
| <code>certificatePassword</code>
| نص يُمثل قيمة كلمة المرور الخاصة بالشهادة. يمكن الاستعاضة عن هذا المفتاح عبر تحديد قيمة متغيّر <code>CSC_KEY_PASSWORD</code> في بيئة التطوير
|-
| <code>certificateSubjectName</code>
| نص يحتوي على موضوع شهادة التوقيع.❗يتطلب هذا المفتاح استخدام ترميز توقيع EV ونظام تشغيل ويندوز
|}

<code>|signingHashAlgorithms|</code>مجموعة الخوارزميات المستخدمة لتوقيع الحزمة (مثلًا sha1 وsha256)، لا تدعم إصدارات <code>AppX</code> سوى خوارزمية تشفير  <code>|sha256certificateSha1|</code>قيمة شفرة <code>SHA1</code> الخاصة بشهادة التوقيع.❗ يتطلب استخدام نظام تشغيل ويندوز| <code>|additionalCertificateFile|</code>قيمة المسار إلى ملفات الشهادة الإضافية|

مثال على توقيع حزمة لنظام تشغيل ويندوز:

<syntaxhighlight class="" lang="json">{
    "electron": {
        "windows": {
            "package": [ "nsis" ],
            "signing": {
                "release": {
                    "certificateFile": "path_to_files",
                    "certificatePassword": "password"
                }
            }
        }
    }
}</syntaxhighlight>
=== التوقيع لنظام لينكس ===

بطبيعة الحال لا يمتلك نظام تشغيل لينكس أيّ متطلبات لتوقيع التطبيقات التي تستهدفه.

== الإضافات ==

يمكن استخدام جميع الإضافات التي تعمل على متصفّحات الإنترنت ضمن منصّة إلكترون. وإذا كانت الإضافة تدعم كلا منصتي إلكترون <code>electron</code> ومتصفح الإنترنت <code>browser</code> (أي تقدّم دعمًا مُدمجًا لإطار عمل إلكترون بالإضافة إلى متصفح الإنترنت)، فسيستخدم إلكترون القسم الذي يستهدفه عند تضمين تلك الإضافة؛ أمّا إذا لم تتضمّن الإضافة أيّ دعم لمنصة إلكترون <code>electron</code> لكنها تحتوي على التعليمات الخاصة بالمتصفح <code>browser</code>، فسيستخدم إلكترون تلك التعليمات لإنشاء التطبيق.

بتفصيل أكثر فإنّ منصّة إلكترون تعتمد على محرك كروميوم (المستخدم في متصفح كروم) لعرض صفحات الويب، وفي ظِل امتلاك بعض الإضافات تعليمات مخصصة لكل متصفح إنترنت، فقد يؤثِّر ذلك على طريقة عمل تلك الإضافات. يُعزى السبب في ذلك إلى دعم إطار عمل إلكترون لمزايا لا تدعمها المتصفِّحات مما قد يتطلب تحديثها لتتوافق بأكثر مع منصّة إلكترون.

ترجمة -وبتصرف- للمقال [https://cordova.apache.org/docs/en/latest/guide/platforms/electron/index.html Electron Platform Guide]، من توثيق [https://cordova.apache.org/ Cordova]