ReactNative/image

المكوّن الخاصّ بإظهار مختلف أنواع الصّور في منصّة 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)	لا

ومن خاصيّات التّنسيق أيضًا:

• Image Style Props...
• Layout Props...
• Shadow Props...
• Transforms...

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.

النوع	مطلوب	المنصة
قيمة متعدّدة ‪(enum('auto', 'resize', 'scale'))	لا	Android

resizeMode

تحدّد الطّريقة التي ستُستخدم لتغيير أبعاد الصّورة الأوّليّة (raw image) في حال اختلاف أبعادها عن أبعاد إطار (frame) الواجهة:

• cover: وهي الطّريقة الافتراضيّة، حيث تغيّر مقياس رسم (scale) الصّورة بانتظامٍ (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أكبر أو تساوي أبعاد الواجهة (بعد طرح الحواشي (padding)).
• contain: تغيّر مقياس رسم (scale) الصورة بانتظام (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أصغر أو تساوي أبعاد الواجهة (بعد طرح الحواشي (padding)).
• stretch: تغيّر ارتفاع الصورة وعرضها بشكلٍ مستقلٍ (independently)، مما قد يؤدي لتغيير نسبة ارتفاع الصورة إلى عرضها.
• repeat: تكرر الصورة حتى تغطي كامل إطار الواجهة مع المحافظة على أبعادها إذا كانت أصغر من الواجهة؛ أمّا إذا كانت أكبر منها فستغيّر مقياس رسم الصّورة بانتظام بحيث تحتويها الواجهة.
• center: تضع الصورة في مركز الإطار بحيث تكون أبعادها موازيةً لأبعاد الواجهة إذا كانت أصغر منها؛ أمّا إذا كانت أكبر منه فستغيّر مقياس رسم الصّورة بانتظامٍ بحيث تحتويها الواجهة.

النوع	مطلوب
قيمة متعددة ‪(enum('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

ملاحظة: ImageSourceهو كائنٌ من الشكل ‪.{ uri: '<http location || file path>' }

مصادر

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