المكون StatusBar في React Native

مكون للتحكم في شريط حالة التطبيق.

الاستخدام مع المكون Navigator

من الممكن تركيب العديد من مكونات StatusBar في نفس الوقت. سيتم دمج الخاصيّات بالترتيب الذي رُكّبت به مكونات StatusBar.

إليك المثال التالي (تجربة حية):

import React, { useState } from 'react';
import { Button, Platform, SafeAreaView, StatusBar, StyleSheet, Text, View } from 'react-native';

const STYLES = ['default', 'dark-content', 'light-content'];
const TRANSITIONS = ['fade', 'slide', 'none'];

const App = () => {
  const [hidden, setHidden] = useState(false);
  const [statusBarStyle, setStatusBarStyle] = useState(STYLES[0]);
  const [statusBarTransition, setStatusBarTransition] = useState(TRANSITIONS[0]);

  const changeStatusBarVisibility = () => setHidden(!hidden);

  const changeStatusBarStyle = () => {
    const styleId = STYLES.indexOf(statusBarStyle) + 1;
    if (styleId === STYLES.length) {
      setStatusBarStyle(STYLES[0]);
    } else {
      setStatusBarStyle(STYLES[styleId]);
    }
  };

  const changeStatusBarTransition = () => {
    const transition = TRANSITIONS.indexOf(statusBarTransition) + 1;
    if (transition === TRANSITIONS.length) {
      setStatusBarTransition(TRANSITIONS[0]);
    } else {
      setStatusBarTransition(TRANSITIONS[transition]);
    }
  };

  return (
    <SafeAreaView style={styles.container}>
      <StatusBar
        animated={true}
        backgroundColor="#61dafb"
        barStyle={statusBarStyle}
        showHideTransition={statusBarTransition}
        hidden={hidden} />
      <Text style={styles.textStyle}>
        StatusBar Visibility:{'\n'}
        {hidden ? 'Hidden' : 'Visible'}
      </Text>
      <Text style={styles.textStyle}>
        StatusBar Style:{'\n'}
        {statusBarStyle}
      </Text>
      {Platform.OS === 'ios' ? (
        <Text style={styles.textStyle}>
          StatusBar Transition:{'\n'}
          {statusBarTransition}
        </Text>
      ) : null}
      <View style={styles.buttonsContainer}>
        <Button
          title="Toggle StatusBar"
          onPress={changeStatusBarVisibility} />
        <Button
          title="Change StatusBar Style"
          onPress={changeStatusBarStyle} />
        {Platform.OS === 'ios' ? (
          <Button
            title="Change StatusBar Transition"
            onPress={changeStatusBarTransition} />
        ) : null}
      </View>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    backgroundColor: '#ECF0F1'
  },
  buttonsContainer: {
    padding: 10
  },
  textStyle: {
    textAlign: 'center',
    marginBottom: 8
  }
});

export default App;

واجهة برمجة تطبيقات أمرية (Imperative API)

في الحالات التي لا يكون فيها استخدام مكوّنٍ أمرًا مناسبًا، هناك أيضًا واجهة برمجة تطبيقات أمريّة متاحة كدوال ساكنة (static functions) على المكون. ومع ذلك، لا يوصى باستخدام واجهة برمجة التطبيقات الساكنة والمكون لنفس الخاصيّة لأن أي قيمة تحددها واجهة برمجة التطبيقات الساكنة ستُتَجاوز (override) وتُبدَّل بواسطة تلك التي حددها المكوّن في التصيير القادم.

الثوابت

‎‎currentHeight‎‎

ارتفاع شريط الحالة، والذي يحوي ارتفاع أي ثلم (notch) في الهاتف إن وجد وهو خاص بمنصة Android فقط.

الخاصيات

‎‎animated‎‎

ما إذا وجب تحريك الانتقال بين تغييرات خاصيّات شريط الحالة. مدعوم لكل من الخاصيّات ‎‎backgroundColor‎‎، و‎‎barStyle‎‎، و‎‎hidden‎‎.

القيمة الافتراضية false.

النوع	مطلوب
قيمة منطقيّة	لا

‎‎backgroundColor‎‎

لون خلفيّة شريط الحالة، وقيمتها الافتراضية هي قيمة لون خلفية StatusBar الافتراضية للنظام أو اللون الأسود 'black' إن لم تُحدَّد.

النوع	مطلوب	المنصة
لون	لا	Android

‎‎barStyle‎‎

تضبط لون نص شريط الحالة، وقيمتها الافتراضية 'default'.

النوع	مطلوب
StatusBarStyle (انظر تعريفات الأنواع في الأسفل)	لا

‎‎hidden‎‎

ما إذا كان شريط الحالة مخفيًا، وقيمتها الافتراضية false.

النوع	مطلوب
قيمة منطقيّة	لا

‎‎networkActivityIndicatorVisible‎‎

ما إذا وجب أن يكون مؤشر نشاط الشبكة مرئيًا وقيمتها الافتراضية false.

النوع	مطلوب	المنصة
قيمة منطقيّة	لا	iOS

‎‎showHideTransition‎‎

تأثير الانتقال عند إظهار وإخفاء شريط الحالة باستخدام الخاصيّة ‎‎hidden‎‎. القيمة الافتراضيّة هي ‎‎'fade'‎‎.

النوع	مطلوب	المنصة
StatusBarAnimation	لا	iOS

‎‎translucent‎‎

ما إذا كان شريط الحالة نصف شفاف. إذا كانت قيمتها القيمةَ ‎‎true‎‎، سيُرسَم التطبيق أسفل شريط الحالة. هذا مفيد عند استخدام لونٍ شبه شفاف لشريط الحالة وقيمتها الافتراضية false.

النوع	مطلوب	المنصة
قيمة منطقيّة	لا	Android

التوابع

‎‎popStackEntry()‎‎

static popStackEntry(entry: any)

الحصول على آخر إِدخالٍ من إدخالات StatusBar من المكدس (stack) وإزالته.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
entry	أي نوع	نعم	الإدخال المعاد من طرف ‎‎pushStackEntry‎‎

‎‎pushStackEntry()‎‎

static pushStackEntry(props: any)

دفع إدخال StatusBar إلى المكدس. يجب تمرير القيمة المُعادة إلى التابع ‎‎popStackEntry‎‎ عند الاكتمال.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
props	أي نوع	نعم	كائن يحتوي على خاصيّات StatusBar لاستخدامها في إدخال المكدس (stack entry).

‎‎replaceStackEntry()‎‎

static replaceStackEntry(entry: any, props: any)

استبدال إدخال مكدس StatusBar موجودٍ بخاصيّاتٍ جديدة.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
entry	أي نوع	نعم	الإدخال المعاد من طرف ‎‎pushStackEntry‎‎ لاستبداله.
props	أي نوع	نعم	كائن يحتوي على خاصيّات StatusBar لاستخدامها في إدخال المكدس البديل.

‎‎setBackgroundColor()‎‎

static setBackgroundColor(color: string, [animated]: boolean)

ضبط لون خلفية شريط الحالة، وهو خاص بنظام Android فقط.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
color	سلسلة نصيّة	نعم	لون الخلفيّة.
animated	قيمة منطقيّة	لا	تحريك تغيُّر النمط.

‎‎setBarStyle()‎‎

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

تعيين نمط شريط الحالة.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
style	StatusBarStyle	نعم	نمط شريط الحالة المرغوب تعيينه.
animated	قيمة منطقيّة	لا	تحريك تغيُّر النمط.

setHidden‎(‎‎)‎

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

إظهار أو إخفاء شريط الحالة.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
hidden	قيمة منطقيّة	نعم	إخفاء شريط الحالة.
animation	StatusBarAnimation	لا	تحريكٌ اختياريّ عند تغيير خاصيّة إخفاء شريط الحالة وهي خاصة بنظام iOS.

‎‎setNetworkActivityIndicatorVisible()‎‎

static setNetworkActivityIndicatorVisible(visible: boolean)

التحكم في إظهار مؤشر نشاط الشبكة، وهو خاص بنظام iOS فقط.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
visible	قيمة منطقيّة	نعم	إظهار المؤشّر.

‎‎setTranslucent()‎

static setTranslucent(translucent: boolean)

التحكّم في شفافية شريط الحالة، وهو خاص بنظام Android فقط.

المعاملات التي يأخذها:

الاسم	النوع	مطلوب	الوصف
translucent	قيمة منطقية	نعم	جعل الشريط شفّافًا.

تعريفات النوع (Type Definitions)

StatusBarAnimation

نوع لتحريك شريط الحالة للتحريكات المطبقة على نظام iOS.

النوع
تعداد enum

الثوابت:

القيمة	النوع	الوصف
'none'	سلسلة نصية	لا تحريك
'fade'	سلسلة نصية	تحريك تلاشي
'slide'	سلسلة نصية	تحريك انزلاق

StatusBarStyle

نوع لنمط شريط الحالة.

النوع
تعداد enum

الثوابت:

القيمة	النوع	الوصف
'default'	سلسلة نصية	نمط شريط الحالة الافتراضي (داكن في نظام التشغيل iOS، فاتح في نظام Android)
'light-content'	سلسلة نصية	خلفيّة داكنة ونصوص بيضاء.
'dark-content'	سلسلة نصية	خلفيّة فاتحة ونصوص داكنة (يتطلّب Android API 23 أو أحدث).

مصادر

• صفحة StatusBar في توثيق React Native الرسمي.