1# image
2
3
4The **\<image>** component is used to render and display images.
5
6> **NOTE**
7>
8> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
9
10## Child Components
11
12Not supported
13
14
15## Attributes
16
17In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
18
19| Name| Type| Default Value| Mandatory| Description|
20| -------- | -------- | -------- | -------- | -------- |
21| src | string | - | No| Image path.<br>- The local path is supported. Supported formats are as follows: PNG, JPG, BMP, SVG, and GIF.<br>- The path to the in-memory image is also supported in the scheme format of **memory://**.<br>**NOTE**<br>To display an online image, download it and then access it with its in-memory path. Do not use URLs.|
22| alt | string | - | No| Placeholder image displayed during image loading.|
23
24
25## Styles
26
27In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
28
29| Name| Type| Default Value| Mandatory| Description|
30| -------- | -------- | -------- | -------- | -------- |
31| object-fit | string | cover | No| Image scale type. For details about available values, see **object-fit**. This style is not supported for SVG images.|
32| match-text-direction | boolean | false | No| Whether image orientation changes with the text direction. This style is not supported for SVG images.|
33| fit-original-size | boolean | false | No| Whether the **\<image>** component adapts to the image source size when its width and height are not set. If this style is set to **true**, **object-fit** will not take effect. This style is not supported for SVG images.|
34
35**Table 1** object-fit
36
37| Type| Description|
38| -------- | -------- |
39| cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries and displayed in the middle.|
40| contain | The image is scaled with the aspect ratio retained for the image to be completely displayed within the display boundaries and displayed in the middle.|
41| fill | The image is scaled to fill the display area, and its aspect ratio is not retained.|
42| none | The image is displayed in the middle with its aspect ratio and size retained.|
43| scale-down | The image is displayed in the middle with its aspect ratio retained, in the size equal to or smaller than the original size.|
44
45>  **NOTE**
46>
47>  When using an SVG image, note that:
48>
49>  - The SVG image will not be drawn if the length or width of the parent component is infinity. Therefore, you are advised to set the length and width for the **\<image>** component.
50>
51>  - If the image length and width are not specified in the SVG description, the SVG image fills the **\<image>** component area.
52>
53>  - If the image length and width are specified in the SVG description, the following rules are adopted to decide the final display effect:
54>
55>    - If the **\<image>** component is too small to afford the SVG image, the SVG image is cropped and only its upper left part is displayed in the component.
56>
57>    - If the **\<image>** component is big enough to afford the SVG image, the SVG image is displayed in the upper left corner of the component.
58
59
60## Events
61
62| Name| Parameter| Description|
63| -------- | -------- | -------- |
64| click | - | Triggered when the component is clicked.|
65| complete | - | Triggered when the image is successfully loaded.|
66| error | - | Triggered when an exception occurs during image loading.|
67
68
69## Example
70
71
72```html
73<!-- xxx.hml -->
74<stack class="content">
75    <image src="/common/bg3.jpg" class="img"></image>
76</stack>
77```
78
79
80```css
81/* xxx.css */
82.img{
83  object-fit: contain
84}
85```
86**4 x 4 widget**
87
88![image.jpg](figures/image.jpg)
89