HarmonyOS API:通用信息

joytrian
发布于 2023-3-27 17:52
浏览
0收藏

版本: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
    },
}

HarmonyOS API:通用信息-鸿蒙开发者社区

示例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;
}

HarmonyOS API:通用信息-鸿蒙开发者社区

通用事件

更新时间: 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

​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);
    }
}


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-components-common-events-0000001478341193-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001478341193__getdata9​

已于2023-3-27 17:52:39修改
收藏
回复
举报
回复
    相关推荐