الواجهة البرمجية للمكوّن 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
لا بد ان تكون هذه الخاصية واحدة من هذه:
- ملف صورة مُدرج بشكل ساكن.
- مسار مطلق 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
على العنصر الأب.
الخاصية loader
وهي دالة مخصصة تُستخدم لتحليل عناوين 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
، لن يكون هناك حيّز لتحميل الصورة بل فقط مسافة فارغة. جرّب الامثلة التالية:
الخاصيات المتقدمة
قد تحتاج في بعض الحالات إلى طرق استخدام أكثر تقدمًا، لهذا ستجد أن المكوّن </ 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
اقرأ أيضًا
أمثلة
المصادر
- الصفحة Next/legacy/image من توثيق Next.js الرسمي.