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 {
  // ‫إذا كان تطبيقك يدعم إصدارات أندرويد التي تسبق الإصدار Ice Cream Sandwich (API level 14)
  implementation 'com.facebook.fresco:animated-base-support:1.3.0'
​
  // ‫لدعم صور GIF المتحركة
  implementation 'com.facebook.fresco:animated-gif:2.0.0'
​
  // ‫لدعم صور WebP بما فيها المتحركة
  implementation 'com.facebook.fresco:animated-webp:2.1.0'
  implementation 'com.facebook.fresco:webpsupport:2.0.0'
​
  // ‫لدعم صور WebP دون الصور المتحركة منها
  implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

الخاصيات

يرث خاصيات المكون View.

accessible

لتحديد قابليّة الوصول للصّورة، إذ يمكن الوصول إلى الصّورة إذا كانت قيمتها true.

النوع	مطلوب	المنصة
(bool)	لا	iOS

accessibilityLabel

النّص الذي سيقرؤه تطبيق قارئ الشّاشة (screen reader) عندما يتفاعل المستخدم مع الصّورة.

النوع	مطلوب	المنصة
سلسلة نصية (string)	لا	iOS

blurRadius

نصف قطر التّمويه (blur) المطبّق على الصورة.

النوع	مطلوب
عدد (number)	لا

ملاحظة: يجب أن تكون قيمة blurRadius أكبر من 5 على منصّة iOS.

capInsets

لتثبيت أبعاد الحواف المحدّدة في capInsets عند تغيير حجم الصّورة، بينما تتمدّد باقي أجزاء الصّورة، وبالتّالي تفيد هذه الخاصيّة في إنشاء عناصر مفيدةٍ متغيّرة الحجم ودائريّة الحوافّ، مثل: الأزرار، والظّلال وغيرها، ويمكن الاطلاع على التّوثيق الرسمي لشركة Apple لمزيدٍ من المعلومات.

النوع	مطلوب	المنصة
Rect	لا	iOS

defaultSource

لعرض الصّورة الثّابتة بينما يحمّل مصدر الصّورة.

النوع	مطلوب
ImageSource (انظر في الأسفل)	لا

ملاحظة: يتم تجاهل هذه الخاصية أثناء البناء الاختباريّ على منصة Android.

fadeDuration

تعمل على منصة Android فقط، وقيمتها الافتراضية هي 300 ميلي ثانية.

النوع	مطلوب	المنصة
عدد (number)	لا	Android

loadingIndicatorSource

تمثّل هذه الخاصية - التي تشبه الخاصّية Source مصدر المستخدم في إظهار مؤشر تحميل الصورة، والذي سيظهَر إلى أن تجهز الصورة للعرض، أي حتى انتهاء تحميلها من الشّبكة.

النوع	مطلوب
ImageSource (مع uri فقط، انظر في الأسفل)، أو عدد	لا

onError

تُستدعى عند حدوث خطأ في التّحميل.

النوع	مطلوب
دالة (function) ({ nativeEvent: { error } }) => void	لا

onLayout

تُستدعى وذلك عند وصل المكون (عرضه) أو عند تغيّر التخطيط.

النوع	مطلوب
دالة (function) ({ nativeEvent: LayoutEvent }) => void	لا

onLoad

تُستدعى عند اكتمال التّحميل بنجاح.

النوع	مطلوب
دالة (function) (ImageLoadEvent) => void	لا

onLoadEnd

تُستدعى عند اكتمال التّحميل سواء أكان ناجحًا أو فاشلًا.

النوع	مطلوب
دالة (function) () => void	لا

onLoadStart

تُستدعى عند بدء التحميل، مثال: ‪onLoadStart={(e) => this.setState({loading: true})}

النوع	مطلوب
دالة (function) () => void	لا

onPartialLoad

تُستدعى عند اكتمال تحميل الصّورة جزئيًّا، ويتعلّق تعريف هذا التّحميل الجزئي بالمُحمِّل (loader)، وتستخدم هذه الخاصيّة مع التحميلات المتقدّمة (progressive) لصور JPEG.

النوع	مطلوب	المنصة
دالة (function) () => void	لا	iOS

onProgress

تُستدعى عند تقدم التّحميل.

النوع	مطلوب	المنصة
دالة (function) ({ nativeEvent: { loaded, total } }) => void	لا	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).

النوع	مطلوب
ImageSource	لا

style

تُستخدم لتنسيق الصورة.

النوع	مطلوب
إحدى خاصيّات التّنسيق: Image Style Layout Shadow Transforms	لا

testID

معرِّف فريد لهذا العنصر يستخدم سكربتات اختبار أتمتة واجهة المستخدم.

النوع
سلسلة نصية (string)

التوابع

abortPrefetch()‎

Image.abortPrefetch(requestId);

يلغي طلبات الجلب المسبق للصّور، ويعمل على منصّة Android فقط.

المعاملات

الاسم	النوع	مطلوب	الوصف
requestId	عدد (number)	نعم	المعرف ID المعاد من ()prefetch

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)	نعم	العنوان البعيد لموقع الصورة
callback	دالة (function) على منصة آندرويد	لا	الدالة التي ستسدعى مع المُعرِّف requestId.

queryCache()‎

Image.queryCache(urls);

يتحقّق من التّخزين المؤقت، ثمّ يعيد ربطًا (mapping) بين عنوان URL وحالة التّخزين المؤقّت (cache status) له، مثلًا على القرص disk أم على الذاكرة memory، وإذا لم يوجد عنوان محدّد في كتلة الربط تلك، فهذا يعني عدم وجوده في المخزن المؤقت.

المعاملات التي تأخذها:

الاسم	النوع	مطلوب	الوصف
urls	مصفوفة (array)	نعم	قائمة عناوين URL لفحص التخزين المؤقت

resolveAssetSource()‎

Image.resolveAssetSource(source);

يعيد المرجع المساعد (asset reference) على شكل كائن له الخاصيّات uri، وwidth، وheight.

المعاملات التي تأخذها:

الاسم	النوع	مطلوب	الوصف
source	ImageSource، عدد (number)	نعم	العدد من النوع المبهم الذي تعيده ‪require('./image.jpg') أو الكائن ImageSource

تعريفات الأنواع

ImageCacheEnum (خاصة بمنصة iOS)

تعداد enum يمكن استخدامه لضبط عملية معالجة التخزين المؤقت أو ضبط أسلوب لمعالجة الاستجابات التي يحتمل أنها جُلبت وخُزِّنت مؤقتًا.

النوع	القيمة الافتراضية
إحدى القيم التالية: (‎'default', 'reload', 'force-cache', 'only-if-cached'‎)	'default'

• default: استخدم الأسلوب الافتراضي الذي توفره المنصة الأصيلة.
• reload: البيانات أو عنوان URL الذي سيُحمَّل من المصدر الأصلي. لا يفترض استخدام أي بيانات مخزنة موجودة آنذاك لتلبية عملية تحميل الطلبية من عنوان URL.
• force-cache: ستُستخدَم البيانات المُخزَّنة الموجودة لتلبية الطلبية بغض النظر عن عمر تلك البيانات المخزنة أو تاريخ انتهاء صلاحيتها. إن لم تتوافر بيانات في المخزن مقابلة للطلبية، فستُطلب البيانات من المصدر الأصلي آنذاك.
• only-if-cashed: ستُستخدَم البيانات المُخزَّنة الموجودة لتلبية الطلبية بغض النظر عن عمر تلك البيانات المخزنة أو تاريخ انتهاء صلاحيتها. إن لم تتوافر بيانات في المخزن مقابلة للطلبية، فلن يُكلف عناء طلب تلك البيانات من المصدر الأصلي، وستُعد حالة الطلبية فاشلة آنذاك.

ImageLoadEvent

كائن يعاد من رد الندار onLoad.

النوع
كائن

الخاصيات التي يأخذها ذلك الكائن:

• width (عدد): عرض الصور المحملة.
• height (عدد): ارتفاع الصورة المحملة.
• uri (سلسلة نصية): سلسلة نصية تمثل مصدر مُعرِّف الصورة.

ImageSource

النوع
كائن، مصفوفة من الكائنات، عدد

الخاصيات المتاحة (إن مُرِّر على شكل كائن أو مصفوفة من الكائنات):

• uri (سلسلة نصية): سلسلةٌ نصّيةٌ تمثّل معرِّف مصدر الصورة (resource identifier)، والذي قد يكون عنوان http، أو مسار الملف المحلّي، أو مصدر صورة ثابت (static image resource).
• width، height (عدد): يمكن تحديدها عند البناء إذا كانت معروفةً، وتُستخدم لضبط الأبعاد الافتراضيّة للمكوّن <Image/>.
• scale (عدد): تُستخدم لتحديد مقياس رسم (scale) الصورة، والقيمة الافتراضيّة له هي 1.0 والتي تعني أنّ كل بكسل (pixel) من الصورة يقابل نقطة إظهارٍ واحدةٍ DIP.
• bundle (سلسلة نصية): خاصة بمنصة iOS، تحدد محزِّم الأصول في iOS (أي iOS asset bundle) الذي توجد الصورة ضمنه. إن لم تحدد قيمته، فستكون [NSBundle mainBundle].
• method (سلسلة نصية): نوع طلبية HTTP المراد استعماله، وقيمته الافتراضية 'GET'.
• headers (كائن): كائن يمثِّل ترويسات طلبية HTTP المراد إرسالها للصورة البعيدة.
• body (سلسلة نصية): محتوى طلبية HTTP المراد إرساله مع الطلبية. يجب أن يكون سلسلة نصية مرمزة ترميزًا صالحًا عبر UTF-8، وسترسل تمامًا كما هي معطاة دون أي تطبيق أي عملية ترميز إضافية (مثل تهريب عناوين url أو ترميز base64).
• cache (نوع ImageCacheEnum): خاص بمنصة iOS، تحدد كيفية معالجة استجابات أو ردود الطلبيات التي يحتمل أن تكون مخزنة مؤقتًا.

الخاصيات المتاحة (إن مُرِّر على شكل عدد):

• number: نوع مبهم (Opaque) معاد من قبل شيءٍ ما مثل ‪.require('./image.jpg')

مصادر

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