Unverified Commit 93f62542 authored by Steven's avatar Steven Committed by GitHub

Add `onLoadingComplete()` prop to Image component (#26824)

This adds a new prop, `onLoadingComplete()`, to handle the most common use case of `ref`.

I also added docs and a warning when using `ref` so we recommend the new prop instead.
 
- Fixes #18398 
- Fixes #22482 
parent 3c994abc
......@@ -195,6 +195,10 @@ The image position when using `layout="fill"`.
[Learn more](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position)
### onLoadingComplete
A callback function that is invoked once the image is completely loaded and the placeholder has been removed.
### loading
> **Attention**: This property is only meant for advanced usage. Switching an
......@@ -242,6 +246,7 @@ Other properties on the `<Image />` component will be passed to the underlying
- `srcSet`. Use
[Device Sizes](/docs/basic-features/image-optimization.md#device-sizes)
instead.
- `ref`. Use [`onLoadingComplete`](#onloadingcomplete) instead.
- `decoding`. It is always `"async"`.
## Related
......
......@@ -120,6 +120,7 @@ export type ImageProps = Omit<
unoptimized?: boolean
objectFit?: ImgElementStyle['objectFit']
objectPosition?: ImgElementStyle['objectPosition']
onLoadingComplete?: () => void
} & (StringImageProps | ObjectImageProps)
const {
......@@ -261,30 +262,37 @@ function defaultImageLoader(loaderProps: ImageLoaderProps) {
// See https://stackoverflow.com/q/39777833/266535 for why we use this ref
// handler instead of the img's onLoad attribute.
function removePlaceholder(
function handleLoading(
img: HTMLImageElement | null,
placeholder: PlaceholderValue
placeholder: PlaceholderValue,
onLoadingComplete?: () => void
) {
if (placeholder === 'blur' && img) {
const handleLoad = () => {
if (!img.src.startsWith('data:')) {
const p = 'decode' in img ? img.decode() : Promise.resolve()
p.catch(() => {}).then(() => {
if (!img) {
return
}
const handleLoad = () => {
if (!img.src.startsWith('data:')) {
const p = 'decode' in img ? img.decode() : Promise.resolve()
p.catch(() => {}).then(() => {
if (placeholder === 'blur') {
img.style.filter = 'none'
img.style.backgroundSize = 'none'
img.style.backgroundImage = 'none'
})
}
}
if (img.complete) {
// If the real image fails to load, this will still remove the placeholder.
// This is the desired behavior for now, and will be revisited when error
// handling is worked on for the image component itself.
handleLoad()
} else {
img.onload = handleLoad
}
if (onLoadingComplete) {
onLoadingComplete()
}
})
}
}
if (img.complete) {
// If the real image fails to load, this will still remove the placeholder.
// This is the desired behavior for now, and will be revisited when error
// handling is worked on for the image component itself.
handleLoad()
} else {
img.onload = handleLoad
}
}
export default function Image({
......@@ -299,6 +307,7 @@ export default function Image({
height,
objectFit,
objectPosition,
onLoadingComplete,
loader = defaultImageLoader,
placeholder = 'empty',
blurDataURL,
......@@ -401,6 +410,11 @@ export default function Image({
)
}
}
if ('ref' in rest) {
console.warn(
`Image with src "${src}" is using unsupported "ref" property. Consider using the "onLoadingComplete" property instead.`
)
}
}
let isLazy =
!priority && (loading === 'lazy' || typeof loading === 'undefined')
......@@ -589,9 +603,9 @@ export default function Image({
{...imgAttributes}
decoding="async"
className={className}
ref={(element) => {
setRef(element)
removePlaceholder(element, placeholder)
ref={(img) => {
setRef(img)
handleLoading(img, placeholder, onLoadingComplete)
}}
style={imgStyle}
/>
......
import { useState } from 'react'
import Image from 'next/image'
const Page = () => (
<div>
<h1>On Loading Complete Test</h1>
<ImageWithMessage id="1" src="/test.jpg" />
<ImageWithMessage
id="2"
src={require('../public/test.png')}
placeholder="blur"
/>
</div>
)
function ImageWithMessage({ id, src }) {
const [msg, setMsg] = useState('[LOADING]')
return (
<>
<Image
id={`img${id}`}
src={src}
width="400"
height="400"
onLoadingComplete={() => setMsg(`loaded img${id}`)}
/>
<p id={`msg${id}`}>{msg}</p>
</>
)
}
export default Page
......@@ -182,6 +182,35 @@ function runTests(mode) {
}
})
it('should callback onLoadingComplete when image is fully loaded', async () => {
let browser
try {
browser = await webdriver(appPort, '/on-loading-complete')
await check(
() => browser.eval(`document.getElementById("img1").src`),
/test(.*)jpg/
)
await check(
() => browser.eval(`document.getElementById("img2").src`),
/test(.*).png/
)
await check(
() => browser.eval(`document.getElementById("msg1").textContent`),
'loaded img1'
)
await check(
() => browser.eval(`document.getElementById("msg2").textContent`),
'loaded img2'
)
} finally {
if (browser) {
await browser.close()
}
}
})
it('should work when using flexbox', async () => {
let browser
try {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment