<NuxtImg>

如何使用和配置 Nuxt Image 组件。

<NuxtImg> 是原生 <img> 标签的直接替代品。

使用内置提供商优化本地和远程图像
将 src 转换为提供商优化的 URL
根据 width 和 height 自动调整图像大小
当提供 sizes 选项时生成响应式大小
支持原生懒加载以及其他 <img> 属性

用法

<NuxtImg> 直接输出一个原生的 img 标签（没有任何包装器）。像使用 <img> 标签一样使用它：

<NuxtImg src="/nuxt-icon.png" />

结果将是：

<img src="/nuxt-icon.png">

使用默认提供商时，您应该将 /nuxt-icon.png 放在 public/ 目录中，以便 Nuxt 3 使上述示例生效。

Props

`custom`

custom 属性决定 <NuxtImg> 应该渲染为一个简单的 <img> 元素还是仅作为自定义渲染的提供商。当设置为 true 时，它会禁用默认渲染行为，允许完全控制图像的显示方式。这对于实现自定义功能（例如占位符）非常有用。

当使用 custom 属性时，<NuxtImg> 会将必要的数据和属性传递给其默认插槽。您可以通过 v-slot 指令访问以下值：

imgAttrs：<img> 元素的属性（例如 alt、width、height、srcset、sizes）。
src：计算出的图像源 URL。
isLoaded：一个布尔值，指示图像是否已加载。

Example Usage

<NuxtImg
  src="/images/nuxt.png"
  alt="image"
  width="400"
  height="400"
  :custom="true"
  v-slot="{ src, isLoaded, imgAttrs }"
>
  <!-- Show the actual image when loaded -->
  <img
    v-if="isLoaded"
    v-bind="imgAttrs"
    :src="src"
  >

  <!-- Show a placeholder while loading -->
  <img
    v-else
    src="https://placehold.co/400x400"
    alt="placeholder"
  >
</NuxtImg>

这种方法确保了自定义渲染场景的灵活性，同时 <NuxtImg> 在后台继续处理图像优化和数据供应。

`src`

图片文件路径

对于 public/ 目录中的静态图片，src 应该采用绝对路径的形式。否则，它应该是提供商期望的以 / 开头的路径或 URL。

<NuxtImg src="/nuxt.png" />

当 src 中使用外部 URL 进行图像优化时，我们需要使用 domains 选项将其列入白名单。

`width` / `height`

指定图片的宽度/高度。

对于图标或头像等静态大小的图片，使用所需的宽度/高度
对于响应式图片（使用 sizes 时），使用原始图片的宽度/高度

`alt`

尽管 Nuxt Image 不会进行任何特殊处理，但值得一提的是 alt 属性。它是一个原生全局属性，用于指定图像无法显示时图像的替代文本。

它 应该始终 提供。

如果图片包含信息，文本应该描述图片
如果图片在 <a> 元素内，文本应该解释链接指向何处
如果图片仅用于装饰，则使用 alt=""

<NuxtImg
  src="/nuxt.png"
  alt="My image file description"
/>

`sizes`

指定响应式尺寸。

这是一个由屏幕尺寸/宽度对组成的空格分隔列表。您可以在此处查看定义的屏幕尺寸列表。

默认情况下，Nuxt 生成 响应式优先 的尺寸。

如果您省略了屏幕尺寸前缀（例如 sm:），则此尺寸是图像的 “默认” 尺寸。否则，Nuxt 将选择最小尺寸作为图像的默认尺寸。
此默认尺寸一直使用到下一个指定的屏幕宽度，依此类推。每个指定的尺寸对都向上应用 - 因此 md:400px 意味着图像在 md 屏幕及以上将尺寸为 400px。

示例:

<NuxtImg
  src="/logos/nuxt.png"
  sizes="100vw sm:50vw md:400px"
/>

`densities`

为像素密度增加的屏幕生成特殊版本的图像。

示例:

<NuxtImg
  src="/logos/nuxt.png"
  height="50"
  densities="x1 x2"
/>

<!--
<img
  src="/_ipx/w_50/logos/nuxt.png" 
  srcset="/_ipx/w_100/logos/nuxt.png x2"
/>
-->

`placeholder`

在实际图像完全加载之前显示一个占位符图像。

您还可以使用 custom prop 来制作您想要的任何占位符。

placeholder prop 可以是字符串、布尔值、数字或数组。每种用法如下所示。

<!-- Automatically generate a placeholder based on the original image -->
<NuxtImg src="/nuxt.png" placeholder />

<!-- Set a width, height for the automatically generated placeholder  -->
<NuxtImg src="/nuxt.png" :placeholder="[50, 25]" />

<!-- Set a width, height, quality & blur for the automatically generated placeholder  -->
<NuxtImg src="/nuxt.png" :placeholder="[50, 25, 75, 5]" />

<!-- Set the width & height of the automatically generated placeholder, image will be a square -->
<NuxtImg src="/nuxt.png" :placeholder="15" />

<!-- Provide your own image -->
<NuxtImg src="/nuxt.png" placeholder="./placeholder.png" />

您还可以利用 useImage() 根据原始图像生成占位符图像，如果源是 SVG 或者您想更好地控制修饰符，这会很有用：

<template>
  <NuxtImg
    src="/nuxt.svg"
    :placeholder="img(`/nuxt.svg`, { h: 10, f: 'png', blur: 2, q: 50 })"
  />
</template>

<script setup lang="ts">
const img = useImage()
</script>

`placeholder-class`

当使用占位符时，您可以使用 placeholder-class 为原始底层 <img> 元素（在渲染占位符时）应用一个类。

<!-- Apply a static class to the original image -->
<NuxtImg
  src="/nuxt.png"
  placeholder
  placeholder-class="custom"
/>

<!-- Apply a dynamic class to the original image -->
<NuxtImg
  src="/nuxt.png"
  placeholder
  :placeholder-class="custom"
/>

如果您需要仅对 已加载 的图像应用一些 CSS，您可以使用类似以下的代码：

img:not(.my-placeholder-class) {
  /* styles here */
}

`provider`

使用其他提供商而不是 nuxt.config 中指定的默认提供商选项。

示例:

<template>
  <NuxtImg
    provider="cloudinary"
    src="/remote/nuxt-org/blog/going-full-static/main.png"
    width="300"
    height="169"
  />
</template>

export default defineNuxtConfig({
  image: {
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/nuxt/image/upload'
    }
  }
})

`preset`

预设是预定义图像修饰符的集合，可用于在您的项目中创建统一形式的图像。

我们可以在 nuxt.config 中使用预设选项定义预设。

<template>
  <NuxtImg preset="cover" src="/nuxt-icon.png" />
</template>

export default defineNuxtConfig({
  image: {
    presets: {
      cover: {
        modifiers: {
          fit: 'cover',
          format: 'jpg',
          width: 300,
          height: 300
        }
      }
    }
  }
})

`format`

如果您想以特定格式提供图像，请使用此属性。

<NuxtImg
  format="webp"
  src="/nuxt-icon.png"
/>

可用格式包括 webp、avif、jpeg、jpg、png、gif 和 svg。如果未指定格式，它将遵循默认图像格式。

`quality`

生成的图像的质量。

<NuxtImg
  src="/nuxt.jpg"
  quality="80"
  width="200"
  height="100"
/>

`fit`

fit 属性指定图像的大小。您可以使用此属性的五个标准值。

cover：（默认）保持纵横比，通过裁剪/剪切以适应来确保图像覆盖提供的两个尺寸
contain：保持纵横比，在提供的两个尺寸内包含图像，必要时使用“letterboxing”。
fill：忽略输入的纵横比，并拉伸到提供的两个尺寸。
inside：保持纵横比，将图像大小调整到尽可能大，同时确保其尺寸小于或等于指定的两个尺寸。
outside：保持纵横比，将图像大小调整到尽可能小，同时确保其尺寸大于或等于指定的两个尺寸。

<NuxtImg
  fit="cover"
  src="/nuxt-icon.png"
  width="200"
  height="100"
/>

有些提供商支持其他值。

`modifiers`

除了标准修饰符，每个提供商可能还有自己的附加修饰符。由于这些修饰符取决于提供商，请参阅其文档以了解可以使用哪些修饰符。

使用 modifiers 属性可以应用任何这些转换。

示例:

<NuxtImg
  provider="cloudinary"
  src="/remote/nuxt-org/blog/going-full-static/main.png"
  width="300"
  height="169"
  :modifiers="{ roundCorner: '0:100' }"
/>

`preload`

如果您想预加载图像，请使用此属性。这将在页面头部放置一个相应的 link 标签。

<NuxtImg src="/nuxt-icon.png" preload />

`loading`

这是一个原生属性，它向浏览器提供关于如何处理视口外图像加载的提示。自 2022 年 3 月以来，所有主要浏览器的最新版本都支持它。

设置 loading="lazy" 以延迟图像加载，直到它出现在视口中。

<NuxtImg src="/nuxt-icon.png" loading="lazy" />

`nonce`

这是一个原生全局属性，定义了一个加密的 nonce（一次性使用的数字），内容安全策略可以使用它来确定是否允许给定元素的给定抓取继续进行。提供 nonce 允许您避免使用 CSP unsafe-inline 指令，该指令会允许所有内联脚本或样式。

<template>
  <NuxtImg
    src="/nuxt-icon.png"
    :nonce="nonce"
  />
</template>

<script setup lang="ts">
// useNonce is not provided by @nuxt/image but might be
// provided by another module, for example nuxt-security
const nonce = useNonce()
</script>

Events

<NuxtImg> 和 <NuxtPicture> 组件中包含的 <img> 元素发出的原生事件会被重新发出，并且可以被监听。

示例: 监听 <NuxtImg> 的原生 onLoad 事件

<NuxtImg
  src="/images/colors.jpg"
  width="500"
  height="500"
  @load="doSomethingOnLoad"
/>

贡献

我们对您的贡献感激不尽。

了解如何使用和配置 Nuxt Picture 组件。