ArkTS组件的三个通用（通用事件、通用属性、通用手势）

---

可以先有个印象，具体使用可以查接口文档

通用事件

点击事件 onClick

组件被点击时触发的事件。
displayX、displayY 相对于屏幕左上角和x或y坐标

触摸事件 onTouch

当手指在组件上按下、滑动、抬起时触发。

挂载、卸载事件

挂载卸载事件指组件从组件树上挂载、卸载时触发的事件。
onAttach12+
onDetach12+
onAppear
onDisAppear

// xxx.ets
import { promptAction } from '@kit.ArkUI'@Entry
@Component
struct AppearExample {@State isShow: boolean = true@State changeAppear: string = '点我卸载挂载组件'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).onAttach(() => {promptAction.showToast({message: 'The text is shown',duration: 2000,bottom: 500})}).onDetach(() => {promptAction.showToast({message: 'The text is hidden',duration: 2000,bottom: 500})})}}.padding(30).width('100%')}
}

拖拽事件

拖拽事件指组件被长按后拖拽时触发的事件。

按键事件 onKeyEvent

按键事件指组件与键盘、遥控器等按键设备交互时触发的事件，适用于所有可获焦组件，例如Button。对于Text，Image等默认不可获焦的组件，可以设置focusable属性为true后使用按键事件。

焦点事件

焦点事件指页面焦点在可获焦组件间移动时触发的事件，组件可使用焦点事件来处理相关逻辑。
仅支持通过外接键盘的tab键、方向键触发。

鼠标事件

在鼠标的单个动作触发多个事件时，事件的顺序是固定的，鼠标事件默认透传。
目前仅支持通过外接鼠标触发。

悬浮事件

光标滑动，或者手写笔在屏幕上悬浮移动扫过组件时触发。
目前支持通过外接鼠标、手写笔以及触控板触发。

组件区域变化事件 onAreaChange

组件区域变化事件指组件显示的尺寸、位置等发生变化时触发的事件。

组件尺寸变化事件

该事件指组件显示的尺寸发生变化时触发的事件。
API Version 12开始支持

组件可见区域变化事件

组件可见区域变化事件是组件在屏幕中的显示区域面积变化时触发的事件，提供了判断组件是否完全或部分显示在屏幕中的能力，适用于广告曝光埋点之类的场景。

组件快捷键事件

开发者可以设置组件的自定义组合键，每个组件可以设置多个组合键。

自定义事件分发

ArkUI在处理触屏事件时，会在触屏事件触发前进行按压点和组件区域的触摸测试，来收集需要响应触屏事件的组件，再基于触摸测试结果分发相应的触屏事件。

自定义事件拦截

为组件提供自定义的事件拦截能力，开发者可根据事件在控件上按下时发生的位置，输入源等事件信息决定控件上的HitTestMode属性。

通用属性

尺寸设置

layoutWeight(value: number | string)

设置组件的布局权重，使用该属性的组件在父容器（Row/Column/Flex）的主轴方向按照权重分配尺寸。

位置设置

align(value: Alignment)
设置容器元素绘制区域内的子元素的对齐方式。

direction(value: Direction)
设置容器元素内主轴方向上的布局。position(value: Position | Edges | LocalizedEdges)
绝对定位，确定子组件相对父组件的位置。

offset(value: Position | Edges | LocalizedEdges)
相对偏移，组件相对原本的布局位置进行偏移

alignRules(value: AlignRuleOption)
指定设置在相对容器中子组件的对齐规则，仅当父容器为RelativeContainer时生效。

布局约束

aspectRatio(value: number)

指定当前组件的宽高比，aspectRatio=width/height。

仅设置width、aspectRatio时，height=width/aspectRatio。
仅设置height、aspectRatio时，width=height*aspectRatio。
同时设置width、height和aspectRatio时，height不生效，height=width/aspectRatio。
设置aspectRatio属性后，组件宽高会受父组件内容区大小限制。

边框设置

border(value: BorderOptions)
设置边框样式。

名称	参数类型	必填	描述
width	Length | EdgeWidths9+ | LocalizedEdgeWidths12+	否	设置边框宽度
color	ResourceColor | EdgeColors9+ | LocalizedEdgeColors12+	否	设置边框颜色
radius	Length | BorderRadiuses9+ | LocalizedBorderRadiuses12+	否	设置边框圆角半径
style	BorderStyle | EdgeStyles9+	否	设置边框样式
dashGap12+	LengthMetrics | EdgeWidths | LocalizedEdgeWidths	否	设置虚线的线段间距，仅在边框样式为虚线时生效。不支持设置百分比
dashWidth12+	LengthMetrics | EdgeWidths | LocalizedEdgeWidths	否	设置虚线的线段长度，仅在边框样式为虚线时生效。不支持设置百分比

borderImage(value: BorderImageOption)

设置组件的图片边框。

// xxx.ets
@Entry
@Component
struct Index {build() {Row() {Column() {Text('This is gradient color.').textAlign(TextAlign.Center).height(50).width(200).borderImage({source: {angle: 90,direction: GradientDirection.Left,colors: [[0xAEE1E1, 0.0], [0xD3E0DC, 0.3], [0xFCD1D1, 1.0]]},slice: { top: 10, bottom: 10, left: 10, right: 10 },width: { top: "10px", bottom: "10px", left: "10px", right: "10px" },repeat: RepeatMode.Stretch,fill: false})}.width('100%')}.height('100%')}
}

背景设置

background(builder: CustomBuilder, options?: { align?: Alignment })

设置组件背景。

属性	类型	描述
backgroundColor	ResourceColor	设置组件的背景颜色。
backgroundImage	Resource	设置组件的背景图片。支持的图片格式有jpg、jpeg、png、bmp、webp、svg。
backgroundSize	Size | BackgroundSize	设置背景图片的尺寸。当值为Size类型时，用于指定背景图片的宽度和高度；当值为BackgroundSize类型时，包含auto（默认值，保持图片原始尺寸）、cover（图片等比例缩放，以完全覆盖容器，可能会裁剪部分图片）、contain（图片等比例缩放，以完全包含在容器内，可能会有空白区域）。
backgroundRepeat	RepeatMode	设置背景图片的重复方式。取值包括repeat（默认值，在水平和垂直方向重复平铺图片）、repeat-x（仅在水平方向重复平铺图片）、repeat-y（仅在垂直方向重复平铺图片）、no-repeat（不重复平铺图片）。
backgroundPosition	Position	设置背景图片的位置。可通过指定left、right、top、bottom、center等关键字组合，或者直接指定具体的长度值来确定背景图片在组件内的位置。
backgroundClip	ClipMode	设置背景的裁剪区域。取值有border-box（默认值，背景绘制到边框边缘）、padding-box（背景绘制到内边距边缘）、content-box（背景绘制到内容边缘）。

透明度设置

opacity(value: number | Resource)

设置组件的不透明度。

显隐控制

visibility(value: Visibility)

控制组件的显隐。

禁用控制

enabled(value: boolean)

设置组件是否可交互。

浮层

overlay(value: string | CustomBuilder | ComponentContent, options?: OverlayOptions )

在当前组件上，增加遮罩文本或者叠加自定义组件以及ComponentContent作为该组件的浮层。浮层不通过组件树进行渲染，部分接口（例如getRectangleById）不支持获取浮层中的组件。

// xxx.ets
@Entry
@Component
struct OverlayExample {build() {Column() {Column() {Text('floating layer').fontSize(12).fontColor(0xCCCCCC).maxLines(1)Column() {Image($r('app.media.img')).width(240).height(240).overlay("Winter is a beautiful season, especially when it snows.", {align: Alignment.Bottom,offset: { x: 0, y: -15 }})}.border({ color: Color.Black, width: 2 })}.width('100%')}.padding({ top: 20 })}
}

Z序控制

zIndex(value: number)

设置组件的堆叠顺序。

图形变换

序号	标题	总结
1	rotate方法	设置组件旋转，参数包括旋转轴、角度、中心点等，从API Version 7开始支持，特定版本用于卡片、元服务，通过示例展示用法
2	translate方法	设置组件平移，参数为偏移量，有相关版本支持和示例，可实现组件位置移动
3	scale方法	设置组件缩放，参数含缩放比例、中心点等，有版本及场景支持说明，示例展示缩放效果
4	transform方法	设置组件变换矩阵，可综合多种变换，介绍了参数、支持情况，示例展示复杂变换应用

图像效果

形状裁剪

颜色渐变

Popup控制、菜单控制

给组件绑定popup弹窗，并设置弹窗内容，交互逻辑和显示状态。
为组件绑定弹出式菜单，弹出式菜单以垂直列表形式显示菜单项，可通过长按、点击或鼠标右键触发。

复用标识

reuseId用于标记自定义组件复用组，当组件回收复用时，复用框架将根据组件的reuseId来划分组件的复用组。

多态样式

设置组件不同状态下的样式。多态样式仅支持通用属性。
从API Version 11开始支持另一种写法attributeModifier，可根据开发者需要动态设置属性。

动态属性设置

attributeModifier(modifier: AttributeModifier)

动态设置组件的属性方法。

// xxx.ets
class MyButtonModifier implements AttributeModifier<ButtonAttribute> {applyNormalAttribute(instance: ButtonAttribute): void {instance.backgroundColor(Color.Black)}applyPressedAttribute(instance: ButtonAttribute): void {instance.backgroundColor(Color.Red)}
}@Entry
@Component
struct attributePressedDemo {@State modifier: MyButtonModifier = new MyButtonModifier()build() {Row() {Column() {Button("Button").attributeModifier(this.modifier)}.width('100%')}.height('100%')}
}

点击回弹效果

clickEffect(value: ClickEffect | null)

设置当前组件点击回弹效果。

外描边设置

outline(value: OutlineOptions)

统一外描边样式设置接口。

模态转场设置–全屏模态转场

bindContentCover(isShow: Optional, builder: CustomBuilder, options?: ContentCoverOptions)

给组件绑定全屏模态页面，点击后显示模态页面。模态页面内容自定义，显示方式可设置无动画过渡，上下切换过渡以及透明渐变过渡方式。

模态转场设置–半模态转场

bindSheet
bindSheet(isShow: Optional, builder: CustomBuilder, options?: SheetOptions)

给组件绑定半模态页面，点击后显示模态页面。

文本通用

属性	描述
fontColor	设置字体颜色，参数value类型为ResourceColor，必填，从API Version 7开始支持，卡片能力从API version 9开始支持，原子化服务API从API version 11开始支持
fontSize	设置字体大小，参数value类型为`Resource
fontStyle	设置字体样式，参数value类型为FontStyle，必填，默认值为FontStyle.Normal。从API Version 7开始支持，卡片能力从API version 9开始支持，原子化服务API从API version 11开始支持
fontWeight	设置文本的字体粗细，设置过大可能会在不同字体下有截断。参数value类型为`FontWeight
fontFamily	设置字体列表，参数value类型为`Resource
lineHeight	设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小。参数value类型为`Resource
decoration	设置文本装饰线样式及其颜色，参数value类型为DecorationStyleInterface，必填，默认值为{type: TextDecorationType.None, color: Color.Black, style: TextDecorationStyle.SOLID} ，style参数不支持卡片能力。从API Version 7开始支持，卡片能力从API version 9开始支持，原子化服务API从API version 11开始支持

安全区域

安全区域是指页面的显示区域，默认不与系统设置的非安全区域比如状态栏、导航栏区域重叠，默认情况下开发者开发的界面都被布局在安全区域内。提供属性方法允许开发者设置组件绘制内容突破安全区域的限制，通过expandSafeArea属性支持组件不改变布局情况下扩展其绘制区域至安全区外，通过设置setKeyboardAvoidMode来配置虚拟键盘弹出时页面的避让模式。页面中有标题栏等文字不希望和非安全区重叠时，建议对组件设置expandSafeArea属性达到沉浸式效果，也可以直接通过窗口接口setWindowLayoutFullScreen设置沉浸式。

expandSafeArea(types?: Array, edges?: Array)

控制组件扩展其安全区域。

// xxx.ets
@Entry
@Component
struct SafeAreaExample1 {@State text: string = ''controller: TextInputController = new TextInputController()build() {Row() {Column().height('100%').width('100%').backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover).expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])}.height('100%')}
}

手势处理

绑定手势方法
为组件绑定不同类型的手势事件，并设置事件的响应方法。

绑定手势识别相关属性

名称	参数类型	默认值	描述
gesture	gesture: GestureType, mask?: GestureMask	gesture: -，mask: GestureMask.Normal	绑定手势。其中gesture为绑定的手势类型，mask为事件响应设置
priorityGesture	gesture: GestureType, mask?: GestureMask	gesture: -，mask: GestureMask.Normal	绑定优先识别手势。gesture是绑定的手势类型，mask是事件响应设置。默认子组件优先识别gesture绑定的手势，父组件配置priorityGesture时，父组件优先识别其绑定的手势；长按手势时，触发长按最短时间小的组件优先响应，忽略priorityGesture设置
parallelGesture	gesture: GestureType, mask?: GestureMask	gesture: -，mask: GestureMask.Normal	绑定可与子组件手势同时触发的手势。gesture为绑定的手势类型，mask为事件响应设置。手势事件为非冒泡事件，父组件设置parallelGesture时，父子组件相同手势事件都可触发，类似冒泡效果

GestureType枚举值

名称	描述
TapGesture	点击手势，支持单次点击、多次点击识别
LongPressGesture	长按手势
PanGesture	平移手势，滑动最小距离为5vp时识别成功
PinchGesture	捏合手势
RotationGesture	旋转手势
SwipeGesture	滑动手势，滑动最小速度为100vp/s时识别成功
GestureGroup	手势识别组，多种手势组合为复合手势，支持连续识别、并行识别和互斥识别

GestureMask枚举值

名称	描述
Normal	不屏蔽子组件的手势，按照默认手势识别顺序进行识别
IgnoreInternal	屏蔽子组件的手势，包括子组件上系统内置的手势（如子组件为List组件时，内置的滑动手势同样会被屏蔽）。若父子组件区域存在部分重叠，则只会屏蔽父子组件重叠的部分

TapGesture事件

名称	功能描述
onAction((event:GestureEvent) => void)	Tap手势识别成功回调

// xxx.ets
@Entry
@Component
struct TapGestureExample {@State value: string = ''build() {Column() {// 单指双击文本触发手势事件Text('Click twice').fontSize(28).gesture(TapGesture({ count: 2 }).onAction((event: GestureEvent) => {if (event) {this.value = JSON.stringify(event.fingerList[0])}}))Text(this.value)}.height(200).width(300).padding(20).border({ width: 3 }).margin(30)}
}

GestureEvent对象属性

名称	类型	描述
repeat	boolean	是否为重复触发事件，用于LongPressGesture手势触发场景
offsetX	number	手势事件偏移量X，单位为vp，用于PanGesture手势触发场景，从左向右滑动offsetX为正，反之为负
offsetY	number	手势事件偏移量Y，单位为vp，用于PanGesture手势触发场景，从上向下滑动offsetY为正，反之为负
angle	number	用于RotationGesture手势触发场景时，表示旋转角度；用于SwipeGesture手势触发场景时，表示滑动手势的角度，即两根手指间的线段与水平方向的夹角变化的度数。角度计算方式：滑动手势被识别到后，连接两根手指之间的线被识别为起始线条，随着手指的滑动，手指之间的线条会发生旋转，根据起始线条两端点和当前线条两端点的坐标，使用反正切函数分别计算其相对于水平方向的夹角，最后arctan2(cy2 - cy1,cx2 - cx1)-arctan2(y2 - y1,x2 - x1)为旋转的角度。以起始线条为坐标系，顺时针旋转为0到180度，逆时针旋转为 - 180到0度
scale	number	缩放比例，用于PinchGesture手势触发场景，取值范围：[0, +∞)
pinchCenterX	number	捏合手势中心点的x轴坐标，单位为vp，用于PinchGesture手势触发场景，取值范围：[0, +∞)
pinchCenterY	number	捏合手势中心点的y轴坐标，单位为vp，用于PinchGesture手势触发场景，取值范围：[0, +∞)
speed8+	number	滑动手势速度，即所有手指相对当前组件元素原始区域滑动的平均速度，单位为vp/秒，用于SwipeGesture手势触发场景，取值范围：[0, +∞)
fingerList8+	FingerInfo []	输入源为触屏产生的手势，fingerList中会包含触发事件的所有触点信息；由鼠标发起的手势，fingerList中只会有一条记录；触摸板的事件大类与鼠标一致，所以由触摸板发起的手势，fingerList只会携带一条记录。手指索引编号与位置对应，即fingerList[index]的id为index。先按下且未参与当前手势触发的手指在fingerList中对应位置为空
velocityX10+	number	用于PanGesture手势中，获取当前手势的x轴方向速度。坐标轴原点为屏幕左上角，分正负方向速度，从左往右为正，反之为负。单位为vp/s
velocityY10+	number	用于PanGesture手势中，获取当前手势的y轴方向速度。坐标轴原点为屏幕左上角，分正负方向速度，从上往下为正，反之为负。单位为vp/s
velocity10+	number	用于PanGesture手势中，获取当前手势的主方向速度。为xy轴方向速度的平方和的算术平方根。单位为vp/s

SourceType枚举值⁸⁺

名称	描述
Unknown	未知设备
Mouse	鼠标
TouchScreen	触摸屏

FingerInfo对象属性⁸⁺

名称	类型	描述
id	number	手指的索引编号，取值范围：[0, +∞)
globalX	number	相对于应用窗口左上角的x轴坐标，单位为vp，取值范围：[0, +∞)
globalY	number	相对于应用窗口左上角的y轴坐标，单位为vp，取值范围：[0, +∞)
localX	number	相对于当前组件元素原始区域左上角的x轴坐标，单位为vp，取值范围：[0, +∞)
localY	number	相对于当前组件元素原始区域左上角的y轴坐标，单位为vp，取值范围：[0, +∞)
displayX12+	number	相对于屏幕左上角的x轴坐标，单位为vp，取值范围：[0, +∞)
displayY12+	number	相对于屏幕左上角的y轴坐标，单位为vp，取值范围：[0, +∞)

SourceTool枚举值⁹⁺

名称	描述
Unknown	未知输入源
Finger	手指输入
Pen	手写笔输入
Mouse12+	鼠标输入
Touchpad12+	触控板输入。触控板单指输入被视为鼠标输入操作
Joystick12+	手柄输入

---