عرض مصدر ReactNative/image

<noinclude>{{DISPLAYTITLE:Image في React Native}}</noinclude>
المكوّن الخاصّ بإظهار مختلف أنواع الصّور في منصّة React، والتي تتضمّن صور الشّبكة وصور المصادر الثّابتة (static resources) والصّور المحلّيّة المؤقّتة والصّور المخزّنة على القرص المحلّي كمعرض الصور.

يبين المثال التّالي كيفيّة جلب الصّور من وسائط التّخزين المحليّة ومن الشّبكة، وكذلك من المعطيات الواردة من <code>:data</code> الخاصّة بعنوان uri، ثم إظهارها.

'''ملاحظة:''' يجب تحديد أبعاد الصورة يدويًّا عند جلبها من الشّبكة أو من المصدر data.

__toc__
== أمثلة ==

* مثال لمكوِّن دالّة (Function Component)
<syntaxhighlight lang="javascript">
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;
</syntaxhighlight>
* مثال لمكوِّن صنف (Class Component)
<syntaxhighlight lang="javascript">
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; 
</syntaxhighlight>كما يمكن إضافة تنسيقٍ <code>style</code> للصّورة كما يلي:

* مثال لمكوِّن دالّة (Function Component)
<syntaxhighlight lang="javascript">
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;
</syntaxhighlight>
* مثال لمكوِّن صنف (Class Component)
<syntaxhighlight lang="javascript">
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; 
</syntaxhighlight>

== دعم صور GIF وWebP على منصة Android ==
لا تُدعم الصّور من نوع GIF وWebP افتراضيًّا على منصّة Android عند بناء شفرة أصيلة شخصيّة، لذا يجب إضافة بعض الوحدات الاختياريّة على المسار <code>android/app/build.gradle</code> بما يتوافق مع حاجة التّطبيق.<syntaxhighlight lang="javascript">
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'
}
</syntaxhighlight>

== الخاصيات ==

=== <code>style</code> ===
الخاصيّة <code>ImageResizeMode</code> هي من نوع <code>enum</code>، وتُستخدم لتغيير وضع تحجيم الصور، ويتم ضبطها عن طريق خاصيّة التنسيق <code>ResizeMode</code> في المكون <code>Image</code>، ويمكن أن تأخذ إحدى القيم (<code>contain</code>,<code>cover</code>, <code>stretch</code>,<code>center</code>,<code>repeat</code>). 
{| class="wikitable"
!النوع
!مطلوب
|-
|تنسيق (style)
|لا
|}
ومن خاصيّات التّنسيق أيضًا:

* [[ReactNative/image style props|<code>Image Style Props...</code>]]
* [[ReactNative/layout props|<code>Layout Props...</code>]]
* [[ReactNative/shadow props|<code>Shadow Props...</code>]]
* [[ReactNative/transforms|<code>Transforms...</code>]]

=== <code>accessible</code> ===
لتحديد قابليّة الوصول للصّورة، إذ يمكن الوصول إلى الصّورة إذا كانت قيمتها <code>true</code>.
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|قيمة منطقية (bool)
|لا
|iOS
|}

=== <code>accessibilityLabel</code> ===
النّص الذي سيقرؤه تطبيق قارئ الشّاشة (screen reader) عندما يتفاعل المستخدم مع الصّورة.
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|سلسلة نصية (string)
|لا
|iOS
|}

=== <code>blurRadius</code> ===
نصف قطر التّمويه (blur) المطبّق على الصورة.
{| class="wikitable"
!النوع
!مطلوب
|-
|عدد (number)
|لا
|}'''ملاحظة:''' يجب أن تكون قيمة <code>blurRadius</code> أكبر من <code>5</code> على منصّة IOS. 
=== <code>capInsets</code>  ===
لتثبيت أبعاد الحواف المحدّدة في <code>capInsets</code> عند تغيير حجم الصّورة، بينما تتمدّد باقي أجزاء الصّورة،  وبالتّالي تفيد هذه الخاصيّة في إنشاء عناصر مفيدةٍ متغيّرة الحجم ودائريّة الحوافّ، مثل: الأزرار، والظّلال وغيرها، ويمكن الاطلاع على [https://developer.apple.com/documentation/uikit/uiimage#//apple_ref/occ/instm/UIImage/resizableImageWithCapInsets التّوثيق الرسمي لشركة Apple] لمزيدٍ من المعلومات.
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|<code>[[ReactNative/rect|Rect]]</code>
|لا
|iOS
|}

=== <code>defaultSource</code> ===
لعرض الصّورة الثّابتة بينما يحمّل مصدر الصّورة.
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|كائن، عدد (number, object)
|لا
|iOS
|-
|عدد (number)
|لا
|Android
|}
فعند تمريرها ككائنٍ فسيكون من الشّكل: <code>{uri: string, width: number, height: number, scale: number}</code>  حيث:

* <code>uri</code>: سلسلةٌ نصّيةٌ تمثّل معرِّف مصدر الصورة (resource identifier)، والذي قد يكون مسار الملف المحلّي، أو مصدر الصّورة الثّابت (المغلَّف بالدالة ‪.<code>require('./path/to/image.png')</code>)
* <code>width</code>، <code>height</code>: يمكن تحديدها عند البناء إذا كانت معروفةً، وتُستخدم لضبط الأبعاد الافتراضيّة للمكوّن <code><Image/></code>.
* <code>scale</code>: تُستخدم لتحديد مقياس رسم (scale) الصورة، والقيمة الافتراضيّة له هي 1.0 والتي تعني أنّ كل بكسل (pixel) من الصورة يقابل نقطة إظهارٍ واحدةٍ DIP.

أمّا عند تمريرها كعددٍ:

* <code>number</code>: نوع مبهم (Opaque) معاد من قبل شيءٍ ما مثل ‪.<code>require('./image.jpg')</code>
'''ملاحظة:''' يتم تجاهل هذه الخاصية أثناء البناء الاختباريّ على منصة Android. 
=== <code>fadeDuration</code> ===
تعمل على منصة Android فقط، وقيمتها الافتراضية هي 300 ميلي ثانية.
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|عدد (number)
|لا
|Android
|}

=== <code>loadingIndicatorSource</code> ===
تمثّل هذه الخاصية - التي تشبه الخاصّية <code>Source</code> مصدر المستخدم في إظهار مؤشر تحميل الصورة، والذي سيظهَر إلى أن تجهز الصورة للعرض، أي حتى انتهاء تحميلها من الشّبكة.
{| class="wikitable"
!النوع
!مطلوب
|-
|مصفوفة، عدد (array of ImageSourcePropTypes, number)
|لا
|}'''ملاحظة:''' يمكنها قبول العدد الذي تعيده ‪.<code>require('./image.jpg')</code>
=== <code>onError</code> ===
تُستدعى بالحدث <code><nowiki>{{nativeEvent: {error}</nowiki></code> وذلك عند حدوث خطأ في التّحميل. 
{| class="wikitable"
!النوع
!مطلوب
|-
|دالة (function)
|لا
|}

=== <code>onLayout</code> ===
تُستدعى بالحدث <code><nowiki>{{{nativeEvent: {layout: {x, y, width, height}</nowiki></code> وذلك عند تغيّر التنسيق. 
{| class="wikitable"
!النوع
!مطلوب
|-
|دالة (function)
|لا
|}

=== <code>onLoad</code> ===
تُستدعى عند اكتمال التّحميل بنجاح.
{| class="wikitable"
!النوع
!مطلوب
|-
|دالة (function)
|لا
|}

=== <code>onLoadEnd</code> ===
تُستدعى عند اكتمال التّحميل سواء أكان ناجحًا أو فاشلًا.
{| class="wikitable"
!النوع
!مطلوب
|-
|دالة (function)
|لا
|}

=== <code>onLoadStart</code> ===
تُستدعى عند بدء التحميل، مثال: ‪<code>onLoadStart={(e) => this.setState({loading: true})}</code>
{| class="wikitable"
!النوع
!مطلوب
|-
|دالة (function)
|لا
|}

=== <code>onPartialLoad</code> ===
تُستدعى عند اكتمال تحميل الصّورة جزئيًّا، ويتعلّق تعريف هذا التّحميل الجزئي بالمُحمِّل (loader)، وتستخدم هذه الخاصيّة مع التحميلات المتقدّمة (progressive) لصور JPEG. 
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|دالة (function)
|لا
|iOS
|}

=== <code>onProgress</code> ===
تُستدعى بالحدث <code><nowiki>{{nativeEvent: {loaded, total}</nowiki></code> وذلك عند تقدم التّحميل. 
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|دالة (function)
|لا
|iOS
|}

=== <code>progressiveRenderingEnabled</code> ===
تعمل على منصّة Android فقط، وتُستخدم لتمكين تدفّق (streaming) صور JPEG المتقدم. ويمكن زيارة [https://frescolib.org/docs/progressive-jpegs.html Progressive JPEGs]  لمزيد من المعلومات.
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|قيمة منطقية (bool)
|لا
|Android
|}

=== <code>resizeMethod</code> ===
تحدّد الطريقة المستخدمة في تغيير أبعاد الصّورة المحمّلة في حال اختلاف أبعادها عن أبعاد  واجهة الصورة:

* <code>auto</code>: وهي الطّريقة الافتراضيّة، وتقوم على التّجريب للاختيار بين الطّريقتين <code>resize</code>، و<code>scale</code>.
* <code>resize</code>: عمليّةٌ برمجيّةٌ تعالج الصّورة المرمّزة (encoded) في الذّاكرة قبل فكّ ترميزها، ويجب استخدامها بدلًا من <code>scale</code> عندما تكون الصّورة أكبر من الواجهة.
* <code>scale</code>: ترسم الصّورة  مكبّرةً أو مصغّرة، وهي أسرع من الطّريقتين السّابقتين كونها تَستخدم مسرّع الجهاز الرّسومي (usually hardware accelerated )، وتُنتج صورًا ذات جودةٍ أعلى، كما تستخدَم عندما تكون الصّور أصغر من الواجهة أو أكبر قليلًا.

ويمكن زيارة [https://frescolib.org/docs/resizing.html Resizing] لمزيد من المعلومات حول <code>resize</code>، و<code>scale</code>.
{| class="wikitable"
!النوع
!مطلوب
!المنصة
|-
|قيمة متعدّدة <code>‪(enum('auto', 'resize', 'scale'))</code>
|لا
|Android
|}

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

* <code>cover</code>: وهي الطّريقة الافتراضيّة، حيث تغيّر مقياس رسم (scale) الصّورة بانتظامٍ (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أكبر أو تساوي أبعاد الواجهة (بعد طرح الحواشي (padding)).
* <code>contain</code>: تغيّر مقياس رسم (scale) الصورة بانتظام (يحافظ على نسبة ارتفاع الصّورة إلى عرضها (aspect ratio))، بحيث تصبح أبعاد الصّورة أصغر أو تساوي أبعاد الواجهة (بعد طرح الحواشي (padding)).
* <code>stretch</code>: تغيّر ارتفاع الصورة وعرضها بشكلٍ مستقلٍ (independently)، مما قد يؤدي لتغيير نسبة ارتفاع الصورة إلى عرضها.
* <code>repeat</code>: تكرر الصورة حتى تغطي كامل إطار الواجهة مع المحافظة على أبعادها إذا كانت أصغر من الواجهة؛ أمّا إذا كانت أكبر منها فستغيّر مقياس رسم الصّورة بانتظام بحيث تحتويها الواجهة.
* <code>center</code>: تضع الصورة في مركز الإطار بحيث تكون أبعادها موازيةً لأبعاد الواجهة إذا كانت أصغر منها؛ أمّا إذا كانت أكبر منه فستغيّر مقياس رسم الصّورة بانتظامٍ بحيث تحتويها الواجهة.
{| class="wikitable"
!النوع
!مطلوب
|-
|قيمة متعددة <code>‪(enum('cover', 'contain', 'stretch', 'repeat', 'center'))</code>
|لا
|}

=== <code>source</code> ===
تمثّل هذه الخاصيّة مصدر الصّورة، سواء كان عنوان URL بعيدًا (remote) أو ملفًّا محلّيًّا (local).

كما يمكن أن تتضمن هذه الخاصيّة العديد من عناوين URL البعيدة مع تحديد العرض، والارتفاع وربّما مقياس الرّسم وغيرها من معاملات URL، فيقوم التّطبيق الأصيل باختيار أفضل <code>uri</code> ليعرضه وذلك اعتمادًا على أبعاد حاوية الصورة (image container)، كما يمكن إضافة الخاصية <code>cache</code> للتحكم بكيفيّة تفاعل الطّلبات الشّبكيّة مع التخزين المحلّيّ المؤقّت (local cache). ويمكن الإطلاع على [[ReactNative/images|التحكم بالتخزين المؤقت للصور]] لمزيد من المعلومات.

صيغ الصّور (format) المدعومة حاليًّا على منصّة Android هي: (<code>png</code>, <code>jpg</code>,<code>jpeg</code>, <code>bmp</code>, <code>gif</code>,<code>webp</code>)، والصيغة <code>psd</code> على منصة iOS. كما تدعم منصة iOS العديد من صيغ الصّور الصّرفة (RAW)، ويمكن الرّجوع إلى توثيق شركة Apple للإطلاع على قائمة الكاميرات المدعومة (وفيما يخص الإصدار iOS 12 فيمكن زيارة [https://support.apple.com/en-ca/HT208967 support apple]. 
{| class="wikitable"
!النوع
!مطلوب
|-
|ImageSourcePropType
|لا
|}

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

== التوابع ==

=== ‪<code>getSize()</code> ===
<syntaxhighlight lang="javascript">
Image.getSize(uri, success, [failure]);
</syntaxhighlight>يعيد ارتفاع وعرض الصّورة بالبكسل قبل إظهارها، ويمكن أن يفشل عند عدم وجود الصورة، أو فشل تحميلها.

يجب تحميل الصّورة في البداية، ثم تخزينها مؤقّتًا قبل تمكُّن هذا التّابع من استرجاع أبعادها، ممّا يعني أنّه يمكن من حيث المبدأ استخدام هذا التّابع لتحميل الصّورة مسبقًا (preload)، ومع ذلك فهو ليس الأمثل لهذا الغرض، ويمكن في المستقبل أن يُبرمَج بحيث لا يحتاج لتحميل كامل معطيات الصورة. ويفضل تحميل الصّور مسبقًا عن طريق واجهة برمجيّة مستقلة. 

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>uri</code>
|سلسلة نصية (string)
|نعم
|موقع الصورة
|-
|<code>success</code>
|دالة (function)
|نعم
|الدالة التي ستطلب عند إيجاد الصورة بنجاحٍ واستعادة ارتفاعها وعرضها
|-
|<code>failure</code>
|دالة (function)
|لا
|الدالة التي ستطلب عند حدوث خطأ كالفشل في استعادة الصورة
|}

=== ‪<code>getSizeWithHeaders()</code>===
<syntaxhighlight lang="javascript">
Image.getSizeWithHeaders(uri, headers, success, [failure]);
</syntaxhighlight>يعيد ارتفاع الصّورة وعرضها بالبكسل قبل إظهارها مع إمكانية إعطاء الترويسات (headers) للطلب، ويمكن أن يفشل عند عدم وجود الصورة أو فشل تحميلها.

يجب تحميل الصورة في البداية، ثمّ تخزينها بشكلٍ مؤقّتٍ قبل تمكُّن هذا التّابع من استرجاع أبعادها، ما يعني أنه يمكن من حيث المبدأ استخدام هذا التابع لتحميل الصّورة مسبقًا (preload)، غير أنّه ليس الأمثل لهذا الغرض، ويمكن في المستقبل أن يُبرمَج بحيث لا يحتاج لتحميل كامل معطيات الصورة. ويفضل أن تحمّل الصور مسبقًا عن طريق واجهة برمجية مستقلة. 

لا يعمل مع الصّور ذات المصدر الثّابت.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>uri</code>
|سلسلة نصية (string)
|نعم
|موقع الصورة
|-
|<code>headers</code>
|كائن (object)
|نعم
|ترويسة الطلب
|-
|<code>success</code>
|دالة (function)
|نعم
|الدالة التي ستطلب عند إيجاد الصورة بنجاح واستعادة ارتفاعها وعرضها
|-
|<code>failure</code>
|دالة (function)
|لا
|الدالة التي ستطلب عند حدوث خطأ كالفشل في استعادة الصورة
|}

=== ‪<code>prefetch()</code>===
<syntaxhighlight lang="javascript">
Image.prefetch(url);
</syntaxhighlight>يجلب الصّور مسبقًا (prefetche) ويخزّنها على قرص التّخزين المؤقت (disk cache) لتُستخدم فيما بعد.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>url</code>
|سلسلة نصية (string)
|نعم
|العنوان البعيد لموقع الصورة
|}

=== ‪<code>abortPrefetch()</code>===
<syntaxhighlight lang="javascript">
Image.abortPrefetch(requestId);
</syntaxhighlight>يلغي طلبات الجلب المسبق للصّور، ويعمل على منصّة Android فقط.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>requestId</code>
|عدد (number)
|نعم
|المعرف ID المعاد من ()prefetch
|}

=== ‪<code>queryCache()</code>===
<syntaxhighlight lang="javascript">
Image.queryCache(urls);
</syntaxhighlight>يتحقّق من التّخزين المؤقت، ثمّ يعيد ربطًا (mapping) بين عنوان URL وحالة التّخزين المؤقّت (cache status) له، مثلًا على القرص <code>disk</code> أم على الذاكرة <code>memory</code>، وإذا لم يوجد عنوان محدّد في كتلة الربط تلك، فهذا يعني عدم وجوده في المخزن المؤقت.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>urls</code>
|مصفوفة (array)
|نعم
|قائمة عناوين URL لفحص التخزين المؤقت
|}

=== ‪<code>resolveAssetSource()</code>===
<syntaxhighlight lang="javascript">
Image.resolveAssetSource(source);
</syntaxhighlight>يعيد المرجع المساعد (asset reference) على شكل كائن له الخاصيّات <code>uri</code>، و<code>width</code>، و<code>height</code>.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>source</code>
|عدد (number)، كائن (object)
|نعم
|العدد من النوع المبهم الذي تعيده ‪require('./image.jpg') 

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

* [https://facebook.github.io/react-native/docs/image صفحة Image  في توثيق React Native الرسميّ]
[[تصنيف:ReactNative]]