Ng-zorro-antd: [RFC] Enhance the function of the image component

[stygian-desolator]

What problem does this feature solve?

Summary

• Provide simpler, easier-to-use, and more feature-rich image component;
• Support configuration CDN for image loading;
• Optimize image loading under SSR;

Feature List

1. fallback. supports fallback, providing a placeholder when the image fails to load;
2. progressive loading. supports progressive loading, providing placeholders for large image loading;
3. layout. Support multiple layout styles of images, including intrinsic, responsive, fixed, fill;
4. background. supports image as background image;
5. responsive loading. automatically create srcset and sizes for images;
6. loader. supports custom loader and provides CDN configuration of pictures;
7. preload. supports preload (only under SSR);

What does the proposed API look like?

Detailed Design

1.fallback

Consistent with the existing api of ng-zorro, src is replaced with fallback after loading failure.

<img nz-image [nzSrc]="currentSrc" [nzFallback]="fallbackSrc" />

2.progressive loading

Consistent with the existing api of ng-zorro, placeholder is used as the src during loading.

<img nz-image [nzSrc]="currentSrc" [nzPlaceholder]="placeholderSrc" />

3.layout

The default is intrinsic.

intrinsic

Fixed layout. When the viewport is larger than the image size, the image keeps its original size. When the viewport is smaller than the image size, the image will be scaled down.

<img nz-image [nzSrc]="currentSrc" nzLayout="intrinsic" />

responsive

Support responsive layout, which changes with the size of the outer container;

<img nz-image [nzSrc]="currentSrc" nzLayout="responsive" />

fixed

Fixed size, does not change with the size of the outer container;

<img nz-image [nzSrc]="currentSrc" nzLayout="fixed" />

fill

Filling, according to the outer container and objectFit to determine the filling method

<img nz-image [nzSrc]="currentSrc" nzLayout="fill" />

4.background

Support the image as a background image with the same size as the outer container, which can be used in scenes such as loading a background page.

<img nz-image [nzSrc]="currentSrc" nzLayout="fill" nzObjectFit="cover"/>
<img nz-image [nzSrc]="currentSrc" nzLayout="fill" nzObjectFit="contain"/>
<img nz-image [nzSrc]="currentSrc" nzLayout="fill" nzObjectFit="none"/>

5. Automatically create srcset and sizes for images

In many cases, users will use the same pictures on screens of different resolutions, and many CDN providers provide rich parameters for image processing, which provides an optimized space for users to display images on screens of different resolutions.

<!-- Default incoming parameters -->
<img nz-image [nzSrc]="currentSrc" />

srcset is filled by default

<!-- For example, use 640, 750, 828, 1080, 1200, 1920, 2048, 3840 as the default filling parameters -->
<img ... srcset="test.jpg?w=640&q=75 640w, test.jpg?w=750&q=75 750w, test.jpg?w=828&q=75 828w, test.jpg?w=1080&q=75 1080w, test.jpg?w=1200&q=75 1200w, test.jpg?w=1920&q=75 1920w, test.jpg?w=2048&q=75 2048w, test.jpg?w=3840&q=75 3840w" sizes="100vw "/>

6. Support custom loader

Used for custom resolution image path

function customLoader({ src, width, height, quality }): string {
  return `customDomain?url=${src}&w=${width}&h=${height}&q=${quality}`;
}

<img nz-image [nzSrc]="currentSrc" [nzLoader]="customLoader" />

7. Support preload (only under SSR)

Setting priority will preload image resources;

<img nz-image nzSrc="test.jpg" nzPriority />

This will create a link tag when the page loads, pre-loading image resources, for example

<link rel="preload" as="image" href="test.jpg">

Reference

• img element - MDN
• preload responsive images web.dev
• next.js image component RFC issue
• next.js image documentation
• next.js image source code

[vthinkxie]

Thanks @stygian-desolator for drafting this RFC, good job!

1. I suggest supporting global config for [nzFallback] and [nzPlaceholder] to avoid too much boilerplate.
2. when nzLayout="fixed", I believe the image component should have height and width attributes

cc @mgechev @atcastle

[mgechev]

Ups, I wrote a comment and forgot to post it.

when nzLayout="fixed", I believe the image component should have height and width attributes

I agree that we need to have width and height. To prevent CLS we may want to always use fixed layout cc @atcastle.

[atcastle]

Yes, that jumped out at me as well--it seems like there's a lot of good features here, but not much to avoid layout shift. I think requiring width and height for fixed images is a very good idea.

[vthinkxie]

Hi
My other point of concern is to change nz-image from directive to component because some new features are conflict with original image attribute.
such as nzPriority vs importance and loader vs width and height

[mgechev]

SGTM