next/image

示例
版本历史
版本改变
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'

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

export default Home

必须属性

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

src

原图片的路径或 URL。此属性是必须的。

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

width

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

除非设置了 layout="fill",否则是必须的。

height

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

除非设置了 layout="fill",否则是必须的。

可选参数

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

layout

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

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

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

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

当设置为 fill 时,图片会将宽度和高度拉伸到 父元素的尺寸,通常与 object-fit 一同使用。

试一试:

loader

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

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

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

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

priority

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

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

高级属性

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

objectFit

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

了解更多信息

objectPosition

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

了解更多信息

loading

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

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

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

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

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

了解更多信息

unoptimized

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

其它属性

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

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

相关内容

有关下一步该做什么,我们建议阅读以下章节: