Image في React Native
المكوّن الخاصّ بإظهار مختلف أنواع الصّور في منصّة React، والتي تتضمّن صور الشّبكة وصور المصادر الثّابتة (static resources) والصّور المحلّيّة المؤقّتة والصّور المخزّنة على القرص المحلّي كمعرض الصور.
يبين المثال التّالي كيفيّة جلب الصّور من وسائط التّخزين المحليّة ومن الشّبكة، وكذلك من المعطيات الواردة من :data
الخاصّة بعنوان uri، ثم إظهارها.
ملاحظة: يجب تحديد أبعاد الصورة يدويًّا عند جلبها من الشّبكة أو من المصدر data.
أمثلة
- مثال لمكوِّن دالّة (Function Component)
import React from 'react';
import { View, Image, StyleSheet } from 'react-native';
const styles = StyleSheet.create({
container: {
paddingTop: 50,
},
tinyLogo: {
width: 50,
height: 50,
},
logo: {
width: 66,
height: 58,
},
});
const DisplayAnImage = () => {
return (
<View style={styles.container}>
<Image
style={styles.tinyLogo}
source={require('@expo/snack-static/react-native-logo.png')}
/>
<Image
style={styles.tinyLogo}
source={{
uri: 'https://reactnative.dev/img/tiny_logo.png',
}}
/>
<Image
style={styles.logo}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg==',
}}
/>
</View>
);
}
export default DisplayAnImage;
- مثال لمكوِّن صنف (Class Component)
import React, { Component } from 'react';
import { AppRegistry, View, Image, StyleSheet } from 'react-native';
const styles = StyleSheet.create({
container: {
paddingTop: 50,
},
tinyLogo: {
width: 50,
height: 50,
},
logo: {
width: 66,
height: 58,
},
});
class DisplayAnImage extends Component {
render() {
return (
<View style={styles.container}>
<Image
style={styles.tinyLogo}
source={require('@expo/snack-static/react-native-logo.png')}
/>
<Image
style={styles.tinyLogo}
source={{uri: 'https://reactnative.dev/img/tiny_logo.png'}}
/>
<Image
style={styles.logo}
source={{uri: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='}}
/>
</View>
);
}
}
export default DisplayAnImage;
كما يمكن إضافة تنسيقٍ style
للصّورة كما يلي:
- مثال لمكوِّن دالّة (Function Component)
import React from 'react';
import { View, Image, StyleSheet } from 'react-native';
const styles = StyleSheet.create({
container: {
paddingTop: 50,
},
stretch: {
width: 50,
height: 200,
resizeMode: 'stretch',
},
});
const DisplayAnImageWithStyle = () => {
return (
<View style={styles.container}>
<Image
style={styles.stretch}
source={require('@expo/snack-static/react-native-logo.png')}
/>
</View>
);
}
export default DisplayAnImageWithStyle;
- مثال لمكوِّن صنف (Class Component)
import React, { Component } from 'react';
import { View, Image, StyleSheet } from 'react-native';
const styles = StyleSheet.create({
stretch: {
width: 50,
height: 200,
resizeMode: 'stretch'
}
});
class DisplayAnImageWithStyle extends Component {
render() {
return (
<View>
<Image
style={styles.stretch}
source={require('@expo/snack-static/react-native-logo.png')}
/>
</View>
);
}
}
export default DisplayAnImageWithStyle;
دعم صور GIF وWebP على منصة Android
لا تُدعم الصّور من نوع GIF وWebP افتراضيًّا على منصّة Android عند بناء شفرة أصيلة شخصيّة، لذا يجب إضافة بعض الوحدات الاختياريّة على المسار android/app/build.gradle
بما يتوافق مع حاجة التّطبيق.
dependencies {
// If your app supports Android versions before Ice Cream Sandwich (API level 14)
implementation 'com.facebook.fresco:animated-base-support:1.3.0'
// For animated GIF support
implementation 'com.facebook.fresco:animated-gif:2.0.0'
// For WebP support, including animated WebP
implementation 'com.facebook.fresco:animated-webp:2.1.0'
implementation 'com.facebook.fresco:webpsupport:2.0.0'
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}
الخاصيات
style
الخاصيّة ImageResizeMode
هي من نوع enum
، وتُستخدم لتغيير وضع تحجيم الصور، ويتم ضبطها عن طريق خاصيّة التنسيق ResizeMode
في المكون Image
، ويمكن أن تأخذ إحدى القيم (contain
,cover
, stretch
,center
,repeat
).
النوع | مطلوب |
---|---|
تنسيق (style )
|
لا |
ومن خاصيّات التّنسيق أيضًا:
accessible
لتحديد قابليّة الوصول للصّورة، إذ يمكن الوصول إلى الصّورة إذا كانت قيمتها true
.
النوع | مطلوب | المنصة |
---|---|---|
(bool) | لا | iOS |
accessibilityLabel
النّص الذي سيقرؤه تطبيق قارئ الشّاشة (screen reader) عندما يتفاعل المستخدم مع الصّورة.
النوع | مطلوب | المنصة |
---|---|---|
سلسلة نصية (string) | لا | iOS |
blurRadius
نصف قطر التّمويه (blur) المطبّق على الصورة.
النوع | مطلوب |
---|---|
عدد (number) | لا |
ملاحظة: يجب أن تكون قيمة blurRadius
أكبر من 5
على منصّة IOS.
capInsets
لتثبيت أبعاد الحواف المحدّدة في capInsets
عند تغيير حجم الصّورة، بينما تتمدّد باقي أجزاء الصّورة، وبالتّالي تفيد هذه الخاصيّة في إنشاء عناصر مفيدةٍ متغيّرة الحجم ودائريّة الحوافّ، مثل: الأزرار، والظّلال وغيرها، ويمكن الاطلاع على التّوثيق الرسمي لشركة Apple لمزيدٍ من المعلومات.
النوع | مطلوب | المنصة |
---|---|---|
Rect
|
لا | iOS |
defaultSource
لعرض الصّورة الثّابتة بينما يحمّل مصدر الصّورة.
النوع | مطلوب | المنصة |
---|---|---|
كائن، عدد (number, object) | لا | iOS |
عدد (number) | لا | Android |
فعند تمريرها ككائنٍ فسيكون من الشّكل: {uri: string, width: number, height: number, scale: number}
حيث:
uri
: سلسلةٌ نصّيةٌ تمثّل معرِّف مصدر الصورة (resource identifier)، والذي قد يكون مسار الملف المحلّي، أو مصدر الصّورة الثّابت (المغلَّف بالدالة .require('./path/to/image.png')
)width
،height
: يمكن تحديدها عند البناء إذا كانت معروفةً، وتُستخدم لضبط الأبعاد الافتراضيّة للمكوّن<Image/>
.scale
: تُستخدم لتحديد مقياس رسم (scale) الصورة، والقيمة الافتراضيّة له هي 1.0 والتي تعني أنّ كل بكسل (pixel) من الصورة يقابل نقطة إظهارٍ واحدةٍ DIP.
أمّا عند تمريرها كعددٍ:
number
: نوع مبهم (Opaque) معاد من قبل شيءٍ ما مثل .require('./image.jpg')
ملاحظة: يتم تجاهل هذه الخاصية أثناء البناء الاختباريّ على منصة Android.
fadeDuration
تعمل على منصة Android فقط، وقيمتها الافتراضية هي 300 ميلي ثانية.
النوع | مطلوب | المنصة |
---|---|---|
عدد (number) | لا | Android |
loadingIndicatorSource
تمثّل هذه الخاصية - التي تشبه الخاصّية Source
مصدر المستخدم في إظهار مؤشر تحميل الصورة، والذي سيظهَر إلى أن تجهز الصورة للعرض، أي حتى انتهاء تحميلها من الشّبكة.
النوع | مطلوب |
---|---|
(array of ImageSourcePropTypes, number) | لا |
ملاحظة: يمكنها قبول العدد الذي تعيده .require('./image.jpg')
onError
تُستدعى بالحدث {{nativeEvent: {error}
وذلك عند حدوث خطأ في التّحميل.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onLayout
تُستدعى بالحدث {{{nativeEvent: {layout: {x, y, width, height}
وذلك عند تغيّر التنسيق.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onLoad
تُستدعى عند اكتمال التّحميل بنجاح.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onLoadEnd
تُستدعى عند اكتمال التّحميل سواء أكان ناجحًا أو فاشلًا.
النوع | مطلوب |
---|---|
دالة (function) | لا |
onLoadStart
تُستدعى عند بدء التحميل، مثال: onLoadStart={(e) => this.setState({loading: true})}
النوع | مطلوب |
---|---|
دالة (function) | لا |
onPartialLoad
تُستدعى عند اكتمال تحميل الصّورة جزئيًّا، ويتعلّق تعريف هذا التّحميل الجزئي بالمُحمِّل (loader)، وتستخدم هذه الخاصيّة مع التحميلات المتقدّمة (progressive) لصور JPEG.
النوع | مطلوب | المنصة |
---|---|---|
دالة (function) | لا | iOS |
onProgress
تُستدعى بالحدث {{nativeEvent: {loaded, total}
وذلك عند تقدم التّحميل.
النوع | مطلوب | المنصة |
---|---|---|
دالة (function) | لا | iOS |
progressiveRenderingEnabled
تعمل على منصّة Android فقط، وتُستخدم لتمكين تدفّق (streaming) صور JPEG المتقدم. ويمكن زيارة Progressive JPEGs لمزيد من المعلومات.
النوع | مطلوب | المنصة |
---|---|---|
(bool) | لا | Android |
resizeMethod
تحدّد الطريقة المستخدمة في تغيير أبعاد الصّورة المحمّلة في حال اختلاف أبعادها عن أبعاد واجهة الصورة:
auto
: وهي الطّريقة الافتراضيّة، وتقوم على التّجريب للاختيار بين الطّريقتينresize
، وscale
.resize
: عمليّةٌ برمجيّةٌ تعالج الصّورة المرمّزة (encoded) في الذّاكرة قبل فكّ ترميزها، ويجب استخدامها بدلًا منscale
عندما تكون الصّورة أكبر من الواجهة.scale
: ترسم الصّورة مكبّرةً أو مصغّرة، وهي أسرع من الطّريقتين السّابقتين كونها تَستخدم مسرّع الجهاز الرّسومي (usually hardware accelerated )، وتُنتج صورًا ذات جودةٍ أعلى، كما تستخدَم عندما تكون الصّور أصغر من الواجهة أو أكبر قليلًا.
ويمكن زيارة Resizing لمزيد من المعلومات حول resize
، وscale
.
النوع | مطلوب | المنصة |
---|---|---|
('auto', 'resize', 'scale')
|
لا | Android |
resizeMode
تحدّد الطّريقة التي ستُستخدم لتغيير أبعاد الصّورة الأوّليّة (raw image) في حال اختلاف أبعادها عن أبعاد إطار (frame) الواجهة:
cover
: وهي الطّريقة الافتراضيّة، حيث تغيّر مقياس رسم (scale) الصّورة بانتظامٍ (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أكبر أو تساوي أبعاد الواجهة (بعد طرح الحواشي (padding)).contain
: تغيّر مقياس رسم (scale) الصورة بانتظام (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أصغر أو تساوي أبعاد الواجهة (بعد طرح الحواشي (padding)).stretch
: تغيّر ارتفاع الصورة وعرضها بشكلٍ مستقلٍ (independently)، مما قد يؤدي لتغيير نسبة ارتفاع الصورة إلى عرضها.repeat
: تكرر الصورة حتى تغطي كامل إطار الواجهة مع المحافظة على أبعادها إذا كانت أصغر من الواجهة؛ أمّا إذا كانت أكبر منها فستغيّر مقياس رسم الصّورة بانتظام بحيث تحتويها الواجهة.center
: تضع الصورة في مركز الإطار بحيث تكون أبعادها موازيةً لأبعاد الواجهة إذا كانت أصغر منها؛ أمّا إذا كانت أكبر منه فستغيّر مقياس رسم الصّورة بانتظامٍ بحيث تحتويها الواجهة.
النوع | مطلوب |
---|---|
('cover', 'contain', 'stretch', 'repeat', 'center')
|
لا |
source
تمثّل هذه الخاصيّة مصدر الصّورة، سواء كان عنوان URL بعيدًا (remote) أو ملفًّا محلّيًّا (local).
كما يمكن أن تتضمن هذه الخاصيّة العديد من عناوين URL البعيدة مع تحديد العرض، والارتفاع وربّما مقياس الرّسم وغيرها من معاملات URL، فيقوم التّطبيق الأصيل باختيار أفضل uri
ليعرضه وذلك اعتمادًا على أبعاد حاوية الصورة (image container)، كما يمكن إضافة الخاصية cache
للتحكم بكيفيّة تفاعل الطّلبات الشّبكيّة مع التخزين المحلّيّ المؤقّت (local cache). ويمكن الإطلاع على التحكم بالتخزين المؤقت للصور لمزيد من المعلومات.
صيغ الصّور (format) المدعومة حاليًّا على منصّة Android هي: (png
, jpg
,jpeg
, bmp
, gif
,webp
)، والصيغة psd
على منصة iOS. كما تدعم منصة iOS العديد من صيغ الصّور الصّرفة (RAW)، ويمكن الرّجوع إلى توثيق شركة Apple للإطلاع على قائمة الكاميرات المدعومة (وفيما يخص الإصدار iOS 12 فيمكن زيارة support apple.
النوع | مطلوب |
---|---|
ImageSourcePropType | لا |
testID
معرِّف فريد لهذا العنصر يستخدم سكربتات اختبار أتمتة واجهة المستخدم.
التوابع
getSize()
Image.getSize(uri, success, [failure]);
يعيد ارتفاع وعرض الصّورة بالبكسل قبل إظهارها، ويمكن أن يفشل عند عدم وجود الصورة، أو فشل تحميلها.
يجب تحميل الصّورة في البداية، ثم تخزينها مؤقّتًا قبل تمكُّن هذا التّابع من استرجاع أبعادها، ممّا يعني أنّه يمكن من حيث المبدأ استخدام هذا التّابع لتحميل الصّورة مسبقًا (preload)، ومع ذلك فهو ليس الأمثل لهذا الغرض، ويمكن في المستقبل أن يُبرمَج بحيث لا يحتاج لتحميل كامل معطيات الصورة. ويفضل تحميل الصّور مسبقًا عن طريق واجهة برمجيّة مستقلة.
المعاملات
الاسم | النوع | مطلوب | الوصف |
---|---|---|---|
uri
|
سلسلة نصية (string) | نعم | موقع الصورة |
success
|
دالة (function) | نعم | الدالة التي ستطلب عند إيجاد الصورة بنجاحٍ واستعادة ارتفاعها وعرضها |
failure
|
دالة (function) | لا | الدالة التي ستطلب عند حدوث خطأ كالفشل في استعادة الصورة |
getSizeWithHeaders()
Image.getSizeWithHeaders(uri, headers, success, [failure]);
يعيد ارتفاع الصّورة وعرضها بالبكسل قبل إظهارها مع إمكانية إعطاء الترويسات (headers) للطلب، ويمكن أن يفشل عند عدم وجود الصورة أو فشل تحميلها.
يجب تحميل الصورة في البداية، ثمّ تخزينها بشكلٍ مؤقّتٍ قبل تمكُّن هذا التّابع من استرجاع أبعادها، ما يعني أنه يمكن من حيث المبدأ استخدام هذا التابع لتحميل الصّورة مسبقًا (preload)، غير أنّه ليس الأمثل لهذا الغرض، ويمكن في المستقبل أن يُبرمَج بحيث لا يحتاج لتحميل كامل معطيات الصورة. ويفضل أن تحمّل الصور مسبقًا عن طريق واجهة برمجية مستقلة.
لا يعمل مع الصّور ذات المصدر الثّابت.
المعاملات
الاسم | النوع | مطلوب | الوصف |
---|---|---|---|
uri
|
سلسلة نصية (string) | نعم | موقع الصورة |
headers
|
كائن (object) | نعم | ترويسة الطلب |
success
|
دالة (function) | نعم | الدالة التي ستطلب عند إيجاد الصورة بنجاح واستعادة ارتفاعها وعرضها |
failure
|
دالة (function) | لا | الدالة التي ستطلب عند حدوث خطأ كالفشل في استعادة الصورة |
prefetch()
Image.prefetch(url);
يجلب الصّور مسبقًا (prefetche) ويخزّنها على قرص التّخزين المؤقت (disk cache) لتُستخدم فيما بعد.
المعاملات
الاسم | النوع | مطلوب | الوصف |
---|---|---|---|
url
|
سلسلة نصية (string) | نعم | العنوان البعيد لموقع الصورة |
abortPrefetch()
Image.abortPrefetch(requestId);
يلغي طلبات الجلب المسبق للصّور، ويعمل على منصّة Android فقط.
المعاملات
الاسم | النوع | مطلوب | الوصف |
---|---|---|---|
requestId
|
عدد (number) | نعم | المعرف ID المعاد من ()prefetch |
queryCache()
Image.queryCache(urls);
يتحقّق من التّخزين المؤقت، ثمّ يعيد ربطًا (mapping) بين عنوان URL وحالة التّخزين المؤقّت (cache status) له، مثلًا على القرص disk
أم على الذاكرة memory
، وإذا لم يوجد عنوان محدّد في كتلة الربط تلك، فهذا يعني عدم وجوده في المخزن المؤقت.
المعاملات
الاسم | النوع | مطلوب | الوصف |
---|---|---|---|
urls
|
مصفوفة (array) | نعم | قائمة عناوين URL لفحص التخزين المؤقت |
resolveAssetSource()
Image.resolveAssetSource(source);
يعيد المرجع المساعد (asset reference) على شكل كائن له الخاصيّات uri
، وwidth
، وheight
.
المعاملات
الاسم | النوع | مطلوب | الوصف |
---|---|---|---|
source
|
عدد (number)، كائن (object) | نعم | العدد من النوع المبهم الذي تعيده require('./image.jpg')
أو الكائن |
ملاحظة: ImageSource
هو كائنٌ من الشكل .{ uri: '<http location || file path>' }