键鼠事件指键盘,鼠标外接设备的输入事件。
鼠标事件
支持的鼠标事件包含通过外设鼠标、触控板触发的事件。
鼠标事件可触发以下回调:
名称 | 描述 |
---|---|
onHover(event: (isHover: boolean) => void) | 鼠标进入或退出组件时触发该回调。 isHover:表示鼠标是否悬浮在组件上,鼠标进入时为true, 退出时为false。 |
onMouse(event: (event?: MouseEvent) => void) | 当前组件被鼠标按键点击时或者鼠标在组件上悬浮移动时,触发该回调,event返回值包含触发事件时的时间戳、鼠标按键、动作、鼠标位置在整个屏幕上的坐标和相对于当前组件的坐标。 |
当组件绑定onHover回调时,可以通过 hoverEffect 属性设置该组件的鼠标悬浮态显示效果。
图1 鼠标事件数据流
鼠标事件传递到ArkUI之后,会先判断鼠标事件是否是左键的按下/抬起/移动,然后做出不同响应:
-
是:鼠标事件先转换成相同位置的触摸事件,执行触摸事件的碰撞测试、手势判断和回调响应。接着去执行鼠标事件的碰撞测试和回调响应。
-
否:事件仅用于执行鼠标事件的碰撞测试和回调响应。
说明
所有单指可响应的触摸事件/手势事件,均可通过鼠标左键来操作和响应。例如当我们需要开发单击Button跳转页面的功能、且需要支持手指点击和鼠标左键点击,那么只绑定一个点击事件(onClick)就可以实现该效果。若需要针对手指和鼠标左键的点击实现不一样的效果,可以在onClick回调中,使用回调参数中的source字段即可判断出当前触发事件的来源是手指还是鼠标。
onHover
onHover(event: (isHover: boolean) => void)
鼠标悬浮事件回调。参数isHover类型为boolean,表示鼠标进入组件或离开组件。该事件不支持自定义冒泡设置,默认父子冒泡。
若组件绑定了该接口,当鼠标指针从组件外部进入到该组件的瞬间会触发事件回调,参数isHover等于true;鼠标指针离开组件的瞬间也会触发该事件回调,参数isHover等于false。
说明
事件冒泡:在一个树形结构中,当子节点处理完一个事件后,再将该事件交给它的父节点处理。
// xxx.ets
@Entry
@Component
struct MouseExample {
@State hoverText: string = 'Not Hover';
@State Color: Color = Color.Gray;
build() {
Column() {
Button(this.hoverText)
.width(200).height(100)
.backgroundColor(this.Color)
.onHover((isHover?: boolean) => { // 使用onHover接口监听鼠标是否悬浮在Button组件上
if (isHover) {
this.hoverText = 'Hovered!';
this.Color = Color.Green;
}
else {
this.hoverText = 'Not Hover';
this.Color = Color.Gray;
}
})
}.width('100%').height('100%').justifyContent(FlexAlign.Center)
}
}
该示例创建了一个Button组件,初始背景色为灰色,内容为“Not Hover”。示例中的Button组件绑定了onHover回调,在该回调中将this.isHovered变量置为回调参数:isHover。
当鼠标从Button外移动到Button内的瞬间,回调响应,isHover值等于true,isHovered的值变为true,将组件的背景色改成Color.Green,内容变为“Hovered!”。
当鼠标从Button内移动到Button外的瞬间,回调响应,isHover值等于false,又将组件变成了初始的样式。
onMouse
onMouse(event: (event?: MouseEvent) => void)
鼠标事件回调。绑定该API的组件每当鼠标指针在该组件内产生行为(MouseAction)时,触发事件回调,参数为 MouseEvent 对象,表示触发此次的鼠标事件。该事件支持自定义冒泡设置,默认父子冒泡。常用于开发者自定义的鼠标行为逻辑处理。
开发者可以通过回调中的MouseEvent对象获取触发事件的坐标(displayX/displayY/windowX/windowY/x/y)、按键( MouseButton )、行为( MouseAction )、时间戳(timestamp)、交互组件的区域( EventTarget )、事件来源( SourceType )等。MouseEvent的回调函数stopPropagation用于设置当前事件是否阻止冒泡。
说明
按键(MouseButton)的值:Left/Right/Middle/Back/Forward 均对应鼠标上的实体按键,当这些按键被按下或松开时触发这些按键的事件。None表示无按键,会出现在鼠标没有按键按下或松开的状态下,移动鼠标所触发的事件中。
// xxx.ets
@Entry
@Component
struct MouseExample {
@State buttonText: string = '';
@State columnText: string = '';
@State hoverText: string = 'Not Hover';
@State Color: Color = Color.Gray;
build() {
Column() {
Button(this.hoverText)
.width(200)
.height(100)
.backgroundColor(this.Color)
.onHover((isHover?: boolean) => {
if (isHover) {
this.hoverText = 'Hovered!';
this.Color &