diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-image.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-image.md index 42fb02b76657c2cd0b5328eabd2f0f2d751586b7..25f34532c9829002669164a3adb9fb8c20cfcb1e 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-image.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-image.md @@ -1,15 +1,24 @@ # Image -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +图片组件，支持本地图片和网络图片的渲染展示。 +> **说明：** +> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -图片组件，用来渲染展示图片。 +## 权限说明 -## 权限列表 +使用网络图片时，需要在config.json（FA模型）或者module.json5（Stage模型）对应的"abilities"中添加网络使用权限ohos.permission.INTERNET。 -ohos.permission.INTERNET（使用网络图片） +```json +"abilities": [ + { + ... + "permissions": ["ohos.permission.INTERNET"], + ... + } +] +``` ## 子组件 @@ -21,61 +30,71 @@ ohos.permission.INTERNET（使用网络图片） Image(src: string | PixelMap | Resource) -- 参数 - | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | - | -------- | -------- | -------- | -------- | -------- | - | src | string\| [PixelMap](../apis/js-apis-image.md#pixelmap7)\| [Resource](../../ui/ts-types.md#resource类型)| 是 | - | 图片的数据源，支持本地图片和网络图片。
\- 支持的图片格式包括png、jpg、bmp、svg和gif。
\- 支持`Base64`字符串。格式`data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, 其中`[base64 data]`为`Base64`字符串数据。
\- 支持`dataability://`路径前缀的字符串，用于访问通过data ability提供的图片路径。 | +通过图片数据源获取图片，用于后续渲染展示。 +**参数：** + +| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | +| -------- | -------- | -------- | -------- | -------- | +| src | string\| [PixelMap](../apis/js-apis-image.md#pixelmap7)\| [Resource](../../ui/ts-types.md#resource类型)| 是 | - | 图片的数据源，支持本地图片和网络图片。
\- 支持的图片格式包括png、jpg、bmp、svg和gif。
\- 支持`Base64`字符串。格式`data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, 其中`[base64 data]`为`Base64`字符串数据。
\- 支持`dataability://`路径前缀的字符串，用于访问通过data ability提供的图片路径。 | ## 属性 +除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + | 名称 | 参数类型 | 默认值 | 描述 | | -------- | -------- | -------- | -------- | -| alt | string | - | 加载时显示的占位图。支持本地图片和网络路径。 | -| objectFit | ImageFit | Cover | 设置图片的缩放类型。 | -| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat枚举说明) | NoRepeat | 设置图片的重复样式。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> - SVG类型图源不支持该属性。 | -| interpolation | ImageInterpolation | None | 设置图片的插值效果，仅针对图片放大插值。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> - SVG类型图源不支持该属性。
> 
> - PixelMap资源不支持该属性。 | -| renderMode | ImageRenderMode | Original | 设置图片渲染的模式。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> - SVG类型图源不支持该属性。 | -| sourceSize | {
width: number,
height: number
} | - | 设置图片解码尺寸，将原始图片解码成指定尺寸的图片，number类型单位为px。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> PixelMap资源不支持该属性。 | -| syncLoad8+ | boolean | false | 设置是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。 | - -- ImageFit枚举说明 - | 名称 | 描述 | - | -------- | -------- | - | Cover | 保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界。 | - | Contain | 保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内。 | - | Fill | 不保持宽高比进行放大缩小，使得图片填充满显示边界。 | - | None | 保持原有尺寸显示。通常配合objectRepeat属性一起使用。 | - | ScaleDown | 保持宽高比显示，图片缩小或者保持不变。 | - -- ImageInterpolation枚举说明 - | 名称 | 描述 | - | -------- | -------- | - | None | 不使用插值图片数据。 | - | High | 高度使用插值图片数据，可能会影响图片渲染的速度。 | - | Medium | 中度使用插值图片数据。 | - | Low | 低度使用插值图片数据。 | - -- ImageRenderMode枚举说明 - | 名称 | 描述 | - | -------- | -------- | - | Original | 按照原图进行渲染，包括颜色。 | - | Template | 将图像渲染为模板图像，忽略图片的颜色信息。 | +| alt | string \| [Resource](../../ui/ts-types.md#resource类型) | - | 加载时显示的占位图，支持本地图片和网络图片。 | +| objectFit | [ImageFit](#imagefit枚举说明) | ImageFit.Cover | 设置图片的缩放类型。 | +| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | NoRepeat | 设置图片的重复样式。
> **说明：**
> - svg类型图源不支持该属性。 | +| interpolation（添加示例代码） | [ImageInterpolation](#imageInterpolation) | ImageInterpolation.None | 设置图片的插值效果，仅针对图片放大插值。
> **说明：**
> - svg类型图源不支持该属性。
> - PixelMap资源不支持该属性。 | +| renderMode | [ImageRenderMode](#imagerendermode) | ImageRenderMode.Original | 设置图片渲染的模式。
> **说明：**
> - svg类型图源不支持该属性。 | +| sourceSize | {
width: number,
height: number
} | - | （需要确定）设置图片裁剪尺寸，将原始图片解码成pixelMap，指定尺寸的图片，单位为px。
> **说明：**
> PixelMap资源不支持该属性。 | +| （添加示例代码）syncLoad8+ | boolean | false | 设置是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。 | +### ImageFit -## 事件 +| 名称 | 描述 | +| -------- | -------- | +| Cover | 保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界。 | +| Contain | 保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内。 | +| Fill | 不保持宽高比进行放大缩小，使得图片充满显示边界。 | +| None | 保持原有尺寸显示，通常配合objectRepeat属性一起使用。 | +| ScaleDown | 保持宽高比显示，图片缩小或者保持不变。 | + +### ImageInterpolation -| 名称 | 功能描述 | +| 名称 | 描述 | | -------- | -------- | -| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,
 componentHeight: number, loadingStatus: number }) => void) | 图片成功加载时触发该回调，返回成功加载的图源尺寸。 | -| onError(callback: (event?: { componentWidth: number, componentHeight: number }) => void) | 图片加载出现异常时触发该回调。 | -| onFinish(callback: () => void) | 当加载的源文件为带动效的svg图片时，当svg动效播放完成时会触发这个回调，如果动效为无限循环动效，则不会触发这个回调。 | +| None | 不使用插值图片数据。 | +| High（需要确认） | 插值图片数据的使用率高，可能会影响图片渲染的速度。 | +| Medium | 插值图片数据的使用率中。 | +| Low | 插值图片数据的使用率低。 | + +### ImageRenderMode + +| 名称 | 描述 | +| -------- | -------- | +| Original | 按照原图进行渲染，包括颜色。 | +| Template | 将图片渲染为模板图片，忽略图片的颜色信息。 | + +## 事件 +除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： + +| 名称 | 功能描述 | +| -------- | -------- | +| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,
 componentHeight: number, loadingStatus: number }) => void) | 图片成功加载时触发该回调，返回成功加载的图片尺寸。
- width：图片的宽，单位为像素。
- height：图片的高，单位为像素。
- componentWidth：组件的宽，单位为像素。
- componentHeight：组件的高，单位为像素。
- loadingStatus：图片加载成功的状态。（几为成功）
| +| onError(callback: (event?: { componentWidth: number, componentHeight: number }) => void) | 图片加载出现异常时触发该回调。
- componentWidth：组件的宽，单位为像素。
- componentHeight：组件的高，单位为像素。
| +| onFinish(callback: () => void) | 当加载的源文件为带动效的svg图片时，当svg动效播放完成时会触发这个回调，如果动效为无限循环动效，则不会触发这个回调。 | ## 示例 -``` -// Image1 +### 图片加载 + +加载并显示不同类型的图片，并设置图片的缩放类型。 + +```ts @Entry @Component struct ImageExample1 { @@ -141,8 +160,11 @@ struct ImageExample1 { ![zh-cn_image_0000001250492613](figures/zh-cn_image_0000001250492613.gif) -``` -// Image2 +### 设置属性 + +添加xxx属性， + +```ts @Entry @Component struct ImageExample2 { @@ -162,12 +184,12 @@ struct ImageExample2 { .border({ width: 1 }).borderStyle(BorderStyle.Dashed) .overlay('Template', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) } - + Text('alt').fontSize(12).fontColor(0xcccccc).width('96%').height(30) Image('') .alt($r('app.media.Image_none')) .width(100).height(100).border({ width: 1 }).borderStyle(BorderStyle.Dashed) - + Text('sourceSize').fontSize(12).fontColor(0xcccccc).width('96%') Row({ space: 50 }) { Image($r('app.media.img_example')) @@ -187,7 +209,7 @@ struct ImageExample2 { .border({ width: 1 }).borderStyle(BorderStyle.Dashed) .overlay('w:200 h:200', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) } - + Text('objectRepeat').fontSize(12).fontColor(0xcccccc).width('96%').height(30) Row({ space: 5 }) { Image($r('app.media.ic_health_heart')) @@ -210,17 +232,18 @@ struct ImageExample2 { ![zh-cn_image_0000001205812616](figures/zh-cn_image_0000001205812616.png) -``` -// Image3 +### 事件调用 + +```ts @Entry @Component struct ImageExample3 { @State width: number = 0 @State height: number = 0 - private on: Resource = $r('app.media.wifi_on') - private off: Resource = $r('app.media.wifi_off') - private on2off: Resource = $r('app.media.wifi_on2off') - private off2on: Resource = $r('app.media.wifi_off2on') + private on: Resource = $r('app.media.image_on') + private off: Resource = $r('app.media.image_off') + private on2off: Resource = $r('app.media.image_on2off') + private off2on: Resource = $r('app.media.image_off2on') @State src: Resource = this.on build() { @@ -235,6 +258,7 @@ struct ImageExample3 { }) .objectFit(ImageFit.Cover) .height(180).width(180) + // 图片加载完成后，获取图片尺寸。 .onComplete((msg: { width: number,height: number }) => { this.width = msg.width this.height = msg.height @@ -247,7 +271,7 @@ struct ImageExample3 { offset: { x: 0, y: 20 } }) } - + // 为图片添加点击事件，点击完成后加载特定图片。 Image(this.src) .width(120).height(120) .onClick(() => {