---

可以先有個印象，具體使用可以查接口文檔

通用事件

點擊事件 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+	手柄輸入

---