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) عندما يتفاعل المستخدم مع الصورة.

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}} وذلك عند حدوث خطأ في التحميل.

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 الرسميّ