<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

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

'use client'

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

معلومة مفيدة: استخدام خصائص مثل loader، التي تقبل دالة، يتطلب استخدام مكونات العميل (Client Components) لتحويل الدالة المقدمة.

بدلاً من ذلك، يمكنك استخدام تكوين 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 بقيمة 33vw، ستكون الصورة المختارة من الخادم أوسع بثلاث مرات مما يجب أن تكون. نظرًا لأن حجم الملف يتناسب مع مربع العرض، فبدون sizes، سيقوم المستخدم بتنزيل صورة أكبر بتسع مرات مما هو ضروري.

تعلم المزيد عن srcset و sizes:

• web.dev
• mdn

quality

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

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

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

'use client'

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

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

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

معلومة مفيدة: استخدام خصائص مثل onLoadingComplete، التي تقبل دالة، يتطلب استخدام مكونات العميل (Client Components) لتحويل الدالة المقدمة.

onLoad

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

دالة رد اتصال يتم استدعاؤها عند تحميل الصورة.

قد يحدث حدث التحميل قبل إزالة العنصر النائب للصورة وفك تشفير الصورة بالكامل. إذا كنت تريد الانتظار حتى يتم تحميل الصورة بالكامل، فاستخدم onLoadingComplete بدلاً من ذلك.

معلومة مفيدة: استخدام خصائص مثل onLoad، التي تقبل دالة، يتطلب استخدام مكونات العميل (Client Components) لتحويل الدالة المقدمة.

onError

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

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

معلومة مفيدة: استخدام خصائص مثل onError، التي تقبل دالة، يتطلب استخدام مكونات العميل (Client Components) لتحويل الدالة المقدمة.

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

الخصائص الأخرى

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

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

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

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

remotePatterns

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

module.exports = {
  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 = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
      },
    ],
  },
}

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

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

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

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

domains

تحذير: نوصي بتكوين remotePatterns بدقة بدلاً من domains لحماية تطبيقك من المستخدمين الضارين. استخدم 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 الخاص بك. يجب أن يصدر الملف دالة افتراضية تُرجع سلسلة نصية، على سبيل المثال:

'use client'

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

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

أمثلة:

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

معلومة جيدة: يتطلب تخصيص ملف محمل الصور، الذي يقبل دالة، استخدام مكونات العميل (Client Components) لتحويل الدالة المقدمة إلى تنسيق قابل للتخزين.

متقدم

التكوين التالي مخصص لحالات الاستخدام المتقدمة وعادةً لا يكون ضروريًا. إذا اخترت تكوين الخصائص أدناه، فستتجاوز أي تغييرات على الإعدادات الافتراضية لـ 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],
  },
}

formats

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

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

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

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 إلى أي عملاء لاحقين بما في ذلك شبكات توصيل المحتوى (CDNs) والمتصفحات.

• يمكنك تكوين 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، مما قد يؤدي إلى ثغرات أمنية بدون سياسة أمان محتوى (Content Security Policy) مناسبة.

إذا كنت بحاجة إلى تقديم صور 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="Picture of the author"
      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="Picture of the author"
      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: '500px', height: '300px' }}>
      <Image
        src={photoUrl}
        alt="Picture of the author"
        sizes="500px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

جربها:

• عرض خاصية fill

اكتشاف السمة (Theme Detection)

إذا كنت تريد عرض صورة مختلفة لوضعي الضوء والظلام، يمكنك إنشاء مكون جديد يضم مكوني <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".

جربها بنفسك:

• عرض توضيحي لاكتشاف سمة الضوء/الظلام

أخطاء متصفح معروفة (Known Browser Bugs)

يستخدم مكون next/image هذا تحميل كسول (lazy loading) أصلي من المتصفح، والذي قد يعود إلى التحميل المتعطش (eager loading) للمتصفحات القديمة قبل Safari 15.4. عند استخدام عنصر نائب ضبابي (blur-up placeholder)، ستعود المتصفحات القديمة قبل Safari 12 إلى عنصر نائب فارغ. عند استخدام أنماط مع width/height بقيمة auto، من الممكن التسبب في انزياح تخطيط (Layout Shift) على المتصفحات القديمة قبل Safari 15 التي لا تحافظ على نسبة العرض إلى الارتفاع (aspect ratio). لمزيد من التفاصيل، راجع هذا الفيديو من 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 إذا كانت الصورة فوق الطية (above the fold)
• Firefox 67+ يعرض خلفية بيضاء أثناء التحميل. حلول ممكنة:
  • تمكين formats من نوع AVIF
  • استخدم placeholder

سجل الإصدارات (Version History)