مكون <Image>

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

سيساعدك مرجع API هذا على فهم كيفية استخدام الخصائص (props) وخيارات التكوين المتاحة لمكون الصورة. لميزات الاستخدام، يرجى زيارة صفحة مكون الصورة.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="صورة المؤلف"
    />
  )
}

الخصائص (Props)

فيما يلي ملخص لخصائص مكون الصورة المتاحة:

الخصائص المطلوبة

يتطلب مكون الصورة الخصائص التالية: src، width، height، و alt.

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="صورة المؤلف"
      />
    </div>
  )
}

src

يجب أن يكون أحد الخيارات التالية:

• ملف صورة مستورد بشكل ثابت
• مسار نصي. يمكن أن يكون عنوان URL خارجي مطلق، أو مسار داخلي اعتمادًا على خاصية المحمل (loader).

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

width

تمثل خاصية width العرض المعروض بالبكسل، لذا ستؤثر على حجم الصورة الظاهر.

مطلوبة، باستثناء الصور المستوردة بشكل ثابت أو الصور ذات خاصية fill.

height

تمثل خاصية height الارتفاع المعروض بالبكسل، لذا ستؤثر على حجم الصورة الظاهر.

مطلوبة، باستثناء الصور المستوردة بشكل ثابت أو الصور ذات خاصية fill.

alt

تستخدم خاصية alt لوصف الصورة لقارئات الشاشة ومحركات البحث. وهي أيضًا النص الاحتياطي إذا تم تعطيل الصور أو حدث خطأ أثناء تحميل الصورة.

يجب أن تحتوي على نص يمكن أن يحل محل الصورة دون تغيير معنى الصفحة. لا يُقصد بها استكمال الصورة ولا يجب أن تكرر المعلومات المقدمة بالفعل في التسميات التوضيحية أعلى أو أسفل الصورة.

إذا كانت الصورة زخرفية بحتة أو غير مخصصة للمستخدم، فيجب أن تكون خاصية alt نصًا فارغًا (alt="").

تعلم المزيد

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

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

loader

دالة مخصصة تستخدم لحل عناوين URL للصور.

loader هي دالة تُرجع سلسلة عنوان URL للصورة، مع الأخذ في الاعتبار المعلمات التالية:

• src
• width
• quality

فيما يلي مثال على استخدام محمل مخصص:

import Image from 'next/image'

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

export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="صورة المؤلف"
      width={500}
      height={500}
    />
  )
}

بدلاً من ذلك، يمكنك استخدام تكوين loaderFile في ملف next.config.js لتكوين كل مثيل لـ next/image في تطبيقك، دون تمرير خاصية.

fill

fill={true} // {true} | {false}

قيمة منطقية تجعل الصورة تملأ العنصر الأب، وهو مفيد عندما يكون width و height غير معروفين.

يجب أن يخصص العنصر الأب نمط position: "relative" أو position: "fixed" أو position: "absolute".

بشكل افتراضي، سيتم تخصيص نمط position: "absolute" لعنصر img تلقائيًا.

إذا لم يتم تطبيق أي أنماط على الصورة، فستتمدد الصورة لملء الحاوية. قد تفضل تعيين object-fit: "contain" لصورة محاطة لتلائم الحافظة والحفاظ على نسبة العرض إلى الارتفاع.

بدلاً من ذلك، سيؤدي object-fit: "cover" إلى ملء الصورة للحاوية بالكامل واقتصاصها للحفاظ على نسبة العرض إلى الارتفاع. لكي يبدو هذا صحيحًا، يجب تعيين نمط overflow: "hidden" للعنصر الأب.

لمزيد من المعلومات، راجع أيضًا:

• position
• object-fit
• object-position

sizes

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

تخدم خاصية sizes غرضين مهمين متعلقين بأداء الصورة:

• أولاً، تستخدم المتصفحات قيمة sizes لتحديد حجم الصورة الذي يجب تنزيله، من srcset الذي تم إنشاؤه تلقائيًا بواسطة next/image. عندما يختار المتصفح، لا يعرف بعد حجم الصورة على الصفحة، لذا يختار صورة بنفس حجم أو أكبر من نافذة العرض. تتيح لك خاصية sizes إخبار المتصفح بأن الصورة ستكون في الواقع أصغر من الشاشة الكاملة. إذا لم تحدد قيمة sizes في صورة ذات خاصية fill، فسيتم استخدام القيمة الافتراضية 100vw (عرض الشاشة الكاملة).
• ثانيًا، تغير خاصية sizes سلوك قيمة srcset التي تم إنشاؤه تلقائيًا. إذا لم تكن هناك قيمة sizes موجودة، يتم إنشاء srcset صغير مناسب لصورة بحجم ثابت (1x/2x/إلخ). إذا تم تعريف sizes، يتم إنشاء srcset كبير مناسب لصورة متجاوبة (640w/750w/إلخ). إذا كانت خاصية sizes تتضمن أحجامًا مثل 50vw، التي تمثل نسبة مئوية من عرض نافذة العرض، فسيتم تقليم srcset لاستبعاد أي قيم صغيرة جدًا بحيث لا تكون ضرورية أبدًا.

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

import Image from 'next/image'

export default function Page() {
  return (
    <div className="grid-element">
      <Image
        fill
        src="/example.png"
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
      />
    </div>
  )
}

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

تعرف على المزيد حول srcset و sizes:

• web.dev
• mdn

quality

quality={75} // {number 1-100}

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

إذا تم تعريف تكوين qualities في next.config.js، فيجب أن تتطابق خاصية quality مع إحدى القيم المحددة في التكوين.

معلومة مفيدة: إذا كانت صورة المصدر الأصلية منخفضة الجودة بالفعل، فقد يؤدي تعيين خاصية الجودة مرتفعة جدًا إلى جعل الصورة المحسنة الناتجة أكبر من صورة المصدر الأصلية.

priority

priority={false} // {false} | {true}

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

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

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

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

عنصر نائب يستخدم أثناء تحميل الصورة. القيم الممكنة هي blur، empty، أو data:image/.... القيمة الافتراضية هي empty.

عند blur، سيتم استخدام خاصية blurDataURL كعنصر نائب. إذا كان src كائنًا من استيراد ثابت وكانت الصورة المستوردة .jpg، .png، .webp، أو .avif، فسيتم ملء blurDataURL تلقائيًا، إلا إذا تم اكتشاف أن الصورة متحركة.

للصور الديناميكية، يجب توفير خاصية blurDataURL. يمكن أن تساعد حلول مثل Plaiceholder في إنشاء base64.

عند data:image/...، سيتم استخدام عنوان URL للبيانات (Data URL) كعنصر نائب أثناء تحميل الصورة.

عند empty، لن يكون هناك عنصر نائب أثناء تحميل الصورة، فقط مساحة فارغة.

جربها:

• عرض توضيحي لعنصر النائب blur
• عرض توضيحي لتأثير اللمعان مع خاصية placeholder لعنوان URL للبيانات
• عرض توضيحي لتأثير اللون مع خاصية blurDataURL

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

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

style

يسمح بتمرير أنماط CSS إلى عنصر الصورة الأساسي.

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

تذكر أن خصائص العرض والارتفاع المطلوبة يمكن أن تتفاعل مع تصميمك. إذا استخدمت التصميم لتعديل عرض الصورة، فيجب أيضًا تصميم ارتفاعها على auto للحفاظ على نسبة العرض إلى الارتفاع الأصلية، وإلا ستتشوه صورتك.

onLoadingComplete

<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />

تحذير: مهمل منذ Next.js 14 لصالح onLoad.

دالة رد اتصال يتم استدعاؤها بمجرد تحميل الصورة بالكامل وإزالة العنصر النائب.

سيتم استدعاء دالة الرد بوسيطة واحدة، مرجع لعنصر <img> الأساسي.

onLoad

<Image onLoad={(e) => console.log(e.target.naturalWidth)} />

دالة رد اتصال يتم استدعاؤها بمجرد تحميل الصورة بالكامل وإزالة العنصر النائب.

سيتم استدعاء دالة الرد بوسيطة واحدة، الحدث الذي يحتوي على target يشير إلى عنصر <img> الأساسي.

onError

<Image onError={(e) => console.error(e.target.id)} />

دالة رد اتصال يتم استدعاؤها إذا فشل تحميل الصورة.

loading

توصية: هذا الخصائص مخصص فقط لحالات الاستخدام المتقدمة. تحويل صورة للتحميل باستخدام eager عادةً ما يؤثر سلبًا على الأداء. نوصي باستخدام خاصية priority بدلاً من ذلك، والتي ستعمل على تحميل الصورة مسبقًا بفعالية.

loading = 'lazy' // {lazy} | {eager}

سلوك تحميل الصورة. الافتراضي هو lazy.

عندما يكون lazy، يتم تأجيل تحميل الصورة حتى تصل إلى مسافة محسوبة من منطقة العرض.

عندما يكون eager، يتم تحميل الصورة على الفور.

تعرف على المزيد حول خاصية loading.

blurDataURL

رابط بيانات (Data URL) ل استخدامها كصورة نائبة قبل تحميل صورة src بنجاح. يكون له تأثير فقط عند دمجه مع placeholder="blur".

يجب أن تكون الصورة مشفرة بـ base64. سيتم تكبيرها وطمسها، لذلك يُنصح باستخدام صورة صغيرة جدًا (10 بكسل أو أقل). تضمين صور أكبر كعناصر نائبة قد يضر بأداء تطبيقك.

جربه:

• عرض خاصية blurDataURL الافتراضية
• عرض تأثير اللون مع خاصية blurDataURL

يمكنك أيضًا إنشاء رابط بيانات بلون ثابت لمطابقة الصورة.

unoptimized

unoptimized = {false} // {false} | {true}

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

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

منذ Next.js 12.3.0، يمكن تعيين هذه الخاصية لجميع الصور عن طريق تحديث next.config.js بالإعداد التالي:

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

overrideSrc

عند تقديم خاصية src لمكون <Image>، يتم إنشاء كل من سمات srcset و src تلقائيًا للنتيجة <img>.

<Image src="/me.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

في بعض الحالات، قد لا يكون من المرغوب فيه إنشاء سمة src ويمكنك تجاوزها باستخدام خاصية overrideSrc.

على سبيل المثال، عند ترقية موقع ويب موجود من <img> إلى <Image>، قد ترغب في الحفاظ على نفس سمة src لأغراض تحسين محركات البحث مثل ترتيب الصور أو تجنب إعادة الزحف.

<Image src="/me.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

تلميح للمتصفح يشير إلى ما إذا كان يجب عليه الانتظار لفك تشفير الصورة قبل عرض تحديثات المحتوى الأخرى أم لا. الافتراضي هو async.

القيم الممكنة هي التالية:

• async - فك تشفير الصورة بشكل غير متزامن والسماح بعرض محتوى آخر قبل اكتمالها.
• sync - فك تشفير الصورة بشكل متزامن لعرض ذري مع محتوى آخر.
• auto - لا توجد تفضيلات لوضع فك التشفير؛ يقرر المتصفح الأفضل.

تعرف على المزيد حول خاصية decoding.

خصائص أخرى

سيتم تمرير الخصائص الأخرى على مكون <Image /> إلى العنصر img الأساسي باستثناء التالي:

• srcSet. استخدم أحجام الجهاز (Device Sizes) بدلاً من ذلك.

خيارات التكوين

بالإضافة إلى الخصائص، يمكنك تكوين مكون الصورة في next.config.js. الخيارات المتاحة هي:

localPatterns

يمكنك تكوين localPatterns اختياريًا في ملف next.config.js للسماح بمسارات محددة بالتحسين وحظر جميع المسارات الأخرى.

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

جيد للمعرفة: المثال أعلاه سيضمن أن خاصية src لـ next/image يجب أن تبدأ بـ /assets/images/ ويجب ألا تحتوي على سلسلة استعلام. محاولة تحسين أي مسار آخر سترد بـ 400 طلب غير صالح.

remotePatterns

لحماية تطبيقك من المستخدمين الضارين، يلزم التكوين لاستخدام الصور الخارجية. هذا يضمن أن الصور الخارجية من حسابك فقط يمكن تقديمها من واجهة برمجة تطبيقات تحسين الصور في Next.js. يمكن تكوين هذه الصور الخارجية باستخدام خاصية remotePatterns في ملف next.config.js، كما هو موضح أدناه:

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

جيد للمعرفة: المثال أعلاه سيضمن أن خاصية src لـ next/image يجب أن تبدأ بـ https://example.com/account123/ ويجب ألا تحتوي على سلسلة استعلام. أي بروتوكول آخر، أو اسم مضيف، أو منفذ، أو مسار غير متطابق سيرد بـ 400 طلب غير صالح.

أدناه مثال لخاصية remotePatterns في ملف next.config.js باستخدام نمط حرف البدل في hostname:

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

جيد للمعرفة: المثال أعلاه سيضمن أن خاصية src لـ next/image يجب أن تبدأ بـ https://img1.example.com أو https://me.avatar.example.com أو أي عدد من النطاقات الفرعية. لا يمكن أن تحتوي على منفذ أو سلسلة استعلام. أي بروتوكول آخر أو اسم مضيف غير متطابق سيرد بـ 400 طلب غير صالح.

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

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

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

جيد للمعرفة: عند حذف protocol، أو port، أو pathname، أو search، فإن حرف البدل ** يكون ضمنيًا. هذا غير موصى به لأنه قد يسمح للمستخدمين الضارين بتحسين عناوين URL لم تقصدها.

أدناه مثال لخاصية remotePatterns في ملف next.config.js باستخدام search:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

جيد للمعرفة: المثال أعلاه سيضمن أن خاصية src لـ next/image يجب أن تبدأ بـ https://assets.example.com ويجب أن تحتوي على سلسلة الاستعلام الدقيقة ?v=1727111025337. أي بروتوكول آخر أو سلسلة استعلام سيرد بـ 400 طلب غير صالح.

domains

تحذير: أصبحت قديمة منذ Next.js 14 لصالح remotePatterns الصارمة لحماية تطبيقك من المستخدمين الضارين. استخدم domains فقط إذا كنت تملك كل المحتوى المقدم من النطاق.

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

ومع ذلك، لا يدعم تكوين domains مطابقة نمط حرف البدل ولا يمكنه تقييد البروتوكول، أو المنفذ، أو مسار المسار.

أدناه مثال لخاصية domains في ملف next.config.js:

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

loaderFile

إذا كنت تريد استخدام مزود سحابي لتحسين الصور بدلاً من استخدام واجهة برمجة تطبيقات تحسين الصور المدمجة في Next.js، يمكنك تكوين loaderFile في next.config.js كما يلي:

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

يجب أن يشير هذا إلى ملف نسبي لجذر تطبيق Next.js الخاص بك. يجب أن يصدر الملف دالة افتراضية تُرجع سلسلة، على سبيل المثال:

export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

بدلاً من ذلك، يمكنك استخدام خاصية loader لتكوين كل مثيل من next/image.

أمثلة:

• تكوين محمل الصور المخصص

متقدم

التكوين التالي مخصص لحالات الاستخدام المتقدمة وعادةً ما لا يكون ضروريًا. إذا اخترت تكوين الخصائص أدناه، فستتجاوز أي تغييرات على إعدادات Next.js الافتراضية في التحديثات المستقبلية.

deviceSizes

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

إذا لم يتم توفير أي تكوين، يتم استخدام الافتراضي أدناه.

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],
  },
}

qualities

ستسمح واجهة برمجة تطبيقات تحسين الصور (Image Optimization API) الافتراضية تلقائيًا بجميع الجودات من 1 إلى 100. إذا كنت ترغب في تقييد الجودات المسموح بها، يمكنك إضافة تكوين إلى next.config.js.

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

في المثال أعلاه، يُسمح فقط بثلاث جودات: 25، 50، و75. إذا لم تتطابق خاصية quality مع قيمة في هذه المصفوفة، فستفشل الصورة بـ 400 طلب غير صالح.

formats

ستكتشف واجهة برمجة تطبيقات تحسين الصور (Image Optimization API) الافتراضية تلقائيًا تنسيقات الصور المدعومة من المتصفح عبر رأس Accept للطلب.

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

إذا لم يتم توفير أي تكوين، يتم استخدام الافتراضي أدناه.

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

يمكنك تمكين دعم AVIF بالتكوين التالي.

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

جيد للمعرفة:

• يستغرق AVIF عادةً 20٪ وقتًا أطول للتشفير ولكنه يضغط بنسبة 20٪ أصغر مقارنة بـ WebP. هذا يعني أن المرة الأولى التي يتم فيها طلب صورة، ستكون عادةً أبطأ ثم الطلبات اللاحقة التي يتم تخزينها مؤقتًا ستكون أسرع.
• إذا كنت تستضيف بنفسك مع وكيل/شبكة توصيل محتوى (Proxy/CDN) أمام Next.js، فيجب تكوين الوكيل لإعادة توجيه رأس Accept.

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

يصف ما يلي خوارزمية التخزين المؤقت لـ المحمل (loader) الافتراضي. بالنسبة لجميع المحملات الأخرى، يرجى الرجوع إلى وثائق مزود السحابة الخاص بك.

يتم تحسين الصور ديناميكيًا عند الطلب وتخزينها في دليل <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

يمكنك تكوين وقت البقاء (TTL) بالثواني للصور المحسنة المخزنة مؤقتًا. في كثير من الحالات، من الأفضل استخدام استيراد صورة ثابتة (Static Image Import) والتي ستقوم تلقائيًا بتجزئة محتويات الملف وتخزين الصورة مؤقتًا إلى الأبد مع رأس Cache-Control بقيمة immutable.

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

يتم تعريف تاريخ انتهاء الصورة المحسنة (أو بالأحرى الحد الأقصى للعمر) إما عن طريق minimumCacheTTL أو رأس Cache-Control للصورة الأصلية، أيهما أكبر.

إذا كنت بحاجة إلى تغيير سلوك التخزين المؤقت لكل صورة، يمكنك تكوين headers لتعيين رأس Cache-Control على الصورة الأصلية (مثل /some-asset.jpg، وليس /_next/image نفسها).

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

disableStaticImages

يسمح السلوك الافتراضي باستيراد الملفات الثابتة مثل import icon from './icon.png' ثم تمريرها إلى خاصية src.

في بعض الحالات، قد ترغب في تعطيل هذه الميزة إذا كانت تتعارض مع ملحقات أخرى تتوقع أن يكون الاستيراد مختلفًا.

يمكنك تعطيل استيراد الصور الثابتة داخل next.config.js:

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

dangerouslyAllowSVG

لا يقوم المحمل (loader) الافتراضي بتحسين صور SVG لعدة أسباب. أولاً، SVG هو تنسيق متجه مما يعني أنه يمكن تغيير حجمه دون فقدان الجودة. ثانياً، يحتوي SVG على العديد من الميزات المشابهة لـ HTML/CSS، مما قد يؤدي إلى ثغرات أمنية بدون رؤوس سياسة أمان المحتوى (CSP) المناسبة.

لذلك، نوصي باستخدام خاصية unoptimized عندما يكون معروفاً أن خاصية src تشير إلى صورة SVG. يحدث هذا تلقائياً عندما ينتهي src بـ ".svg".

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

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

بالإضافة إلى ذلك، يُوصى بشدة بتعيين contentDispositionType لإجبار المتصفح على تنزيل الصورة، وكذلك تعيين contentSecurityPolicy لمنع تنفيذ البرامج النصية المضمنة في الصورة.

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

سيقوم المحمل (loader) الافتراضي تلقائياً بتجاوز تحسين الصور للصور المتحركة وعرض الصورة كما هي.

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

الصور المتجاوبة

تحتوي مجموعة srcset المُنشأة افتراضياً على صور 1x و 2x لدعم نسب بكسل مختلفة للأجهزة. ومع ذلك، قد ترغب في عرض صورة متجاوبة تتمدد مع نافذة العرض. في هذه الحالة، ستحتاج إلى تعيين sizes بالإضافة إلى style (أو className).

يمكنك عرض صورة متجاوبة باستخدام إحدى الطرق التالية.

صورة متجاوبة باستخدام استيراد ثابت

إذا لم تكن الصورة المصدر ديناميكية، يمكنك استيرادها بشكل ثابت لإنشاء صورة متجاوبة:

import Image from 'next/image'
import me from '../photos/me.jpg'

export default function Author() {
  return (
    <Image
      src={me}
      alt="صورة المؤلف"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

جربها:

• عرض الصورة المتجاوبة مع نافذة العرض

صورة متجاوبة مع نسبة العرض إلى الارتفاع

إذا كانت الصورة المصدر ديناميكية أو عنوان URL بعيد، ستحتاج أيضاً إلى توفير width و height لتعيين نسبة العرض إلى الارتفاع الصحيحة للصورة المتجاوبة:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="صورة المؤلف"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

جربها:

• عرض الصورة المتجاوبة مع نافذة العرض

صورة متجاوبة مع fill

إذا كنت لا تعرف نسبة العرض إلى الارتفاع، ستحتاج إلى تعيين خاصية fill وتعيين position: relative على العنصر الأب. اختيارياً، يمكنك تعيين نمط object-fit اعتماداً على السلوك المطلوب للتمدد مقابل الاقتصاص:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
      <Image
        src={photoUrl}
        alt="صورة المؤلف"
        sizes="300px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

جربها:

• عرض خاصية fill

كشف السمة باستخدام CSS

إذا كنت ترغب في عرض صورة مختلفة لوضعي الضوء والظلام، يمكنك إنشاء مكون جديد يضم مكوني <Image> ويعرض الصورة الصحيحة بناءً على استعلام CSS الإعلامي.

.imgDark {
  display: none;
}

@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'

type Props = Omit<ImageProps, 'src' | 'priority' | 'loading'> & {
  srcLight: string
  srcDark: string
}

const ThemeImage = (props: Props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

import styles from './theme-image.module.css'
import Image from 'next/image'

const ThemeImage = (props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

معلومة جيدة: يضمن السلوك الافتراضي لـ loading="lazy" تحميل الصورة الصحيحة فقط. لا يمكنك استخدام priority أو loading="eager" لأن ذلك سيؤدي إلى تحميل كلتا الصورتين. بدلاً من ذلك، يمكنك استخدام fetchPriority="high".

جربها:

• عرض كشف السمة للوضعين الفاتح والداكن

getImageProps

للحالات الأكثر تقدمًا، يمكنك استدعاء getImageProps() للحصول على الخصائص التي سيتم تمريرها إلى عنصر <img> الأساسي، وبدلاً من ذلك تمريرها إلى مكون آخر أو نمط أو لوحة رسم (canvas)، إلخ.

هذا أيضًا يتجنب استدعاء useState() من React مما قد يؤدي إلى أداء أفضل، ولكنه لا يمكن استخدامه مع خاصية placeholder لأن العنصر النائب لن يتم إزالته أبدًا.

كشف السمة باستخدام <picture>

إذا كنت ترغب في عرض صورة مختلفة لوضعي الضوء والظلام، يمكنك استخدام عنصر <picture> لعرض صورة مختلفة بناءً على نظام الألوان المفضل للمستخدم.

import { getImageProps } from 'next/image'

export default function Page() {
  const common = { alt: 'مثال السمة', width: 800, height: 400 }
  const {
    props: { srcSet: dark },
  } = getImageProps({ ...common, src: '/dark.png' })
  const {
    props: { srcSet: light, ...rest },
  } = getImageProps({ ...common, src: '/light.png' })

  return (
    <picture>
      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
      <source media="(prefers-color-scheme: light)" srcSet={light} />
      <img {...rest} />
    </picture>
  )
}

التوجيه الفني (Art Direction)

إذا كنت ترغب في عرض صورة مختلفة للهواتف المحمولة وأجهزة الكمبيوتر، والمعروف أحيانًا باسم التوجيه الفني، يمكنك توفير خصائص مختلفة لـ src و width و height و quality لـ getImageProps().

import { getImageProps } from 'next/image'

export default function Home() {
  const common = { alt: 'مثال التوجيه الفني', sizes: '100vw' }
  const {
    props: { srcSet: desktop },
  } = getImageProps({
    ...common,
    width: 1440,
    height: 875,
    quality: 80,
    src: '/desktop.jpg',
  })
  const {
    props: { srcSet: mobile, ...rest },
  } = getImageProps({
    ...common,
    width: 750,
    height: 1334,
    quality: 70,
    src: '/mobile.jpg',
  })

  return (
    <picture>
      <source media="(min-width: 1000px)" srcSet={desktop} />
      <source media="(min-width: 500px)" srcSet={mobile} />
      <img {...rest} style={{ width: '100%', height: 'auto' }} />
    </picture>
  )
}

خلفية CSS

يمكنك حتى تحويل سلسلة srcSet إلى دالة CSS image-set() لتحسين صورة الخلفية.

import { getImageProps } from 'next/image'

function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}

export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }

  return (
    <main style={style}>
      <h1>مرحباً بالعالم</h1>
    </main>
  )
}

أخطاء متصفح معروفة

يستخدم مكون next/image هذا تحميل كسول أصلي من المتصفح، والذي قد يعود إلى التحميل المتعطش للمتصفحات الأقدم من Safari 15.4. عند استخدام العنصر النائب blur-up، ستعود المتصفحات الأقدم من Safari 12 إلى عنصر نائب فارغ. عند استخدام أنماط مع width/height بقيمة auto، من الممكن التسبب في تحول التخطيط (Layout Shift) على المتصفحات الأقدم من Safari 15 التي لا تحافظ على نسبة العرض إلى الارتفاع. لمزيد من التفاصيل، راجع هذا الفيديو من MDN.

• Safari 15 - 16.3 يعرض حدًا رماديًا أثناء التحميل. Safari 16.4 أصلح هذه المشكلة. الحلول الممكنة:
  • استخدم CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • استخدم priority إذا كانت الصورة فوق الطية
• Firefox 67+ يعرض خلفية بيضاء أثناء التحميل. الحلول الممكنة:
  • تمكين تنسيقات formats AVIF
  • استخدم placeholder

سجل الإصدارات