react native safe area context

رد الفعل الآمن منطقة آمن

طريقة مرنة للتعامل مع منطقة آمنة ، تعمل أيضًا على Android و Web!

ابدء

npm install react-native-safe-area-context

yarn add react-native-safe-area-context

تحتاج بعد ذلك إلى ربط الأجزاء الأصلية للمكتبة للمنصات التي تستخدمها.

• منصة iOS:

  $ npx pod-install

نسخة داعمة React-Itive

إصدار	رد الفعل الأصلي
5	0.74
4	0.64

دعم الهندسة المعمارية الجديدة

هذه المكتبة لديها حاليًا دعم تجريبي للعمارة الجديدة منصقة React. لاحظ أنه سيكون هناك تغييرات في كسر وسيتم دعم أحدث إصدار من React-Native.

الاستخدام

تحتوي هذه المكتبة على مفهومين مهمين ، إذا كنت على دراية بسياق React ، فهذا مشابه جدًا.

مقدمي الخدمات

مكون SafeAreaProvider هو View من حيث يوفره المستهلكون. هذا يعني أنه إذا تتداخل هذا العرض مع أي عناصر النظام (شريط الحالة ، الشقوق ، وما إلى ذلك) ، فسيتم توفير هذه القيم للمستهلكين المنحدرين. عادةً ما يكون لديك مزود واحد في الجزء العلوي من التطبيق الخاص بك.

المستهلكون

المستهلكون عبارة عن مكونات وخطافات تسمح باستخدام قيم أقصى أقصى المقدمة من أقرب موفر الوالدين. تكون القيم دائمًا بالنسبة إلى مزود وليس لهذه المكونات.

• SafeAreaView هي الطريقة المفضلة لاستهلاك insets. هذا هو View منتظمة مع إدراج مطبق كحشوة أو هامش إضافي. إنه يوفر أداء أفضل من خلال تطبيق Insets أصلاً وتجنب وميض يمكن أن يحدث مع المستهلكين الآخرين القائم على JS.

• يوفر UseveaReaInsets مزيدًا من المرونة ، ولكنه يمكن أن يتسبب في وميض تخطيط في بعض الحالات. استخدم هذا إذا كنت بحاجة إلى مزيد من التحكم في كيفية تطبيق Insets.

API

SafeAreaProvider

يجب عليك إضافة SafeAreaProvider في مكون جذر التطبيق الخاص بك. قد تحتاج إلى إضافته في أماكن أخرى مثل جذر الوسائط والطرق عند استخدام react-native-screens .

لاحظ أنه لا ينبغي أن يكون مقدمو الخدمات داخل View متحركة مع Animated أو داخل عرض ScrollView لأنه يمكن أن يسبب تحديثات متكررة للغاية.

مثال

 import { SafeAreaProvider } from 'react-native-safe-area-context' ;

function App ( ) {
  return < SafeAreaProvider > ... </ SafeAreaProvider > ;
} 

الدعائم

يقبل جميع الدعائم عرض. لديه نمط افتراضي من {flex: 1} .

initialMetrics

اختياري ، الافتراضات إلى null .

يمكن استخدامها لتوفير القيمة الأولية للإطار والأطقاس ، وهذا يسمح بالعرض على الفور. انظر التحسين لمزيد من المعلومات حول كيفية استخدام هذا الدعامة.

SafeAreaview

SafeAreaView هو مكون View منتظم مع إدراج المنطقة الآمنة المطبقة كحشو أو هامش.

تتم إضافة أنماط الحشوة أو الهامش إلى insets ، على سبيل المثال style={{paddingTop: 10}} على SafeAreaView الذي يحتوي على 20 سيؤدي إلى حشو أعلى من 30.

مثال

 import { SafeAreaView } from 'react-native-safe-area-context' ;

function SomeComponent ( ) {
  return (
    < SafeAreaView style = { { flex : 1 , backgroundColor : 'red' } } >
      < View style = { { flex : 1 , backgroundColor : 'blue' } } />
    </ SafeAreaView >
  ) ;
} 

الدعائم

يقبل جميع الدعائم عرض.

edges

اختياري ، مجموعة من top ، right ، bottom ، left . الإعدادات الافتراضية للجميع.

يحدد الحواف لتطبيق insets المنطقة الآمنة على.

على سبيل المثال ، إذا كنت لا تريد أن تنطبق Insets على الحافة العليا لأن العرض لا يمس الجزء العلوي من الشاشة: يمكنك استخدامه:

 < SafeAreaView edges = { [ 'right' , 'bottom' , 'left' ] } />

اختياريا يمكن ضبطه على كائن { top?: EdgeMode, right?: EdgeMode, bottom?: EdgeMode, left?: EdgeMode } أين EdgeMode = 'off' | 'additive' | 'maximum' . الإضافة هي الوضع الافتراضي وهي نفس النجاح والحافة في المصفوفة: finalPadding = safeArea + padding . سيستخدم الحد الأقصى للوضع أقحم المنطقة الآمن أو الحشو/الهامش (يعتمد على mode ) إذا كانت المساحة الآمنة أقل: finalPadding = max(safeArea, padding) . على سبيل المثال ، إذا كنت تريد عنصر واجهة مستخدم عائم يجب أن يكون في حافة المنطقة الآمنة السفلية على الأجهزة ذات المساحة الآمنة أو 24 بكسل من أسفل الشاشة على الأجهزة بدون مساحة آمنة أو إذا كانت المنطقة الآمنة أقل من 24 بكسل:

 < SafeAreaView style = { { paddingBottom : 24 } } edges = { { bottom : 'maximum' } } /> 

mode

اختياري ، padding (افتراضي) أو margin .

تطبيق المنطقة الآمنة على الحشو أو الهامش.

قد يكون هذا مفيدًا على سبيل المثال لإنشاء مكون فاصل آمن ARAY ARAY:

 < SafeAreaView mode = "margin" style = { { height : 1 , backgroundColor : '#eee' } } />

يستخدم exafeareainsets

إرجاع insets المنطقة الآمنة لأقرب مزود. هذا يسمح بمعالجة قيم أقحم من JavaScript. لاحظ أنه لا يتم تحديث insets بشكل متزامن بحيث قد يتسبب في تأخير طفيف على سبيل المثال عند تدوير الشاشة.

كائن مع { top: number, right: number, bottom: number, left: number } .

 import { useSafeAreaInsets } from 'react-native-safe-area-context' ;

function HookComponent ( ) {
  const insets = useSafeAreaInsets ( ) ;

  return < View style = { { paddingBottom : Math . max ( insets . bottom , 16 ) } } /> ;
}

يستخدم afeareaframe

إرجاع إطار أقرب مزود. يمكن استخدام هذا كبديل لوحدة Dimensions .

كائن مع { x: number, y: number, width: number, height: number }

SafeAreaInsetsContext

رد فعل السياق مع قيمة insets المنطقة الآمنة.

يمكن استخدامها مع مكونات الفصل:

 import { SafeAreaInsetsContext } from 'react-native-safe-area-context' ;

class ClassComponent extends React . Component {
  render ( ) {
    return (
      < SafeAreaInsetsContext . Consumer >
        { ( insets ) => < View style = { { paddingTop : insets . top } } /> }
      </ SafeAreaInsetsContext . Consumer >
    ) ;
  }
}

withSafeAreaInsets

مكون عالي الترتيب الذي يوفر إدراج منطقة آمنة مثل الدعامة insets .

 type Props = WithSafeAreaInsetsProps & {
  someProp : number ;
} ;

class ClassComponent extends React . Component < Props > {
  render ( ) {
    return < View style = { { paddingTop : this . props . insets . top } } / >;
  }
}

const ClassComponentWithInsets = withSafeAreaInsets ( ClassComponent ) ;

< ClassComponentWithInsets someProp = { 1 } / > ;

SafeAreaFrameContext

رد فعل سياق مع قيمة إطار المنطقة الآمنة.

initialWindowMetrics

insets وإطار النافذة على العرض الأولي. يمكن استخدام هذا مع initialMetrics من SafeAreaProvider . انظر التحسين لمزيد من المعلومات.

اعتراض مع:

 {
  frame : { x : number , y : number , width : number , height : number } ,
  insets : { top : number , left : number , right : number , bottom : number } ,
}

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

واجهات برمجة التطبيقات المنهكة

يستخدم

استخدام useSafeAreaInsets بدلا من ذلك.

SafeAreAconsumer

استخدم SafeAreaInsetsContext.Consumer بدلاً من ذلك.

SafeAreaContext

استخدم SafeAreaInsetsContext بدلاً من ذلك.

initialwindowsafeareainsets

استخدم initialWindowMetrics بدلاً من ذلك.

الويب SSR

إذا كنت تقوم بتقديم جانب الخادم على الويب ، فيمكنك استخدام initialMetrics لحقن الإينترات وقيمة الإطار بناءً على الجهاز الذي يتمتع به المستخدم ، أو ببساطة تمرير قيم صفر. نظرًا لأن قياس insets غير متزامن ، فإنه سيؤدي إلى كسر محتوى صفحتك خلاف ذلك.

تحسين

إذا استطعت ، استخدم SafeAreaView . يتم تنفيذه أصليًا ، لذلك عند تدوير الجهاز ، لا يوجد تأخير من الجسر غير المتزامن.

لتسريع العرض الأولي ، يمكنك استيراد initialWindowMetrics من هذه الحزمة وتعيينها كدعم initialMetrics على المزود كما هو موضح في الويب SSR. لا يمكنك القيام بذلك في حالة إعادة تشكيل مزودك ، أو كنت تستخدم react-native-navigation .

 import {
  SafeAreaProvider ,
  initialWindowMetrics ,
} from 'react-native-safe-area-context' ;

function App ( ) {
  return (
    < SafeAreaProvider initialMetrics = { initialWindowMetrics } >
      ...
    </ SafeAreaProvider >
  ) ;
} 

الاختبار

هذه المكتبة تتضمن وهمية مدمجة للشرق. سوف تستخدم المقاييس التالية افتراضيا:

 {
  frame : {
    width : 320 ,
    height : 640 ,
    x : 0 ,
    y : 0 ,
  } ,
  insets : {
    left : 0 ,
    right : 0 ,
    bottom : 0 ,
    top : 0 ,
  } ,
}

لاستخدامه ، أضف الكود التالي إلى ملف إعداد Jest:

 import mockSafeAreaContext from 'react-native-safe-area-context/jest/mock' ;

jest . mock ( 'react-native-safe-area-context' , ( ) => mockSafeAreaContext ) ;

للحصول على مزيد من التحكم في قيم الاختبار ، من الممكن أيضًا تمرير initialMetrics إلى SafeAreaProvider لتوفير بيانات وهمية للإطار والأشخاص.

 export function TestSafeAreaProvider ( { children } ) {
  return (
    < SafeAreaProvider
      initialMetrics = { {
        frame : { x : 0 , y : 0 , width : 0 , height : 0 } ,
        insets : { top : 0 , left : 0 , right : 0 , bottom : 0 } ,
      } }
    >
      { children }
    </ SafeAreaProvider >
  ) ;
} 

تمكين تحليل بابل للوحدات النمطية

أثناء محاولة استخدام هذا الوهمية ، هناك خطأ في كثير من الأحيان هو:

 SyntaxError : Cannot use import statement outside a module .

تنشأ هذه المشكلة بسبب استخدام بيان الاستيراد. لحلها ، تحتاج إلى السماح بابل بتحليل الملف.

بشكل افتراضي ، لا يقوم Jest بتحليل الملفات الموجودة داخل مجلد Node_Modules.

ومع ذلك ، يمكنك تعديل هذا السلوك كما هو موضح في الوثائق Jest على تخصيص transformIgnorePatterns . إذا كنت تستخدم مسبقًا ، مثل واحد من React-Native ، فيجب عليك تحديث تكوين Jest الخاص بك لتضمين react-native-safe-area-context كما هو موضح أدناه:

transformIgnorePatterns: [
  'node_modules/(?!((jest-)?react-native|@react-native(-community)?|react-native-safe-area-context)/)' ,
] ;

يضمن هذا التعديل بابل بابل بشكل صحيح الوحدات النمطية ، وتجنب خطأ بناء الجملة المذكور أعلاه.

المساهمة

انظر دليل المساهمة