إضافة شريط الحالة في كوردوفا

من موسوعة حسوب

يوفر الكائن StatusBar بعض الدوال التي يمكن استخدامها لتخصيص شريط الحالة في منصتي iOS و أندرويد.

التثبيت

تتطلب هذه الطريقة في التثبيت الإصدارَ 5.0 من كوروفا وما فوقه: 

cordova plugin add cordova-plugin-statusbar‎

لا يزال بالإمكان تثبيت هذه الإضافة على الإصدارات القديمة من كوردوفا عبر المُعرِّف المُهمل التالي: 

cordova plugin add org.apache.cordova.statusbar‎

من الممكن أيضًا تثبيت هذه الإضافة عبر مستودع git مباشرة (إلا أنه غير مستقر) 

cordova plugin add https://github.com/apache/cordova-plugin-statusbar.git‎

تفضيلات

الملف Config.xml

  • StatusBarOverlaysWebView: (قيمة منطقية، القيمة الافتراضية هي true). على منصة iOS 7، هذا الخيار يجعل شريط الحالة يركَب (overlay) على العارض أو العكس عند بدء التشغيل.
<preference name="StatusBarOverlaysWebView" value="true" />‎
  • StatusBarBackgroundColor: (سلسلة نصية تمثل لونًا سداسعشريًا [color hex]، بدون قيمة افتراضية). على منصة iOS 7، يضبط هذا الخيار لون خلفية شريط الحالة، حيث يعطيها اللون المُتضمّن في السلسلة النصية السداسعشرية (‎#RRGGBB) عند بدء التشغيل. إذا لم يتم تعيين هذه القيمة، فسيكون لون الخلفية شفافًا.
<preference name="StatusBarBackgroundColor" value="#000000" />‎
  • StatusBarStyle: (نمط شريط الحالة، االقيمة الافتراضية هي lightcontent). على منصة iOS 7، يعيّن هذا الخيار نمط شريط الحالة. الخيارات الافتراضية المتاحة هي: lightcontent و blacktranslucent و blackopaque.
<preference name="StatusBarStyle" value="lightcontent" />‎
  • StatusBarDefaultScrollToTop: (قيمة منطقية، القيمة الافتراضية تساوي false). في نظام التشغيل iOS 7، يتيح هذا الخيار لعارض كوروفا استخدام السلوك الافتراضي في التمرير إلى الأعلى (scroll-to-top). القيمة الافتراضية هي false، ما يعني أنّه يمكنك الاستماع إلى الحدث "statusTap" (الموضح أدناه) وتخصيص السلوك.
<preference name="StatusBarDefaultScrollToTop" value="false" />‎

ملاحظات خاصة بمنصة أندرويد

توصي إرشادات منصة أندرويد من الإصدار 5 وما بعده، بأن يكون لون شريط الحالة مختلفًا عن لون التطبيق الرئيسي (بخلاف لون شريط الحالة المُوحّد في العديد من تطبيقات iOS 7+‎)، لذلك قد ترغب في تعيين لون شريط الحالة في وقت التشغيل عبر التابعين StatusBar.backgroundColorByHexString و StatusBar.backgroundColorByName. فيما يلي إحدى الطرق الممكنة للقيام بذلك: 

if (cordova.platformId == 'android') {
    StatusBar.backgroundColorByHexString("#333");
}‎

إخفاء شريط الحالة عند بدء التشغيل

خلال وقت التشغيل، يمكنك استخدام الدالة StatusBar.hide أدناه، ولكن إذا كنت تريد إخفاء شريط الحالة عند بدء تشغيل التطبيق، فعليك تعديل الملف Info.plist الخاص بتطبيقك.

أضف أو عدّل هاتين الخاصيتين إذا لم تكونا موجودتين. عيّن "Status bar is initially hidden" إلى القيمة "YES" وعّين "View controller-based status bar appearance" إلى القيمة "NO". إذا عدّلتها يدويًا من دون استخدام بيئة العمل Xcode، فستكون المفاتيح والقيم كما يلي: 

<key>UIStatusBarHidden</key>
<true/>
<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>‎

التوابع

تعرِّف هذه الإضافة كائنًا عامًّا StatusBar.

على الرغم من أنّ هذا الكائن موجود في النطاق العام (global scope)، إلا أنه لن يكون متوفرًا إلا بعد إطلاق الحدث deviceready. 

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(StatusBar);
}‎
  • StatusBar.overlaysWebView
  • StatusBar.styleDefault
  • StatusBar.styleLightContent
  • StatusBar.styleBlackTranslucent
  • StatusBar.styleBlackOpaque
  • StatusBar.backgroundColorByName
  • StatusBar.backgroundColorByHexString
  • StatusBar.hide
  • StatusBar.show

الخاصيات

  • StatusBar.isVisible

الأحداث

  • statusTap

StatusBar.overlaysWebView

على منصة iOS 7، يجعل هذا التابعُ شريطَ الحالة يركب (overlay) على العارض، أو العكس. 

StatusBar.overlaysWebView(true);‎

الوصف

على منصة iOS 7، اضبط هذا الخيار عند القيمة false لإظهار شريط الحالة مثل ما هو الحال في منصة iOS 6. قم بتعيين نمط ولون الخلفية بالشكل الذي تراه مناسبًا باستخدام الدوال الأخرى.

المنصات المدعومة

  • iOS

مثال سريع

StatusBar.overlaysWebView(true);
StatusBar.overlaysWebView(false);‎

StatusBar.styleDefault

استدع هذا التابع لاستخدام شريط الحالة الافتراضي (نص غامق على خلفية فاتحة). 

StatusBar.styleDefault();‎

المنصات المدعومة

  • iOS
  • أندرويد 6 وما بعده
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.styleLightContent

استدع هذا التابع لأجل استخدام شريط الحالةlightContent (نص فاتح على خلفية داكنة). 

StatusBar.styleLightContent();‎

المنصات المدعومة

  • iOS
  • أندرويد 6 وما بعده
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.styleBlackTranslucent

استدع هذا التابع لاستخدام شريط الحالة من النوع blackTranslucent (نص فاتح، على خلفية داكنة). 

StatusBar.styleBlackTranslucent();‎

المنصات المدعومة

  • iOS
  • أندرويد 6 وما بعده
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.styleBlackOpaque

استدع هذا التابع لاستخدام شريط الحالة من النوع blackOpaque (نص فاتح على خلفيات داكنة). 

StatusBar.styleBlackOpaque();‎

المنصات المدعومة

  • iOS
  • أندرويد 6 وما بعده
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.backgroundColorByName

على منصة iOS 7، عند ضبط الخاصية StatusBar.statusBarOverlaysWebView عند القيمة false، فيمكنك تعيين لون خلفية شريط الحالة باسم اللون. 

StatusBar.backgroundColorByName("red");‎

أسماء الألوان المدعومة هي: 

black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown‎

المنصات المدعومة

  • iOS
  • أندرويد الإصدار 5 وما بعده
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.backgroundColorByHexString

يعيّن هذا التابع لون خلفية شريط الحالة عبر إعطائه سلسلة نصية تحتوي لونًا سداسعشريًا (hex). 

StatusBar.backgroundColorByHexString("#C0C0C0");‎

اختصارات ألوان CSS مدعومةٌ أيضًا. 

StatusBar.backgroundColorByHexString("#333"); // => #333333
StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB‎

على منصة iOS 7، عند ضبط الخاصية StatusBar.statusBarOverlaysWebView عند القيمة false، فيمكنك تعيين لون خلفية شريط الحالة عبر سلسلة نصية سداسعشرية (‎#RRGGBB).

على منصتي WP7 و WP8، يمكنك أيضًا تحديد قيم من قبيل ‎#AARRGGBB، حيث تمثل AA قيمة الشفافية ألفا (alpha value)

المنصات المدعومة

  • iOS
  • أندرويد 5 ومابعده
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.hide

يخفي هذا التابع شريط الحالة. 

StatusBar.hide();‎

المنصات المدعومة

  • iOS
  • أندرويد
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.show

يعرض هذا التابع شريط الحالة. 

StatusBar.show();‎

المنصات المدعومة

  • iOS
  • أندرويد
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

StatusBar.isVisible

تحقق من هذه الخاصية لمعرفة ما إذا كان شريط الحالة مرئيًا أم لا. 

if (StatusBar.isVisible) {
    // افعل شيئًا ما
}‎

المنصات المدعومة

  • iOS
  • أندرويد
  • Windows Phone 7
  • Windows Phone 8
  • Windows Phone 8.1

statusTap

أنصِت لهذا الحدث لمعرفة ما إذا تم النقر على شريط الحالة. 

window.addEventListener('statusTap', function() {
    // أو افعل ما تريد ،document.body.scrollTop = 0 مرّر إلى أعلى عبر
});‎

المنصات المدعومة

  • iOS

انظر أيضا

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Cordova/cordova_plugin_statusbar&oldid=26662»