提交 435dce5a 编写于 作者: E ester.zhou

update ts-basic-components-image.md

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 034b6749
# Image # Image
The **\<Image>** component is used to render and display local and online images.
> **NOTE**<br> > **NOTE**
>
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. > This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
The **&lt;Image&gt;** component is used to render and display images.
## Required Permissions ## Required Permissions
ohos.permission.INTERNET (using Internet images) To use online images, you need to add the **ohos.permission.INTERNET** permission to the corresponding abilities in the **config.json** (for the FA model) or **module.json5** file (for the stage model).
```
"abilities": [
{
...
"permissions": ["ohos.permission.INTERNET"],
...
}
]
```
## Child Components ## Child Components
None Not supported
## APIs ## APIs
Image(value: {uri: string | PixelMap}) Image(src: string | PixelMap | Resource)
- Parameters Obtains an image from the specified source for subsequent rendering and display.
| Name | Type | Mandatory | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| uri | string | Yes | - | Image URI. Both local and Internal URIs are supported. |
**Parameters**
| Name| Type | Mandatory| Default Value| Description |
| ------ | ------------------------------------------------------------ | ---- | ------ | ------------------------------------------------------------ |
| src | string \| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](../../ui/ts-types.md) | Yes | - | Image source. Both local and online images are supported.<br>When using resources referenced using a relative path, for example, `Image("common/test.jpg")`, the **\<Image>** component cannot be called across bundles or modules. Therefore, you are advised to use `$r` to reference image resources that need to be used globally.<br>\- The following image formats are supported: PNG, JPG, BMP, SVG, GIF.<br>\- Base64 strings are supported. The value format is `data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, where `[base64 data]` is a Base64 string.<br/>\- The value can also be a path starting with `dataability://`, which is used to access the image path provided by a Data ability. |
## Attributes ## Attributes
| Name | Type | Default Value | Description | In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| -------- | -------- | -------- | -------- |
| alt | string | - | Placeholder image displayed during loading. Both local and Internal URIs are supported. | | Name | Type | Default Value | Description |
| objectFit | ImageFit | ImageFit.Cover | Image scale type. | | --------------------- | ---------------------------------------- | ------------------------ | ---------------------------------------- |
| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat enums) | ImageRepeat.NoRepeat | Whether the image is repeated.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images. | | alt | string \| [Resource](../../ui/ts-types.md) | - | Placeholder image displayed during loading. Both local and Internet URIs are supported. |
| interpolation | ImageInterpolation | ImageInterpolation.None | Interpolation effect of the image. This attribute is valid only when the image is zoomed in.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images.<br/>> <br/>> - This attribute is not applicable to a **PixelMap** object. | | objectFit | [ImageFit](#imagefit-enums) | ImageFit.Cover | Image scale type. |
| renderMode | ImageRenderMode | ImageRenderMode.Original | Rendering mode of the image.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> - This attribute is not applicable to SVG images. | | objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | NoRepeat | Whether the image is repeated.<br>**NOTE**<br>This attribute is not applicable to SVG images. |
| sourceSize | {<br/>width: number,<br/>height: number<br/>} | - | Decoding size of the image. The original image is decoded into an image of the specified size. If the value is of the number type, the unit px is used.<br/>> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br/>> This attribute is not applicable to a **PixelMap** object. | | interpolation | [ImageInterpolation](#imageinterpolation) | ImageInterpolation.None | Interpolation effect of the image. This attribute is valid only when the image is zoomed in.<br>**NOTE**<br>This attribute is not applicable to SVG images or **PixelMap** objects. |
| syncLoad<sup>8+</sup> | boolean | false | Whether to load images synchronously. By default, images are loaded asynchronously. During synchronous loading, the UI thread is blocked and the placeholder diagram is not displayed. | | renderMode | [ImageRenderMode](#imagerendermode) | ImageRenderMode.Original | Rendering mode of the image.<br>**NOTE**<br>This attribute is not applicable to SVG images. |
| sourceSize | {<br>width: number,<br>height: number<br>} | - | Decoding size of the image. The original image is decoded into an image of the specified size, in px.<br>**NOTE**<br>This attribute is not applicable to **PixelMap** objects. |
- ImageFit enums | syncLoad<sup>8+</sup> | boolean | false | Whether to load images synchronously. By default, images are loaded asynchronously. During synchronous loading, the UI thread is blocked and the placeholder diagram is not displayed. |
| Name | Description |
| -------- | -------- | ### ImageFit
| Cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries. |
| Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. | | Name | Description |
| Fill | The video content is resized to fill the display area while retaining its aspect ratio. | | --------- | -------------------------------- |
| None | The original size is retained. Generally, this enum is used together with the **objectRepeat** attribute. | | Cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries. |
| ScaleDown | The image content is displayed with its aspect ratio retained. The size is smaller than or equal to the original size. | | Contain | The image is scaled with its aspect ratio retained for the content to be completely displayed within the display boundaries. |
| Fill | The image is scaled to fill the display area, and its aspect ratio is not retained. |
- ImageInterpolation enums | None | The image is displayed in its original size. Generally, this enum is used together with the **objectRepeat** attribute.|
| Name | Description | | ScaleDown | The image is displayed with its aspect ratio retained, in a size smaller than or equal to the original size. |
| -------- | -------- |
| None | Interpolation image data is not used. | ### ImageInterpolation
| High | The interpolation image data is used at the high level. The use of the interpolation image data may affect the image rendering speed. |
| Medium | The interpolation image data is used at the medium level. |
| Low | The interpolation image data is used at the low level. |
- ImageRenderMode enums
| Name | Description |
| -------- | -------- |
| Original | The image is rendered based on the original image, including the color. |
| Template | The image is rendered as a template image, and its color is ignored. |
| Name | Description |
| ------ | ------------------------- |
| None | Interpolation image data is not used. |
| High | The interpolation image data is used at the high level, which may affect the image rendering speed.|
| Medium | The interpolation image data is used at the medium level. |
| Low | The interpolation image data is used at the low level. |
### ImageRenderMode
| Name | Description |
| -------- | --------------------- |
| Original | The image is rendered based on the original image, including the color. |
| Template | The image is rendered as a template image, and its color is ignored.|
## Events ## Events
| Name | Description | In addition to the universal events (ts-universal-events-click.md), the following events are supported.
| -------- | -------- |
| onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number }) =&gt; void) | Triggered when an image is successfully loaded. The loaded image is returned. |
| onError(callback: (event?: { componentWidth: number, componentHeight: number }) =&gt; void) | An exception occurs during image loading. |
| onFinish(callback: () =&gt; void) | If the source file to be loaded is an SVG image, this callback is invoked when the SVG animation playback is complete. If the animation is an infinite loop, this callback is not triggered. |
| Name | Description |
| ---------------------------------------- | ---------------------------------------- |
| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,<br> componentHeight: number, loadingStatus: number }) =&gt; void) | Triggered when an image is successfully loaded. The size of the loaded image is returned.<br>- **width**: width of the image, in pixels.<br>- **height**: height of the image, in pixels.<br>- **componentWidth**: width of the container component, in pixels.<br>- **componentHeight**: height of the container component, in pixels.<br>- **loadingStatus**: image loading status.<br>|
| onError(callback: (event?: { componentWidth: number, componentHeight: number }) =&gt; void) | Triggered when an exception occurs during image loading.<br>- **componentWidth**: width of the container component, in pixels.<br>- **componentHeight**: height of the container component, in pixels.<br>|
| onFinish(callback: () =&gt; void) | Triggered when the animation playback in the loaded SVG image is complete. If the animation is an infinite loop, this callback is not triggered.|
## Example ## Example
### Loading Images
``` Load and display different types of images and set the scale type of the images.
// Image1
```ts
@Entry @Entry
@Component @Component
struct ImageExample1 { struct ImageExample1 {
...@@ -143,9 +161,9 @@ struct ImageExample1 { ...@@ -143,9 +161,9 @@ struct ImageExample1 {
![en-us_image_0000001211898484](figures/en-us_image_0000001211898484.gif) ![en-us_image_0000001211898484](figures/en-us_image_0000001211898484.gif)
### Setting Attributes
``` ```ts
// Image2
@Entry @Entry
@Component @Component
struct ImageExample2 { struct ImageExample2 {
...@@ -163,12 +181,12 @@ struct ImageExample2 { ...@@ -163,12 +181,12 @@ struct ImageExample2 {
.border({ width: 1 }).borderStyle(BorderStyle.Dashed) .border({ width: 1 }).borderStyle(BorderStyle.Dashed)
.overlay('Template', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) .overlay('Template', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
} }
Text('alt').fontSize(12).fontColor(0xcccccc).width('96%').height(30) Text('alt').fontSize(12).fontColor(0xcccccc).width('96%').height(30)
Image('') Image('')
.alt($r('app.media.Image_none')) .alt($r('app.media.Image_none'))
.width(100).height(100).border({ width: 1 }).borderStyle(BorderStyle.Dashed) .width(100).height(100).border({ width: 1 }).borderStyle(BorderStyle.Dashed)
Text('sourceSize').fontSize(12).fontColor(0xcccccc).width('96%') Text('sourceSize').fontSize(12).fontColor(0xcccccc).width('96%')
Row({ space: 50 }) { Row({ space: 50 }) {
Image($r('app.media.img_example')) Image($r('app.media.img_example'))
...@@ -188,7 +206,7 @@ struct ImageExample2 { ...@@ -188,7 +206,7 @@ struct ImageExample2 {
.border({ width: 1 }).borderStyle(BorderStyle.Dashed) .border({ width: 1 }).borderStyle(BorderStyle.Dashed)
.overlay('w:200 h:200', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) .overlay('w:200 h:200', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
} }
Text('objectRepeat').fontSize(12).fontColor(0xcccccc).width('96%').height(30) Text('objectRepeat').fontSize(12).fontColor(0xcccccc).width('96%').height(30)
Row({ space: 5 }) { Row({ space: 5 }) {
Image($r('app.media.ic_health_heart')) Image($r('app.media.ic_health_heart'))
...@@ -211,18 +229,18 @@ struct ImageExample2 { ...@@ -211,18 +229,18 @@ struct ImageExample2 {
![en-us_image_0000001212058474](figures/en-us_image_0000001212058474.png) ![en-us_image_0000001212058474](figures/en-us_image_0000001212058474.png)
### Invoking Events
``` ```ts
// Image3
@Entry @Entry
@Component @Component
struct ImageExample3 { struct ImageExample3 {
@State width: number = 0 @State width: number = 0
@State height: number = 0 @State height: number = 0
private on: Resource = $r('app.media.wifi_on') private on: Resource = $r('app.media.image_on')
private off: Resource = $r('app.media.wifi_off') private off: Resource = $r('app.media.image_off')
private on2off: Resource = $r('app.media.wifi_on2off') private on2off: Resource = $r('app.media.image_on2off')
private off2on: Resource = $r('app.media.wifi_off2on') private off2on: Resource = $r('app.media.image_off2on')
@State src: Resource = this.on @State src: Resource = this.on
build() { build() {
...@@ -237,6 +255,7 @@ struct ImageExample3 { ...@@ -237,6 +255,7 @@ struct ImageExample3 {
}) })
.objectFit(ImageFit.Cover) .objectFit(ImageFit.Cover)
.height(180).width(180) .height(180).width(180)
// Obtain the size of an image after the image loading is complete.
.onComplete((msg: { width: number,height: number }) => { .onComplete((msg: { width: number,height: number }) => {
this.width = msg.width this.width = msg.width
this.height = msg.height this.height = msg.height
...@@ -249,7 +268,7 @@ struct ImageExample3 { ...@@ -249,7 +268,7 @@ struct ImageExample3 {
offset: { x: 0, y: 20 } offset: { x: 0, y: 20 }
}) })
} }
// Add a click event so that a specific image is loaded upon clicking.
Image(this.src) Image(this.src)
.width(120).height(120) .width(120).height(120)
.onClick(() => { .onClick(() => {
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册