صورة

يمتد مكون الصورة في Next.js عنصر HTML <img> لتحسين الصور تلقائيًا.

import Image from 'next/image'

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

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

المرجع

الخصائص

الخصائص التالية متاحة:

src

مصدر الصورة. يمكن أن يكون أحد الخيارات التالية:

مسار داخلي كنص.

<Image src="/profile.png" />

رابط خارجي مطلق (يجب تكوينه مع remotePatterns).

<Image src="https://example.com/profile.png" />

استيراد ثابت.

import profile from './profile.png'

export default function Page() {
  return <Image src={profile} />
}

alt

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

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

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

تعلم المزيد عن إرشادات إمكانية الوصول للصور.

width و height

تمثل خصائص width و height الحجم الجوهري للصورة بالبكسل. تستخدم هذه الخاصية لاستنتاج نسبة العرض إلى الارتفاع الصحيحة التي يستخدمها المتصفحات لحجز مساحة للصورة وتجنب تحول التخطيط أثناء التحميل. لا تحدد حجم العرض المعروض للصورة، والذي يتم التحكم فيه بواسطة CSS.

<Image src="/profile.png" width={500} height={500} />

يجب تعيين كل من خصائص width و height إلا إذا:

• تم استيراد الصورة بشكل ثابت
• تحتوي الصورة على خاصية fill

إذا كان الارتفاع والعرض غير معروفين، نوصي باستخدام خاصية fill.

fill

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

<Image src="/profile.png" fill={true} />

التحديد المكاني:

• يجب أن يعين العنصر الأب position: "relative", "fixed", "absolute".
• افتراضيًا، يستخدم عنصر <img> position: "absolute".

ملاءمة الكائن:

إذا لم يتم تطبيق أي أنماط على الصورة، فستتمدد الصورة لملء الحاوية. يمكنك استخدام objectFit للتحكم في الاقتصاص والقياس.

• "contain": سيتم تصغير الصورة لتناسب الحاوية والحفاظ على نسبة العرض إلى الارتفاع.
• "cover": ستملأ الصورة الحاوية ويتم اقتصاصها.

تعلم المزيد عن position و object-fit.

loader

دالة مخصصة تستخدم لإنشاء رابط URL للصورة. تستقبل الدالة المعلمات التالية، وتعيد نص 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 في تطبيقك، دون تمرير خاصية.

sizes

تحديد أحجام الصورة عند نقاط التوقف المختلفة. يستخدمها المتصفح لاختيار الحجم الأنسب من مجموعة srcset المنشأة.

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 عندما:

• تستخدم الصورة خاصية fill
• يتم استخدام CSS لجعل الصورة متجاوبة

إذا كان sizes مفقودًا، يفترض المتصفح أن الصورة ستكون بعرض نافذة العرض (100vw). يمكن أن يتسبب ذلك في تحميل صور كبيرة بشكل غير ضروري.

بالإضافة إلى ذلك، يؤثر sizes على كيفية إنشاء srcset:

• بدون sizes: ينشئ Next.js مجموعة srcset محدودة (مثل 1x، 2x)، مناسبة للصور ذات الحجم الثابت.
• مع sizes: ينشئ Next.js مجموعة srcset كاملة (مثل 640w، 750w، إلخ)، محسنة للتخطيطات المتجاوبة.

تعلم المزيد عن srcset و sizes على web.dev و mdn.

quality

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

// الجودة الافتراضية هي 75
<Image quality={75} />

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

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

style

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

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

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

معلومة مفيدة: إذا كنت تستخدم خاصية style لتعيين عرض مخصص، تأكد من تعيين height: 'auto' أيضًا للحفاظ على نسبة العرض إلى الارتفاع للصورة.

priority

قيمة منطقية تشير إلى ما إذا كان يجب تحميل الصورة مسبقًا.

// الأولوية الافتراضية هي false
<Image priority={false} />

• true: تحميل مسبق للصورة. يعطل التحميل البطيء.
• false: تحميل الصورة بشكل بطيء.

متى تستخدمها:

• عندما تكون الصورة فوق الطية.
• عندما تكون الصورة عنصر أكبر محتوى مرئي (LCP).
• عندما تريد تحسين أداء التحميل الأولي لصفحتك.

متى لا تستخدمها:

• عند استخدام خاصية loading (سيؤدي إلى تحذيرات).

loading

يتحكم في متى يجب أن يبدأ تحميل الصورة.

// الافتراضي هو lazy
<Image loading="lazy" />

• lazy: تأجيل تحميل الصورة حتى تصل إلى مسافة محسوبة من نافذة العرض.
• eager: تحميل الصورة فورًا، بغض النظر عن موقعها في الصفحة.

استخدم eager فقط عندما تريد التأكد من تحميل الصورة فورًا.

تعلم المزيد عن خاصية loading.

placeholder

يحدد عنصر نائب لاستخدامه أثناء تحميل الصورة، مما يحسن أداء التحميل الملحوظ.

// الافتراضي هو empty
<Image placeholder="empty" />

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

أمثلة:

• عنصر نائب blur
• تأثير توهج مع خاصية placeholder لرابط البيانات
• تأثير لوني مع خاصية blurDataURL

تعلم المزيد عن خاصية placeholder.

blurDataURL

رابط بيانات لاستخدامه كصورة نائبة قبل تحميل الصورة بنجاح. يمكن تعيينه تلقائيًا أو استخدامه مع خاصية placeholder="blur".

<Image placeholder="blur" blurDataURL="..." />

يتم تكبير الصورة وضبابتها تلقائيًا، لذا يوصى باستخدام صورة صغيرة جدًا (10 بكسل أو أقل).

تلقائي

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

تعيين يدوي

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

• أداة عبر الإنترنت مثل png-pixel.com
• مكتبة مثل Plaiceholder

قد يؤثر blurDataURL الكبير على الأداء. احتفظ به صغيرًا وبسيطًا.

أمثلة:

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

onLoad

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

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

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

onError

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

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

unoptimized

قيمة منطقية تشير إلى ما إذا كان يجب تحسين الصورة. هذا مفيد للصور التي لا تستفيد من التحسين مثل الصور الصغيرة (أقل من 1 كيلوبايت)، أو الصور المتجهة (SVG)، أو الصور المتحركة (GIF).

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  // الافتراضي هو false
  return <Image {...props} unoptimized />
}

• true: سيتم تقديم الصورة المصدر كما هي من src بدلاً من تغيير الجودة أو الحجم أو التنسيق.
• false: سيتم تحسين الصورة المصدر.

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

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

overrideSrc

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

<Image src="/profile.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="/profile.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
<Image decoding="async" />

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

تعلم المزيد عن خاصية decoding.

خصائص أخرى

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

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

خصائص مهملة

onLoadingComplete

تحذير: أصبحت هذه الخاصية قديمة في Next.js 14، يُرجى استخدام onLoad بدلاً منها.

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

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

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

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

يمكنك تكوين مكون الصورة في ملف next.config.js. الخيارات المتاحة هي:

localPatterns

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

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

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

remotePatterns

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

module.exports = {
  images: {
    remotePatterns: [new URL('https://example.com/account123/**')],
  },
}

إذا كنت تستخدم إصدارًا أقدم من 15.3.0، يمكنك تكوين remotePatterns باستخدام الكائن:

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

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

أنماط الأحرف البديلة (Wildcard Patterns):

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

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

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

هذا يسمح بنطاقات فرعية مثل image.example.com. سلاسل الاستعلام والمنافذ المخصصة ما زالت محظورة.

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

سلاسل الاستعلام (Query Strings):

يمكنك أيضًا تقييد سلاسل الاستعلام باستخدام خاصية search:

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

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

loaderFile

loaderFiles يسمح لك باستخدام خدمة تحسين صور مخصصة بدلاً من Next.js.

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

يجب أن يكون المسار نسبيًا لجذر المشروع. يجب أن يصدر الملف دالة افتراضية تُرجع سلسلة URL:

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

مثال:

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

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

deviceSizes

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

إذا لم يتم توفير أي تكوين، يتم استخدام القيمة الافتراضية التالية:

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

imageSizes

imageSizes يسمح لك بتحديد قائمة بعروض الصور. هذه الأبعاد تُدمج مع مصفوفة أحجام الأجهزة لتشكيل المصفوفة الكاملة للأحجام المستخدمة لإنشاء srcset للصورة.

إذا لم يتم توفير أي تكوين، يتم استخدام القيمة الافتراضية التالية:

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

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

qualities

qualities يسمح لك بتحديد قائمة بقيم جودة الصور.

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

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

formats

formats يسمح لك بتحديد قائمة بتنسيقات الصور المستخدمة.

module.exports = {
  images: {
    // الافتراضي
    formats: ['image/webp'],
  },
}

يحدد Next.js تلقائيًا تنسيقات الصور المدعومة من المتصفح عبر رأس Accept في الطلب لتحديد تنسيق الإخراج الأمثل.

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

يمكنك تمكين دعم AVIF، والذي سيعود إلى التنسيق الأصلي لصورة src إذا كان المتصفح لا يدعم AVIF:

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

معلومة مفيدة:

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

minimumCacheTTL

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

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

module.exports = {
  images: {
    minimumCacheTTL: 60, // دقيقة واحدة
  },
}

يمكنك زيادة TTL لتقليل عدد عمليات إعادة التحقق وتقليل التكلفة المحتملة:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 يومًا
  },
}

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

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

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

disableStaticImages

disableStaticImages يسمح لك بتعطيل استيراد الصور الثابتة.

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

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

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

dangerouslyAllowSVG

dangerouslyAllowSVG يسمح لك بتقديم صور SVG.

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

بشكل افتراضي، لا يقوم Next.js بتحسين صور SVG لعدة أسباب:

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

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

<Image src="/my-image.svg" unoptimized />

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

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

contentDispositionType

contentDispositionType يسمح لك بتكوين رأس Content-Disposition.

module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

بشكل افتراضي، يعين المحمل (loader) رأس Content-Disposition إلى attachment للحماية الإضافية نظرًا لأن API يمكنه تقديم صور خارجية عشوائية.

القيمة الافتراضية هي attachment مما يجبر المتصفح على تنزيل الصورة عند الزيارة مباشرة. هذا مهم بشكل خاص عندما يكون dangerouslyAllowSVG صحيحًا.

يمكنك تكوين inline اختياريًا للسماح للمتصفح بعرض الصورة عند الزيارة مباشرة، دون تنزيلها.

خيارات التكوين القديمة

domains

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

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

فيما يلي مثال لخاصية domains في ملف next.config.js:

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

الدوال

getImageProps

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

import { getImageProps } from 'next/image'

const props = getImageProps({
  src: 'https://example.com/image.jpg',
  alt: 'A scenic mountain view',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>A scenic mountain view</figcaption>
    </figure>
  )
}

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

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

يستخدم مكون next/image تحميل كسول (lazy loading) أصليًا في المتصفح، والذي قد يعود إلى التحميل المبكر للمتصفحات الأقدم من Safari 15.4. عند استخدام العنصر النائب المموه (blur-up placeholder)، ستعود المتصفحات الأقدم من Safari 12 إلى عنصر نائب فارغ. عند استخدام أنماط بعرض/ارتفاع 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 إذا كانت الصورة فوق الطية (above the fold)

• Firefox 67+ يعرض خلفية بيضاء أثناء التحميل. الحلول الممكنة:

  • تمكين تنسيقات AVIF formats
  • استخدم placeholder

أمثلة

تنسيق الصور

تنسيق مكون الصورة مشابه لتنسيق عنصر <img> عادي، ولكن هناك بعض الإرشادات التي يجب مراعاتها:

استخدم className أو style، وليس styled-jsx. في معظم الحالات، نوصي باستخدام خاصية className. يمكن أن يكون هذا وحدة CSS Module مستوردة، أو صفحة أنماط عامة، إلخ.

import styles from './styles.module.css'

export default function MyImage() {
  return <Image className={styles.image} src="/my-image.png" alt="My Image" />
}

يمكنك أيضًا استخدام خاصية style لتعيين أنماط مضمنة.

export default function MyImage() {
  return (
    <Image style={{ borderRadius: '8px' }} src="/my-image.png" alt="My Image" />
  )
}

عند استخدام fill، يجب أن يكون للعنصر الأصلي position: relative أو display: block. هذا ضروري لعرض عنصر الصورة بشكل صحيح في هذا الوضع التخطيطي.

<div style={{ position: 'relative' }}>
  <Image fill src="/my-image.png" alt="My Image" />
</div>

لا يمكنك استخدام styled-jsx لأنه محصور بالمكون الحالي (ما لم تحدد النمط كـ global).

صور متجاوبة مع التصدير الثابت

عند استيراد صورة ثابتة، يقوم Next.js تلقائيًا بتعيين عرضها وارتفاعها بناءً على الملف. يمكنك جعل الصورة متجاوبة عن طريق تعيين النمط:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="Mountains"
        // استيراد صورة سيقوم
        // تلقائيًا بتعيين العرض والارتفاع
        src={mountains}
        sizes="100vw"
        // جعل الصورة تعرض بعرض كامل
        // والحفاظ على نسبة العرض إلى الارتفاع
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

صور متجاوبة مع عنوان URL بعيد

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

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 مع خاصية objectFit مضبوطة على cover. هذا سيجعل الصورة تملأ العرض الكامل للحاوية الأم.

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Fill() {
  return (
    <div
      style={{
        display: 'grid',
        gridGap: '8px',
        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',
      }}
    >
      <div style={{ position: 'relative', width: '400px' }}>
        <Image
          alt="Mountains"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* والمزيد من الصور في الشبكة... */}
    </div>
  )
}

صورة الخلفية

استخدم خاصية fill لجعل الصورة تغطي مساحة الشاشة بالكامل:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="Mountains"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

لمشاهدة أمثلة على مكون الصورة المستخدم مع الأنماط المختلفة، راجع عرض تجريبي لمكون الصورة.

الصور البعيدة

لاستخدام صورة بعيدة، يجب أن تكون خاصية src سلسلة عنوان URL.

import Image from 'next/image'

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

بما أن Next.js لا يمكنه الوصول إلى الملفات البعيدة أثناء عملية البناء، ستحتاج إلى توفير خاصيات width، height و blurDataURL يدويًا.

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

للسماح بتحسين الصور بأمان، حدد قائمة بأنماط عناوين URL المدعومة في next.config.js. كن محددًا قدر الإمكان لمنع الاستخدام الضار. على سبيل المثال، سيتيح التكوين التالي الصور فقط من دلو AWS S3 محدد:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
        search: '',
      },
    ],
  },
}

اكتشاف السمة

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

جربها:

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

توجيه فني

إذا كنت تريد عرض صورة مختلفة للجوال وسطح المكتب، يُعرف أحيانًا باسم التوجيه الفني (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>
  )
}

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