diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/image-matrix-1.jpg b/zh-cn/application-dev/reference/arkui-ts/figures/image-matrix-1.jpg new file mode 100644 index 0000000000000000000000000000000000000000..9a2140166f2056e424976046655e5480903f2c0f Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/image-matrix-1.jpg differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/image-matrix-2.jpg b/zh-cn/application-dev/reference/arkui-ts/figures/image-matrix-2.jpg new file mode 100644 index 0000000000000000000000000000000000000000..01285cbbaff67c9b1e99c8eb7ae384889ad99bb1 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/image-matrix-2.jpg differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001592882500.gif b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001592882500.gif new file mode 100644 index 0000000000000000000000000000000000000000..ccdd2b1aa8255ce173bc923f6686bdfb99e61ce3 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001592882500.gif differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001607845173.gif b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001607845173.gif new file mode 100644 index 0000000000000000000000000000000000000000..f312df91ae0f7fd8cd8520904a11ddaccd7c58e4 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_image_0000001607845173.gif differ 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 6163a9cc3a097bc2b1e30a10f5a139301d7a7af5..4e4158658ff7940b443f618a3bb944c8f048a791 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,6 +1,6 @@ # Image -图片组件，支持本地图片和网络图片的渲染展示。 +Image为图片组件，常用于在应用中显示图片。Image支持加载[PixelMap](../apis/js-apis-image.md#pixelmap7)、[ResourceStr](ts-types.md#resourcestr)和[DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor)类型的数据源，支持png、jpg、bmp、svg和gif类型的图片格式。 > **说明：** > @@ -21,77 +21,122 @@ Image(src: PixelMap | ResourceStr | DrawableDescriptor) -通过图片数据源获取图片，用于后续渲染展示。Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。 +通过图片数据源获取图片，用于后续渲染展示。 + +Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。 从API version 9开始，该接口支持在ArkTS卡片中使用。 **参数：** -| 参数名 | 参数类型 | 必填 | 参数描述 | -| ---- | ---------------------------------------- | ---- | ---------------------------------------- | -| src |  [PixelMap](../apis/js-apis-image.md#pixelmap7) \|ResourceStr\| [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | 是 | 图片的数据源，支持本地图片和网络图片。
当使用相对路径引用图片资源时，例如`Image("common/test.jpg")`，不支持跨包/跨模块调用该Image组件，建议使用`$r`方式来管理需全局使用的图片资源。
\- 支持的图片格式包括png、jpg、bmp、svg和gif。
\- 支持`Base64`字符串。格式`data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, 其中`[base64 data]`为`Base64`字符串数据。
\- 支持`datashare://`路径前缀的字符串，用于访问通过data ability提供的图片路径。
\- 支持file:///data/storage路径前缀的字符串，用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。
\- 支持[DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor)对象
- 详细使用方法可参考[显示图片](../../ui/arkts-graphics-display.md)
**说明：**
- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。
- ArkTS卡片上不支持`http://`等网络相关路径前缀、`datashare://`路径前缀以及`file://data/storage`路径前缀的字符串
- ArkTS卡片上不支持 [PixelMap](../apis/js-apis-image.md#pixelmap7)类型 | +| 参数名 | 参数类型 | 必填 | 参数描述 | +| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| src | [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [ResourceStr](ts-types.md#resourcestr)\| [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](../../ui/arkts-graphics-display.md#加载图片资源)。
1. PixelMap格式为像素图，常用于图片编辑的场景。
2. ResourceStr包含Resource和string格式。
string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。
- 支持`Base64`字符串。格式`data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data]`, 其中`[base64 data]`为`Base64`字符串数据。
- 支持file://路径前缀的字符串。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。
Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。
3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。
**说明：**
- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。
- ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。
- ArkTS卡片上不支持 [PixelMap](../apis/js-apis-image.md#pixelmap7)类型。 | ## 属性 -除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： - -| 名称 | 参数类型 | 描述 | -| ------------------------ | ---------------------------------------- | ---------------------------------------- | -| alt | string \| [Resource](ts-types.md#resource类型) | 加载时显示的占位图，支持本地图片。
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| objectFit | [ImageFit](ts-appendix-enums.md#imagefit) | 设置图片的缩放类型。
默认值：ImageFit.Cover
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 设置图片的重复样式。
默认值：ImageRepeat.NoRepeat
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
svg类型图源不支持该属性。 | -| interpolation | [ImageInterpolation](#imageinterpolation) | 设置图片的插值效果，即减轻低清晰度图片在放大显示的时候出现的锯齿问题，仅针对图片放大插值。
默认值：ImageInterpolation.None
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
svg类型图源不支持该属性。
PixelMap资源不支持该属性。 | -| renderMode | [ImageRenderMode](#imagerendermode) | 设置图片渲染的模式。
默认值：ImageRenderMode.Original
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
svg类型图源不支持该属性。 | -| sourceSize | {
width: number,
height: number
} | 设置图片裁剪尺寸，将原始图片解码成pixelMap，指定尺寸的图片，单位为px。
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
PixelMap资源和SVG图片不支持该属性。 | -| matchTextDirection | boolean | 设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。
默认值：false
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| fitOriginalSize | boolean | 图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。
默认值：false
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| fillColor | [ResourceColor](ts-types.md#resourcecolor) | 填充颜色。设置的填充颜色会覆盖在图片上。仅对svg图源生效，设置后会替换svg图片的fill颜色。
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| autoResize | boolean | 是否需要在图片解码过程中对图源做resize操作，该操作会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。
默认值：true
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| syncLoad8+ | boolean | 设置是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。
默认值：false
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| copyOption9+ | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 设置图片是否可复制（SVG图片不支持复制）。
当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。
默认值：CopyOptions.None
该接口支持在ArkTS卡片中使用。 | -| colorFilter9+ | [ColorFilter](ts-types.md#colorfilter9) | 给图像设置颜色滤镜效果。
该接口支持在ArkTS卡片中使用。 | -| draggable(deprecated) | boolean | 设置默认拖拽效果。（不能和[onDragStart](ts-universal-events-drag-drop.md)事件同时使用。）
默认值：false
该接口支持在ArkTS卡片中使用。
**说明：**
从 API version 9 开始支持，从 API version 10 开始废弃，建议使用通用属性[draggable](ts-universal-events-drag-drop.md)替代。 | +属性的详细使用指导请参考[添加属性](../../ui/arkts-graphics-display.md#添加属性)。除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： + +| 名称 | 参数类型 | 描述 | +| -------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| alt | string \| [Resource](ts-types.md#resource类型) | 加载时显示的占位图，支持本地图片（png、jpg、bmp、svg和gif类型），不支持网络图片。
默认值：null
从API version 9开始，该接口支持在ArkTS卡片中使用。 | +| objectFit | [ImageFit](ts-appendix-enums.md#imagefit) | 设置图片的缩放类型。
默认值：ImageFit.Cover
从API version 9开始，该接口支持在ArkTS卡片中使用。 | +| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 设置图片的重复样式。从中心点向两边重复，剩余空间不足放下一张图片时会截断。
默认值：ImageRepeat.NoRepeat
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
svg类型图源不支持该属性。 | +| interpolation | [ImageInterpolation](#imageinterpolation) | 设置图片的插值效果，即减轻低清晰度图片在放大显示的时候出现的锯齿问题，仅针对图片放大插值。
默认值：ImageInterpolation.None
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
svg类型图源不支持该属性。
PixelMap资源不支持该属性。 | +| renderMode | [ImageRenderMode](#imagerendermode) | 设置图片的渲染模式为原色或黑白。
默认值：ImageRenderMode.Original
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
svg类型图源不支持该属性。 | +| sourceSize | {
width: number,
height: number
} | 设置图片解码尺寸，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。
单位：px
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
仅在目标尺寸小于图源尺寸时生效。
svg类型图源不支持该属性。
PixelMap资源不支持该属性。 | +| matchTextDirection | boolean | 设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。
默认值：false
从API version 9开始，该接口支持在ArkTS卡片中使用。 | +| fitOriginalSize | boolean | 图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。
默认值：false
从API version 9开始，该接口支持在ArkTS卡片中使用。 | +| fillColor | [ResourceColor](ts-types.md#resourcecolor) | 设置填充颜色，设置后填充颜色会覆盖在图片上。
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
仅对svg图源生效，设置后会替换svg图片的填充颜色。 | +| autoResize | boolean | 设置图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为1920x1080，而显示区域大小为200x200，则图片会自动解码到200x200的尺寸，大幅度节省图片占用的内存。
默认值：true
从API version 9开始，该接口支持在ArkTS卡片中使用。 | +| syncLoad8+ | boolean | 设置是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。
默认值：false
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
建议加载尺寸较小的本地图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。 | +| copyOption9+ | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 设置图片是否可复制。
当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。
默认值：CopyOptions.None
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
svg图片不支持复制。 | +| colorFilter9+ | [ColorFilter](ts-types.md#colorfilter9) | 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。
矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。
RGBA值分别是0和1之间的浮点数字，当矩阵对角线值为1时，保持图片原有色彩。
**计算规则：**
如果输入的滤镜矩阵为：
![image-matrix-1](figures/image-matrix-1.jpg)
像素点为[R, G, B, A]
则过滤后的颜色为 [R’, G’, B’, A’]
![image-matrix-2](figures/image-matrix-2.jpg)
从API version 9开始，该接口支持在ArkTS卡片中使用。 | +| draggable(deprecated) | boolean | 设置组件默认拖拽效果，设置为true时，组件可拖拽。
不能和[onDragStart](ts-universal-events-drag-drop.md)事件同时使用。
默认值：false
**说明：**
从 API version 9 开始支持，从 API version 10 开始废弃，建议使用通用属性[draggable](ts-universal-events-drag-drop.md)替代。 | > **说明：** > -> 使用快捷组合键对Image组件复制的前提是，该组件必须处于获焦状态。将Image组件的属性focusable设置为true，即可使用TAB键将焦点切换到Image组件上，再将Image组件的focusOnTouch属性设置为true，即可实现点击获焦。 -> 图片设置svg图源时，支持的标签范围有限，目前支持的svg标签包括svg、rect、circle、ellipse、path、line、polyline、polygon。 +> - 使用快捷组合键对Image组件复制时，Image组件必须处于[获焦状态](../../ui/arkts-common-events-focus-event.md#设置组件是否获焦)。Image组件默认不获焦，需将[focusable](ts-universal-attributes-focus.md)属性设置为true，即可使用TAB键将焦点切换到组件上，再将[focusOnTouch](ts-universal-attributes-focus.md)属性设置为true，即可实现点击获焦。 +> - 图片设置为svg图源时，当前支持的标签是svg、rect、circle、ellipse、path、line、polyline和polygon。 -### ImageInterpolation +## ImageInterpolation 从API version 9开始，该接口支持在ArkTS卡片中使用。 -| 名称 | 描述 | -| ------ | ------------------------- | -| None | 不使用插值图片数据。 | -| High | 插值图片数据的使用率高，可能会影响图片渲染的速度。 | -| Medium | 插值图片数据的使用率中。 | -| Low | 插值图片数据的使用率低。 | +| 名称 | 描述 | +| ------ | ---------------------------------------------------- | +| None | 不使用图片插值。 | +| High | 高图片插值，插值质量最高，可能会影响图片渲染的速度。 | +| Medium | 中图片插值。 | +| Low | 低图片插值。 | -### ImageRenderMode +## ImageRenderMode 从API version 9开始，该接口支持在ArkTS卡片中使用。 -| 名称 | 描述 | -| -------- | --------------------- | -| Original | 按照原图进行渲染，包括颜色。 | -| Template | 将图片渲染为模板图片，忽略图片的颜色信息。 | +| 名称 | 描述 | +| -------- | -------------- | +| Original | 原色渲染模式。 | +| Template | 黑白渲染模式。 | ## 事件 除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： -| 名称 | 功能描述 | -| ---------------------------------------- | ---------------------------------------- | -| onComplete(callback: (event?: { width: number, height: number, 
componentWidth: number, componentHeight: number, 
loadingStatus: number ,contentWidth10+: number, 
contentHeight10+: number, contentOffsetX10+: number, 
contentOffsetY10+: number}) => void) | 图片成功加载时触发该回调，返回成功加载的图片尺寸。
- width：图片的宽，单位为像素。
- height：图片的高，单位为像素。
- componentWidth：组件的宽，单位为像素。
- componentHeight：组件的高，单位为像素。
- loadingStatus：图片加载成功的状态。
- contentWidth：图片实际绘制的宽度，单位为像素。
- contentHeight：图片实际绘制的高度，单位为像素。
- contentOffsetX：实际绘制内容相对于组件自身的x轴偏移，单位为像素。
- contentOffsetY：实际绘制内容相对于组件自身的y轴偏移，单位为像素。
从API version 9开始，该接口支持在ArkTS卡片中使用。
**说明：**
loadingStatus返回的状态值为0时，代表图片加载失败；返回的状态值为1时，代表图片加载成功, API version 10新增属性仅在loadingStatus返回1时有效。 | -| onError(callback: (event?: { componentWidth: number, componentHeight: number , message9+: string }) => void) | 图片加载出现异常时触发该回调。
- componentWidth：组件的宽，单位为像素。
- componentHeight：组件的高，单位为像素。
从API version 9开始，该接口支持在ArkTS卡片中使用。 | -| onFinish(event: () => void) | 当加载的源文件为带动效的svg图片时，当svg动效播放完成时会触发这个回调，如果动效为无限循环动效，则不会触发这个回调。
从API version 9开始，该接口支持在ArkTS卡片中使用。 | +### onComplete + +onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number}) => void) }) => void) + +图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。 + +从API version 9开始，该接口支持在ArkTS卡片中使用。 + +**参数：** + +| 参数名 | 类型 | 说明 | +| ---------------------------- | ------ | ------------------------------------------------------------ | +| width | number | 图片的宽。
单位：像素 | +| height | number | 图片的高。
单位：像素 | +| componentWidth | number | 组件的宽。
单位：像素 | +| componentHeight | number | 组件的高。
单位：像素 | +| loadingStatus | number | 图片加载成功的状态值。
**说明：**
返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 | +| contentWidth10+ | number | 图片实际绘制的宽度。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | +| contentHeight10+ | number | 图片实际绘制的高度。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | +| contentOffsetX10+ | number | 实际绘制内容相对于组件自身的x轴偏移。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | +| contentOffsetY10+ | number | 实际绘制内容相对于组件自身的y轴偏移。
单位：像素
**说明：**
仅在loadingStatus返回1时有效。 | + + +### onError + +onError(callback: (event?: { componentWidth: number, componentHeight: number , message: string }) => void) + +图片加载异常时触发该回调。 + +从API version 9开始，该接口支持在ArkTS卡片中使用。 + +**参数：** + +| 参数名 | 类型 | 说明 | +| -------------------- | ------ | ------------------------- | +| componentWidth | number | 组件的宽。
单位：像素 | +| componentHeight | number | 组件的高。
单位：像素 | +| message9+ | string | 报错信息。 | + + +### onFinish + +onFinish(event: () => void) + +当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。 + +仅支持svg格式的图片。 + +从API version 9开始，该接口支持在ArkTS卡片中使用。 ## 示例 -### 图片加载 +### 加载基本类型图片 -加载显示不同类型的图片，并设置图片的缩放类型。
overlay属性用于设置图片的遮罩文本，具体使用可参考[浮层](ts-universal-attributes-overlay.md)。 ```ts @Entry @@ -100,178 +145,70 @@ struct ImageExample1 { build() { Column() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { - Row({ space: 5 }) { - Image($r('app.media.example_png')) - .width(110).height(110).border({ width: 1 }) + Row() { + // 加载png格式图片 + Image($r('app.media.ic_camera_master_ai_leaf')) + .width(110).height(110).margin(15) .overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - Image($r('app.media.example_gif')) - .width(110).height(110).border({ width: 1 }) + // 加载gif格式图片 + Image($r('app.media.loading')) + .width(110).height(110).margin(15) .overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) } - - Row({ space: 5 }) { - Image($r('app.media.example_svg')) - .width(110).height(110).border({ width: 1 }) + Row() { + // 加载svg格式图片 + Image($r('app.media.ic_camera_master_ai_clouded')) + .width(110).height(110).margin(15) .overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - Image($r('app.media.example_jpg')) - .width(110).height(110).border({ width: 1 }) + // 加载jpg格式图片 + Image($r('app.media.ic_public_favor_filled')) + .width(110).height(110).margin(15) .overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - }.margin({ top: 25, bottom: 10 }) + } } }.height(320).width(360).padding({ right: 10, top: 10 }) } } ``` -![zh-cn_image_0000001250492613](figures/zh-cn_image_0000001250492613.gif) +![zh-cn_image_0000001592882500](figures/zh-cn_image_0000001592882500.gif) +### 加载网络图片 +加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。如果需要更灵活的网络配置，可以使用[HTTP](../../connectivity/http-request.md)工具包发送网络请求，接着将返回的数据解码为Image组件中的`PixelMap`，图片开发可参考[图片处理](../../media/image-overview.md)。 -### 网络图片 - -加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。如果需要更灵活的网络配置，可以使用SDK中提供的[HTTP](../../connectivity/http-request.md)工具包发送网络请求，接着将返回的数据解码为Image组件中的`PixelMap`，图片开发可参考[图片处理](../../media/image-overview.md)。代码如下。 - -```tsx -// @ts-nocheck -import http from '@ohos.net.http'; -import ResponseCode from '@ohos.net.http' -import image from '@ohos.multimedia.image' - - -@Entry -@Component -struct Index { - - // 先创建一个PixelMap状态变量用于接收网络图片 - @State image: PixelMap = undefined - - build() { - Column({space: 10}) { - Button("获取网络图片") - .onClick(() => { - this.httpRequest() - }) - Image(this.image).height(100).width(100) - } - .width('100%') - .height('100%') - .padding(10) - } - - // 网络图片请求方法 - private httpRequest() { - let httpRequest = http.createHttp() - - httpRequest.request( - "https://www.example.com/xxx.png", // 请填写一个具体的网络图片地址 - (error, data) => { - if(error) { - console.log("error code: " + error.code + ", msg: " + error.message) - } else { - let code = data.responseCode - if(ResponseCode.ResponseCode.OK == code) { - let imageSource = image.createImageSource(data.result) - let options = {alphaType: 0, // 透明度 - editable: false, // 是否可编辑 - pixelFormat: 3, // 像素格式 - scaleMode: 1, // 缩略值 - size: {height: 100, width: 100}} // 创建图片大小 - imageSource.createPixelMap(options).then((pixelMap) => { - this.image = pixelMap - }) - } else { - console.log("response code: " + code) - } - } - } - ) - } -} -``` - -**说明**：网络图片加载的请求方式、超时、额外请求参数等配置可以参考HTTP工具包中关于[`request()`](../../reference/apis/js-apis-http.md)请求方法的细节。 - -### 设置属性 +使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[权限申请声明](../../security/accesstoken-guidelines.md)。 ```ts @Entry @Component struct ImageExample2 { - build() { Column({ space: 10 }) { - Text('renderMode').fontSize(12).fontColor(0xcccccc).width('96%').height(30) - Row({ space: 50 }) { - Image($r('app.media.img_example')) - .renderMode(ImageRenderMode.Original).width(100).height(100) - .border({ width: 1 }) - .overlay('Original', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - Image($r('app.media.img_example')) - .renderMode(ImageRenderMode.Template).width(100).height(100) - .border({ width: 1 }) - .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 }) - - Text('sourceSize').fontSize(12).fontColor(0xcccccc).width('96%') - Row({ space: 50 }) { - Image($r('app.media.img_example')) - .sourceSize({ - width: 150, - height: 150 - }) - .objectFit(ImageFit.ScaleDown).width('25%').aspectRatio(1) - .border({ width: 1 }) - .overlay('w:150 h:150', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - Image($r('app.media.img_example')) - .sourceSize({ - width: 200, - height: 200 - }) - .objectFit(ImageFit.ScaleDown).width('25%').aspectRatio(1) - .border({ width: 1 }) - .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')) - .width(120).height(125).border({ width: 1 }) - .objectRepeat(ImageRepeat.XY).objectFit(ImageFit.ScaleDown) - .overlay('ImageRepeat.XY', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - Image($r('app.media.ic_health_heart')) - .width(110).height(125).border({ width: 1 }) - .objectRepeat(ImageRepeat.Y).objectFit(ImageFit.ScaleDown) - .overlay('ImageRepeat.Y', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - Image($r('app.media.ic_health_heart')) - .width(110).height(125).border({ width: 1 }) - .objectRepeat(ImageRepeat.X).objectFit(ImageFit.ScaleDown) - .overlay('ImageRepeat.X', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) - } - }.height(150).width('100%').padding({ right: 10 }) + Image("https://www.example.com/xxx.png")// 直接加载网络地址，请填写一个具体的网络图片地址 + .alt($r('app.media.icon'))// 使用alt，在网络图片加载成功前使用占位图 + .width(100) + .height(100) + } } } ``` -![zh-cn_image_0000001205812616](figures/zh-cn_image_0000001205812616.png) -### 事件调用 +### 为图片添加事件 + ```ts @Entry @Component struct ImageExample3 { - @State widthValue: number = 0 - @State heightValue: number = 0 - 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 + @State widthValue: number = 0; + @State heightValue: number = 0; + 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() { Column() { @@ -298,7 +235,7 @@ struct ImageExample3 { offset: { x: 0, y: 20 } }) } - // 为图片添加点击事件，点击完成后加载特定图片。 + // 为图片添加点击事件，点击完成后加载特定图片 Image(this.src) .width(120).height(120) .onClick(() => { @@ -321,144 +258,4 @@ struct ImageExample3 { } ``` -![zh-cn_image_0000001205972610](figures/zh-cn_image_0000001205972610.gif) - -### 渲染沙箱路径图片 - -```ts -import fileio from '@ohos.fileio'; -import fs from '@ohos.file.fs'; -import context from '@ohos.app.ability.common'; - -@Entry -@Component -struct LoadImageExample { - @State resourcesPath: string = '' - @State sandboxPath: string = '' - context: context.UIAbilityContext = getContext(this) as context.UIAbilityContext - - build() { - Column() { - Button('读取沙箱图片') - .margin({ bottom: 10, top: 10 }) - .onClick(() => { - this.sandboxPath = this.context.getApplicationContext().filesDir + '/icon.png' - console.log(`读取沙箱图片=========>${this.sandboxPath}`) - let fd = fs.openSync(this.sandboxPath, 0o100) - console.log(`create file========>${fd}`) - let srcPath = this.context.bundleCodeDir + '/entry/resources/base/media/icon.png' - console.log('mySrcpath' + srcPath) - fileio.copyFileSync(srcPath, this.sandboxPath) // 复制图片到沙箱路径 - this.sandboxPath = 'file://' + this.context.getApplicationContext().filesDir + '/icon.png' - }) - Button('读取资源图片') - .margin({ bottom: 10 }) - .onClick(() => { - this.resourcesPath = 'file://' + this.context.bundleCodeDir + '/entry/resources/base/media/icon.png' - }) - Text(`资源图片路径:${this.resourcesPath}`) - .fontSize(20) - .margin({ bottom: 10 }) - Image(this.resourcesPath) - .width(100) - .height(100) - .colorFilter([ - 0.30, 0.59, 0.11, 0, 0, - 0.30, 0.59, 0.11, 0, 0, - 0.30, 0.59, 0.11, 0, 0, - 0, 0, 0, 1.0, 0 - ]) - Text(`沙箱图片路径:${this.sandboxPath}`) - .fontSize(20) - .margin({ bottom: 10 }) - Image(this.sandboxPath) - .width(100) - .height(100) - } - .width('100%').height('100%') - } -} -``` - -### 为图片增加滤镜 - -```ts -// xxx.ets -@Entry -@Component -struct colorFilterExample { - @State colorFilterR: number = 0 - @State colorFilterG: number = 0 - @State colorFilterB: number = 0 - @State colorFilterA: number = 0 - - build() { - Row() { - Column() { - Image($r('app.media.sky')) - .width(200) - .height(200) - Image($r('app.media.sky')) - .width(200) - .height(200) - .colorFilter([ - this.colorFilterR, 0, this.colorFilterR, 0, 0, - 0, this.colorFilterG, this.colorFilterG, 0, 0, - this.colorFilterB, 0, this.colorFilterB, 0, 0, - 0, 0, this.colorFilterA, 0, 0 - ]) - - Row() { - Text('R') - Slider({ - min: 0, - max: 1, - step: 0.01 - }) - .onChange((valueR) => { - this.colorFilterR = valueR - }) - } - - Row() { - Text('G') - Slider({ - min: 0, - max: 1, - step: 0.01 - }) - .onChange((valueG) => { - this.colorFilterG = valueG - }) - } - - Row() { - Text('B') - Slider({ - min: 0, - max: 1, - step: 0.01 - }) - .onChange((valueB) => { - this.colorFilterB = valueB - }) - } - - Row() { - Text('A') - Slider({ - min: 0, - max: 1, - step: 0.01 - }) - .onChange((valueA) => { - this.colorFilterA = valueA - }) - } - }.width('90%').alignItems(HorizontalAlign.Center) - }.height('100%').width('100%').justifyContent(FlexAlign.Center) - } -} -``` - -![colorFilter](figures/colorFilter.gif) \ No newline at end of file +![zh-cn_image_0000001607845173](figures/zh-cn_image_0000001607845173.gif) \ No newline at end of file diff --git a/zh-cn/application-dev/ui/arkts-graphics-display.md b/zh-cn/application-dev/ui/arkts-graphics-display.md index 111cc1576008265d0c9854a1c958eb84ab43bd9c..87c8dd307cbf0141424c8706c21e744b7ecdaa08 100644 --- a/zh-cn/application-dev/ui/arkts-graphics-display.md +++ b/zh-cn/application-dev/ui/arkts-graphics-display.md @@ -9,7 +9,7 @@ Image通过调用接口来创建，接口调用形式如下： ```ts -Image(src: string | Resource | media.PixelMap) +Image(src: PixelMap | ResourceStr | DrawableDescriptor) ``` @@ -70,9 +70,9 @@ Image支持加载存档图、多媒体像素图两种类型。 Image($rawfile('snap')) ``` -- 媒体库datashare +- 媒体库file://data/storage - 支持datashare://路径前缀的字符串，用于访问通过媒体库提供的图片路径。 + 支持file://路径前缀的字符串，用于访问通过媒体库提供的图片路径。 1. 调用接口获取图库的照片url。 ​ @@ -124,7 +124,7 @@ Image支持加载存档图、多媒体像素图两种类型。 2. 从媒体库获取的url格式通常如下。 ​ ```ts - Image('file://media/5') + Image('file://media/Photos/5') .width(200) ``` @@ -146,6 +146,7 @@ PixelMap是图片解码后的像素图，具体用法请参考[图片开发指 ``` 2. 引用多媒体。 + 请求网络图片请求，解码编码PixelMap。 1. 引用网络权限与媒体库权限。 @@ -272,7 +273,216 @@ struct MyComponent { } ``` -![zh-cn_image_0000001511421240](figures/zh-cn_image_0000001511421240.png) +![zh-cn_image_0000001622804833](figures/zh-cn_image_0000001622804833.png) + + +### 图片插值 + +当原图分辨率较低并且放大显示时，图片会模糊出现锯齿。这时可以使用interpolation属性对图片进行插值，使图片显示得更清晰。 + + +```ts +@Entry +@Component +struct Index { + build() { + Column() { + Row() { + Image($r('app.media.grass')) + .width('40%') + .interpolation(ImageInterpolation.None) + .borderWidth(1) + .overlay("Interpolation.None", { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + .margin(10) + Image($r('app.media.grass')) + .width('40%') + .interpolation(ImageInterpolation.Low) + .borderWidth(1) + .overlay("Interpolation.Low", { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + .margin(10) + }.width('100%') + .justifyContent(FlexAlign.Center) + + Row() { + Image($r('app.media.grass')) + .width('40%') + .interpolation(ImageInterpolation.Medium) + .borderWidth(1) + .overlay("Interpolation.Medium", { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + .margin(10) + Image($r('app.media.grass')) + .width('40%') + .interpolation(ImageInterpolation.High) + .borderWidth(1) + .overlay("Interpolation.High", { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + .margin(10) + }.width('100%') + .justifyContent(FlexAlign.Center) + } + .height('100%') + } +} +``` + +![zh-cn_image_0000001643127365](figures/zh-cn_image_0000001643127365.png) + + +### 设置图片重复样式 + +通过objectRepeat属性设置图片的重复样式方式，重复样式请参考[ImageRepeat](../reference/arkui-ts/ts-appendix-enums.md#imagerepeat)枚举说明。 + + +```ts +@Entry +@Component +struct MyComponent { + build() { + Column({ space: 10 }) { + Row({ space: 5 }) { + Image($r('app.media.ic_public_favor_filled_1')) + .width(110) + .height(115) + .border({ width: 1 }) + .objectRepeat(ImageRepeat.XY) + .objectFit(ImageFit.ScaleDown) + // 在水平轴和竖直轴上同时重复绘制图片 + .overlay('ImageRepeat.XY', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + Image($r('app.media.ic_public_favor_filled_1')) + .width(110) + .height(115) + .border({ width: 1 }) + .objectRepeat(ImageRepeat.Y) + .objectFit(ImageFit.ScaleDown) + // 只在竖直轴上重复绘制图片 + .overlay('ImageRepeat.Y', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + Image($r('app.media.ic_public_favor_filled_1')) + .width(110) + .height(115) + .border({ width: 1 }) + .objectRepeat(ImageRepeat.X) + .objectFit(ImageFit.ScaleDown) + // 只在水平轴上重复绘制图片 + .overlay('ImageRepeat.X', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + } + }.height(150).width('100%').padding(8) + } +} +``` + +![zh-cn_image_0000001593444112](figures/zh-cn_image_0000001593444112.png) + + +### 设置图片渲染模式 + +通过renderMode属性设置图片的渲染模式为原色或黑白。 + + +```ts +@Entry +@Component +struct MyComponent { + build() { + Column({ space: 10 }) { + Row({ space: 50 }) { + Image($r('app.media.example')) + // 设置图片的渲染模式为原色 + .renderMode(ImageRenderMode.Original) + .width(100) + .height(100) + .border({ width: 1 }) + // overlay是通用属性，用于在组件上显示说明文字 + .overlay('Original', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + Image($r('app.media.example')) + // 设置图片的渲染模式为黑白 + .renderMode(ImageRenderMode.Template) + .width(100) + .height(100) + .border({ width: 1 }) + .overlay('Template', { align: Alignment.Bottom, offset: { x: 0, y: 20 } }) + } + }.height(150).width('100%').padding({ top: 20,right: 10 }) + } +} +``` + +![zh-cn_image_0000001593293100](figures/zh-cn_image_0000001593293100.png) + + +### 设置图片解码尺寸 + +通过sourceSize属性设置图片解码尺寸，降低图片的分辨率。 + +原图尺寸为1280\*960，该示例将图片解码为150\*100和400\*400。 + + +```ts +@Entry +@Component +struct Index { + build() { + Column() { + Row({ space: 20 }) { + Image($r('app.media.example')) + .sourceSize({ + width: 150, + height: 150 + }) + .objectFit(ImageFit.ScaleDown) + .width('25%') + .aspectRatio(1) + .border({ width: 1 }) + .overlay('width:150 height:150', { align: Alignment.Bottom, offset: { x: 0, y: 40 } }) + Image($r('app.media.example')) + .sourceSize({ + width: 400, + height: 400 + }) + .objectFit(ImageFit.ScaleDown) + .width('25%') + .aspectRatio(1) + .border({ width: 1 }) + .overlay('width:400 height:400', { align: Alignment.Bottom, offset: { x: 0, y: 40 } }) + }.height(150).width('100%').padding(20) + + } + } +} +``` + +![zh-cn_image_0000001593769844](figures/zh-cn_image_0000001593769844.png) + + +### 为图片添加滤镜效果 + +通过colorFilter修改图片的像素颜色，为图片添加滤镜。 + + +```ts +@Entry +@Component +struct Index { + build() { + Column() { + Row() { + Image($r('app.media.example')) + .width('40%') + .margin(10) + Image($r('app.media.example')) + .width('40%') + .colorFilter( + [1, 1, 0, 0, 0, + 0, 1, 0, 0, 0, + 0, 0, 1, 0, 0, + 0, 0, 0, 1, 0]) + .margin(10) + }.width('100%') + .justifyContent(FlexAlign.Center) + } + } +} +``` + +![zh-cn_image_0000001643171357](figures/zh-cn_image_0000001643171357.png) ### 同步加载图片 diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593293100.png b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593293100.png new file mode 100644 index 0000000000000000000000000000000000000000..219903664ec5a078311c94aea36d400d378bb999 Binary files /dev/null and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593293100.png differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593444112.png b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593444112.png new file mode 100644 index 0000000000000000000000000000000000000000..e9542d910023d1105619589525c50312eff59e9b Binary files /dev/null and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593444112.png differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593769844.png b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593769844.png new file mode 100644 index 0000000000000000000000000000000000000000..2d55f958227b92833b2fe4e4e5b65a5535b7b807 Binary files /dev/null and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001593769844.png differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001622804833.png b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001622804833.png new file mode 100644 index 0000000000000000000000000000000000000000..1dcef5d17c1a081235b1ce2fb61878675a1c15ab Binary files /dev/null and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001622804833.png differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001643127365.png b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001643127365.png new file mode 100644 index 0000000000000000000000000000000000000000..c93a6e87b1d4f5eb0da5a6bb993285d2d742d8f0 Binary files /dev/null and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001643127365.png differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001643171357.png b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001643171357.png new file mode 100644 index 0000000000000000000000000000000000000000..b9680fe616ccf50248ecd353256f336e2cb23bf1 Binary files /dev/null and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001643171357.png differ