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) عندما يتفاعل المستخدم مع الصورة.
blurRadius
نصف قطر التمويه (blur) المطبّق على الصورة.
| النوع | مطلوب |
|---|---|
| عدد (number) | لا |
ملاحظة: يجب أن تكون قيمة
blurRadiusأكبر من5على منصة IOS.
capInsets
لتثبيت أبعاد الحواف المحدّدة في capInsets عند تغيير حجم الصورة، بينما تتمدّد باقي أجزاء الصّورة، وبالتالي تفيد هذه الخاصية في إنشاء عناصر مفيدةٍ متغيّرة الحجم ودائريّة الحوافّ كالأزرار والظلال وغيرها، ويمكن الاطلاع على التوثيق الرسمي لشركة Apple لمزيدٍ من المعلومات.
defaultSource
لعرض الصّورة الثابتة بينما يحمّل مصدر الصّورة.
فعند تمريرها ككائنٍ فإنه يكون من الشكل: {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 ميلي ثانية.
loadingIndicatorSource
تمثّل هذه الخاصية - التي تشبه الخاصّية Source مصدر المستخدم في إظهار مؤشر تحميل الصورة، والذي سيظهَر إلى أن تجهز الصورة للعرض، أي حتى انتهاء تحميلها من الشّبكة.
ملاحظة: يمكنها قبول العدد الذي تعيده
require('./image.jpg').
onError
تُستدعى بالحدث {nativeEvent: {error}} وذلك عند حدوث خطأ في التحميل.
onLayout
تُستدعى بالحدث {nativeEvent: {layout: {x, y, width, height}}} وذلك عند تغيّر التنسيق.
onLoad
تُستدعى عند اكتمال التحميل بنجاح.
onLoadEnd
تُستدعى عند اكتمال التحميل سواء أكان ناجحًا أو فاشلًا.
onLoadStart
تُستدعى عند بدء التحميل. مثال: onLoadStart={(e) => this.setState({loading: true})}
onPartialLoad
تُستدعى عند اكتمال تحميل الصورة بشكلٍ جزئيٍّ، ويتعلّق تعريف هذا التحميل الجزئي بالمُحمِّل (loader)، وتستخدم هذه الخاصيّة مع التحميلات المتقدمة (progressive) لصور JPEG.
onProgress
تُستدعى بالحدث {nativeEvent: {loaded, total}} وذلك عند تقدم التّحميل.
progressiveRenderingEnabled
تعمل على منصة Android فقط، وتُستخدم لتمكين تدفق (streaming) صور JPEG المتقدم. ويمكن زيارة الرابط [./https://frescolib.org/docs/progressive-jpegs.html https://frescolib.org/docs/progressive-jpegs.html] لمزيد من المعلومات.
resizeMethod
تحدد الطريقة المستخدمة في تغيير أبعاد الصورة المحمّلة في حال اختلاف أبعادها عن الأبعاد التي ستُعرض بها:
auto: وهي الطريقة الافتراضية، وتقوم على التجريب للاختيار بين الطريقتينresizeوscale.resize: عمليّةٌ برمجيّةٌ تعالج الصورة المرمّزة (encoded) في الذاكرة قبل فكّ ترميزها. ويجب استخدامها بدلًا منscaleعندما تكون الصورة أكبر من العرض.scale: ترسم الصورة بشكلٍ مكبّرٍ أو مصغّرٍ، وهي أسرع من الطريقتين السابقتين كونها تستخدم مسرع الجهاز الرسومي (hardware accelerated)، وتُنتج صورًا ذات جودةٍ أعلى. تستخدَم عندما تكون الصور أصغر من العرض أو أكبر قليلًا.
ويمكن زيارة [./https://frescolib.org/docs/resizing.html https://frescolib.org/docs/resizing.html] لمزيد من المعلومات حول resize و scale.
resizeMode
تحدد الطريقة التي ستُستخدم لتغيير أبعاد الصورة الأوّليّة (raw image) في حال اختلاف أبعادها عن أبعاد إطار (frame) العرض:
cover: وهي الطريقة الافتراضية، حيث تغيّر مقياس رسم (scale) الصورة بانتظامٍ (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أكبر أو تساوي أبعاد الإطار (بعد طرح الحواشي (padding)).contain: تغيّر مقياس رسم (scale) الصورة بانتظام (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أصغر أو تساوي أبعاد الإطار (بعد طرح الحواشي (padding)).stretch: تغيّر ارتفاع الصورة وعرضها بشكلٍ مستقلٍ (independently)، مما قد يؤدي لتغيير نسبة ارتفاع الصورة إلى عرضها.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 فإنه يمكن زيارة [./https://support.apple.com/en-ca/HT208967 https://support.apple.com/en-ca/HT208967]).
testID
معرِّف فريد لهذا العنصر يستخدم سكربتات اختبار أتمتة واجهة المستخدم.
التوابع
getSize()
Image.getSize(uri, success, [failure]);
يعيد ارتفاع وعرض الصورة بالبكسل قبل إظهارها، ويمكن أن يفشل عند عدم وجود الصورة أو فشل تحميلها.
يجب تحميل الصورة في البداية ثم تخزينها بشكلٍ مؤقّتٍ قبل أن يتمكّن هذا التابع من استرجاع أبعادها، مما يعني أنه يمكن من حيث المبدأ استخدام هذا التابع لتحميل الصّورة مسبقًا (preload)، غير أنه ليس الأمثل لهذا الغرض، ويمكن في المستقبل أن يُبرمَج بحيث لا يحتاج لتحميل كامل معطيات الصورة. ويفضل أن تحمّل الصور مسبقًا عن طريق واجهة برمجية مستقلة.
المعاملات
getSizeWithHeaders()
Image.getSizeWithHeaders(uri, headers, success, [failure]);
يعيد ارتفاع الصّورة وعرضها بالبكسل قبل إظهارها مع إمكانية إعطاء الترويسات (headers) للطلب، ويمكن أن يفشل عند عدم وجود الصورة أو فشل تحميلها.
يجب تحميل الصورة في البداية ثم تخزينها بشكلٍ مؤقّتٍ قبل أن يتمكّن هذا التابع من استرجاع أبعادها، مما يعني أنه يمكن من حيث المبدأ استخدام هذا التابع لتحميل الصّورة مسبقًا (preload)، غير أنه ليس الأمثل لهذا الغرض، ويمكن في المستقبل أن يُبرمَج بحيث لا يحتاج لتحميل كامل معطيات الصورة. ويفضل أن تحمّل الصور مسبقًا عن طريق واجهة برمجية مستقلة.
لا يعمل مع الصور ذات المصدر الثابت.
المعاملات
prefetch()
Image.prefetch(url);
يجلب الصّور بشكلٍ مسبقٍ (prefetche) ويخزنها على قرص التخزين المؤقت (disk cache) لتُستخدم فيما بعد.
المعاملات
abortPrefetch()
Image.abortPrefetch(requestId);
يلغي طلبات الجلب المسبق للصور، ويعمل على منصة Android فقط.
المعاملات
queryCache()
Image.queryCache(urls);
يتحقق من التخزين المؤقت، ثم يعيد ربطًا (mapping) بين عنوان URL وحالة التخزين المؤقت (cache status) له، مثلًا على القرص disk أم على الذاكرة memory، وإذا لم يوجد عنوان محدد في كتلة الربط تلك، فهذا يعني عدم وجوده في المخزن المؤقت.
المعاملات
resolveAssetSource()
Image.resolveAssetSource(source);
يعيد المرجع المساعد (asset reference) على شكل كائن له الخاصيات uri و width و height.
المعاملات
ملاحظة:
ImageSourceهو كائنٌ من الشكل{ uri: '<http location || file path>' }.
مصادر
- صفحة Image في توثيق React Native الرسميّ