عرض مصدر Next.js/next image

<noinclude>{{DISPLAYTITLE:الواجهة البرمجية للمكوّن Next/image في Next.js}}</noinclude>
<blockquote>'''ملاحظة''': كُتب هذا التوثيق للواجهة البرمجية الخاصة بالمكوّن image ولتحسين الصور. للاطلاع أكثر على هذه الميزة واستخدامها في Next.js عُد إلى صفحة "[[Next.js/image optimization|تحسين الصور]]" من هذا التوثيق.

'''ملاحظة''': إن كنت تستخدم إصدارًا أقدم من 13، فارجع إلى توثيق [[Next.js/next legacy image|next/legacy/image]] إذ جرى تغيير اسم المكون بدءًا من ذلك الإصدار.

'''تنبيه:''' ظهرت بعض الثغرات في متصفحي Safari (نسخة 15 وما بعد) و فايرفوكس (نسخة 67 وما بعد) وإليك بعض الحلول المقترحة:

* تظهر في سفاري حواف رمادية عند تحميل الصورة، قد يكون الحل باستخدام قواعد CSS التالية:
<syntaxhighlight lang="css">
@supports (font: -apple-system-body)
          (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
</syntaxhighlight>

* تظهر خلفية بيضاء أثناء التحميل في فايرفوكس وقد يكون الحل هو تمكين تنسيق AVIF أو استخدام الخاصية <code>placeholder="blur</code>
</blockquote>

== الخاصيات الضرورية ==
نستعرض في هذا القسم الخاصيات الضرورية لعمل المكوّن <code></ Image></code>.

=== الخاصية <code>src</code> ===
لا بد أن تكون هذه الخاصية واحدة من هذه:

# ملف صورة [[Next.js/image optimization#.D8.A7.D9.84.D8.B5.D9.88.D8.B1%20.D8.A7.D9.84.D9.85.D8.AD.D9.84.D9.8A.D8.A9|مُدرج بشكل ساكن]].
# مسار مطلق absolute لعنوان URL خارجي أو داخلي وفقًا للمحمّل <code>loader</code> أو وفقًا لإعدادات المحمّل المخصصة.

عند استخدام عنوان URL خارجي، لا بد من إضافته إلى النطاقات domains في ملف التهيئة <code>next.config.js</code>.

=== الخاصية <code>width</code> ===
وتمثّل هذه الخاصية الاتساع المُصيَّر مقدرًا بالبكسل، وبالتالي سيؤثر على حجم الصورة عند عرضها. تُعد هذه الخاصية مطلوبة ما عدا حالة الصورة المدرجة بشكل ساكن أو تلك التي تكون قيمة الخاصية <code>layout</code> لها هي <code>"fill"</code>.

=== الخاصية <code>height</code> ===
وتمثّل هذه الخاصية الارتفاع المُصيَّر مقدرًا بالبكسل، وبالتالي سيؤثر على حجم الصورة عند عرضها. تُعد هذه الخاصية مطلوبة ما عدا حالة الصورة المدرجة بشكل ساكن أو تلك التي تكون قيمة الخاصية <code>layout</code> لها هي <code>"fill"</code>.

=== الخاصية <code>alt</code> ===
وتستخدم لوصف الصورة كتابيًا كي تتمكن قارئات الشاشة ومحركات البحث من تمييزها. كما يُعد الوصف طريقة لتفادي حالة عدم تحميل الصورة سواء كان عرض الصور معطلًا في المتصفح أو حدث خطأ ما أثناء التحميل. ينبغي أن تضم هذه الخاصية نصًا يمكن أن نستبدل به الصورة دون يغيّر معنى الصفحة، وليس الغرض منه تعزيز محتوى الصورة. وبالتالي يجب ألا يكرر هذا النص المعلومات الت تعرضها العناوين أعلى وأسفل الصورة. اما إذا كانت الصورة للديكور فقط ولا تحوي معلومات أساسية للمستخدم  ينبغي أن يكون النص فارغًا (<code>""=alt</code>)

== الخاصيات الاختيارية ==
يقبل المكوّن <code></ Image></code> مجموعة من الخاصيات الاختيارية إضافة إلى تلك الإجبارية. لهذا نلقي نظرة في هذا القسم على أكثر الخاصيات المستخدمة شيوعًا، كما سنتعرف لاحقًا إلى بعض الخاصيات نادرة الاستعمال.

=== الخاصية <code>loader</code> ===
وهي دالة تعيد عنوان URL نصي للصورة وتقبل المعاملات التالية:

* <code>src</code>
* <code>width</code>
* <code>quality</code>

إليك مثالًا عن استخدام محمّل مخصص مع <code>next/image</code>:<syntaxhighlight lang="javascript">
import Image from 'next/image'

const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}
</syntaxhighlight>بإمكانك بدلًا من ذلك استخدام إعدادات <code>loaderFile</code> في <code>next.config.js</code> لتهيئة كل نسخة من الكائن  <code>next/image</code>  في تطبيقك دون تمرير أية خاصيات.

=== الخاصية <code>fill</code> ===
تأخذ الخاصية قيمة منطقية تحدد فيما إذا كانت الصورة ستملأ مساحة العنصر الأب بدلًا من ضبط الخاصيتين <code>width</code> و <code>height</code>

ينبغي في هذه الحالة أن يمتلك العنصر الأب خاصية التنسيق <code>position: "relative"‎</code> أو <code>position: "fixed"‎</code> أو <code>position: "absolute"‎</code>.

يمتلك العنصر <code>img</code> افتراضيًا التنسيق <code>position: "absolute"‎</code> وبالتالي ستتوسع الصورة حتى تملأ المساحة المخصصة لها، لهذا يمكنك استخدام الخاصية <code>object-fit: "contain"‎</code> لتملأ الصورة الحاوية التي تضمها وتحتفظ بتناسب أبعادها. بينما سيؤدي التنسيق إلى تمدد الصورة واقتصاصها حتى تحافظ على تناسب الأبعاد، ولكي يبدو  الأمر صحيحًا،لا بد من ضبط تنسيق الطفحان للعنصر الأب بالشكل <code>overflow: "hidden"</code>.

=== الخاصية <code>sizes</code> ===
تؤثر قيمة الخاصية <code>sizes</code> بشدة على أداء الصورة التي تستخدم الخاصية <code>fill</code> أو التي تُنسّق لتكون متجاوبة. وللخاصية <code>sizes</code> غايتان أساسيتان تتعلقان بأداء الصورة:

'''الأولى''': يستخدم المتصفح هذه الخاصية حجم الصورة التي ينبغي تحميلها من مجموعة الأحجام التي يوّلدها المكون <code>next/image</code> تلقائيًا. عندما يختار المتصفح حجم الصورة، فهو لا يعرف بعد حجم الصورة على الصفحة، لهذا سيختار الصورة التي تمتلك أبعادًا أكبر أو تعادل أبعاد نافذة العرض. وهكذا تخبر الخاصية <code>sizes</code> المتصفح أن الصورة ستكون أقل من حجم الشاشة الكامل. وانتبه إلى أن عرض الصورة سيكون <code>100vw</code> إن لم تستخدم الخاصية مع صورة تستخدم الخاصية <code>fill</code>. 

'''الثانية''': تضبط الخاصية <code>sizes</code> طريقة توليد الكائن <code>next/image</code> لمجموعة أحجام الصورة. فإن لم تكن الخاصية <code>sizes</code> موجودة ستوُلد مجموعة صغيرة من القياسات التي تناسب الصور ثابتة الحجم. لكن إذا عُرفت هذه الخاصية ستكون المجموعة المولَّدة أكبر وملائمة أكثر للصور المتجاوبة. 

إن ضمت الخاصية <code>sizes</code> قياسات مثل <code>50vw</code> والتي تشير إلى نسبة مئوية من اتساع نافذة العرض، ستُختصر قائمة الأحجام كي لا تتضمن أية قيم أصغر بكثير من اللازم.

فإن عرفت مثلًا أن التنسيق الذي تستخدمه سيسبب تمدد الصورة لتحتل اتساع النافذة في أجهزة الهاتف المحمول أو في تخطيط العمودين الخاص بالأجهزة اللوحية أو تخطيط الأعمدة الثلاث في شاشات الحواسب المكتبية، لا بد أن تستخدم الخاصية <code>sizes</code> كالتالي:<syntaxhighlight lang="javascript">
import Image from 'next/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      fill
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)
</syntaxhighlight>قد يؤثر ستخدام الخاصية <code>sizes</code> في المثال السابق بشكل واضح على معايير الأداء. فمن دون استخدام القياس <code>33vw</code> ستكون اتساع الصورة التي تحملها الصفحة من الخادم أكبر بثلاث مرات من المطلوب، ولأن حجم الملف يتناسب طردًا مع مربّع الاتساع، سيحمّل المستخدم صورة أكبر بتسع مرات من المطلوب إن لم نستخدم <code>sizes</code>.

=== الخاصية <code>quality</code> ===
وتمثل نوعية الصورة المحسنة كرقم صحيح بين 1 و 100. تمثّل 100 الدقة الأفضل والقيمة الافتراضية 75.

=== الخاصية <code>priority</code> ===
تُعد الصور ذات أولوية عالية عندما تأخذ هذه الخاصية القيمة <code>true</code>  ويُعاد تحميلها، وتعطل ميزة التحميل الكسول تلقائيًا في حال استخدام هذه الخاصية. القيمة الافتراضية هي <code>false</code>.

لا بد من استخدام هذه الخاصية لأي صورة يعدّها المتصفح "أكبر عنصر سيُرسم على الشاشة LCP". من الملائم أحيانًا وجود عدة صور تستخدم الخاصية <code>priority</code>، لأن العديد من الصور قد تكون LCP لواجهات عرض مختلفة.

إن القيم الافتراضية للخاصية <code>priority</code> هي <code>false</code>، ولا ينبغي استخدامها ما لم تكن الصورة مرئية في الجزء الظاهر من الصفحة.

=== الخاصية <code>placeholder</code> ===
تستخدم لحجز مساحة كافية للصورة أثناء التحميل. ولها قيمتان: الافتراضية <code>empty</code> و <code>blur</code>.

* عندما تكون قيمة الخاصية <code>blur</code>، تُستخدم الخاصية <code>blurDataURL</code> لحجز حيّز الصورة. وإن كانت قيمة الخاصية <code>src</code> كائنًا مصدره إدراج ساكن لصورة لها أحد الامتدادات <code>jpg.</code> أو <code>png.</code> أو <code>webp.</code> أو <code>avif.</code>، سيُحدد <code>blurDataURL</code> حيّز الصورة تلقائيًا. يجب استخدام الخاصية <code>blurDataURL</code> مع الصور الديناميكية، كما أن حلولًا مثل [https://github.com/joe-bell/plaiceholder Plaiceholder] قد تساعد عند تمثيل العناصر باستخدام التشفير <code>base64</code>.
* عندما تكون قيمة الخاصية <code>empty</code>، لن يكون هناك حيّز لتحميل الصورة بل فقط مسافة فارغة. جرّب الامثلة التالية:
** [https://image-component.nextjs.gallery/placeholder مثال] عن حيّز التحميل مع <code>blur</code>.
** [https://image-component.nextjs.gallery/shimmer مثال] عن تأثير الوميض مع الخاصية <code>blurDataURL</code>.
** [https://image-component.nextjs.gallery/color مثال] عن التأثير اللوني مع الخاصية <code>blurDataURL</code>.

== الخاصيات المتقدمة ==
قد تحتاج في بعض الحالات إلى طرق استخدام أكثر تقدمًا، لهذا ستجد أن المكوّن <code></ Image></code> يمتلك الخاصيات الاختيارية المتقدمة التالية.

=== الخاصية <code>style</code> ===
تسمح هذه الخاصية بتمرير تنسيقات CSS إلى عنصر الصورة التحتي <code><img></code>. 

تذكر أن الخاصيتين الإجباريتين <code>width</code> و <code>height</code> قد تتفاعلان مع تنسيقك، فإن ضبطت الاتساع <code>width</code> لا بد من ضبط الارتفاع أيضًا بالشكل <code>"height="auto</code> وإلا ستتشوه الصورة.

=== الدالة <code>onLoadingComplete</code> ===
وهي دالة تُنفَّذ بمجرد أن يكتمل تحميل الصورة ويُزال الحيّز المحدد لها أثناء التحميل. تقبل هذه الدالة معاملًا واحدًا هو مرجع إلى العنصر التحتي للصورة  <code><img></code>.

=== الدالة <code>onLoad</code> ===
وهي دالة تُستدعى عند بداية تحميل الصورة. وتجدر الملاحظة هنا أن حدث التحميل قد يحدث قبل إزالة الحيز المحدد للصورة واكتمال عرض الصورة. وبإمكانك استخدام <code>onLoadingComplete</code> بدلًا عنها.

=== الدالة <code>onErorr</code> ===
وهي دالة تُستدعى إن أخفق تحميل الصورة.

=== الخاصية <code>loading</code> ===
<blockquote>'''تنبيه''': صممت هذه الخاصية للاستخدام المتقدم. فقد يسيء استخدام التحميل الشره <code>eager</code> إلى الأداء. لهذا ننصح باستخدام الخاصية <code>priority</code> بدلًا عنها، إذ تحمّل هذه الخاصية الصورة "بشراهة" في معظم الحالات تقريبًا.</blockquote>تحدد الخاصية سلوك تحميل الصورة، وقيمتها الافتراضية <code>lazy</code> (كسول). ففي حالة السلوك الكسول <code>lazy</code>، لا تُحمّل الصورة حتى تقترب مسافة محددة من نافذة العرض (قبل أن تُعرض بقليل). أما في حالة السلوك الشره <code>eager</code>، ستُحمّل الصورة مباشرة.

=== الخاصية <code>blurDataURL</code> ===
وهو عنوان URL خاص بالبيانات (له البادئة ":data") يُستخدم كحيّز تحميل صورة قبل تحميل الصورة المحددة في الخاصية <code>src</code>. يظهر تأثير هذه الخاصية عندما تُستخدم مع الخاصية <code>"placeholder="blur</code>.

ينبغي أن تكون الصورة مرمّزة وفق القاعدة <code>base64</code>، إذ تُكبّر الصورة وتُغشّى. لهذا يستحسن أن تكون هذه الصورة صغيرة (10 بكسل أو أقل)، فإضافة صور كبيرة إلى حيّز التحميل قد يسيء إلى الأداء. راجع الأمثلة السابقة في فقرة الخاصية <code>placeholder</code>.

=== الخاصية <code>unoptimized</code> ===
تُقدم الصورة في حال كانت قيمة هذه الخاصية <code>true</code> كما هي دون تغيير في النوعية أو الحجم أو التنسيق. القيمة الافتراضية لهذه الخاصية <code>false</code>.

يمكن تعيين هذه الخاصية لكل الصور بتحديث الملف <code>next.config.js</code> من خلال إضافة الإعدادات التالية:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    unoptimized: true,
  },
}
</syntaxhighlight>

== خاصيات أخرى ==
تمرر الخاصيات الأخرى للمكوّن <code></ Image></code> إلى عنصر الصورة التحتي <code>img</code> ما عدا الخاصيات التالية:

* <code>srcSet</code>: استعمل <code>DeviceSizes</code> بدلًا عنها.
* <code>decoding</code>: وتكون دائمًا <code>"async"</code>.

=== خاصيات الإعداد ===

=== الخاصية <code>remotePatterns</code> ===
<blockquote>'''ملاحظة''': يُعد الإعداد <code>remotePatterns</code> تجريبيًا حاليًا وعرضة للتغيير. استخدم <code>domains</code> في نسخ الإنتاج.</blockquote>لا بد من تهيئة تطبيقك حتى يستخدم صورًا من مصادر خارجية دون أن يتسلل المستخدمين المشبوهين من خلالها إلى تطبيقك. وبهذا تتأكد أن الصور الخارجية التي تأتي من حساباتك فقط يمكن تخديمها بواسطة واجهة Next.js البرمجية لتحسين الصور. يمكن أن تُهيأ هذه الصور من خلال الخاصية <code>remotePatterns</code> في الملف <code>next.config.js</code> كما يلي:<syntaxhighlight lang="javascript">
module.exports = {
  experimental: {
    images: {
      remotePatterns: [
        {
          protocol: 'https',
          hostname: 'example.com',
          port: '',
          pathname: '/account123/**',
        },
      ],
    },
  },
}
</syntaxhighlight><blockquote>'''ملاحظة''': يتأكد المثال السابق من ضرورة أن تبدأ الخاصية <code>src</code> للمكوّن <code>next/image</code> بالعنوان <code>/<nowiki>https://example.com/account123</nowiki></code>. وأي بروتوكول أو اسم مضيف أو منفذ أو مسار لا يتطابق معه سيولّد الخطأ 400 (طلب خاطئ bad request)</blockquote>إليك مثالًا آخر عن استخدام الخاصية <code>remotePatterns</code> في الملف <code>next.config.js</code>:<syntaxhighlight lang="javascript">
module.exports = {
  experimental: {
    images: {
      remotePatterns: [
        {
          protocol: 'https',
          hostname: '**.example.com',
        },
      ],
    },
  },
}
</syntaxhighlight><blockquote>'''ملاحظة''': يتأكد المثال السابق من ضرورة أن تبدأ الخاصية <code>src</code> للمكوّن <code>next/image</code> بأحد العناوين <code><nowiki>https://img1.example.com</nowiki></code> أو <code><nowiki>https://me.avatar.example.com</nowiki></code>. وأي بروتوكول أو اسم مضيف أو منفذ أو مسار لا يتطابق معه سيولّد الخطأ 400 (طلب خاطئ bad request).</blockquote>يمكن استخدام أنماط الأحرف البديلة لترميز <code>pathname</code> أو <code>hostname</code> وفقًا للصيغتين التاليتين:

* <code>*</code>: يتطابق من قسم مسار مفرد أو نطاق فرعي.
* <code>**</code>: يتطابق مع أي عدد من أقسام المسارات في نهايتها أو مع النطاقات الفرعية في بدايتها.

لا تعمل الصيغة <code>**</code> وسط النمط.

=== النطاقات <code>domain</code> ===
'''ملاحظة''': ننصح باستخدام الخاصية بدلًا عنها كي تتمكن من تحديد بروتوكول أو مسار

تقدم قائمة بأسماء المضيف المتاحة لاستخدام الصور الخارجية. لكن لا تدعم هذه الخاصية المحارف البديلة، ولا يمكن أن تحدد بروتوكولًا أو منفذًا أو مسارًا.

إليك مثالًا عن استخدام الخاصية <code>domains</code> في الملف <code>next.config.js</code>:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}
</syntaxhighlight>

=== إعدادات المحمِّل ===
إن أردت استخدام مزوّد سحابي لتحسين الصور بدلًا من استخدام واجهة Next.js البرمجية المدمجة لتحسين الصور، يمكنك إعداد الخاصية <code>loaderFile</code>  في ملف <code>next.config.js</code>:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}
</syntaxhighlight>لا بد أن تشير إلى ملف بالنسبة إلى جذر تطبيق Next.js، ولا بد أن يصدّر الملف دالة تعيد نصًا. إليك مثالًا:<syntaxhighlight lang="javascript">
export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
</syntaxhighlight>بإمكانك أيضًا استخدام الخاصية <code>loader</code> لتهيئة كل نسخة من الكائن <code>next/image</code> على حدى.

== إعدادات متقدمة ==
تُعد الإعدادات التالية متقدمة ولحالات محدودة وليست ضرورية عادة. فإن اخترت أن تضبط الخاصيات القادمة، فستبدّل كل التغييرات التي ستحصل على إعدادات Next.js الافتراضية في التحديثات المستقبلية.

=== الخاصية <code>deviceSizes</code> ===
إن كنت تعرف اتساع اجهزة مستخدميك، يمكنك وضع قائمة بالاتساعات الممكنة باستخدام الخاصية <code>deviceSizes</code> وذلك ضمن الملف <code>next.config.js</code>. تُستخدم هذه القائمة عندما يستخدم المكوّن <code>next/image</code> الخاصية <code>sizes</code> للتأكد من تقديم الصورة الصحيحة الملائمة لجهاز المستخدم. 

إن لم تكن هناك أية إعدادات بهذا الخصوص، تُطبق القيم الافتراضية التالية:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}
</syntaxhighlight>

=== الخاصية <code>imageSizes</code> ===
بإمكانك تحديد قائمة بالاتساعات التي قد تأخذها صورة من خلال الخاصية <code>images.imageSizes</code> وذلك ضمن ملف التهيئة <code>next.config.js</code>. تُضم هذه القيم إلى مصفوفة <code>deviceSizes</code> لتشكيل مصفوفة من القياسات التي تُستخدم في توليد قيم مجموعات <code>srcset</code> التي تحدد الأبعاد الملائمة لكل نافذة عرض.

يعود السبب في وجود قائمتين منفصلتين هو أن الخاصية <code>imageSizes</code> تُستخدم فقط للصورة التي تمتلك الخاصية <code>sizes</code>، التي تدل على أن اتساع الصورة أقل من اتساع الشاشة، وبالتالي يجب أن تكون القياسات في الخاصية <code>imageSizes</code> أصغر من قيمة الخاصية <code>deviceSizes</code>.

إن لم تكن هناك أية إعدادات بهذا الخصوص، تُطبق القيم الافتراضية التالية:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}
</syntaxhighlight>

=== تنسيقات الصور المقبولة ===
تكتشف الواجهة البرمجية الافتراضية لتحسين الصور التنسيقات التي يدعمها المتصفح تلقائيًا من خلال الترويسة <code>Accept</code> للطلب.

إن تطابقت الترويسة <code>Accept</code> مع أكثر من تنسيق من التنسيقات المهيأة يُستخدم التنسيق الأول في القائمة، لهذا ينبغي الانتباه إلى ترتيب عناصر القائمة. إن لم تجد الواجهة أي تطابق (أو كانت الصورة المصدرية متحركة)، ستتراجع واجهة تحسين الصور إلى تنسيق الصورة الأصلي.

إن لم تكن هناك أية إعدادات بهذا الخصوص، تُطبق القيم الافتراضية التالية:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    formats: ['image/webp'],
  },
}
</syntaxhighlight>بإمكانك تفعيل التنسيق AVIF من خلال الإعداد التالي:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}
</syntaxhighlight><blockquote>'''ملاحظة''': تتطلب الصورة وفق تنسيق AVIF زمنًا أطول بحوالي 20% لتشفيرها، لكن يمكن أن تُضغط أكثر موفرة 20% موازنةً بالتنسيق WebP. وهذا يعني أن تحميل تلك الصور للمرة الأولى سيكون أبطأ لكن التحميلات التالية من الذاكرة المؤقتة سيكون أسرع.

'''ملاحظة''': إن قررت أن تستضيف تطبيقك باستخدام مخدم وكيل أو شبكة توزيع محتوى Proxy/CDN أمام تطبيق Next.js، لا بد من ضبط الخادم الوكيل لتوجيه الترويسة <code>Accept</code>.</blockquote>

=== سلوك التخزين المؤقت ===
سنشرح تاليًا خوارزمية التخزين المؤقت للمُحمّل الافتراضي، لهذا يُرجى العودة إلى مزوّد الخدمة السحابية الذي تستخدم لمعلومات أوفى.

تُحسن الطلب تلقائيًا عند الطلب وتُخزّن في المجلد ‎<code><distDir>/cache/images</code>. تُقدّم الصورة المحسنة لاحقًا من هذا المجلد حتى تنتهي فترة صلاحيتها. عندما يتطابق الطلب مع ملف انتهت صلاحيته، تُقدّم الصورة كما هي مباشرة ثم تُحسّن الصورة مجددًا في الخلفية (يُدعى هذا أيضًا إعادة التحقق) وتُخزَّن في نفس المجلد وتُعطى فترة صلاحية جديدة.

تُحدد حالة التخزين المؤقت لصورة بقراءة قيمة ترويسة الاستجابة <code>x-nextjs-cache</code> التي تمتلك إحدى القيم التالية:

* <code>MISS</code>: المسار غير موجود في الذاكرة المؤقتة (يحدث ذلك غالبًا مرة واحدة عند أول زيارة).
* <code>STALE</code>: المسار موجود في الذاكرة المؤقتة لكنه تجاوز فترة الصلاحية لذا سيُحدّث في الخلفية.
* <code>HIT</code>: المسار في الذاكرة المؤقتة وضمن فترة الصلاحية.

تُحدد الصلاحية (أو العمر الأقصى) بالقيمة الأعلى للإعداد <code>minimumCacheTTL</code> أو ترويسة تيار رفع الصورة <code>Cache-Control</code>، وخاصة القيمة <code>max-age</code> للترويسة <code>Cache-Control</code>. وإن وجدت كلتا القيمتين <code>s-maxage</code> و <code>max-age</code> ستؤخذ القيمة <code>s-maxage</code>. تمرر قيمة <code>max-age</code> أيضًا ضمن أي تيار تنزيل للصور نحو العميل بما في ذلك شبكات إيصال المحتوى والمتصفحات.

* بإمكانك ضبط الإعداد <code>minimumCacheTTL</code> لزيادة زمن الصلاحية عندما لا يتضمن تيار رفع الصورة الترويسة <code>Cache-Control</code> أو أن قيمته صغيرة جدًا.
* بإمكانك تهيئة <code>deviceSizes</code> و <code>imageSizes</code> لتقليل العدد الكلي للصور التي يمكن توليدها.
* يمكنك استخدام الإعداد <code>formats</code> لتعطيل التنسيقات المتعددة للصورة لصالح تنسيق محدد.

=== الخاصية <code>minimumCacheTTL</code> ===
بإمكانك ضبط زمن الصلاحية (زمن البقاء) Time To Live بالثانية للصور المخزنة في الذاكرة المؤقتة. لكن من الأفضل في حالات كثيرة استخدام [[Next.js/image optimization|الإدراج الساكن للصور]] الذي يرمّز مباشرة محتوى الملف ويخزّن الذاكرة بشكل دائم من خلال ضبط قيمة الترويسة <code>Cache-Control</code> على <code>immutable</code>.<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}
</syntaxhighlight>تُحدد الصلاحية (أو العمر الأقصى) بالقيمة الأعلى للإعداد <code>minimumCacheTTL</code> أو ترويسة تيار رفع الصورة <code>Cache-Control</code>، وخاصة القيمة <code>max-age</code> للترويسة <code>Cache-Control</code>. فإن أردت تغيير هذا السلوك لكل صورة على حدى، تستطيع ذلك من خلال تهيئة الترويسات <code>headers</code> لكي تضيف الترويسة <code>Cache-Control</code> إلى تيار رفع الصورة (الصورة <code>some-asset.jpg/</code> مثلًا وليست الصورة <code>next/image_/</code> نفسها).

لا توجد آلية للتحقق من الذاكرة المؤقتة حاليًا، لذلك من الأفضل أن تبقي قيمة  <code>minimumCacheTTL</code> منخفضةً وإلا قد تضطر إلى تغيير الخاصية <code>src</code> يدويًا أو تلغي المجلد <code>distDir>/cache/images></code>.

=== تعطيل الإدراج الساكن ===
يسمح لك السلوك الافتراضي لمكون الصور أن تدرج ملفات صور ساكنة من خلال الأمر <code>import icon from './icon.png</code> ثم تمررها إلى الخاصية <code>src</code>. لكن قد ترغب في بعض الحالات أن تُعطِّل هذه الميزة إن تعارضت مع ملحقات أخرى تتوقع أن يكون إدراج الملفات مختلفًا. 

تستطيع تعطيل الإدراج الساكن للصور من خلال ملف التهيئة <code>next.config.js</code>:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    disableStaticImages: true,
  },
}
</syntaxhighlight>

=== خطورة السماح بالصور الشعاعية SVG ===
لا يُحسن المُحمّل الافتراضي الصور الشعاعية ذات التنسيق SVG لأسباب عدة أولها أنه بالإمكان تغيير أبعاد الصور الشعاعية دون أن تفقد شيئًا، والثاني أن للتنسيق SVG الكثير من الميزات التي تشابه HTML/CSS مما قد يسبب ثغرات ما لم تُضبط [[Next.js/security headers|ترويسات سياسة أمان المحتوى CSP]] بشكل ملائم. 

إن أردت تقديم صور SVG من خلال واجهة التحسين الافتراضية، اضبط الخاصيتين <code>dangerouslyAllowSVG</code> و <code>contentSecurityPolicy</code> ضمن ملف <code>next.config.js</code>:<syntaxhighlight lang="javascript">
module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}
</syntaxhighlight>

=== الصور المتحركة ===
يتجاوز المحمّل الافتراضي عملية تحسين الصور المتحركة تلقائيًا ويقدم الصورة كما هي. يدعم الكشف التلقائي عن الصور المتحركة التنسيقات GIF و APNG و WebP. لكن إن أردت أن تتجاوز صراحة تحسين صورة محددة، استخدم الخاصية <code>unoptimized</code>.

== اقرأ أيضًا ==

* [[Next.js/image optimization|تحسين الصور في Next.js]]

== أمثلة ==

* [https://github.com/vercel/next.js/tree/canary/examples/image-component Image Component]

== المصادر ==

* الصفحة [https://nextjs.org/docs/api-reference/next/image Next/image] من توثيق Next.js الرسمي.
[[تصنيف:Next.js|{{SUBPAGENAME}}]]
[[تصنيف:Next.js API|{{SUBPAGENAME}}]]