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)
设置边框样式。

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 })

设置组件背景。

透明度设置

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)

设置组件的堆叠顺序。

图形变换

图像效果

形状裁剪

颜色渐变

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)

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

文本通用

安全区域

安全区域是指页面的显示区域，默认不与系统设置的非安全区域比如状态栏、导航栏区域重叠，默认情况下开发者开发的界面都被布局在安全区域内。提供属性方法允许开发者设置组件绘制内容突破安全区域的限制，通过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%')
  }
}

手势处理

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

绑定手势识别相关属性

GestureType枚举值

GestureMask枚举值

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对象属性

SourceType枚举值⁸⁺

FingerInfo对象属性⁸⁺

SourceTool枚举值⁹⁺