Skip to content

Commit c9bdf9b

Browse files
AndrewKushnirdylhunn
AndrewKushnir
authored and
dylhunn
committed
fix(common): rename rawSrc -> ngSrc in NgOptimizedImage directive (#47362) (#47396)
As an ongoing effort to stabilize the NgOptimizedImage API before existing the Developer Preview, this commit renames the `rawSrc` attribute used for the NgOptimizedImage selector matching to `ngSrc`. The `rawSrcset` is also renamed to `ngSrcset` for consistency. The motivation for this change is to align the attribute name better with other built-in directives, such as `ngFor`, `ngIf`, `ngClass`, `ngStyle`, etc. Note: this is technically a breaking change, but since the NgOptimizedImage directive is in the Developer Preview mode, we land the change in a patch branch. PR Close #47362 PR Close #47396
1 parent a61d553 commit c9bdf9b

File tree

17 files changed

+296
-256
lines changed

17 files changed

+296
-256
lines changed

‎aio/content/guide/image-directive-setup.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,4 +93,4 @@ providers: [
9393

9494
A loader function for the `NgOptimizedImage` directive takes an object with the `ImageLoaderConfig` type (from `@angular/common`) as its argument and returns the absolute URL of the image asset. The `ImageLoaderConfig` object contains the `src`and `width` properties.
9595

96-
Note: a custom loader must support requesting images at various widths in order for `rawSrcset` to work properly.
96+
Note: a custom loader must support requesting images at various widths in order for `ngSrcset` to work properly.

‎aio/content/guide/image-directive.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,11 @@ You will need to import the directive into your application. In addition, you wi
2525

2626
### Overview
2727

28-
To activate the `NgOptimizedImage` directive, replace your image's `src` attribute with `rawSrc`.
28+
To activate the `NgOptimizedImage` directive, replace your image's `src` attribute with `ngSrc`.
2929

3030
<code-example format="typescript" language="typescript">
3131

32-
&lt;img rawSrc="cat.jpg" width="400" height="200"&gt;
32+
&lt;img ngSrc="cat.jpg" width="400" height="200"&gt;
3333

3434
</code-example>
3535

@@ -43,7 +43,7 @@ Always mark the [LCP image](https://web.dev/lcp/#what-elements-are-considered) o
4343

4444
<code-example format="typescript" language="typescript">
4545

46-
&lt;img rawSrc="cat.jpg" width="400" height="200" priority&gt;
46+
&lt;img ngSrc="cat.jpg" width="400" height="200" priority&gt;
4747

4848
</code-example>
4949

@@ -84,21 +84,21 @@ You can typically fix this by adding `height: auto` or `width: auto` to your ima
8484

8585
### Handling `srcset` attributes
8686

87-
If your `<img>` tag defines a `srcset` attribute, replace it with `rawSrcset`.
87+
If your `<img>` tag defines a `srcset` attribute, replace it with `ngSrcset`.
8888

8989
<code-example format="html" language="html">
9090

91-
&lt;img rawSrc="hero.jpg" rawSrcset="100w, 200w, 300w"&gt;
91+
&lt;img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w"&gt;
9292

9393
</code-example>
9494

95-
If the `rawSrcset` attribute is present, `NgOptimizedImage` generates and sets the [`srcset` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) using the configured image loader. Do not include image file names in `rawSrcset` - the directive infers this information from `rawSrc`. The directive supports both width descriptors (e.g. `100w`) and density descriptors (e.g. `1x`) are supported.
95+
If the `ngSrcset` attribute is present, `NgOptimizedImage` generates and sets the [`srcset` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) using the configured image loader. Do not include image file names in `ngSrcset` - the directive infers this information from `ngSrc`. The directive supports both width descriptors (e.g. `100w`) and density descriptors (e.g. `1x`) are supported.
9696

97-
You can also use `rawSrcset` with the standard image [`sizes` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes).
97+
You can also use `ngSrcset` with the standard image [`sizes` attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes).
9898

9999
<code-example format="html" language="html">
100100

101-
&lt;img rawSrc="hero.jpg" rawSrcset="100w, 200w, 300w" sizes="50vw"&gt;
101+
&lt;img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw"&gt;
102102

103103
</code-example>
104104

@@ -108,7 +108,7 @@ By default, `NgOptimizedImage` sets `loading=lazy` for all images that are not m
108108

109109
<code-example format="html" language="html">
110110

111-
&lt;img rawSrc="cat.jpg" width="400" height="200" loading="eager"&gt;
111+
&lt;img ngSrc="cat.jpg" width="400" height="200" loading="eager"&gt;
112112

113113
</code-example>
114114

‎goldens/public-api/common/index.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -545,16 +545,18 @@ export class NgOptimizedImage implements OnInit, OnChanges, OnDestroy {
545545
ngOnDestroy(): void;
546546
// (undocumented)
547547
ngOnInit(): void;
548+
ngSrc: string;
549+
ngSrcset: string;
548550
set priority(value: string | boolean | undefined);
549551
// (undocumented)
550552
get priority(): boolean;
551-
rawSrc: string;
552-
rawSrcset: string;
553+
// @deprecated
554+
set rawSrc(value: string);
553555
set width(value: string | number | undefined);
554556
// (undocumented)
555557
get width(): number | undefined;
556558
// (undocumented)
557-
static ɵdir: i0.ɵɵDirectiveDeclaration<NgOptimizedImage, "img[rawSrc]", never, { "rawSrc": "rawSrc"; "rawSrcset": "rawSrcset"; "width": "width"; "height": "height"; "loading": "loading"; "priority": "priority"; "src": "src"; "srcset": "srcset"; }, {}, never, never, true>;
559+
static ɵdir: i0.ɵɵDirectiveDeclaration<NgOptimizedImage, "img[ngSrc],img[rawSrc]", never, { "rawSrc": "rawSrc"; "ngSrc": "ngSrc"; "ngSrcset": "ngSrcset"; "width": "width"; "height": "height"; "loading": "loading"; "priority": "priority"; "src": "src"; "srcset": "srcset"; }, {}, never, never, true>;
558560
// (undocumented)
559561
static ɵfac: i0.ɵɵFactoryDeclaration<NgOptimizedImage, never>;
560562
}

‎packages/common/src/directives/ng_optimized_image/error_helper.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
*/
88

99
// Assembles directive details string, useful for error messages.
10-
export function imgDirectiveDetails(rawSrc: string, includeRawSrc = true) {
11-
const rawSrcInfo =
12-
includeRawSrc ? `(activated on an <img> element with the \`rawSrc="${rawSrc}"\`) ` : '';
13-
return `The NgOptimizedImage directive ${rawSrcInfo}has detected that`;
10+
export function imgDirectiveDetails(ngSrc: string, includeNgSrc = true) {
11+
const ngSrcInfo =
12+
includeNgSrc ? `(activated on an <img> element with the \`ngSrc="${ngSrc}"\`) ` : '';
13+
return `The NgOptimizedImage directive ${ngSrcInfo}has detected that`;
1414
}

‎packages/common/src/directives/ng_optimized_image/image_loaders/image_loader.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -118,10 +118,10 @@ function throwUnexpectedAbsoluteUrlError(path: string, url: string): never {
118118
throw new RuntimeError(
119119
RuntimeErrorCode.INVALID_LOADER_ARGUMENTS,
120120
ngDevMode &&
121-
`Image loader has detected a \`<img>\` tag with an invalid \`rawSrc\` attribute: ${
121+
`Image loader has detected a \`<img>\` tag with an invalid \`ngSrc\` attribute: ${
122122
url}. ` +
123-
`This image loader expects \`rawSrc\` to be a relative URL - ` +
123+
`This image loader expects \`ngSrc\` to be a relative URL - ` +
124124
`however the provided value is an absolute URL. ` +
125-
`To fix this, provide \`rawSrc\` as a path relative to the base URL ` +
125+
`To fix this, provide \`ngSrc\` as a path relative to the base URL ` +
126126
`configured for this loader (\`${path}\`).`);
127127
}

‎packages/common/src/directives/ng_optimized_image/lcp_image_observer.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ import {getUrl} from './url';
2727
*/
2828
@Injectable({providedIn: 'root'})
2929
export class LCPImageObserver implements OnDestroy {
30-
// Map of full image URLs -> original `rawSrc` values.
30+
// Map of full image URLs -> original `ngSrc` values.
3131
private images = new Map<string, string>();
3232
// Keep track of images for which `console.warn` was produced.
3333
private alreadyWarned = new Set<string>();
@@ -65,8 +65,8 @@ export class LCPImageObserver implements OnDestroy {
6565
// Exclude `data:` and `blob:` URLs, since they are not supported by the directive.
6666
if (imgSrc.startsWith('data:') || imgSrc.startsWith('blob:')) return;
6767

68-
const imgRawSrc = this.images.get(imgSrc);
69-
if (imgRawSrc && !this.alreadyWarned.has(imgSrc)) {
68+
const imgNgSrc = this.images.get(imgSrc);
69+
if (imgNgSrc && !this.alreadyWarned.has(imgSrc)) {
7070
this.alreadyWarned.add(imgSrc);
7171
logMissingPriorityWarning(imgSrc);
7272
}
@@ -75,9 +75,9 @@ export class LCPImageObserver implements OnDestroy {
7575
return observer;
7676
}
7777

78-
registerImage(rewrittenSrc: string, rawSrc: string) {
78+
registerImage(rewrittenSrc: string, originalNgSrc: string) {
7979
if (!this.observer) return;
80-
this.images.set(getUrl(rewrittenSrc, this.window!).href, rawSrc);
80+
this.images.set(getUrl(rewrittenSrc, this.window!).href, originalNgSrc);
8181
}
8282

8383
unregisterImage(rewrittenSrc: string) {
@@ -93,8 +93,8 @@ export class LCPImageObserver implements OnDestroy {
9393
}
9494
}
9595

96-
function logMissingPriorityWarning(rawSrc: string) {
97-
const directiveDetails = imgDirectiveDetails(rawSrc);
96+
function logMissingPriorityWarning(ngSrc: string) {
97+
const directiveDetails = imgDirectiveDetails(ngSrc);
9898
console.warn(formatRuntimeError(
9999
RuntimeErrorCode.LCP_IMG_MISSING_PRIORITY,
100100
`${directiveDetails} this image is the Largest Contentful Paint (LCP) ` +

0 commit comments

Comments
 (0)