الواجهة البرمجية للمكوّن next/legacy/image في Next.js

من موسوعة حسوب

ملاحظة: كُتب هذا التوثيق للواجهة البرمجية الخاصة بالمكوّن image ولتحسين الصور. للاطلاع أكثر على هذه الميزة واستخدامها في Next.js عُد إلى صفحة "تحسين الصور" من هذا التوثيق.

ملاحظة: بدءًا من الإصدار 13 أعيد تسمية المكون next/image إلى next/legacy/image.

أعيدت كتابة شيفرة المكوّن ابتداءً من النسخة لتحسين الأداء وتحسين تجربة المطورين. لكن لإيجاد حل لعملية التحديث كي تتلائم مع النسخ القديمة، أعيدت تسمية المكوّن next/image ليصبح next/legacy/image.

مقارنة بين المكوّنين:

  • إزالة العنصر الذي يحيط بعنصر الصورة من أجل استخدام طريقة أصيلة لحساب النسبة بين بعدي الصورة.
  • دعم الخاصية style.
  • إزالة الخاصية layout لصالح استخدام style أو className.
  • إزالة الخاصية objectFit لصالح استخدام style أو className.
  • إزالة الخاصية objectPosition لصالح استخدام style أو className.
  • إزالة الخاصية IntersectionObserver لمصلحة استخدام الأسلوب الأصلي في التحميل الكسول Lazy load.
  • إزالة الخاصية lazyBoundary لعدم وجود مكافئ أصيل native.
  • إزالة الخاصية lazyRoot لعدم وجود مكافئ أصيل native.
  • إزالة الإعداد loader لصالح استخدام الخاصية loader.
  • تغير صفة الخاصية alt من اختياري إلى ضروري.
  • تغير دالة الاستدعاء onLoadingComplete لتقبل معامل واحد كمرجع إلى العنصر <img>.

الخاصيات الضرورية

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

الخاصية src

لا بد ان تكون هذه الخاصية واحدة من هذه:

  1. ملف صورة مُدرج بشكل ساكن.
  2. مسار مطلق absolute لعنوان URL خارجي أو داخلي وفقًا للمحمّل loader أو وفقًا لإعدادات المحمّل المخصصة.

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

الخاصية width

وتمثّل هذه الخاصية الاتساع المُصيَّر أو الاتساع الأصلي مقدرًا بالبكسل، وذلك وفقًا لقيم الخاصيتين layout و sizes.

  • تمثل الخاصية width الاتساع المُصيّر مقدرًا بالبكسل عند استخدام القيم layout="intrinsic" أو layout="fixed"، وسيؤثر ذلك على حجم الصورة التي تظهر.
  • تمثل الخاصية width الاتساع الأصلي مقدرًا بالبكسل عند استخدام القيم layout="responsive" و layout="fill"، وسيؤثر ذلك فقط على نسبة العرض aspect ratio.

هذه الخاصية مطلوبة ما عدا حالة الصورة المدرجة بشكل ساكن أو تلك التي تكون قيمة الخاصية layout لها هي "fill".

الخاصية height

وتمثّل هذه الخاصية الارتفاع المُصيَّر أو الإرتفاع الأصلي مقدرًا بالبكسل، وذلك وفقًا لقيم الخاصيتين layout و sizes.

  • تمثل الخاصية width الإرتفاع المُصيّر مقدرًا بالبكسل عند استخدام القيم layout="intrinsic" أو layout="fixed"، وسيؤثر ذلك على حجم الصورة التي تظهر.
  • تمثل الخاصية width الإرتفاع الأصلي مقدرًا بالبكسل عند استخدام القيم layout="responsive" و layout="fill"، وسيؤثر ذلك فقط على نسبة العرض aspect ratio.

هذه الخاصية مطلوبة ما عدا حالة الصورة المدرجة بشكل ساكن أو تلك التي تكون قيمة الخاصية layout لها هي "fill".

الخاصيات الاختيارية

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

الخاصية layout

إليك جدولًا بسلوك التخطيط layout عندما تتغير نافذة العرض view port:

لتخطيط layout السلوك السمة srcSet السمة sizes هل تمتلك مُغلِّف ومُحجّم؟
intrinsic افتراضي يُصغِّر الصورة ليلائم اتساع الحاوية حجم الصورة. 1x أو 2x وفقًا لحجم الصورة imageSize غير متاحة نعم
fixed يضبط الاتساع width والارتفاع height تمامًا. 1x أو 2x وفقًا لحجم الصورة imageSize غير متاحة نعم
responsive يُغيّر الحجم ليلائم اتساع الحاوية 640w أو 750w أو 2048w أو 3840w وفقًا لحجم الصورة وأبعاد جهاز العرض 100vw نعم
fill يغير الحجم وفق المحورين X و Y ليلائم الحاوية 640w أو 750w أو 2048w أو 3840w وفقًا لحجم الصورة وأبعاد جهاز العرض 100vw نعم
  • التخطيط الافتراضي intrinsic:
    • يُصغّر أبعاد الصورة لتلائم نافذة عرض أصغر، لكن ستحافظ على أبعاد الصورة في نوافذ العرض الأوسع.
  • التخطيط fixed:
    • لا تتغير أبعاد الصورة عندما تتغير نافذة العرض (لا تجاوب) ويشابه في ذلك سلوك العنصر img.
  • التخطيط responsive:
    • يُصغّر أبعاد الصورة لتلائم نافذة عرض أصغر، ويكبر أبعاد الصورة في نوافذ العرض الأوسع.
    • عليك التأكد من استخدام العنصر الأب للتنسيق display:block ضمن صفحة التنسيقات المورّثة CSS.
  • التخطيط fill:
    • يمدد الصورة في كلا الاتجاهين أي وفق الطول والعرض لتطابق أبعاد العنصر الأب، بحيث يكون تنسيق موقع الأب "نسبي relative".
    • يترافق استخدام التخطيط مع الخاصية objectFit.
    • تأكد من تطبيق قاعدة التنسيق position: relative على العنصر الأب.

المُحمِّل

وهي دالة مخصصة تُستخدم لتحليل عناوين URL. يُلغي استخدام المحمِّل كخاصية في المكوِّن المُحمِّل الافتراضي المُعرَّف في القسم images ضمن الملف next.config.js.

تأخذ دالة المحمّل loader التي تعيد عنوان URL نصي للصورة المعاملات التالية:

  • src
  • width
  • quality

إليك مثالًا عن استخدام محمّل مخصص مع next/image:

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}
    />
  )
}

الخاصية sizes

قيمة نصية تقدّم معلومات عن اتساع الصورة في حالات مختلفة. وتؤثر قيمة الخاصية sizes بشدة على أداء الصورة التي تستخدم الخاصية layout="responsive" أو layout="fill"، وسيجري تجاهلها في الصور التي تستخدم layout="intrinsic" أو layout="fixed". وللخاصية sizes غايتان أساسيتان تتعلقان بأداء الصورة:

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

الثانية: تُحلل الخاصية sizes وتستخدم لاقتصاص مجموعة الأحجام التي يوّلدها المكون next/legacy/image تلقائيًا. فإن ضمت الخاصية sizes قياسات مثل 50vw والتي تشير إلى نسبة مئوية من اتساع نافذة العرض، ستُختصر قائمة الأحجام كي لا تتضمن أية قيم أصغر بكثير من اللازم.

لو عرفت مثلًا أن التنسيق الذي تستخدمه سيسبب تمدد الصورة لتحتل اتساع النافذة في أجهزة الهاتف المحمول أو في تخطيط العمودين الخاص بالأجهزة اللوحية أو تخطيط الأعمدة الثلاث في شاشات الحواسب المكتبية، لا بد أن تستخدم الخاصية sizes كالتالي:

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

قد يؤثر ستخدام الخاصية sizes في المثال السابق بشكل واضح على معايير الأداء. فمن دون استخدام القياس 33vw ستكون اتساع الصورة التي تحملها الصفحة من الخادم أكبر بثلاث مرات من المطلوب، ولأن حجم الملف يتناسب طردًا مع مربّع الاتساع، سيحمّل المستخدم صورة أكبر بتسع مرات من المطلوب إن لم نستخدم sizes.

الخاصية quality

وتمثل نوعية الصورة المحسنة كرقم صحيح بين 1 و 100. تمثّل 100 الدقة الأفضل والقيمة الافتراضية 75.

الخاصية priority

تُعد الصور ذات أولوية عالية عندما تأخذ هذه الخاصية القيمة true ويُعاد تحميلها، وتعطل ميزة التحميل الكسول تلقائيًا في حال استخدام هذه الخاصية.

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

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

الخاصية placeholder

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

  • عندما تكون قيمة الخاصية blur، تُستخدم الخاصية blurDataURL لحجز حيّز الصورة. وإن كانت قيمة الخاصية src كائنًا مصدره إدراج ساكن لصورة لها أحد الامتدادات jpg. أو png. أو webp. أو avif.، سيُحدد blurDataURL حيّز الصورة تلقائيًا. يجب استخدام الخاصية blurDataURL مع الصور الديناميكية، كما أن حلولًا مثل Plaiceholder قد تساعد عند تمثيل العناصر باستخدام التشفير base64.
  • عندما تكون قيمة الخاصية empty، لن يكون هناك حيّز لتحميل الصورة بل فقط مسافة فارغة. جرّب الامثلة التالية:
    • مثال عن حيّز التحميل مع blur.
    • مثال عن تأثير الوميض مع الخاصية blurDataURL.
    • مثال عن التأثير اللوني مع الخاصية blurDataURL.

الخاصيات المتقدمة

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

الخاصية style

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

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

الخاصية objectFit

وتعرّف طريقة ضبط الصورة لتتلائم مع حاوية العنصر الأب عند استخدام التخطيط "layout="fill. تمرر هذه الخاصية إلى خاصية CSS التي تماثلها بالاسم object-fit والعائدة للصورة التي تحددها الخاصية src.

الخاصية objectPosition

تعرّف هذه الخاصية موضع الصورة ضمن العنصر الأب عند استخدام التخطيط layout="fill"، وتُمرر إلى خاصية CSS التي تماثلها بالاسم object-position والمطبّقة على الصورة.

الدالة onLoadingComplete

وهي دالة تُنفَّذ بمجرد أن يكتمل تحميل الصورة ويُزال الحيّز المحدد لها أثناء التحميل. تقبل هذه الدالة معاملًا واحدًا وهو كائن له الخاصيات التالية:

  • naturalWidth
  • naturalHeight

الخاصية loading

تنبيه: صممت هذه الخاصية للاستخدام المتقدم. فقد يسيء استخدام التحميل الشره eager إلى الأداء. لهذا ننصح باستخدام الخاصية priority بدلًا عنها، إذ تحمّل هذه الخاصية الصورة "بشراهة" في معظم الحالات تقريبًا.

تحدد الخاصية سلوك تحميل الصورة، وقيمتها الافتراضية lazy (كسول). ففي حالة السلوك الكسول lazy، لا تُحمّل الصورة حتى تقترب مسافة محددة من نافذة العرض (قبل أن تُعرض بقليل). أما في حالة السلوك الشره eager، ستُحمّل الصورة مباشرة.

الخاصية blurDataURL

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

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

الخاصية lazyBoundary

وهي نص (يشابه في صيغته الخاصية margin) يعمل كصندوق إحاطة لاكتشاف التقاطع بين نافذة العرض والصورة ويسبب بدء التحميل الكسول لها، وتأخذ الخاصية القيمة الافتراضية "200px". إن وضعت الصورة ضمن عنصر أب يدعم التمرير بدلًا من أن تكون في جذر الصفحة، ستحتاج أيضًا إلى تحديد قيمة الخاصية lazyRoot.

الخاصية lazyRoot

وهي مرجع React يدل على العنصر الأب الذي يدعم التمرير، وتأخذ القيمة الافتراضية null (نافذة العرض تحتجزها الصفحة). ينبغي أن يشير المرجع إلى عنصر DOM أو مكوّن React يوجّه المرجع إلى عنصر DOM التحتي.

إليك مثالًا يشير إلى عنصر DOM: 

import Image from 'next/image'
import React from 'react'

const lazyRoot = React.useRef(null)

const Example = () => (
  <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
    <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
    <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
  </div>
)

وإليك مثالًا آخر يشير إلى مكوّن React: 

import Image from 'next/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

الخاصية unoptimized

تُقدم الصورة في حال كانت قيمة هذه الخاصية true كما هي دون تغيير في النوعية أو الحجم. القيمة الافتراضية لهذه الخاصية false.

يمكن تعيين هذه الخاصية لكل الصور بتحديث الملف next.config.js من خلال إضافة الإعدادات التالية:

module.exports = {
    images: {
      unoptimized: true,
    },
  },
}

خاصيات أخرى

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

  • srcSet: استعمل DeviceSizes بدلًا عنها.
  • ref: استعمل onLoadingComplete بدلًا عنها.
  • decoding: وتكون دائمًا "async".

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

الخاصية remotePatterns

ملاحظة: يُعد الإعداد remotePatterns تجريبيًا حاليًا وعرضة للتغيير. استخدم domains في نسخ الإنتاج.

لا بد من تهيئة تطبيقك حتى يستخدم صورًا من مصادر خارجية دون أن يتسلل المستخدمين المشبوهين من خلالها إلى تطبيقك. وبهذا تتأكد أن الصور الخارجية التي تأتي من حساباتك فقط يمكن تخديمها بواسطة واجهة Next.js البرمجية لتحسين الصور. يمكن أن تُهيأ هذه الصور من خلال الخاصية remotePatterns في الملف next.config.js كما يلي:

module.exports = {
  experimental: {
    images: {
      remotePatterns: [
        {
          protocol: 'https',
          hostname: 'example.com',
          port: '',
          pathname: '/account123/**',
        },
      ],
    },
  },
}

ملاحظة: يتأكد المثال السابق من ضرورة أن تبدأ الخاصية src للمكوّن next/image بالعنوان /https://example.com/account123. وأي بروتوكول أو اسم مضيف أو منفذ أو مسار لا يتطابق معه سيولّد الخطأ 400 (طلب خاطئ bad request)

إليك مثالًا آخر عن استخدام الخاصية remotePatterns في الملف next.config.js:

module.exports = {
  experimental: {
    images: {
      remotePatterns: [
        {
          protocol: 'https',
          hostname: '**.example.com',
        },
      ],
    },
  },
}

ملاحظة: يتأكد المثال السابق من ضرورة أن تبدأ الخاصية src للمكوّن next/image بأحد العناوين https://img1.example.com أو https://me.avatar.example.com. وأي بروتوكول أو اسم مضيف أو منفذ أو مسار لا يتطابق معه سيولّد الخطأ 400 (طلب خاطئ bad request).

يمكن استخدام أنماط الأحرف البديلة لترميز pathname أو hostname وفقًا للصيغتين التاليتين:

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

لا تعمل الصيغة ** وسط النمط.

النطاقات domain

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

إليك مثالًا آخر عن استخدام الخاصية domains في الملف next.config.js:

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

إعدادات المحمِّل

إن أردت استخدام مزوّد سحابي لتحسين الصور بدلًا من استخدام واجهة Next.js البرمجية المدمجة لتحسين الصور، يمكنك إعداد الخاصية loader والبادئة path في ملف next.config.js. يسمح لك ذلك استخدام عناوين URL النسبية ضمن الخاصية src لمكوّن الصورة وتوليد المسار المطلق الصحيح تلقائيَا لمزوّدك.

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

المحمِّلات المدمجة

إليك بعض المزودات السحابية المدمجة لتحسين الصورة:

  • الافتراضي: يعمل تلقائيًا مع أو خادم مخصص.
  • Vercel: يعمل تلقائيًا عندما تنشر التطبيق على Vercel، ولا يحتاج أية إعدادات.
  • Imgix: من خلال المحمّل loader: 'imgix'.
  • Cloudinary: من خلال المحمّل loader: 'cloudinary'.
  • Akamai: من خلال المحمّل loader: 'akamai'.
  • مخصص: من خلال المحمّل loader: 'custom' ويستخدم أي مزوّد سحابي من خلال تهيئة الخاصية loader في المكوّن next/legacy/image.

لا يمكن تحسين الصور أثناء بناء التطبيق باستخدام next export، بل فقط عند الطلب. لهذا عليك استخدام محمّل آخر غير المحمّل الافتراضي إن أردت استخدام next/image مع next export. يستخدم المحمّل الافتراضي للمكوّن next/legacy/image المكتبة squoosh لأنها سريعة التثبيت ومناسبة لبيئة التطوير. ننصح بشدة عند استعمال الأمر next start في بيئة التطوير أن تثبِّت المكتبة sharp بتنفيذ الأمر yarn add sharp في جذر المشروع. لا يُعد ذلك ضروريًا للنشر على Vercel لأنها مثبّتة تلقائيًا عليه.

إعدادات متقدمة

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

الخاصية deviceSizes

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

إن لم تكن هناك أية إعدادات بهذا الخصوص، تُطبق القيم الافتراضية التالية:

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

الخاصية imageSizes

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

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

إن لم تكن هناك أية إعدادات بهذا الخصوص، تُطبق القيم الافتراضية التالية:

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

تنسيقات الصور المقبولة

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

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

إن لم تكن هناك أية إعدادات بهذا الخصوص، تُطبق القيم الافتراضية التالية:

module.exports = {
  images: {
    formats: ['image/webp'],
  },
}

بإمكانك تفعيل التنسيق AVIF من خلال الإعداد التالي:

module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}

ملاحظة: تتطلب الصورة وفق تنسيق AVIF زمنًا أطول بحوالي 20% لتشفيرها، لكن يمكن أن تُضغط أكثر موفرة 20% موازنةً بالتنسيق WebP. وهذا يعني أن تحميل تلك الصور للمرة الأولى سيكون أبطأ لكن التحميلات التالية من الذاكرة المؤقتة سيكون أسرع.

سلوك التخزين المؤقت

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

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

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

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

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

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

الخاصية minimumCacheTTL

بإمكانك ضبط زمن الصلاحية (زمن البقاء) Time To Live بالثانية للصور المخزنة في الذاكرة المؤقتة. لكن من الأفضل في حالات كثيرة استخدام الإدراج الساكن للصور الذي يرمّز مباشرة محتوى الملف ويخزّن الذاكرة بشكل دائم من خلال ضبط قيمة الترويسة Cache-Control على immutable.

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

تُحدد الصلاحية (أو العمر الأقصى) بالقيمة الأعلى للإعداد minimumCacheTTL أو ترويسة تيار رفع الصورة Cache-Control، وخاصة القيمة max-age للترويسة Cache-Control. فإن أردت تغيير هذا السلوك لكل صورة على حدى، تستطيع ذلك من خلال تهيئة الترويسات headers لكي تضيف الترويسة Cache-Control إلى تيار رفع الصورة (الصورة some-asset.jpg/ مثلًا وليست الصورة next/image_/ نفسها).

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

تعطيل الإدراج الساكن

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

تستطيع تعطيل الإدراج الساكن للصور من خلال ملف التهيئة next.config.js:

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

خطورة السماح بالصور الشعاعية SVG

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

إن أردت تقديم صور SVG من خلال واجهة التحسين الافتراضية، اضبط الخاصيتين dangerouslyAllowSVG و contentSecurityPolicy ضمن ملف next.config.js:

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

الصور المتحركة

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

اقرأ أيضًا

أمثلة

المصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Next.js/next_legacy_image&oldid=32660»