الفرق بين المراجعتين ل"Cordova/platforms electron"
رقية-بورية (نقاش | مساهمات) (رفع المحتوى) |
(لا فرق)
|
مراجعة 10:54، 25 مارس 2021
إلكترون (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