HarmonyOS API:通用信息
版本:v3.1 Beta
通用属性
更新时间: 2023-02-17 09:19
说明
从API version 4开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
常规属性
常规属性是指组件普遍支持的用来设置组件基本标识和外观显示特征的属性。
名称 | 类型 | 默认值 | 必填 | 描述 |
id | string | - | 否 | 组件的唯一标识。 |
style | string | - | 否 | 组件的样式声明。 |
class | string | - | 否 | 组件的样式类,用于引用样式表。 |
ref | string | - | 否 | 用来指定指向子元素或子组件的引用信息,该引用将注册到父组件的$refs 属性对象上。 |
disabled | boolean | false | 否 | 当前组件是否被禁用,在禁用场景下,组件将无法响应用户交互。 |
data | string | - | 否 | 给当前组件设置data属性,进行相应的数据存储和读取。JS文件中: - 在事件回调中使用 e.target.attr.data 读取数据,e为事件回调函数入参。 - 使用$element或者$refs获取DOM元素后,通过attr.data 进行访问。 从API Version 6 开始,建议使用data-*。 |
data-*6+ | string | - | 否 | 给当前组件设置data-*属性,进行相应的数据存储和读取。大小写不敏感,如data-A和data-a默认相同。JS文件中: - 在事件回调中使用 e.target.dataSet.a读取数据,e为事件回调函数入参。 - 使用$element或者$refs获取DOM元素后,通过dataSet.a进行访问。 |
click-effect5+ | string | - | 否 | 通过这个属性可以设置组件的弹性点击效果,当前支持如下三种效果: - spring-small:建议小面积组件设置,缩放(90%)。 - spring-medium:建议中面积组件设置,缩放(95%)。 - spring-large:建议大面积组件设置,缩放(95%)。 |
dir6+ | string | auto | 否 | 设置元素布局模式,支持设置rtl、ltr和auto三种属性值: - rtl:使用从右往左布局模式。 - ltr:使用从左往右布局模式。 - auto:跟随系统语言环境。 |
渲染属性
渲染属性是指组件普遍支持的用来设置组件是否渲染的属性。
名称 | 类型 | 默认值 | 描述 |
for | Array | - | 根据设置的数据列表,展开当前元素。 |
if | boolean | - | 根据设置的boolean值,添加或移除当前元素。 |
show | boolean | - | 根据设置的boolean值,显示或隐藏当前元素。 |
说明
属性和样式不能混用,不能在属性字段中进行样式设置。
示例
示例1
<!-- xxx.hml -->
<div id="container">
<button class="btn" type="capsule" value="toggleDisplay" onclick="toggleDisplay"></button>
<list class="list">
<list-item for="{{ array }}" class="listItem">
<text class="text" onclick="toggleShow" show="{{ visible }}"
if="{{ display }}">{{ $item.value }}</text>
</list-item>
</list>
</div>
/* xxx.css */
#container {
flex-direction: column;
width: 100%;
margin-top: 10px;
}
.text {
font-size: 50px;
font-weight: 500;
margin-left: 12px;
}
.listItem {
width: 100%;
height: 100px;
line-height: 60px;
border-bottom: 1px solid #DEDEDE;
font-size: 20px;
}
.btn{
width: 280px;
font-size: 26px;
margin: 10px 0;
}
// xxx.js
export default {
data: {
visible: true,
display: true,
title: "",
i: 4,
array: [
{"value": "列表文本0"},
{"value": "列表文本1"},
{"value": "列表文本2"},
{"value": "列表文本3"},
],
},
toggleShow: function() {
this.array.push({"value": "列表文本" + this.i })
this.i++
},
toggleDisplay: function() {
this.display = !this.display
},
}
示例2
<!-- xxx.hml -->
<div class="container">
<div>
<text class="text1" dir='rtl' >hello world</text>
</div>
<div>
<text class="text2" dir='ltr' >hello world</text>
</div>
</div>
/* xxx.css */
.container {
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
width: 100%;
height: 100%;
}
.text1{
width: 90%;
height: 100px;
background-color: aqua;
}
.text2{
width: 90%;
height: 100px;
background-color: blue;
}
通用事件
更新时间: 2023-02-17 09:19
说明
从API version 4开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
事件说明
- 事件绑定在组件上,当组件达到事件触发条件时,会执行JS中对应的事件回调函数,实现页面UI视图和页面JS逻辑层的交互;
- 事件回调函数中通过参数可以携带额外的信息,如组件上的数据对象dataset,事件特有的回调参数。
相对于私有事件,大部分组件都可以绑定如下事件。
名称 | 参数 | 描述 | 是否支持冒泡 | 是否支持捕获 |
touchstart | TouchEvent | 手指刚触摸屏幕时触发该事件。TouchEvent具体可参考表2 。 | 是5+ | 是5+ |
touchmove | TouchEvent | 手指触摸屏幕后移动时触发该事件。 | 是5+ | 是5+ |
touchcancel | TouchEvent | 手指触摸屏幕中动作被打断时触发该事件。 | 是5+ | 是5+ |
touchend | TouchEvent | 手指触摸结束离开屏幕时触发该事件。 | 是5+ | 是5+ |
click | - | 点击动作触发该事件。 | 是6+ | 否 |
doubleclick7+ | - | 双击动作触发该事件 | 否 从API Version 9 开始支持冒泡。 | 否 |
longpress | - | 长按动作触发该事件。 | 否 从API Version 9 开始支持冒泡。 | 否 |
swipe5+ | SwipeEvent | 组件上快速滑动后触发该事件。 SwipeEvent具体可参考表4 。 | 否 从API Version 9 开始支持冒泡。 | 否 |
attached6+ | - | 当前组件节点挂载在渲染树后触发。 | 否 | 否 |
detached6+ | - | 当前组件节点从渲染树中移除后触发。 | 否 | 否 |
pinchstart7+ | PinchEvent | 手指开始执行捏合操作时触发该事件。 PinchEvent具体可参考表5。 | 否 | 否 |
pinchupdate7+ | PinchEvent | 手指执行捏合操作过程中触发该事件。 | 否 | 否 |
pinchend7+ | PinchEvent | 手指捏合操作结束离开屏幕时触发该事件。 | 否 | 否 |
pinchcancel7+ | PinchEvent | 手指捏合操作被打断时触发该事件。 | 否 | 否 |
dragstart7+ | DragEvent | 用户开始拖拽时触发该事件。 DragEvent具体可参考表6。 | 否 | 否 |
drag7+ | DragEvent | 拖拽过程中触发该事件。 | 否 | 否 |
dragend7+ | DragEvent | 用户拖拽完成后触发。 | 否 | 否 |
dragenter7+ | DragEvent | 进入释放目标时触发该事件。 | 否 | 否 |
dragover7+ | DragEvent | 在释放目标内拖动时触发。 | 否 | 否 |
dragleave7+ | DragEvent | 离开释放目标区域时触发。 | 否 | 否 |
drop7+ | DragEvent | 在可释放目标区域内释放时触发。 | 否 | 否 |
说明
除上述事件外,其他事件均为非冒泡事件,如input的change事件,详见各个组件。
表1 BaseEvent对象属性列表
属性 | 类型 | 说明 |
type | string | 当前事件的类型,比如click、longpress等。 |
timestamp | number | 该事件触发时的时间戳。 |
deviceId6+ | number | 触发该事件的设备ID信息。 |
target6+ | Target | 触发该事件的目标对象。 |
表2 TouchEvent对象属性列表(继承BaseEvent)
属性 | 类型 | 说明 |
touches | Array<TouchInfo> | 触摸事件时的属性集合,包含屏幕触摸点的信息数组。 |
changedTouches | Array<TouchInfo> | 触摸事件时的属性集合,包括产生变化的屏幕触摸点的信息数组。数据格式和touches一样。该属性表示有变化的触摸点,如从无变有,位置变化,从有变无。例如用户手指刚接触屏幕时,touches数组中有数据,但changedTouches无数据。 |
表3 TouchInfo
属性 | 类型 | 说明 |
globalX | number | 距离屏幕左上角(不包括状态栏)横向距离。屏幕的左上角为原点。 |
globalY | number | 距离屏幕左上角(不包括状态栏)纵向距离。屏幕的左上角为原点。 |
localX | number | 距离被触摸组件左上角横向距离。组件的左上角为原点。 |
localY | number | 距离被触摸组件左上角纵向距离。组件的左上角为原点。 |
size | number | 触摸接触面积。 |
force6+ | number | 接触力信息。 |
表4 SwipeEvent 基础事件对象属性列表(继承BaseEvent)
属性 | 类型 | 说明 |
direction | string | 滑动方向,可能值有: - left:向左滑动; - right:向右滑动; - up:向上滑动; - down:向下滑动。 |
distance6+ | number | 在滑动方向上的滑动距离。 |
表5 PinchEvent 对象属性列表7+
属性 | 类型 | 说明 |
scale | number | 缩放比例 |
pinchCenterX | number | 捏合中心点X轴坐标,单位px |
pinchCenterY | number | 捏合中心点Y轴坐标,单位px |
表6 DragEvent对象属性列表(继承BaseEvent)7+
属性 | 类型 | 说明 |
type | string | 事件名称。 |
globalX | number | 距离屏幕左上角坐标原点横向距离。 |
globalY | number | 距离屏幕左上角坐标原点纵向距离。 |
timestamp | number | 时间戳。 |
dataTransfer9+ | DataTransfer | 用于传输数据。 |
Target对象6+
当组件触发事件后,事件回调函数默认会收到一个事件对象,通过该事件对象可以获取相应的信息。
属性 | 类型 | 说明 |
dataSet6+ | Object | 组件上通过通用属性设置的data-*的自定义属性组成的集合。 |
示例:
<!-- xxx.hml -->
<div>
<div data-a="dataA" data-b="dataB"
style="width: 100%; height: 50%; background-color: saddlebrown;"@touchstart='touchstartfunc'></div>
</div>
// xxx.js
export default {
touchstartfunc(msg) {
console.info(`on touch start, point is: ${msg.touches[0].globalX}`);
console.info(`on touch start, data is: ${msg.target.dataSet.a}`);
}
}
DataTransfer对象9+
在拖拽操作的过程中,可以通过dataTransfer对象来传输数据,以便在拖拽操作结束的时候对数据进行其他操作。
setData9+
setData(key: string, value: object): boolean
设置给定key关联的数据。如果没有与该key关联的数据,则将其添加到末尾。如果该key关联的数据已经存在,则在相同位置替换现有数据。
参数:
参数名 | 参数类型 | 必填 | 描述 |
key | string | 是 | 数据键值。 |
value | object | 是 | 要存储的数据。 |
返回值:
类型 | 说明 |
boolean | 执行结果,true表示成功,false表示失败。 |
示例:
// setData的value参数,可以是基本数据类型。
dragStart(e) {
var isSetOk = e.dataTransfer.setData('name', 1);
},
// setData的value参数,也可以是对象类型。
dragStart(e) {
var person = new Object();
person.name = "tom";
person.age = 21;
var isSetOk = e.dataTransfer.setData('person', person);
}
getData9+
getData(key: string): object
获取给定key关联的数据,如果没有与该key关联的数据,则返回空字符串。
参数:
参数名 | 参数类型 | 必填 | 描述 |
key | string | 是 | 数据键值。 |
返回值:
类型 | 说明 |
object | 获取的数据。 |
示例:
dragStart(e) {
var person = new Object();
person.name = "tom";
person.age = 21;
e.dataTransfer.setData('person', person);
},
dragEnd(e){
var person = e.dataTransfer.getData('person');
},
clearData9+
clearData(key?: string): boolean
删除给定key关联的数据。如果没有与该key关联的数据,则该方法不会产生任何效果。
如果key为空,则删除所有数据。
参数:
参数名 | 参数类型 | 必填 | 描述 |
key | string | 否 | 数据键值。 |
返回值:
类型 | 说明 |
boolean | 执行结果,true表示成功,false表示失败。 |
示例:
dragEnd(e) {
var isSuccess = e.dataTransfer.clearData('name');
}
setDragImage9+
setDragImage(pixelmap: PixelMap, offsetX: number,offsetY: number): boolean
用于设置自定义的拖动图像。
参数:
参数名 | 参数类型 | 必填 | 描述 |
pixelmap | 是 | 前端传入的图片资源。 | |
offsetX | number | 是 | 相对于图片的横向偏移量。 |
offsetY | number | 是 | 相对于图片的纵向偏移量。 |
返回值:
类型 | 说明 |
boolean | 执行结果,true表示成功,false表示失败。 |
示例:
import image from '@ohos.multimedia.image';
export default {
createPixelMap() {
let color = new ArrayBuffer(4 * 96 * 96);
var buffer = new Uint8Array(color);
for (var i = 0; i < buffer.length; i++) {
buffer[i] = (i + 1) % 255;
}
let opts = {
alphaType: 0,
editable: true,
pixelFormat: 4,
scaleMode: 1,
size: {
height: 96, width: 96
}
}
const promise = image.createPixelMap(color, opts);
promise.then((data) => {
console.error('-create pixmap has info message:' + JSON.stringify(data));
this.pixelMap = data;
this.pixelMapReader = data;
})
},
onInit() {
this.createPixelMap
},
dragStart(e) {
e.dataTransfer.setDragImage(this.pixelMapReader, 50, 50);
}
}