# NgOptimizedImage 入门

# NgOptimizedImage 指令可以轻松采用关于性能的最佳实践来加载图片。

该指令可确保最大内容绘制 (LCP)图片的加载优先级为：

自动设置 <img> 标签上的 fetchpriority属性
默认惰性加载其他图片
断言文档头中有相应的预连接链接标签
自动生成 srcset属性
如果应用程序使用 SSR，则生成预加载提示

除了优化 LCP 图片的加载之外，NgOptimizedImage还实施了许多图片最佳实践，例如：

使用图片 CDN URL 应用图片优化
通过要求 width和 height来防止布局偏移
如果 width或 height设置不正确，则会发出警告
给出渲染时图片是否会在视觉上失真的警告

# 快速上手link

#

# 步骤 1：导入 NgOptimizedImagelink

#

import { NgOptimizedImage } from '@angular/common'

该指令被定义为独立指令，因此组件应该直接导入它。

# 第 2 步：（可选）设置加载器link

# 使用 NgOptimizedImage 不一定需要图片加载器，但使用带有图片 CDN 的加载器可以实现强大的性能特性，包括为图片自动设置 `srcset`。

有关设置加载器的简短指南，请参阅本页末尾的配置图片加载器部分。

# 第 3 步：启用该指令link

# 要激活 `NgOptimizedImage`指令，请将图片的 `src`属性替换为 `ngSrc`。

<img ngSrc="cat.jpg">

如果你使用的是内置的第三方加载器，请确保忽略了 src中的基本 URL 路径，因为它会由此加载器自动附加。

# 步骤 4：将图片标记为 `priority`link

# 始终将页面上的 `LCP 图片` 标记为 `priority`的，以优先加载它。

<img ngSrc="cat.jpg" width="400" height="200" priority>

将图片标记为 priority会应用以下优化：

设置 fetchpriority=high（在这里阅读有关优先级提示的更多内容）
设置 loading=eager（在这里阅读有关原生惰性加载的更多信息）
如果做服务器端渲染，则会自动生成预加载链接元素。

如果 LCP 元素是不具有 priority属性的图片，则 Angular 会在开发过程中显示警告。页面的 LCP 元素可能会因许多因素而异 - 例如用户屏幕的尺寸，因此一个页面可能有多个应该标记为 priority的图片。有关更多详细信息，请参阅 CSS for Web Vitals 。

# 第 5 步：包括高度和宽度link

# 为了防止与图片相关的布局移位，NgOptimizedImage 要求你为图片指定高度和宽度，如下所示：

<img ngSrc="cat.jpg" width="400" height="200">

对于响应式图片（会相对于视口而增长和缩小的图片），width和 height属性应该是图片文件的内在大小。

对于固定大小的图片，width和 height属性应该反映图片的所需渲染的大小。这些属性的纵横比应始终与图片的固有纵横比匹配。

注意：如果你不知道图片的大小，请考虑使用“填充（fill）模式”来继承父容器的大小，如下所述：

# 使用 `fill`模式link

# 如果你希望让图片填充其容器元素，可以用 `fill`属性。当你想实现“背景图片”行为时，这通常会很有用。当你不知道图片的确切宽度和高度时，它也会很有帮助，但如果你确实有一个具有已知大小的父容器，可能希望将图片适配进其中（请参阅下面的“object-fit”） .

当你将 fill属性添加到图片时，不需要也不应该包含 width和 height，如下例所示：

<img ngSrc="cat.jpg" fill>

你可以用 object-fit 这个 CSS 属性来更改图片填充其容器的方式。如果你使用 object-fit: "contain"来设置图片的样式，则图片将保持其纵横比并被黑边化（译注：类似于电影在不同分辨率播放时加黑边）以适配此元素。如果你设置了 object-fit: "cover"，则元素将保留其长宽比，完全填充元素，并且某些内容可能会被“裁剪”。

请在 MDN object-fit 文档 中查看上述内容的可视化示例。

你还可以用 object-location 属性来设置 图片的样式，以调整其在容器元素中的位置。

重要说明：为了正确渲染“fill”图片，其父元素必须使用 position: "relative"、position: "fixed"或 position: "absolute"来设置样式。

# 调整图片样式link

# 根据图片的样式，添加 `width`和 `height`属性可能会导致图片的渲染方式不同。如果你的图片样式正在以扭曲的纵横比渲染图片， `NgOptimizedImage`会发出警告。

你通常可以通过将 height: auto或 width: auto添加到图片的样式中来解决此问题。有关更多信息，请参阅关于标签的 web.dev 文章 (opens new window) 。

如果图片上的 height和 width属性让你无法用 CSS 以你想要的方式调整图片大小，请考虑改用“填充”模式，并为图片的父元素设置样式。

# 性能优化特性link

# NgOptimizedImage 包含许多旨在提高应用程序加载性能的特性。本节会介绍这些特性。

# 添加资源提示link

# 你可以为图片源添加 `preconnect资源提示` ，以确保 LCP 图片尽快加载。始终将资源提示放在文档的 `<head>`中。

<link rel="preconnect" href="https://my.cdn.origin" />

默认情况下，如果你使用第三方图片服务的加载器，当 NgOptimizedImage指令检测到提供 LCP 图片的源缺少 preconnect资源提示时，它将在开发期间发出警告。

要禁用这些警告，请注入 PRECONNECT_CHECK_BLOCKLIST标记：

providers: [
  {provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

# 使用自动 `srcset`请求正确大小的图片link

# 定义 `srcset属性` 可确保浏览器为用户的视口请求正确大小的图片，因此不会浪费时间下载太大的图片。 `NgOptimizedImage`会根据 img 标签上 `sizes` 属性的存在与否和值来为图片生成适当的 `srcset`。

# 固定大小的图片link

# 如果你的图片的大小应该是“固定的”（即跨设备的大小相同，除了像素密度不同），则无需设置 `sizes`属性。可以从图片的 `width`和 `height`属性自动生成 `srcset`，无需更多的输入属性。

生成的示例 srcset： <img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x">

# 响应式图片link

# 如果你的图片应该是响应式的（即会根据视口大小放大和缩小），那么你需要定义一个 `sizes` 属性来生成 `srcset`。

如果你以前没有使用过 sizes，一个很好的起点是根据视口宽度来设置它。例如，如果你的 CSS 要让图片填充视口宽度的 100% ，则将 sizes设置为 100vw，浏览器将选择 srcset中最接近视口宽度的图片（在考虑像素密度之后）。如果你的图片只可能占屏幕的一半（例如：在侧边栏中），请将 sizes设置为 50vw以确保浏览器选择较小的图片。以此类推。

如果你发现上述内容无法涵盖你所需的图片行为，请参阅有关高级尺寸值的文档。

默认情况下，响应式断点是：

如果你想自定义这些断点，可以用 IMAGE_CONFIG提供者来实现：

providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],

如果你想手动定义 srcset属性，可以用 ngSrcset属性提供自己的：

<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w">

如果存在 ngSrcset属性，则 NgOptimizedImage会根据包含的大小生成并设置 srcset。不要在 ngSrcset中包含图片文件名 - 该指令会从 ngSrc推断此信息。该指令支持宽度描述符（例如 100w）和密度描述符（例如 1x）。

<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw">

# 禁用自动 srcset 生成link

# 要禁用单个图片的 srcset 生成，你可以在图片上添加 `disableOptimizedSrcset`属性：

<img ngSrc="about.jpg" disableOptimizedSrcset>

# 禁用图片惰性加载link

# 默认情况下， `NgOptimizedImage`为所有未标记 `priority`的图片设置 `loading=lazy`。你可以通过设置 `loading`属性来为非优先图片禁用此行为。此属性会接受值： `eager`、 `auto`和 `lazy`。[有关详细信息，请参阅标准图片loading

属性的文档](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading#value) 。

<img ngSrc="cat.jpg" width="400" height="200" loading="eager">

# 高级的 `sizes`值link

# 你可能希望在不同大小的屏幕上以不同的宽度显示图片。这种模式的一个常见例子是基于网格或列的布局，它在移动设备上渲染为单列，在较大的设备上渲染为两列。你可以用“媒体查询”语法在 `sizes`属性中捕获此行为，例如以下内容：

<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw">

上面的示例中的 sizes属性表示“我希望此图片在 768px 宽的设备上是屏幕宽度的 100% 。否则，我希望它是屏幕宽度的 50% 。

有关 size 属性的其它信息，请参阅 web.dev sizesmdn。

# 为 `NgOptimizedImage`配置图片加载器link

# “加载器”是一个为给定图片文件生成图片转换 URL的函数。如果合适，`NgOptimizedImage`就会设置图片的大小、格式和图片质量转换。

NgOptimizedImage提供了一个不应用转换的通用加载器和一个用于各种第三方图片服务的加载器。它还支持编写你自己的自定义加载器。

加载器类型	Loader type	行为	Behavior
通用加载器Generic loader	通用加载器返回的 URL 将始终与 src 的值匹配。换句话说，此加载器不应用任何转换。使用 Angular 来提供图片的站点是此加载器的主要预期用例。The URL returned by the generic loader will always match the value of src. In other words, this loader applies no transformations. Sites that use Angular to serve images are the primary intended use case for this loader.
第三方图片服务的加载器Loaders for third-party image services	此加载器为第三方图片服务返回的 URL 将遵循该特定图片服务使用的 API 约定。The URL returned by the loaders for third-party image services will follow API conventions used by that particular image service.
自定义加载器Custom loaders	自定义加载器的行为由其开发人员定义。如果使用 NgOptimizedImage 预配置的加载器不支持你想要的图片服务，就应该使用自定义加载器。A custom loader's behavior is defined by its developer. You should use a custom loader if your image service isn't supported by the loaders that come preconfigured with NgOptimizedImage.

基于 Angular 应用程序常用的图片服务，NgOptimizedImage提供了预配置的加载器以使用以下图片服务：

图片服务	Image Service	Angular API
Cloudflare 图片大小调整Cloudflare Image Resizing	`provideCloudflareLoader`	文档Documentation
Cloudinary	`provideCloudinaryLoader`	文档Documentation
ImageKit	`provideImageKitLoader`	文档Documentation
Imgix	`provideImgixLoader`	文档Documentation

要使用通用加载器，无需额外的代码更改。这是默认行为。

# 内置加载器link

# 要将现有的加载器用于第三方图片服务，请将你选择的服务的提供者工厂添加到 `providers`数组中。在下面的示例中，使用了 Imgix 加载器：

providers: [
  provideImgixLoader('https://my.base.url/'),
],

图片资产的基本 URL 应作为参数传递给提供者工厂。对于大多数网站，此基本 URL 应匹配以下模式之一：

你可以在相应 CDN 提供者的文档中了解有关基本 URL 结构的更多信息。

# 自定义加载器link

# 要使用自定义加载器，请提供你的加载器函数作为 `IMAGE_LOADER`DI 标记的值。在下面的示例中，自定义加载器函数会返回一个以 `https://example.com`开头的 URL，其中包含 `src`和 `width`作为 URL 参数。

providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}`;
    },
  },
],

NgOptimizedImage指令的加载器函数接受 ImageLoaderConfig类型的对象（来自 @angular/common）作为其参数，并返回图片资产的绝对 URL。 ImageLoaderConfig对象包含 src和 width属性。

注意：自定义加载器必须支持请求各种宽度的图片，以便 ngSrcset正常工作。

最后复查时间： 11/7/2022

← HTTP客户端测试介绍 →

# NgOptimizedImage 入门

# NgOptimizedImage 指令可以轻松采用关于性能的最佳实践来加载图片。

# 快速上手link

#

# 步骤 1：导入 NgOptimizedImagelink

#

# 第 2 步：（可选）设置加载器link

# 使用 NgOptimizedImage 不一定需要图片加载器，但使用带有图片 CDN 的加载器可以实现强大的性能特性，包括为图片自动设置 srcset。

# 第 3 步：启用该指令link

# 要激活 NgOptimizedImage指令，请将图片的 src属性替换为 ngSrc。

# 步骤 4：将图片标记为 prioritylink

# 始终将页面上的 LCP 图片 标记为 priority的，以优先加载它。

# 第 5 步：包括高度和宽度link

# 为了防止与图片相关的布局移位，NgOptimizedImage 要求你为图片指定高度和宽度，如下所示：

# 使用 fill模式link

# 调整图片样式link

# 根据图片的样式，添加 width和 height属性可能会导致图片的渲染方式不同。如果你的图片样式正在以扭曲的纵横比渲染图片， NgOptimizedImage会发出警告。

# 性能优化特性link

# NgOptimizedImage 包含许多旨在提高应用程序加载性能的特性。本节会介绍这些特性。

# 添加资源提示link

# 你可以为图片源添加 preconnect资源提示 ，以确保 LCP 图片尽快加载。始终将资源提示放在文档的 &lt;head&gt;中。

# 使用自动 srcset请求正确大小的图片link

# 定义 srcset属性 可确保浏览器为用户的视口请求正确大小的图片，因此不会浪费时间下载太大的图片。 NgOptimizedImage会根据 img 标签上 sizes 属性的存在与否和值来为图片生成适当的 srcset。