next/image

示例

Image 组件

版本历史

版本	改变
`v11.0.0`	`src` prop support for static import. `placeholder` prop added. `blurDataURL` prop added.
`v10.0.5`	添加了 `loader` 属性。
`v10.0.1`	添加了 `layout` 属性。
`v10.0.0`	添加了 `next/image` 。

在继续之前，我们建议你首先阅读图片优化章节。

通过 <Image /> 组件可以开启图片优化功能，<Image /> 组件导出（export）自 next/image。

用法

例如，假定有一个包含了以下文件的项目：

pages/index.js
public/me.png

我们可以输出经过优化的图片，如下所示：

import Image from 'next/image'
import profilePic from '../public/me.png'

function Home() {
  return (
    <>
      <h1>My Homepage</h1>
      <Image src={profilePic} alt="Picture of the author" />
      <p>Welcome to my homepage!</p>
    </>
  )
}

export default Home

必须属性

必须为 <Image /> 组件设置以下属性。

src

Required and must be one of the following:

A statically imported image file, as in the example code above, or
A path string. This can be either an absolute external URL, or an internal path depending on the loader.

如果使用的是外部 URL，则必须添加到 next.config.js 配置文件中的 domains 配置项中。

width

图片的宽度（以像素为单位）。必须是不带单位的整数。

Required, except for statically imported images, or those with layout="fill".

height

图片的高度（以像素为单位）。必须是不带单位的整数。

Required, except for statically imported images, or those with layout="fill".

可选参数

<Image /> 组件还可以接受以下可选属性。

layout

当视口（viewport）改变尺寸时图片的布局行为。默认为 intrinsic。

当设置为 fixed 时，图片的尺寸不会随着视口的改变而改变（无响应性），类似于原始的 img 元素。

当设置为 intrinsic 时，图片将针对较小的视口按比例缩小尺寸，但对于较大的视口将保持原始尺寸。

当设置为 responsive 时，图片将缩小尺寸以适应较小的视口，并在较大视口时放大尺寸。

当设置为 fill 时，图片的宽度和高度会被拉伸到父元素的尺寸，通常与 objectFit 属性以同使用。

试一试：

loader

一个用于解析 URL 的自定义函数。默认为 next.config.js 中的 images 对象。

loader 是一个接受以下参数并返回一个字符串的函数：

src
width
quality

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

该值为字符串，用于媒体查询到设备尺寸的映射。默认值为 100vw。

我们建议在使用 layout="responsive" 或 layout="fill" 时设置 sizes，并且图片的宽度 不同鱼 视口（viewport）的宽度。

了解更多信息.

quality

图片优化后的质量，介于 1 到 100 之间的整数，其中 100 表示最佳质量。默认值为 75。

priority

当设置为 true 时，图片将被视为高优先级，并且会预加载。

当需要图片在首屏可见时才使用。默认值为 false。

placeholder

A placeholder to use while the image is loading, possible values are blur or empty. Defaults to empty.

When blur, the blurDataURL property will be used as the placeholder. If src is an object from a static import and the imported image is jpg, png, or webp, then blurDataURL will automatically be populated.

For dynamic images, you must provide the blurDataURL property. Solutions such as Plaiceholder can help with base64 generation.

When empty, there will be no placeholder while the image is loading, only empty space.

Try it out:

高级属性

在某些情况下，你可能需要更多高级的用法。<Image /> 组件可以接受以下高级属性（可选）。

objectFit

当设置为 layout="fill" 时，图片的 object-fit 属性的取值。

了解更多信息

objectPosition

当设置为 layout="fill" 时，图片 object-position 属性的取值。

了解更多信息

loading

注意：此属性仅用于高级用途。将图片切换为 eager 方式加载，通常会 损伤性能。

我们建议改用 priority 属性，该属性几乎可以在所有的用例中迅速加载图片。

加载图片时的行为。默认为 lazy。

当设置为 lazy 时，将图片的加载推迟到其距离视口（viewport）达到某一距离时。

当设置为 eager 时，图片将被立即加载。

了解更多信息

blurDataURL

A Data URL to be used as a placeholder image before the src image successfully loads. Only takes effect when combined with placeholder="blur".

Must be a base64-encoded image. It will be enlarged and blurred, so a very small image (10px or less) is recommended. Including larger images as placeholders may harm your application performance.

Try it out:

You can also generate a solid color Data URL to match the image.

unoptimized

当设置为 true 时，直接提供原始图片，不修改图片质量、尺寸或格式。默认为 false。

其它属性

除了以下属性外，<Image /> 组件所接收到的其它属性将被传递给底层的 img 元素：

style。使用 className 替代。
srcSet。使用 Device Sizes 替代。
decoding。始终是 "async"。