触摸热区设置
设置组件的响应热区。在ArkUI开发框架中,处理触屏事件和鼠标事件时,会在事件触发前进行按压点与组件响应热区的触摸测试,以收集需响应事件的组件。基于测试结果,框架会分发相应的事件。影响点击事件、触摸事件、拖拽事件、鼠标事件、轴事件、悬浮事件、无障碍悬浮事件和手势事件的分发。
说明:
本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
设置触摸热区属性时,手指需在热区内按下,随后抬起时若满足事件响应条件,事件将被触发。此外,在当前手势结束前,若条件满足,可持续触发的事件也会被激活。
responseRegion
responseRegion(value: Array<Rectangle> | Rectangle): T
设置一个或多个触摸热区。从API版本26.0.0开始,未主动设置时Button、Button模式的Toggle、Select、Chip和ChipGroup组件的触摸热区默认最小高度从28vp变更为32vp。该变更仅影响触摸命中范围,不影响组件实际显示高度。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | Array<Rectangle> | Rectangle | 是 | 触摸热区,包括位置和大小。 默认触摸热区为整个组件,默认值: { x:0, y:0, width:'100%', height:'100%' } |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件。 |
mouseResponseRegion10+
mouseResponseRegion(value: Array<Rectangle> | Rectangle): T
设置一个或多个鼠标触摸热区。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | Array<Rectangle> | Rectangle | 是 | 鼠标触摸热区,包括位置和大小。 默认触摸热区为整个组件,默认值: { x:0, y:0, width:'100%', height:'100%' } |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件。 |
responseRegionList22+
responseRegionList(regions: Array<ResponseRegion>): T
设置组件的触摸热区列表。调用该接口时,responseRegion与mouseResponseRegion接口不再生效。
原子化服务API: 从API version 22开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| regions | Array<ResponseRegion> | 是 | 组件的触摸热区数组。 每个触摸热区均包括输入工具类型、位置和大小。 默认值: [{ tool:ResponseRegionSupportedTool.ALL, x:LengthMetrics.vp(0), y:LengthMetrics.vp(0), width:LengthMetrics.percent(1), height:LengthMetrics.percent(1) }] |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件。 |
Rectangle对象说明
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| x | Length | 否 | 是 | 触摸点相对于组件左上角的x轴坐标。 默认值:0vp |
| y | Length | 否 | 是 | 触摸点相对于组件左上角的y轴坐标。 默认值:0vp |
| width | Length | 否 | 是 | 触摸热区的宽度。 默认值:'100%' |
| height | Length | 否 | 是 | 触摸热区的高度。 默认值:'100%' |
说明:
x和y可以设置正负值百分比。当x设置为'100%'时表示热区往右偏移组件本身宽度大小,当x设置为'-100%'时表示热区往左偏移组件本身宽度大小。当y设置为'100%'时表示热区往下偏移组件本身高度大小,当y设置为'-100%'时表示热区往上偏移组件本身高度大小。
width和height设置百分比时,只能设置正值百分比。width:'100%'表示热区宽度设置为该组件本身的宽度。比如组件本身宽度是100vp,那么'100%'表示热区宽度也为100vp。height:'100%'表示热区高度设置为该组件本身的高度。
百分比相对于组件自身宽高进行计算。
当父组件设置clip(true)时,子组件的响应会受到父组件触摸热区的影响,不在父组件触摸热区内的子组件无法响应手势和事件。
width和height不支持calc()的动态计算。
ResponseRegion22+对象说明
由输入工具类型、触摸位置和大小组成的触摸热区。
说明:
当父组件设置clip为true时,子组件的响应会受到父组件触摸热区的影响,不在父组件触摸热区内的子组件无法响应手势和事件。
如果触摸热区未配置输入工具类型,触摸位置和大小均采用默认值。
x和y的计算结果为正值时,分别代表向右偏移和向下偏移;当计算结果为负值时,分别代表向左偏移和向上偏移。
width和height采用string类型时,string需采用小写字符否则不生效,支持calc()的动态计算。指定calc()的入参字符串格式为'宽高缩放比例 ± 宽高增量',宽高缩放比例为百分比,宽高增量单位为px或vp。例如'calc(80% + 10vp)'中,80%为宽高缩放比例、10vp为宽高增量。width和height采用LengthMetrics类型且单位为percent时,相对于组件自身宽高进行计算,percent(1)代表100%。当计算结果为负值时,采用默认值。
原子化服务API: 从API version 22开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| tool | ResponseRegionSupportedTool | 否 | 是 | 触摸热区适用的输入工具类型。 默认值:ResponseRegionSupportedTool.ALL |
| x | LengthMetrics | 否 | 是 | 触摸点相对于组件左上角的x轴坐标。 默认值:LengthMetrics.vp(0) |
| y | LengthMetrics | 否 | 是 | 触摸点相对于组件左上角的y轴坐标。 默认值:LengthMetrics.vp(0) |
| width | LengthMetrics | string | 否 | 是 | 触摸热区的宽度。 默认值:LengthMetrics.percent(1) |
| height | LengthMetrics | string | 否 | 是 | 触摸热区的高度。 默认值:LengthMetrics.percent(1) |
示例
示例1(通过responseRegion接口设置触摸热区)
该示例通过responseRegion设置按钮的触摸热区以响应点击事件。
// xxx.ets
@Entry
@Component
struct TouchTargetExample {
@State text: string = "";
build() {
Column({ space: 20 }) {
Text("{x:0,y:0,width:'50%',height:'100%'}")
// 热区宽度为按钮的一半,点击button1右半部无响应
Button("button1")
.responseRegion({
x: 0,
y: 0,
width: '50%',
height: '100%'
})
.onClick(() => {
this.text = 'button1 clicked'
})
// 为一个组件添加多个热区
Text("[{x:'100%',y:0,width:'50%',height:'100%'}," +
"\n{ x: 0, y: 0, width: '50%', height: '100%' }]")
Button("button2")
.responseRegion([
{
x: '100%',
y: 0,
width: '50%',
height: '100%'
}, // 第一个热区宽度为按钮的一半,且右移一个按钮宽度,点击button2右边按钮宽度一半的区域,点击事件生效
{
x: 0,
y: 0,
width: '50%',
height: '100%'
}// 第二个热区宽度为按钮的一半,点击button2左半部,点击事件生效
])
.onClick(() => {
this.text = 'button2 clicked'
})
// 热区大小为整个按钮,且下移一个按钮高度,点击button3下方按钮大小区域,点击事件生效
Text("{x:0,y:'100%',width:'100%',height:'100%'}")
Button("button3")
.responseRegion({
x: 0,
y: '100%',
width: '100%',
height: '100%'
})
.onClick(() => {
this.text = 'button3 clicked'
})
Text(this.text).margin({ top: 50 })
}.width('100%').margin({ top: 10 })
}
}
[图示请参阅官方原文]
示例2(通过responseRegionList接口设置触摸热区)
该示例通过responseRegionList设置按钮的触摸热区以响应点击事件。
从API version 22开始,新增responseRegionList接口。
// xxx.ets
@Entry
@Component
struct TouchTargetExample {
@State text: string = "";
build() {
Column({ space: 20 }) {
Text("left part of button1")
// 热区宽度为按钮的一半,点击button1右半部无响应
Button("button1")
.responseRegionList([{
x: LengthMetrics.vp(0),
y: LengthMetrics.vp(0),
width: LengthMetrics.percent(0.5),
height: LengthMetrics.percent(1),
}])
.onClick(() => {
this.text = 'button1 clicked'
})
// 热区一的大小为整个按钮,且右移一个按钮宽度,点击button2左边按钮大小区域,点击事件生效
// 热区二的大小为整个按钮,且下移一个按钮高度,鼠标点击button2下方按钮大小区域,点击事件生效
Text("one button size right of button2," + "\n one button size below button2")
Button("button2")
.responseRegionList([{
x: LengthMetrics.percent(1),
y: LengthMetrics.vp(0),
width: LengthMetrics.percent(1),
height: LengthMetrics.percent(1),
}, {
tool: ResponseRegionSupportedTool.MOUSE,
x: LengthMetrics.vp(0),
y: LengthMetrics.percent(1),
width: 'calc(100% + 0vp)',
height: 'calc(100% - 0px)',
}])
.onClick(() => {
this.text = 'button2 clicked'
})
Text(this.text).margin({ top: 50 })
}.width('100%').margin({ top: 10 })
}
}
[图示请参阅官方原文]
示例3(设置鼠标的触摸热区以响应点击事件)
该示例通过mouseResponseRegion设置鼠标的触摸热区以响应点击事件。
// xxx.ets
@Entry
@Component
struct MouseResponseRegionExample {
@State clickInfo: string = '点击热区触发事件';
build() {
Column({ space: 30 }) {
// 示例1:单个热区(仅按钮左半部分响应鼠标点击)
Text('热区:按钮左半区域(点击左半才触发)')
.fontSize(14)
Button('Button1(左半热区)')
.width(200)
.height(60)
// 鼠标热区:仅按钮左半部分(x/y相对组件自身,宽度50%)
.mouseResponseRegion({
// 热区相对组件的X坐标(左上角为原点)
x: 0,
// 热区相对组件的Y坐标
y: 0,
// 热区宽度(按钮的50%)
width: '50%',
// 热区高度(按钮的100%)
height: '100%'
})
.onClick(() => {
this.clickInfo = 'Button1 左半热区被点击';
})
// 示例2:多个热区(按钮左半 + 按钮下方区域都响应)
Text('热区:按钮左半 + 按钮下方区域(点击两处都触发)')
.fontSize(14)
Button('Button2(多热区)')
.width(200)
.height(60)
// 鼠标热区:数组形式,包含2个独立热区
.mouseResponseRegion([
// 热区1:按钮左半部分
{
x: 0,
y: 0,
width: '50%',
height: '100%'
},
// 热区2:按钮正下方区域(y=100%表示按钮底部,高度60vp)
{
x: 0,
y: '100%',
width: '100%',
height: 60
}
])
.onClick(() => {
this.clickInfo = 'Button2 任一热区被点击';
})
// 示例3:热区在按钮外部(按钮右侧空白处响应)
Text('热区:按钮右侧外部(点击按钮右边空白处触发)')
.fontSize(14)
Button('Button3(右侧外热区)')
.width(200)
.height(60)
// 鼠标热区:按钮右侧外部区域(x=100%表示按钮右边缘)
.mouseResponseRegion({
// 热区X坐标:按钮右边缘
x: '100%',
y: 0,
// 热区宽度80vp
width: 80,
height: '100%'
})
.onClick(() => {
this.clickInfo = 'Button3 右侧外热区被点击';
})
// 显示点击结果
Text(this.clickInfo)
.fontSize(16)
.margin({ top: 20 })
}
.width('100%')
.height('100%')
// 整体居中显示
.justifyContent(FlexAlign.Center)
}
}
[图示请参阅官方原文]
本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
