HarmonyOS API：基础组件

joytrian

发布于 2023-3-29 16:00

浏览

0收藏

版本：v3.1 Beta

image

更新时间: 2023-02-17 09:19

说明

从API version 4开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

图片组件，用来渲染展示图片。

子组件

不支持。

示例

div class="container out-container">
    <div class="container">
        <text class="title">基础用法</text>
        <div>
            <image class="images" src="common/images/bg-tv.jpg"></image>
            <image class="images round" src="common/images/bg-tv.jpg"></image>
        </div>
    </div>

    <text class="title">填充模式</text>
    <div class="divImg">
        <div class="container">
            <image class="images fill" src="common/images/bg-tv.jpg"></image>
            <text class="object-fit object-fill">fill</text>
        </div>

        <div class="container">
            <image class="images cover" src="common/images/bg-tv.jpg"></image>
            <text class="object-fit object-cover">cover</text>
        </div>

        <div class="container">
            <image class="images contain" src="common/images/bg-tv.jpg"></image>
            <text class="object-fit object-contain">contain</text>
        </div>

        <div class="container">
            <image class="images none" src="common/images/bg-tv.jpg"></image>
            <text class="object-fit object-none">none</text>
        </div>

        <div class="container">
            <image class="images scale-down" src="common/images/bg-tv.jpg"></image>
            <text class="object-fit object-scale">scale-down</text>
        </div>
    </div>

    <text class="title">加载失败</text>
    <div class="loading">
        <image class="fail-image" src="common/images/bg-tv2.jpg" oncomplete="imageComplete(1)" onerror="imageError(1)"></image>
        <text class="fail" show="{{ txt }}">加载失败</text>
    </div>
    <text class="object-fit object-fail">自定义提示</text>
</div>

HarmonyOS API：基础组件-鸿蒙开发者社区

属性

除支持通用属性外，还支持如下属性：

名称	类型	默认值	必填	描述
src	string	-	否	图片的路径，支持本地路径，图片格式包括png、jpg、bmp、svg和gif。 - 支持Base64字符串⁶⁺。格式为data:image/[png \| jpeg \| bmp \| webp];base64, [base64 data], 其中[base64 data]为Base64字符串数据。 - 支持dataability://的路径前缀，用于访问通过data ability提供的图片路径⁶⁺。
alt	string	-	否	占位图，当指定图片在加载中时显示。

样式

除支持通用样式外，还支持如下属性：

名称	类型	默认值	必填	描述
object-fit	string	cover	否	设置图片的缩放类型，不支持svg格式。可选值类型说明请见object-fit类型说明。
match-text-direction	boolean	false	否	图片是否跟随文字方向，不支持svg格式。
fit-original-size	boolean	false	否	image组件在未设置宽高的情况下是否适应图源尺寸，该属性为true时object-fit属性不生效，svg类型图源不支持该属性。
object-position⁷⁺	string	0px 0px	否	设置图片在组件内展示的位置。设置类型有两种： 1. 像素，单位px，示例 15px 15px 代表X轴或者Y轴移动的位置 2. 字符，可选值： - left 图片显示在组件左侧； - top 图片显示在组件顶部位置； - right 图片显示在组件右侧位置； - bottom 图片显示在组件底部位置。

表1 object-fit 类型说明

类型	描述
cover	保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界，居中显示。
contain	保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内，居中显示。
fill	不保持宽高比进行放大缩小，使得图片填充满显示边界。
none	保持原有尺寸进行居中显示。
scale-down	保持宽高比居中显示，图片缩小或者保持不变。

说明

使用svg图片资源时：
建议设置image组件的长宽，否则在父组件的长或宽为无穷大的场景下，svg资源将不会绘制；
如果svg描述中未指定相应的长宽，则svg将会填满image组件区域；
如果svg描述中指定了相应的长宽，和image组件本身的长宽效果如下：
如果image组件本身的长宽小于svg中的长宽，svg会被裁切，仅显示左上角部分；
如果image组件本身的长宽大于svg中的长宽，svg会被放置在image组件的左上角，image组件其他部分显示空白。
图片设置svg图源时，支持的标签范围有限，目前支持的svg标签包括svg、rect、circle、ellipse、path、line、polyline、polygon、animate、animateMotion、animateTransform。

事件

除支持通用事件外，还支持如下事件：

名称	参数	描述
complete	{ width：width， height：height }	图片成功加载时触发该回调，返回成功加载的图源尺寸。
error	{ width：width， height：height }	图片加载出现异常时触发该回调，异常时长宽为零。

方法

支持通用方法。

image-animator

更新时间: 2023-02-17 09:19

说明

从API version 4开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

图片帧动画播放器。

子组件

不支持。

属性

除支持通用属性外，还支持如下属性：

名称	类型	默认值	必填	描述
images	Array<ImageFrame>	-	是	设置图片帧信息集合。每一帧的帧信息包含图片路径、图片大小和图片位置信息。目前支持以下图片格式：png、jpg。ImageFrame的详细说明请见表 ImageFrame说明。使用时需要使用数据绑定的方式： - hml文件中引用图片资源：images = {{images}}， - js文件中声明相应变量： images: [{src: "/common/heart-rate01.png",duration:"100"}]。从API Version 6 开始，支持配置每一帧图片的时长，单位毫秒。
predecode⁶⁺	number	0	否	是否启用预解码，默认值为0，即不启用预解码，如该值设为2，则播放当前页时会提前加载后面两张图片至缓存以提升性能。
iteration	number \| string	infinite	否	设置帧动画播放次数。number表示固定次数，infinite枚举表示无限次数播放。
reverse	boolean	false	否	设置播放顺序。false表示从第1张图片播放到最后1张图片； true表示从最后1张图片播放到第1张图片。
fixedsize	boolean	true	否	设置图片大小是否固定为组件大小。 true表示图片大小与组件大小一致，此时设置图片的width 、height 、top 和left属性是无效的。false表示每一张图片的 width 、height 、top和left属性都要单独设置。
duration	string	-	是	设置单次播放时长。单位支持[s(秒)\|ms(毫秒)]，默认单位为ms。 duration为0时，不播放图片。值改变只会在下一次循环开始时生效，当images中设置了单独的duration后，该属性设置无效。
fillmode⁵⁺	string	forwards	否	指定帧动画执行结束后的状态。可选项有： - none：恢复初始状态。 - forwards：保持帧动画结束时的状态（在最后一个关键帧中定义）。

表1 ImageFrame说明

名称	类型	默认值	必填	描述
src	<uri>	-	是	图片路径，图片格式为svg，png和jpg。
width	<length>	0	否	图片宽度。
height	<length>	0	否	图片高度。
top	<length>	0	否	图片相对于组件左上角的纵向坐标。
left	<length>	0	否	图片相对于组件左上角的横向坐标。
duration⁶⁺	number	-	否	每一帧图片的播放时长，单位毫秒。

样式

支持通用样式。

事件

除支持通用事件外，还支持如下事件：

名称	参数	描述
start	-	帧动画启动时触发。
pause	-	帧动画暂停时触发。
stop	-	帧动画结束时触发。
resume	-	帧动画恢复时触发。

方法

支持通用方法外，还支持如下方法：

名称	参数	描述
start	-	开始播放图片帧动画。再次调用，重新从第1帧开始播放。
pause	-	暂停播放图片帧动画。
stop	-	停止播放图片帧动画。
resume	-	继续播放图片帧。
getState	-	获取播放状态。 - playing：播放中 - paused：已暂停 - stopped：已停止。

示例

<!-- xxx.hml -->
<div class="container">
  <image-animator class="animator" ref="animator" images="{{frames}}" duration="1s" />
  <div class="btn-box">
    <input class="btn" type="button" value="start" @click="handleStart" />
    <input class="btn" type="button" value="stop" @click="handleStop" />
    <input class="btn" type="button" value="pause" @click="handlePause" />
    <input class="btn" type="button" value="resume" @click="handleResume" />
  </div>
</div>

/* xxx.css */
.container {
  flex-direction: column;
  justify-content: center;
  align-items: center;
  left: 0px;
  top: 0px;
  width: 454px;
  height: 454px;
  background-color: black;
}
.animator {
  width: 70px;
  height: 70px;
}
.btn-box {
  width: 264px;
  height: 120px;
  flex-wrap: wrap;
  justify-content: space-around;
  align-items: center;
}
.btn {
  border-radius: 8px;
  width: 120px;
  margin-top: 8px;
}

//xxx.js
export default {
  data: {
    frames: [
      {
        src: "/common/asserts/heart78.png",
      },
      {
        src: "/common/asserts/heart79.png",
      },
      {
        src: "/common/asserts/heart80.png",
      },
      {
        src: "/common/asserts/heart81.png",
      },
      {
        src: "/common/asserts/heart82.png",
      },
      {
        src: "/common/asserts/heart83.png",
      },
      {
        src: "/common/asserts/heart84.png",
      },
      {
        src: "/common/asserts/heart85.png",
      },
      {
        src: "/common/asserts/heart86.png",
      },
      {
        src: "/common/asserts/heart87.png",
      },
      {
        src: "/common/asserts/heart88.png",
      },
      {
        src: "/common/asserts/heart89.png",
      },
      {
        src: "/common/asserts/heart90.png",
      },
      {
        src: "/common/asserts/heart91.png",
      },
      {
        src: "/common/asserts/heart92.png",
      },
      {
        src: "/common/asserts/heart93.png",
      },
      {
        src: "/common/asserts/heart94.png",
      },
      {
        src: "/common/asserts/heart95.png",
      },
      {
        src: "/common/asserts/heart96.png",
      },
    ],
  },
  handleStart() {
    this.$refs.animator.start();
  },
  handlePause() {
    this.$refs.animator.pause();
  },
  handleResume() {
    this.$refs.animator.resume();
  },
  handleStop() {
    this.$refs.animator.stop();
  },
};

HarmonyOS API：基础组件-鸿蒙开发者社区