دليل استخدام منصة إلكترون (Electron) في Cordova

إلكترون (Electron) هو إطار عمل يستخدم تقنيات الويب (مثل HTML وCSS وJS) لبناء تطبيقات حاسوب عابرة للمنصات (أي تعمل على منصّات مختلفة).

متطلبات النظام لتشغيل إطار عمل إلكترون

نظام لينكس

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

نظام ماك

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

brew install rpm

نظام تشغيل ويندوز

• الإصدار 2.7.10 أو أعلى من بايثون.
• واجهة سطر أوامر PowerShell. لكن إذا كنت تستخدم نظام تشغيل Windows 7، فستحتاج إلى الإصدار 3.0 على الأقل لتتمكن من توقيع التطبيقات.
• أدوات استكشاف وإصلاح المشاكل لنظام ويندوز. وهي حزمة أدوات لتعزيز قدرات استكشاف الأخطاء ويُنصح بتثبيتها مع الإصدار 10.0.15063.468 من حزمة أدوات تطوير ويندوز (Windows SDK).

نظرة سريعة

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

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

npm i -g cordova
cordova create sampleApp
cd  sampleApp
cordova platform add electron

ملاحظة: إذا كنت تستخدم واجهة سطر أوامر كوردوفا أقدم من الإصدار 9، فستحتاج إلى استخدام دالّة cordova-electron عوضًا عن دالّة electron لأيّ تعليمة تتطلّب ذكر اسم المنصّة. مثال على ذلك:

cordova platform add cordova-electron
cordova run cordova-electron

استعراض مشروع كوردوفا

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

cordova run electron --nobuild

بناء مشروع كوردوفا

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

cordova build electron
cordova build electron --debug

الإصدار المستقر

cordova build electron --release

تخصيص خيارات نافذة التطبيق

يوفر إطار عمل إلكترون خيارات متعدِّدة للتحكم بنافذة المُستعرض وسيُغطي هذا القسم كيفية إعداد بعض الخيارات الأساسية. راجع قسم خيارات نافذة العرض من توثيق إلكترون لرؤية كامل قائمة الخيارات.

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

<platform name="electron">
    <preference name="ElectronSettingsFilePath" value="res/electron/settings.json" />
</platform>

إذا أردت تغيير أيٍّ من خيارات نافذة المُستعرض (BrowserWindow) الافتراضية، فستحتاج إلى إضافة تلك الخيارات إلى مُكوِّن browserWindow الموجود في ملف res/electron/settings.json كما هو موضَّح أدناه:

{
    "browserWindow": { ... }
}

كيفية تحديد حجم النافذة الافتراضي

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

{
    "browserWindow": {
        "width": 1024,
        "height": 768
    }
}

كيفية منع تغيير حجم نافذة المستعرض

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

{
    "browserWindow": {
        "resizable": false
    }
}

كيفية استخدام العرض الكامل لنافذة المستعرض

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

{
    "browserWindow": {
        "fullscreen": true
    }
}

كيفية دعم نظام برامج Node.js وواجهة برمجة تطبيقات إلكترون (Electron APIs)

حدد قيمة خاصية nodeIntegration إلى true لدعم مكتبات Node.js واستخدام الرموز التي يتشاركها Node.js وإلكترون كما هو موضح في المثال التالي. افتراضيًّا تًعَدّ قيمة هذه الخاصية هي false ويمكنك قراءة المزيد من التفاصيل حول دعم مكتبات - RequireJS - Meteor - AngularJS و jQuery في توثيق إلكترون.

{
    "browserWindow": {
        "webPreferences": {
            "nodeIntegration": false
        }
    }
}

تخصيص عملية إلكترون الرئيسية

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

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

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

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

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

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

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

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

لينكس

الحزمة	المعمارية
tar.gz	x64

ماك

الحزمة	المعمارية
dmg	x64
zip	x64

ويندوز

الحزمة	المعمارية
nsis	x64

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

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

{
    "electron": {}
}

بما أنّ إطار عمل إلكترون يُستخدم لإنشاء تطبيقات عابرة للمنصات (أي تعمل على أنظمة تشغيل مختلفة)، فستحتاج إلى تخصيص إعدادات منفصلة لكلّ منصّة على حدة. يتضمن مكوّن إلكترون الموجود في ملفّ build.json ثلاث خصائص تفصِل بين إعدادات الإصدار لكلّ نظام تشغيل كما هو موضّح في المثال التالي:

{
    "electron": {
        "linux": {},
        "mac": {},
        "windows": {}
    }
}

يحتوي كلّ مكوِّن على الخصائص اللازمة لتحديد أيّ حزمة يجب توليدها وكيف تُوقّع.

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

• الحزمة (package): وهي مصفوفة تضمّ ترميز الإصدارات التي ستوَلّد لاحقًا.
• المعمارية (arch): وهي مصفوفة من المعماريات التي تستهدفها كلّ حزمة منفصلة.
• التوقيع (signing): وهو مُكوِّن يحتوي معلومات التوقيع. راجع صفحة إعدادات التوقيع لمزيد من المعلومات عن هذه النقطة.

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

إضافة حزمة

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

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

{
    "electron": {
        "mac": {
            "package": [
                "dmg",
                "tar.gz",
                "zip"
            ]
        }
    }
}

الحزم المتاحة لكل نظام تشغيل:

نوع الحزمة	لينكس	ماك	ويندوز
default	-	dmg - zip	-
dmg	-	✅	-
mas	-	✅	-
mas-dev	✅	-	-
pkg	-	✅	-
7z	✅	✅	✅
zip	✅	✅	✅
tar.xz	✅	✅	✅
tar.lz	✅	✅	✅
tar.gz	✅	✅	✅
tar.bz2	✅	✅	✅
dir	✅	✅	✅
nsis	-	-	✅
nsis-web	-	-	✅
portable	-	-	✅
appx	-	-	✅¹
msi	-	-	✅
AppImage	✅	-	-
snap	✅	-	-
deb	✅	-	-
rpm	✅	-	-
freebsd	✅	-	-
pacman	✅	-	-
p5p	✅	-	-
apk	✅	-	-

• ¹ يجدر بنا التنويه إلى أنّ الإصدار 10 فقط من نظام تشغيل ويندوز يمكنه إنشاء حزمة AppX.

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

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

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

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

• ia32
• x64
• armv7l
• arm64

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

{
    "electron": {
        "mac": {
            "package": [ "dmg" ],
            "arch": [ "x64" ]
        }
    }
}

كيفية دعم إصدار متعدد المنصّات

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

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

الخادم ¹	لينكس	ماك	ويندوز
لينكس	✅	-	❗²
ماك ³	✅	✅	❗²
ويندوز	-	-	✅

القيود:

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

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

{
    "electron": {
        "linux": {},
        "mac": {},
        "windows": {}
    }
}

إعدادات التوقيع

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

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

مفتاح الكائن	الوصف
entitlements	قيمة المسار إلى ملف الاستحقاقات (entitlements file)
entitlementsInherit	قيمة المسار إلى ملف الاستحقاقات الذي يرث إعدادات الأمان
identity	نص يحتوي على اسم الشهادة
requirements	قيمة المسار إلى ملف المتطلبات ❗لاحظ أن هذا المفتاح غير متاح في إعدادات توقيع إصدار المتجر (mas)
provisioningProfile	قيمة المسار إلى ملف التزويد (provisioning profile)

مثال على ذلك:

{
    "electron": {
        "mac": {
            "package": [
                "dmg",
                "mas",
                "mas-dev"
            ],
            "signing": {
                "release": {
                    "identity": "APACHE CORDOVA (TEAMID)",
                    "provisioningProfile": "release.mobileprovision"
                }
            }
        }
    }
}

هناك بعض الاستثناءات لكيفية استخدام توقيع المعلومات في نظام ماك. لكن تستخدم جميع إصدرات الحزم إعدادات توقيع debug و release افتراضيًّا، ما عدا mas وmas-dev.

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

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

cordova build electron --debug

يهدف الأمر أعلاه إلى:

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

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

cordova build electron --release

ينتج عن الأمر السابق:

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

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

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

مفتاح الكائن	الوصف
certificateFile	نص يُمثل قيمة المسار إلى ملف الشهادة
certificatePassword	نص يُمثل قيمة كلمة المرور الخاصة بالشهادة. يمكن الاستعاضة عن هذا المفتاح عبر تحديد قيمة متغيّر CSC_KEY_PASSWORD في بيئة التطوير
certificateSubjectName	نص يحتوي على موضوع شهادة التوقيع. ❗يتطلب هذا المفتاح استخدام ترميز توقيع EV ونظام تشغيل ويندوز
signingHashAlgorithms	مجموعة الخوارزميات المستخدمة لتوقيع الحزمة (مثلًا sha1 وsha256)، لا تدعم إصدارات AppX سوى خوارزمية تشفير
sha256certificateSha1	قيمة شفرة SHA1 الخاصة بشهادة التوقيع. ❗ يتطلب استخدام نظام تشغيل ويندوز
additionalCertificateFile	قيمة المسار إلى ملفات الشهادة الإضافية

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

{
    "electron": {
        "windows": {
            "package": [ "nsis" ],
            "signing": {
                "release": {
                    "certificateFile": "path_to_files",
                    "certificatePassword": "password"
                }
            }
        }
    }
}

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

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

الإضافات

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

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

المصادر

• صفحة Electron Platform Guide من توثيق Cordova