react native safe area context

react-native-safe-area-context

วิธีที่ยืดหยุ่นในการจัดการพื้นที่ปลอดภัยยังทำงานบน Android และเว็บ!

เริ่มต้น

npm install react-native-safe-area-context

yarn add react-native-safe-area-context

จากนั้นคุณต้องเชื่อมโยงส่วนดั้งเดิมของไลบรารีสำหรับแพลตฟอร์มที่คุณใช้

• แพลตฟอร์ม iOS:

  $ npx pod-install

รองรับเวอร์ชัน React-Natial

รุ่น	เวอร์ชัน React-Native
5	0.74
4	0.64

การสนับสนุนสถาปัตยกรรมใหม่

ปัจจุบันห้องสมุดนี้ได้รับการสนับสนุนจากการทดลองสำหรับสถาปัตยกรรมแบบตอบสนองใหม่ โปรดทราบว่าจะมีการเปลี่ยนแปลงที่แตกหักและจะรองรับ React-Native เวอร์ชันล่าสุดเท่านั้น

การใช้งาน

ห้องสมุดนี้มีแนวคิดสำคัญ 2 ข้อหากคุณคุ้นเคยกับ React Context สิ่งนี้คล้ายกันมาก

ผู้ให้บริการ

ส่วนประกอบ SafeAreAprovider เป็น View จากที่สิ่งที่ใส่เข้าไปโดยผู้บริโภคมีความสัมพันธ์กับ ซึ่งหมายความว่าหากมุมมองนี้ทับซ้อนกับองค์ประกอบของระบบใด ๆ (แถบสถานะรอยบาก ฯลฯ ) ค่าเหล่านี้จะถูกจัดเตรียมให้กับผู้บริโภค โดยปกติคุณจะมีผู้ให้บริการหนึ่งรายที่ด้านบนของแอพของคุณ

ผู้บริโภค

ผู้บริโภคเป็นส่วนประกอบและตะขอที่อนุญาตให้ใช้ค่าสิ่งที่ใส่เข้าไปโดยผู้ให้บริการหลักที่ใกล้ที่สุด ค่ามักจะสัมพันธ์กับผู้ให้บริการเสมอและไม่ใช่ส่วนประกอบเหล่านี้

• Safeareaview เป็นวิธีที่ต้องการในการบริโภคสิ่งที่ใส่เข้าไป นี่คือ View ปกติพร้อมสิ่งที่ใส่เข้าไปเป็นช่องว่างพิเศษหรืออัตรากำไรขั้นต้น มันให้ประสิทธิภาพที่ดีขึ้นโดยการใช้สิ่งที่ใส่เข้าไปโดยธรรมชาติและหลีกเลี่ยงการสั่นไหวที่สามารถเกิดขึ้นได้กับผู้บริโภคที่ใช้ JS รายอื่น

• USEFeareAinsets มีความยืดหยุ่นมากขึ้น แต่อาจทำให้เลย์เอาต์บางส่วนสั่นไหวในบางกรณี ใช้สิ่งนี้หากคุณต้องการควบคุมวิธีการใช้สิ่งที่ใส่เข้าไป

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 ปกติที่มีส่วนประกอบที่ปลอดภัยที่ใช้เป็นช่องว่างภายในหรือระยะขอบ

การเพิ่มรูปแบบหรือระยะขอบจะถูกเพิ่มเข้าไปในสิ่งที่ใส่เข้าไปตัวอย่างเช่น 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 ค่าเริ่มต้นสำหรับทั้งหมด

ตั้งค่าขอบเพื่อใช้สิ่งที่ใส่เข้าไปในพื้นที่ปลอดภัย

ตัวอย่างเช่นหากคุณไม่ต้องการให้สิ่งที่ใส่เข้าไปในขอบด้านบนเนื่องจากมุมมองไม่ได้สัมผัสด้านบนของหน้าจอที่คุณสามารถใช้ได้:

 < 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) ตัวอย่างเช่นหากคุณต้องการองค์ประกอบ UI ที่ลอยอยู่ที่ขอบพื้นที่ปลอดภัยด้านล่างบนอุปกรณ์ที่มีพื้นที่ปลอดภัยหรือ 24px จากด้านล่างของหน้าจอบนอุปกรณ์ที่ไม่มีพื้นที่ปลอดภัยหรือพื้นที่ปลอดภัยน้อยกว่า 24px:

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

mode

ไม่บังคับ, padding (ค่าเริ่มต้น) หรือ margin

ใช้พื้นที่ปลอดภัยกับช่องว่างภายในหรือระยะขอบ

สิ่งนี้มีประโยชน์เช่นในการสร้างส่วนประกอบตัวคั่นที่ปลอดภัยในพื้นที่ที่ปลอดภัย:

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

usefeareainsets

ส่งคืนพื้นที่ที่ปลอดภัยของผู้ให้บริการที่ใกล้ที่สุด สิ่งนี้ช่วยให้การจัดการค่าสิ่งที่ใส่เข้าไปจาก JavaScript โปรดทราบว่าสิ่งที่ใส่เข้าไปจะไม่ได้รับการอัปเดตแบบซิงโครนัสดังนั้นอาจทำให้เกิดความล่าช้าเล็กน้อยเช่นเมื่อหมุนหน้าจอ

วัตถุที่มี { 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 ) } } /> ;
}

USEFEAREAFRAME

ส่งคืนเฟรมของผู้ให้บริการที่ใกล้ที่สุด สิ่งนี้สามารถใช้เป็นทางเลือกแทนโมดูล Dimensions

วัตถุที่มี { x: number, y: number, width: number, height: number }

SafeAreaInsetsContext

ทำปฏิกิริยาบริบทด้วยค่าของพื้นที่ปลอดภัย

สามารถใช้กับส่วนประกอบคลาส:

 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

สิ่งที่ใส่เข้าไปและเฟรมของหน้าต่างในการเรนเดอร์เริ่มต้น สิ่งนี้สามารถใช้กับ initialMetrics จาก SafeAreaProvider ดูการเพิ่มประสิทธิภาพสำหรับข้อมูลเพิ่มเติม

วัตถุกับ:

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

หมายเหตุ: ค่านี้อาจเป็นโมฆะหรือล้าสมัยเนื่องจากคำนวณเมื่อโมดูลดั้งเดิมถูกสร้างขึ้น

APIs ที่ไม่ได้รับการคัดเลือก

USEFEAREA

ใช้ useSafeAreaInsets แทน

safeareaconsumer

ใช้ SafeAreaInsetsContext.Consumer แทน

SafeAreacontext

ใช้ SafeAreaInsetsContext แทน

InitialWindowSafeareainsets

ใช้ initialWindowMetrics แทน

เว็บ SSR

หากคุณกำลังทำเรนเดอร์ด้านเซิร์ฟเวอร์บนเว็บคุณสามารถใช้ initialMetrics เพื่อฉีดสิ่งที่ใส่เข้าไปและค่าเฟรมตามอุปกรณ์ที่ผู้ใช้มีหรือเพียงแค่ผ่านค่าศูนย์ เนื่องจากการวัดที่ใส่เข้าไปคือ async มันจะทำลายการแสดงผลเนื้อหาหน้าเว็บของคุณเป็นอย่างอื่น

การเพิ่มประสิทธิภาพ

ถ้าทำได้ให้ใช้ 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 >
  ) ;
} 

การเปิดใช้งานการแยกย่อยของ Babel สำหรับโมดูล

ในขณะที่พยายามใช้การเยาะเย้ยนี้ข้อผิดพลาดที่พบบ่อยคือ:

 SyntaxError : Cannot use import statement outside a module .

ปัญหานี้เกิดขึ้นเนื่องจากการใช้คำสั่งนำเข้า ในการแก้ไขคุณต้องอนุญาตให้บาเบลแยกวิเคราะห์ไฟล์

โดยค่าเริ่มต้น JEST ไม่ได้แยกวิเคราะห์ไฟล์ที่อยู่ภายในโฟลเดอร์ Node_Modules

อย่างไรก็ตามคุณสามารถปรับเปลี่ยนพฤติกรรมนี้ตามที่ระบุไว้ในเอกสารตลกเกี่ยวกับการปรับแต่ง transformIgnorePatterns หากคุณใช้ค่าที่ตั้งไว้ล่วงหน้าเช่นเดียวกับ React-Native คุณควรอัปเดตการกำหนดค่า jest ของคุณเพื่อรวม react-native-safe-area-context ดังที่แสดงด้านล่าง:

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

การปรับนี้ช่วยให้มั่นใจได้ว่าบาเบลจะแยกโมดูลอย่างถูกต้องโดยหลีกเลี่ยงข้อผิดพลาดทางไวยากรณ์ดังกล่าว

การบริจาค

ดูคู่มือการสนับสนุน