HarmonyOS API:通用事件
版本:v3.1 Beta
点击事件
更新时间: 2023-02-17 09:19
组件被点击时触发的事件。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
事件
名称  | 支持冒泡  | 功能描述  | 
onClick(event: (event?: ClickEvent) => void)  | 否  | 点击动作触发该回调,event返回值见ClickEvent对象说明。  | 
ClickEvent对象说明
名称  | 类型  | 描述  | 
screenX  | number  | 点击位置相对于应用窗口左上角的X坐标。  | 
screenY  | number  | 点击位置相对于应用窗口左上角的Y坐标。  | 
x  | number  | 点击位置相对于被点击元素左上角的X坐标。  | 
y  | number  | 点击位置相对于被点击元素左上角的Y坐标。  | 
timestamp8+  | number  | 事件时间戳。触发事件时距离系统启动的时间间隔,单位纳秒。  | 
target8+  | EventTarget  | 触发事件的元素对象显示区域。  | 
source8+  | 事件输入设备。  | 
EventTarget8+对象说明
名称  | 参数类型  | 描述  | 
area  | Area  | 目标元素的区域信息。  | 
示例
// xxx.ets
@Entry
@Component
struct ClickExample {
  @State text: string = ''
  build() {
    Column() {
      Row({ space: 20 }) {
        Button('Click').width(100).height(40)
          .onClick((event: ClickEvent) => {
            this.text = 'Click Point:' + '\n  screenX:' + event.screenX + '\n  screenY:' + event.screenY
            + '\n  x:' + event.x + '\n  y:' + event.y + '\ntarget:' + '\n  component globalPos:('
            + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n  width:'
            + event.target.area.width + '\n  height:' + event.target.area.height + '\ntimestamp' + event.timestamp;
          })
        Button('Click').width(200).height(50)
          .onClick((event: ClickEvent) => {
            this.text = 'Click Point:' + '\n  screenX:' + event.screenX + '\n  screenY:' + event.screenY
            + '\n  x:' + event.x + '\n  y:' + event.y + '\ntarget:' + '\n  component globalPos:('
            + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n  width:'
            + event.target.area.width + '\n  height:' + event.target.area.height + '\ntimestamp' + event.timestamp;
          })
      }.margin(20)
      Text(this.text).margin(15)
    }.width('100%')
  }
}
触摸事件
更新时间: 2023-02-17 09:19
当手指在组件上按下、滑动、抬起时触发。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
事件
名称  | 是否冒泡  | 功能描述  | 
onTouch(event: (event?: TouchEvent) => void)  | 是  | 手指触摸动作触发该回调,event返回值见TouchEvent介绍。  | 
TouchEvent对象说明
名称  | 类型  | 描述  | 
type  | 触摸事件的类型。  | |
touches  | Array<TouchObject>  | 全部手指信息。  | 
changedTouches  | Array<TouchObject>  | 当前发生变化的手指信息。  | 
stopPropagation  | () => void  | 阻塞事件冒泡。  | 
timestamp8+  | number  | 事件时间戳。触发事件时距离系统启动的时间间隔,单位纳秒。  | 
target8+  | 触发事件的元素对象显示区域。  | |
source8+  | 事件输入设备。  | 
TouchObject对象说明
名称  | 类型  | 描述  | 
type  | 触摸事件的类型。  | |
id  | number  | 手指唯一标识符。  | 
screenX  | number  | 触摸点相对于应用窗口左上角的X坐标。  | 
screenY  | number  | 触摸点相对于应用窗口左上角的Y坐标。  | 
x  | number  | 触摸点相对于被触摸元素左上角的X坐标。  | 
y  | number  | 触摸点相对于被触摸元素左上角的Y坐标。  | 
示例
// xxx.ets
@Entry
@Component
struct TouchExample {
  @State text: string = ''
  @State eventType: string = ''
  build() {
    Column() {
      Button('Touch').height(40).width(100)
        .onTouch((event: TouchEvent) => {
          if (event.type === TouchType.Down) {
            this.eventType = 'Down'
          }
          if (event.type === TouchType.Up) {
            this.eventType = 'Up'
          }
          if (event.type === TouchType.Move) {
            this.eventType = 'Move'
          }
          this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
          + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
          + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
          + event.target.area.width + '\nheight:' + event.target.area.height
        })
      Button('Touch').height(50).width(200).margin(20)
        .onTouch((event: TouchEvent) => {
          if (event.type === TouchType.Down) {
            this.eventType = 'Down'
          }
          if (event.type === TouchType.Up) {
            this.eventType = 'Up'
          }
          if (event.type === TouchType.Move) {
            this.eventType = 'Move'
          }
          this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
          + event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
          + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
          + event.target.area.width + '\nheight:' + event.target.area.height
        })
      Text(this.text)
    }.width('100%').padding(30)
  }
}
挂载卸载事件
更新时间: 2023-02-17 09:19
挂载卸载事件指组件从组件树上挂载、卸载时触发的事件。
说明
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
事件
名称  | 支持冒泡  | 功能描述  | 
onAppear(event: () => void)  | 否  | 组件挂载显示时触发此回调。  | 
onDisAppear(event: () => void)  | 否  | 组件卸载消失时触发此回调。  | 
示例
// xxx.ets
import promptAction from '@ohos.promptAction'
@Entry
@Component
struct AppearExample {
  @State isShow: boolean = true
  @State changeAppear: string = 'Hide Text'
  private myText: string = 'Text for onAppear'
  build() {
    Column() {
      Button(this.changeAppear)
        .onClick(() => {
          this.isShow = !this.isShow
        }).margin(15)
      if (this.isShow) {
        Text(this.myText).fontSize(26).fontWeight(FontWeight.Bold)
          .onAppear(() => {
            this.changeAppear = 'Hide Text'
            promptAction.showToast({
              message: 'The text is shown',
              duration: 2000
            })
          })
          .onDisAppear(() => {
            this.changeAppear = 'Show Text'
            promptAction.showToast({
              message: 'The text is hidden',
              duration: 2000
            })
          })
      }
    }.padding(30).width('100%')
  }
}
拖拽事件
更新时间: 2023-02-17 09:19
拖拽事件指组件被长按后拖拽时触发的事件。
说明
从API Version 8开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
该模块能力在HarmonyOS 3.1 Beta1暂不支持。
事件
名称  | 支持冒泡  | 功能描述  | 
onDragStart(event: (event?: DragEvent, extraParams?: string) => CustomBuilder | DragItemInfo)  | 否  | 第一次拖拽此事件绑定的组件时,触发回调。 - event:拖拽事件信息,包括拖拽点坐标。 - extraParams:拖拽事件额外信息,详见extraParams说明。 返回值:当前跟手效果所拖拽的对象,用于显示拖拽时的提示组件。 长按150ms可触发拖拽事件。优先级:长按手势配置时间小于等于150ms时,长按手势优先触发,否则拖拽事件优先触发。  | 
onDragEnter(event: (event?: DragEvent, extraParams?: string) => void)  | 否  | 拖拽进入组件范围内时,触发回调。 - event:拖拽事件信息,包括拖拽点坐标。 - extraParams:拖拽事件额外信息,详见extraParams说明。 当监听了onDrop事件时,此事件才有效。  | 
onDragMove(event: (event?: DragEvent, extraParams?: string) => void)  | 否  | 拖拽在组件范围内移动时,触发回调。 - event:拖拽事件信息,包括拖拽点坐标。 - extraParams:拖拽事件额外信息,详见extraParams说明。 当监听了onDrop事件时,此事件才有效。  | 
onDragLeave(event: (event?: DragEvent, extraParams?: string) => void)  | 否  | 拖拽离开组件范围内时,触发回调。 - event:拖拽事件信息,包括拖拽点坐标。 - extraParams:拖拽事件额外信息,详见extraParams说明。 当监听了onDrop事件时,此事件才有效。  | 
onDrop(event: (event?: DragEvent, extraParams?: string) => void)  | 否  | 绑定此事件的组件可作为拖拽释放目标,当在本组件范围内停止拖拽行为时,触发回调。 - event:拖拽事件信息,包括拖拽点坐标。 - extraParams:拖拽事件额外信息,详见extraParams说明。  | 
DragItemInfo说明
名称  | 类型  | 必填  | 描述  | 
pixelMap  | 否  | 设置拖拽过程中显示的图片。  | |
builder  | 否  | 拖拽过程中显示自定义组件,如果设置了pixelMap,则忽略此值。  | |
extraInfo  | string  | 否  | 拖拽项的描述。  | 
extraParams说明
用于返回组件在拖拽中需要用到的额外信息。
extraParams是Json对象转换的string字符串,可以通过Json.parse转换的Json对象获取如下属性。
名称  | 类型  | 描述  | 
selectedIndex  | number  | 当拖拽事件设在父容器的子元素时,selectedIndex表示当前被拖拽子元素是父容器第selectedIndex个子元素,selectedIndex从0开始。 仅在ListItem组件的拖拽事件中生效。  | 
insertIndex  | number  | 当前拖拽元素在List组件中放下时,insertIndex表示被拖拽元素插入该组件的第insertIndex个位置,insertIndex从0开始。 仅在List组件的拖拽事件中生效。  | 
DragEvent说明
名称  | 类型  | 描述  | 
getX()  | number  | 当前拖拽点x轴坐标,单位为vp。  | 
getY()  | number  | 当前拖拽点y轴坐标,单位为vp。  | 
示例
// xxx.ets
@Extend(Text) function textStyle () {
  .width('25%')
  .height(35)
  .fontSize(16)
  .textAlign(TextAlign.Center)
  .backgroundColor(0xAFEEEE)
}
@Entry
@Component
struct DragExample {
  @State numbers: string[] = ['one', 'two', 'three', 'four', 'five', 'six']
  @State text: string = ''
  @State bool: boolean = true
  @State eventType: string = ''
  @State appleVisible: Visibility = Visibility.Visible
  @State orangeVisible: Visibility = Visibility.Visible
  @State bananaVisible: Visibility = Visibility.Visible
  private dragList: string[] = ['apple', 'orange', 'banana']
  @State fruitVisible: Visibility[] = [Visibility.Visible, Visibility.Visible, Visibility.Visible]
  @State index: number = 0
  // 自定义拖拽过程中显示的内容
  @Builder pixelMapBuilder() {
    Column() {
      Text(this.text)
        .width('50%')
        .height(60)
        .fontSize(16)
        .borderRadius(10)
        .textAlign(TextAlign.Center)
        .backgroundColor(Color.Yellow)
    }
  }
  build() {
    Column() {
      Text('There are three Text elements here')
        .fontSize(12)
        .fontColor(0xCCCCCC)
        .width('90%')
        .textAlign(TextAlign.Start)
        .margin(5)
      Row({ space: 15 }) {
        ForEach(this.dragList, (item, index) => {
          Text(item)
            .textStyle()
            .visibility(this.fruitVisible[index])
            .onDragStart(() => {
              this.bool = true
              this.text = item
              this.fruitVisible[index] = Visibility.None
              return this.pixelMapBuilder
            })
            .onTouch((event: TouchEvent) => {
              if (event.type === TouchType.Down) {
                this.eventType = 'Down'
                this.index = index
              }
              if (event.type === TouchType.Up) {
                this.eventType = 'Up'
                if (this.bool) {
                  this.fruitVisible[index] = Visibility.Visible
                }
              }
            })
        })
      }.padding({ top: 10, bottom: 10 }).margin(10)
      Text('This is a List element')
        .fontSize(12)
        .fontColor(0xCCCCCC)
        .width('90%')
        .textAlign(TextAlign.Start)
        .margin(15)
      List({ space: 20 }) {
        ForEach(this.numbers, (item) => {
          ListItem() {
            Text(item)
              .width('100%')
              .height(80)
              .fontSize(16)
              .borderRadius(10)
              .textAlign(TextAlign.Center)
              .backgroundColor(0xAFEEEE)
          }
        }, item => item)
      }
      .editMode(true)
      .height('50%')
      .width('90%')
      .border({ width: 1 })
      .padding(15)
      .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 })
      .onDragEnter((event: DragEvent, extraParams: string) => {
        console.log('List onDragEnter, ' + extraParams + 'X:' + event.getX() + 'Y:' + event.getY())
      })
      .onDragMove((event: DragEvent, extraParams: string) => {
        console.log('List onDragMove, ' + extraParams + 'X:' + event.getX() + 'Y:' + event.getY())
      })
      .onDragLeave((event: DragEvent, extraParams: string) => {
        console.log('List onDragLeave, ' + extraParams + 'X:' + event.getX() + 'Y:' + event.getY())
      })
      .onDrop((event: DragEvent, extraParams: string) => {
        let jsonString = JSON.parse(extraParams);
        if (this.bool) {
          // 通过splice方法插入元素
          this.numbers.splice(jsonString.insertIndex, 0, this.text)
          this.bool = false
        }
        this.fruitVisible[this.index] = Visibility.None
      })
    }.width('100%').height('100%').padding({ top: 20 }).margin({ top: 20 })
  }
}




















