基础说明
.1、应用模型
.1.1、构成要素
- 应用组件
应用组件是应用的基本组成单位，是应用的运行入口。用户启动、使用和退出应用过程中，应用组件会在不同的状态间切换，这些状态称为应用组件的生命周期。应用组件提供生命周期的回调函数，开发者通过应用组件的生命周期回调感知应用的状态变化。应用开发者在编写应用时，首先需要编写的就是应用组件，同时还需编写应用组件的生命周期回调函数，并在应用配置文件中配置相关信息。这样，操作系统在运行期间通过配置文件创建应用组件的实例，并调度它的生命周期回调函数，从而执行开发者的代码。 - 应用进程模型
应用进程模型定义应用进程的创建和销毁方式，以及进程间的通信方式。 - 应用线程模型
应用线程模型定义应用进程内线程的创建和销毁方式、主线程和UI线程的创建方式、线程间的通信方式。 - 应用任务管理模型
应用任务管理模型定义任务（Mission）的创建和销毁方式，以及任务与组件间的关系。HarmonyOS应用任务管理由系统应用负责，三方应用无需关注，下文不做具体介绍。 - 应用配置文件
应用配置文件中包含应用配置信息、应用组件信息、权限信息、开发者自定义信息等，这些信息在编译构建、分发和运行阶段分别提供给编译工具、应用市场和操作系统使用。
.1.2、应用模型分类
https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/stage-model-development-overview-0000001427744552-V3
- FA（Feature Ability）模型：HarmonyOS早期版本开始支持的模型，已经不再主推。
- Stage模型：HarmonyOS 3.1 Developer Preview版本开始新增的模型，是目前主推且会长期演进的模型。在该模型中，由于提供了AbilityStage、WindowStage等类作为应用组件和Window窗口的“舞台”，因此称这种应用模型为Stage模型。
Stage模型与FA模型最大的区别在于： Stage模型中，多个应用组件共享同一个ArkTS引擎实例；而FA模型中，每个应用组件独享一个ArkTS引擎实例。因此在Stage模型中，应用组件之间可以方便的共享对象和状态，同时减少复杂应用运行对内存的占用。Stage模型作为主推的应用模型，开发者通过它能够更加便利地开发出分布式场景下的复杂应用。
.1.3、Module、HAP、HAR、HSP等应用程序包的基础概念
一个应用包含一个或者多个Module，可以在DevEco Studio工程中创建一个或者多个Module
.1.3.1、Module
Module是HarmonyOS应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务配置文件，每一个Module都可以独立进行编译和运行。Module分为“Ability”和“Library”两种类型
.1.3.2、HAP（Harmony Ability Package）
“Ability”类型的Module对应于编译后的HAP。
1、开发者通过DevEco Studio把应用程序编译为一个或者多个.hap后缀的文件，即HAP。HAP是HarmonyOS应用安装的基本单位，包含了编译后的代码、资源、三方库及配置文件。HAP可分为Entry和Feature两种类型。
- Entry类型的HAP：是应用的主模块，在module.json5配置文件中的type标签配置为“entry”类型。在同一个应用中，同一设备类型只支持一个Entry类型的HAP，通常用于实现应用的入口界面、入口图标、主特性功能等。
- Feature类型的HAP：是应用的动态特性模块，在module.json5配置文件中的type标签配置为“feature”类型。一个应用程序包可以包含一个或多个Feature类型的HAP，也可以不包含；Feature类型的HAP通常用于实现应用的特性功能，可以配置成按需下载安装，也可以配置成随Entry类型的HAP一起下载安装（请参见module对象内部结构中的“deliveryWithInstall”）。
2、每个HarmonyOS应用可以包含多个.hap文件，一个应用中的.hap文件合在一起称为一个Bundle，而bundleName就是应用的唯一标识（请参见app.json5配置文件中的bundleName标签）。需要特别说明的是：在应用上架到应用市场时，需要把应用包含的所有.hap文件（即Bundle）打包为一个.app后缀的文件用于上架，这个.app文件称为App Pack（Application Package），其中同时包含了描述App Pack属性的pack.info文件；在云端（服务器）分发和终端设备安装时，都是以HAP为单位进行分发和安装的。
3、打包后的HAP包结构包括ets、libs、resources等文件夹和resources.index、module.json、pack.info等文件。
- ets目录用于存放应用代码编译后的字节码文件。
- libs目录用于存放库文件。库文件是HarmonyOS应用依赖的第三方代码（.so二进制文件）。
- resources目录用于存放应用的资源文件（字符串、图片等），便于开发者使用和维护，详见资源分类与访问。
- resources.index是资源索引表，由IDE编译工程时生成。
- module.json是HAP的配置文件，内容由工程配置中的module.json5和app.json5组成，该文件是HAP中必不可少的文件。IDE会自动生成一部分默认配置，开发者按需修改其中的配置。详细字段请参见应用配置文件。
- pack.info是Bundle中用于描述每个HAP属性的文件，例如app中的bundleName和versionCode信息、module中的name、type和abilities等信息，由IDE工具生成Bundle包时自动生成。
.1.3.3、HAR（Harmony Archive）
“Library”类型的Module对应于HAR
.1.3.4、HSP（Harmony Shared Package）
“Library”类型的Module对应于HAR（Harmony Archive），或者HSP（Harmony Shared Package）。
像素单位
.1、基础单位
为开发者提供4种像素单位，框架采用vp为基准数据单位。
PS：个人建议使用lpx，配置好配置文件，这里就可以按照UI设计稿实际的来，可以更好的实现设计效果
| 名称 | 描述 |
|---|---|
| px | 屏幕物理像素单位 |
| vp | 屏幕密度相关像素，根据屏幕像素密度转换为屏幕物理像素，当数值不带单位时，默认单位vp。在实际宽度为1440物理像素的屏幕上，1vp约等于3px。 |
| fp | 字体像素，与vp类似适用屏幕密度变化，随系统字体大小设置变化。 |
| lpx | 视窗逻辑像素单位，lpx单位为实际屏幕宽度与逻辑宽度（通过designWidth配置）的比值，designWidth默认值为720。当designWidth为720时，在实际宽度为1440物理像素的屏幕上，1lpx为2px大小。 |
.2、像素单位转换
提供其他单位与px单位互相转换的方法
| 接口 | 描述 |
|---|---|
| vp2px(value : number) : number | 将vp单位的数值转换为以px为单位的数值 |
| px2vp(value : number) : number | 将px单位的数值转换为以vp为单位的数值 |
| fp2px(value : number) : number | 将fp单位的数值转换为以px为单位的数值 |
| px2fp(value : number) : number | 将px单位的数值转换为以fp为单位的数值 |
| lpx2px(value : number) : number | 将lpx单位的数值转换为以px为单位的数值 |
| px2lpx(value : number) : number | 将px单位的数值转换为以lpx为单位的数值 |
例如：
// xxx.ets
@Entry
@Component
struct Example {
build() {
Column() {
Flex({ wrap: FlexWrap.Wrap }) {
Column() {
Text("width(220)")
.width(220)
.height(40)
.backgroundColor(0xF9CF93)
.textAlign(TextAlign.Center)
.fontColor(Color.White)
.fontSize('12vp')
}.margin(5)
Column() {
Text("width('220px')")
.width('220px')
.height(40)
.backgroundColor(0xF9CF93)
.textAlign(TextAlign.Center)
.fontColor(Color.White)
}.margin(5)
Column() {
Text("width('220vp')")
.width('220vp')
.height(40)
.backgroundColor(0xF9CF93)
.textAlign(TextAlign.Center)
.fontColor(Color.White)
.fontSize('12vp')
}.margin(5)
Column() {
Text("width('220lpx') designWidth:720")
.width('220lpx')
.height(40)
.backgroundColor(0xF9CF93)
.textAlign(TextAlign.Center)
.fontColor(Color.White)
.fontSize('12vp')
}.margin(5)
Column() {
Text("width(vp2px(220) + 'px')")
.width(vp2px(220) + 'px')
.height(40)
.backgroundColor(0xF9CF93)
.textAlign(TextAlign.Center)
.fontColor(Color.White)
.fontSize('12vp')
}.margin(5)
Column() {
Text("fontSize('12fp')")
.width(220)
.height(40)
.backgroundColor(0xF9CF93)
.textAlign(TextAlign.Center)
.fontColor(Color.White)
.fontSize('12fp')
}.margin(5)
Column() {
Text("width(px2vp(220))")
.width(px2vp(220))
.height(40)
.backgroundColor(0xF9CF93)
.textAlign(TextAlign.Center)
.fontColor(Color.White)
.fontSize('12fp')
}.margin(5)
}.width('100%')
}
}
}
系统枚举说明
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-appendix-enums-0000001478061741-V3
太多了，不一一列举了，先浏览一遍，用的时候在查吧。
页面相关
Ability
- Ability是应用所具备能力的抽象，也是应用程序的重要组成部分。一个应用可以具备多种能力（即可以包含多个Ability）
- Ability可以分为FA（Feature Ability）和PA（Particle Ability）两种类型;
- 在配置文件（config.json）中注册Ability时，可以通过配置Ability元素中的“type”属性来指定Ability模板类型，“type”的取值可以为“page”、“service”或“data”，分别代表Page模板、Service模板、Data模板。
Page Ability
其实这个东西和安卓的Activity意义差不多，就是提供一个和用户交互的窗口，而**AbilitySlice**其实就是相当于fragment，一个Page里面可以有多个AbilitySlice就是相当于一个Activity中有多个fragment，都是有独立的生命周期。
- setMainRoute：设置默认展示AbilitySlice
- addActionRoute：添加其他的要展示的AbilitySlice，其中router要在abilities-skills-actions下定义
生命周期
- onStart() 相当于安卓的onCreate(),仅执行一次，且是布局的初始化使用，调用后进入INACTIVE状态；
- onActive()相当于安卓的onResume(),用户重新回到该page时回调；
- onInactive()相当于安卓的onPause(),用户离开该page时调用；
- onBackground()相当于安卓的onSaveInstanceState(),页面进入不可见状态，释放部分无用资源；
- onForeground()相当于安卓的onRestoreInstanceState(),页面准备进入可见状态，部分资源需要重新获取或者初始化；
- onStop()和安卓的名没咋变，功能也一样，页面销毁时调用
原因如下：
1、用户通过系统管理能力关闭指定Page，例如使用任务管理器关闭Page。
2、用户行为触发Page的terminateAbility()方法调用，例如使用应用的退出功能。
3、配置变更导致系统暂时销毁Page并重建。
4、系统出于资源管理目的，自动触发对处于BACKGROUND状态Page的销毁。
页面切换
对应两个slice的生命周期方法回调顺序为：
FooAbilitySlice.onInactive() --> BarAbilitySlice.onStart() --> BarAbilitySlice.onActive() --> FooAbilitySlice.onBackground()
-
AbilitySlice同一page内切换使用present(new TargetSlice(), new Intent())，带返回的页面切换presentForResult(new TargetSlice(), new Intent(), 0)，返回结果由导航目标AbilitySlice在其生命周期内通过setResult()进行设置，接收方通过onResult()接收。（PS：系统为每个Page维护了一个AbilitySlice实例的栈，当开发者在调用present()或presentForResult()时指定的AbilitySlice实例已经在栈中存在时，则栈中位于此实例之上的AbilitySlice均会出栈并终止其生命周期）
-
不同Page间导航，可以使用startAbility()或startAbilityForResult()方法，获得返回结果的回调为onAbilityResult()。在Ability中调用setResult()可以设置返回结
-
跨设备迁移，需要在需要迁移的page中实现IAbilityContinuation接口
1、*onStartContinuation()*：Page请求迁移后，系统首先回调此方法，开发者可以在此回调中决策当前是否可以执行迁移，比如，弹框让用户确认是否开始迁移。 2、*onSaveData()*：如果onStartContinuation()返回true，则系统回调此方法，开发者在此回调中保存必须传递到另外设备上以便恢复Page状态的数据。 3、*onRestoreData()*：源侧设备上Page完成保存数据后，系统在目标侧设备上回调此方法，开发者在此回调中接受用于恢复Page状态的数据。注意，在目标侧设备上的Page会重新启动其生命周期，无论其启动模式如何配置。且系统回调此方法的时机在onStart()之前。 4、onCompleteContinuation()*：目标侧设备上恢复数据一旦完成，系统就会在源侧设备上回调Page的此方法，以便通知应用迁移流程已结束。开发者可以在此检查迁移结果是否成功，并在此处理迁移结束的动作，例如，应用可以在迁移完成后终止自身生命周期。 5、*onRemoteTerminated()*：如果开发者使用continueAbilityReversibly()而不是continueAbility()，则此后可以在源侧设备上使用reverseContinueAbility()进行回迁。这种场景下，相当于同一个Page（的两个实例）同时在两个设备上运行，迁移完成后，如果目标侧设备上Page因任何原因终止，则源侧Page通过此回调接收终止通知。 请求迁移：实现IAbilityContinuation的Page可以在其生命周期内，调用continueAbility()或continueAbilityReversibly()请求迁移。两者的区别是，通过后者发起的迁移此后可以进行回迁。 请求回迁：使用continueAbilityReversibly()请求迁移并完成后，源侧设备上已迁移的Page可以发起回迁，以便使用户活动重新回到此设备。（reverseContinueAbility()）
Service Ability
基于Service模板的Ability（以下简称“Service”）主要用于后台运行任务（如执行音乐播放、文件下载等），但不提供用户交互界面。Service可由其他应用或Ability启动，即使用户切换到其他应用，Service仍将在后台继续运行。
- Service是单实例的。在一个设备上，相同的Service只会存在一个实例
- 如果多个Ability共用这个实例，只有当与Service绑定的所有Ability都退出后，Service才能够退出
- 由于Service是在主线程里执行的，因此，如果在Service里面的操作时间过长，开发者必须在Service里创建新的线程来处理（详见线程间通信），防止造成主线程阻塞，应用程序无响应
生命周期
onStart()
该方法在创建Service的时候调用，用于Service的初始化。在Service的整个生命周期只会调用一次，调用时传入的Intent应为空。
onCommand()
在Service创建完成之后调用，该方法在客户端每次启动该Service时都会调用，用户可以在该方法中做一些调用统计、初始化类的操作。
onConnect()
在Ability和Service连接时调用，该方法返回IRemoteObject对象，用户可以在该回调函数中生成对应Service的IPC通信通道，以便Ability与Service交互。Ability可以多次连接同一个Service，系统会缓存该Service的IPC通信对象，只有第一个客户端连接Service时，系统才会调用Service的onConnect方法来生成IRemoteObject对象，而后系统会将同一个RemoteObject对象传递至其他连接同一个Service的所有客户端，而无需再次调用onConnect方法。
onDisconnect()
在Ability与绑定的Service断开连接时调用。
onStop()
在Service销毁时调用。Service应通过实现此方法来清理任何资源，如关闭线程、注册的侦听器等。
启动
和普通的页面跳转逻辑一致；如果Service尚未运行，则系统会先调用onStart()来初始化Service，再回调Service的onCommand()方法来启动Service。如果Service正在运行，则系统会直接回调Service的onCommand()方法来启动Service。
停止
Service一旦创建就会一直保持在后台运行，除非必须回收内存资源，否则系统不会停止或销毁Service。开发者可以在Service中通过terminateAbility()停止本Service或在其他Ability调用stopAbility()来停止Service。
连接
通过connectAbility() 连接回调，需要传入目标Service的Intent与IAbilityConnection的实例，其中intent的实现和页面跳转的intent设置基本一致。
service中的onConnect()需要返回一个IRemoteObject对象，HarmonyOS提供了IRemoteObject的默认实现，用户可以通过继承LocalRemoteObject来创建自定义的实现类
通用信息
.1、事件
.1.1、点击事件—onClick(event: (event?: ClickEvent) => void)
组件被点击时触发的事件。
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-events-click-0000001477981153-V3
例如：
// xxx.ets
@Entry
@Component
struct ClickExample {
@State text: string = ''
build() {
Column() {
Row({ space: 20 }) {
Button('Click').width(100).height(40)
.onClick((event: ClickEvent) => {
this.text = 'Click Point:' + '\n screenX:' + event.screenX + '\n screenY:' + event.screenY
+ '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:'
+ event.target.area.width + '\n height:' + event.target.area.height + '\ntimestamp' + event.timestamp;
})
Button('Click').width(200).height(50)
.onClick((event: ClickEvent) => {
this.text = 'Click Point:' + '\n screenX:' + event.screenX + '\n screenY:' + event.screenY
+ '\n x:' + event.x + '\n y:' + event.y + '\ntarget:' + '\n component globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\n width:'
+ event.target.area.width + '\n height:' + event.target.area.height + '\ntimestamp' + event.timestamp;
})
}.margin(20)
Text(this.text).margin(15)
}.width('100%')
}
}
.1.2、触摸事件—onTouch(event: (event?: TouchEvent) => void)
当手指在组件上按下、滑动、抬起时触发。
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-events-touch-0000001427902424-V3
例如：
// xxx.ets
@Entry
@Component
struct TouchExample {
@State text: string = ''
@State eventType: string = ''
build() {
Column() {
Button('Touch').height(40).width(100)
.onTouch((event: TouchEvent) => {
if (event.type === TouchType.Down) {
this.eventType = 'Down'
}
if (event.type === TouchType.Up) {
this.eventType = 'Up'
}
if (event.type === TouchType.Move) {
this.eventType = 'Move'
}
this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
+ event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
+ event.target.area.width + '\nheight:' + event.target.area.height
})
Button('Touch').height(50).width(200).margin(20)
.onTouch((event: TouchEvent) => {
if (event.type === TouchType.Down) {
this.eventType = 'Down'
}
if (event.type === TouchType.Up) {
this.eventType = 'Up'
}
if (event.type === TouchType.Move) {
this.eventType = 'Move'
}
this.text = 'TouchType:' + this.eventType + '\nDistance between touch point and touch element:\nx: '
+ event.touches[0].x + '\n' + 'y: ' + event.touches[0].y + '\nComponent globalPos:('
+ event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
+ event.target.area.width + '\nheight:' + event.target.area.height
})
Text(this.text)
}.width('100%').padding(30)
}
}
.1.3、挂载卸载事件—onAppear(event: () => void)onDisAppear(event: () => void)
挂载卸载事件指组件从组件树上挂载、卸载时触发的事件。
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-events-show-hide-0000001428061696-V3
例如：
// xxx.ets
import promptAction from '@ohos.promptAction'
@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)
.onAppear(() => {
promptAction.showToast({
message: 'The text is shown',
duration: 2000
})
})
.onDisAppear(() => {
promptAction.showToast({
message: 'The text is hidden',
duration: 2000
})
})
}
}.padding(30).width('100%')
}
}
.1.4、拖拽事件
拖拽事件指组件被长按后拖拽时触发的事件。
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-events-drag-drop-0000001427584820-V3
| 名称 | 功能描述 |
|---|---|
| onDragStart(event: (event?: DragEvent, extraParams?: string) => CustomBuilder | DragItemInfo) | 第一次拖拽此事件绑定的组件时，触发回调 |
| onDragEnter(event: (event?: DragEvent, extraParams?: string) => void) | 拖拽进入组件范围内时，触发回调 |
| onDragMove(event: (event?: DragEvent, extraParams?: string) => void) | 拖拽在组件范围内移动时，触发回调 |
| onDragLeave(event: (event?: DragEvent, extraParams?: string) => void) | 拖拽离开组件范围内时，触发回调 |
| onDrop(event: (event?: DragEvent, extraParams?: string) => void) | 绑定此事件的组件可作为拖拽释放目标，当在本组件范围内停止拖拽行为时，触发回调 |
.1.5、按键事件(键盘操作)—onKeyEvent(event: (event?: KeyEvent) => void)
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-events-key-0000001427744780-V3
按键事件指组件与键盘、遥控器等按键设备交互时触发的事件，适用于所有可获焦组件，例如Button。对于Text，Image等默认不可获焦的组件，可以设置focusable属性为true后使用按键事件。
例如：
// xxx.ets
@Entry
@Component
struct KeyEventExample {
@State text: string = ''
@State eventType: string = ''
build() {
Column() {
Button('KeyEvent')
.onKeyEvent((event: KeyEvent) => {
if (event.type === KeyType.Down) {
this.eventType = 'Down'
}
if (event.type === KeyType.Up) {
this.eventType = 'Up'
}
this.text = 'KeyType:' + this.eventType + '\nkeyCode:' + event.keyCode + '\nkeyText:' + event.keyText
})
Text(this.text).padding(15)
}.height(300).width('100%').padding(35)
}
}
.1.6、焦点事件—onFocus(event: () => void) onBlur(event:() => void)
焦点事件指页面焦点在可获焦组件间移动时触发的事件，组件可使用焦点事件来处理相关逻辑。
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-focus-event-0000001478181373-V3
- 目前仅支持通过外接键盘的tab键、方向键触发。
- 存在默认交互逻辑的组件例如Button、TextInput等，默认即为可获焦，Text、Image等组件则默认状态为不可获焦，不可获焦状态下，无法触发焦点事件，需要设置focusable属性为true才可触发。
例如：
// xxx.ets
@Entry
@Component
struct FocusEventExample {
@State oneButtonColor: string = '#FFC0CB'
@State twoButtonColor: string = '#87CEFA'
@State threeButtonColor: string = '#90EE90'
build() {
Column({ space: 20 }) {
// 通过外接键盘的上下键可以让焦点在三个按钮间移动，按钮获焦时颜色变化，失焦时变回原背景色
Button('First Button')
.backgroundColor(this.oneButtonColor)
.width(260)
.height(70)
.fontColor(Color.Black)
.focusable(true)
.onFocus(() => {
this.oneButtonColor = '#FF0000'
})
.onBlur(() => {
this.oneButtonColor = '#FFC0CB'
})
Button('Second Button')
.backgroundColor(this.twoButtonColor)
.width(260)
.height(70)
.fontColor(Color.Black)
.focusable(true)
.onFocus(() => {
this.twoButtonColor = '#FF0000'
})
.onBlur(() => {
this.twoButtonColor = '#87CEFA'
})
Button('Third Button')
.backgroundColor(this.threeButtonColor)
.width(260)
.height(70)
.fontColor(Color.Black)
.focusable(true)
.onFocus(() => {
this.threeButtonColor = '#FF0000'
})
.onBlur(() => {
this.threeButtonColor = '#90EE90'
})
}.width('100%').margin({ top: 20 })
}
}
.1.7、鼠标事件—onHover(event: (isHover?: boolean) => void)onMouse(event: (event?: MouseEvent) => void)
在鼠标的单个动作触发多个事件时，事件的顺序是固定的，鼠标事件默认透传。
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-mouse-key-0000001478341101-V3
例如：
// xxx.ets
@Entry
@Component
struct MouseEventExample {
@State hoverText: string = 'no hover';
@State mouseText: string = '';
@State action: string = '';
@State mouseBtn: string = '';
@State color: Color = Color.Blue;
build() {
Column({ space: 20 }) {
Button(this.hoverText)
.width(180).height(80)
.backgroundColor(this.color)
.onHover((isHover: boolean) => {
// 通过onHover事件动态修改按钮在是否有鼠标悬浮时的文本内容与背景颜色
if (isHover) {
this.hoverText = 'hover';
this.color = Color.Pink;
} else {
this.hoverText = 'no hover';
this.color = Color.Blue;
}
})
Button('onMouse')
.width(180).height(80)
.onMouse((event: MouseEvent) => {
switch (event.button) {
case MouseButton.None:
this.mouseBtn = 'None';
break;
case MouseButton.Left:
this.mouseBtn = 'Left';
break;
case MouseButton.Right:
this.mouseBtn = 'Right';
break;
case MouseButton.Back:
this.mouseBtn = 'Back';
break;
case MouseButton.Forward:
this.mouseBtn = 'Forward';
break;
case MouseButton.Middle:
this.mouseBtn = 'Middle';
break;
}
switch (event.action) {
case MouseAction.Hover:
this.action = 'Hover';
break;
case MouseAction.Press:
this.action = 'Press';
break;
case MouseAction.Move:
this.action = 'Move';
break;
case MouseAction.Release:
this.action = 'Release';
break;
}
this.mouseText = 'onMouse:\nButton = ' + this.mouseBtn +
'\nAction = ' + this.action + '\nXY=(' + event.x + ',' + event.y + ')' +
'\nscreenXY=(' + event.screenX + ',' + event.screenY + ')';
})
Text(this.mouseText)
}.padding({ top: 30 }).width('100%')
}
}
鼠标悬浮时改变文本内容与背景颜色：
鼠标点击时：
.1.8、组件区域变化事件—onAreaChange(event: (oldValue: Area, newValue: Area) => void)
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-component-area-change-event-0000001478061665-V3
组件区域变化事件指组件显示的尺寸、位置等发生变化时触发的事件。
例如：
// xxx.ets
@Entry
@Component
struct AreaExample {
@State value: string = 'Text'
@State sizeValue: string = ''
build() {
Column() {
Text(this.value)
.backgroundColor(Color.Green).margin(30).fontSize(20)
.onClick(() => {
this.value = this.value + 'Text'
})
.onAreaChange((oldValue: Area, newValue: Area) => {
console.info(`Ace: on area change, oldValue is ${JSON.stringify(oldValue)} value is ${JSON.stringify(newValue)}`)
this.sizeValue = JSON.stringify(newValue)
})
Text('new area is: \n' + this.sizeValue).margin({ right: 30, left: 30 })
}
.width('100%').height('100%').margin({ top: 30 })
}
}
.1.9、组件可见区域变化事件—onVisibleAreaChange(ratios: Array, event: (isVisible: boolean, currentRatio: number) => void)
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-component-visible-area-change-event-0000001477981161-V3
组件可见区域变化事件是组件在屏幕中的显示区域面积变化时触发的事件，提供了判断组件是否完全或部分显示在屏幕中的能力，适用于广告曝光埋点之类的场景。
例如：
// xxx.ets
@Entry
@Component
struct ScrollExample {
scroller: Scroller = new Scroller()
private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@State testTextStr: string = 'test'
@State testRowStr: string = 'test'
build() {
Column() {
Column() {
Text(this.testTextStr)
.fontSize(20)
Text(this.testRowStr)
.fontSize(20)
}
.height(100)
.backgroundColor(Color.Gray)
.opacity(0.3)
Scroll(this.scroller) {
Column() {
Text("Test Text Visible Change")
.fontSize(20)
.height(200)
.margin({ top: 50, bottom: 20 })
.backgroundColor(Color.Green)
// 通过设置ratios为[0.0, 1.0]，实现当组件完全显示或完全消失在屏幕中时触发回调
.onVisibleAreaChange([0.0, 1.0], (isVisible: boolean, currentRatio: number) => {
console.info('Test Text isVisible: ' + isVisible + ', currentRatio:' + currentRatio)
if (isVisible && currentRatio >= 1.0) {
console.info('Test Text is fully visible. currentRatio:' + currentRatio)
this.testTextStr = 'Test Text is fully visible'
}
if (!isVisible && currentRatio <= 0.0) {
console.info('Test Text is completely invisible.')
this.testTextStr = 'Test Text is completely invisible'
}
})
Row() {
Text('Test Row Visible Change')
.fontSize(20)
.margin({ bottom: 20 })
}
.height(200)
.backgroundColor(Color.Yellow)
.onVisibleAreaChange([0.0, 1.0], (isVisible: boolean, currentRatio: number) => {
console.info('Test Row isVisible:' + isVisible + ', currentRatio:' + currentRatio)
if (isVisible && currentRatio >= 1.0) {
console.info('Test Row is fully visible.')
this.testRowStr = 'Test Row is fully visible'
}
if (!isVisible && currentRatio <= 0.0) {
console.info('Test Row is is completely invisible.')
this.testRowStr = 'Test Row is is completely invisible'
}
})
ForEach(this.arr, (item) => {
Text(item.toString())
.width('90%')
.height(150)
.backgroundColor(0xFFFFFF)
.borderRadius(15)
.fontSize(16)
.textAlign(TextAlign.Center)
.margin({ top: 10 })
}, item => item)
}.width('100%')
}
.backgroundColor(0x317aff)
.scrollable(ScrollDirection.Vertical)
.scrollBar(BarState.On)
.scrollBarColor(Color.Gray)
.scrollBarWidth(10)
.onScroll((xOffset: number, yOffset: number) => {
console.info(xOffset + ' ' + yOffset)
})
.onScrollEdge((side: Edge) => {
console.info('To the edge')
})
.onScrollEnd(() => {
console.info('Scroll Stop')
})
}.width('100%').height('100%').backgroundColor(0xDCDCDC)
}
}
.2、通用属性
.2.1、尺寸相关
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-size-0000001428061700-V3
.2.1.1、width—设置组件自身的宽度
缺省时使用元素自身内容需要的宽度。若子组件的宽大于父组件的宽，则会画出父组件的范围。
单位：vp
.2.1.2、height—设置组件自身的高度
缺省时使用元素自身内容需要的高度。若子组件的高大于父组件的高，则会画出父组件的范围。
单位：vp
.2.1.3、size—设置高宽尺寸。
单位：vp
.2.1.4、padding—设置内边距属性
参数为Length类型时，四个方向内边距同时生效。
默认值：0
单位：vp
padding设置百分比时，上下左右内边距均以父容器的width作为基础值。
.2.1.5、margin—设置外边距属性
参数为Length类型时，四个方向外边距同时生效。
默认值：0
单位：vp
margin设置百分比时，上下左右外边距均以父容器的width作为基础值。
.2.1.6、layoutWeight—按权重设置宽高(仅在Row/Column/Flex布局中生效)
父容器尺寸确定时，设置了layoutWeight属性的子元素与兄弟元素占主轴尺寸按照权重进行分配，忽略元素本身尺寸设置，表示自适应占满剩余空间。
默认值：0
说明：
仅在Row/Column/Flex布局中生效。
可选值为大于等于0的数字，或者可以转换为数字的字符串。
.2.1.7、constraintSize—设置约束尺寸，组件布局时，进行尺寸范围限制
constraintSize的优先级高于Width和Height。若设置的minWidth大于maxWidth，则minWidth生效，minHeight与maxHeight同理。
默认值：
{
minWidth: 0,
maxWidth: Infinity,
minHeight: 0,
maxHeight: Infinity
}
.2.2、位置相关
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-location-0000001427584824-V3
.2.2.1、align—设置元素内容在元素绘制区域内的对齐方式
默认值：Alignment.Center
.2.2.2、direction----设置元素水平方向的布局
默认值：Direction.Auto
.2.2.3、position—绝对定位，设置元素左上角相对于父容器左上角偏移位置
在布局容器中，设置该属性不影响父容器布局，仅在绘制时进行位置调整。
适用于置顶显示、悬浮按钮等组件在父容器中位置固定的场景。
.2.2.4、markAnchor—设置元素在位置定位时的锚点，以元素左上角作为基准点进行偏移
通常配合position和offset属性使用，单独使用时，效果类似offset
默认值：{x: 0,y: 0}
.2.2.5、offset—相对定位，设置元素相对于自身的偏移量
设置该属性，不影响父容器布局，仅在绘制时进行位置调整。
默认值：{x: 0,y: 0}
.2.2.6、alignRules—指定相对容器的对齐规则
- left：设置左对齐参数。
- right：设置右对齐参数。
- middle：设置横向居中对齐方式的参数。
- top：设置顶部对齐的参数。
- bottom：设置底部对齐的参数。
- center：设置纵向居中对齐方式的参数。
left?: { anchor: string, align: HorizontalAlign }
该接口支持在ArkTS卡片中使用。
说明： - anchor：设置作为锚点的组件的id值。
- align：设置相对于锚点组件的对齐方式。
.2.3、布局约束
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-layout-constraints-0000001427744784-V3
.2.3.1、aspectRatio—指定当前组件的宽高比
指定当前组件的宽高比，aspectRatio = width/height。
.2.3.2、displayPriority—设置当前组件在布局容器中显示的优先级(仅在Row/Column/Flex(单行)容器组件中生效)
当父容器空间不足时，低优先级的组件会被隐藏。
小数点后的数字不作优先级区分，即区间为[x, x + 1)内的数字视为相同优先级。例如：1.0与1.9为同一优先级。
图1 竖屏显示
图2 横屏显示
横屏显示
.2.4、Flex布局（子属性仅当父组件是 Flex、Column、Row 时生效）
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-flex-layout-0000001478181377-V3
.2.4.1、flexBasis—设置组件在父容器主轴方向上的基准尺寸
默认值：‘auto’（表示组件在主轴方向上的基准尺寸为组件原本的大小）。
不支持百分比设置
.2.4.2、flexGrow—设置父容器的剩余空间分配给此属性所在组件的比例
默认值：0
.2.4.3、flexShrink—设置父容器压缩尺寸分配给此属性所在组件的比例
父容器为Row、Column时，默认值：0
父容器为flex时，默认值：1
.2.4.4、alignSelf—子组件在父容器交叉轴的对齐格式，会覆盖Flex布局容器中的alignItems设置
默认值：ItemAlign.Auto
.2.5、边框设置
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-border-0000001478341105-V3
.2.5.1、border—统一边框样式设置接口
- width：设置边框宽度。
- color：设置边框颜色。
- radius：设置边框圆角半径。
- style：设置边框样式。
说明：
边框宽度默认值为0，即不显示边框。
.2.5.2、borderStyle—设置元素的边框样式
默认值：BorderStyle.Solid
.2.5.3、borderWidth—设置元素的边框宽度，不支持百分比
.2.5.4、borderColor—设置元素的边框颜色
默认值：Color.Black
.2.5.5、borderRadius—设置元素的边框圆角半径，不支持百分比
.2.6、图片边框设置
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-border-image-0000001478061669-V3
.2.6.1、borderImage—图片边框或者渐变色边框设置接口
.2.7、背景设置
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-background-0000001477981165-V3
.2.7.1、backgroundColor—设置组件的背景色
.2.7.2、backgroundImage—背景图片
src：图片地址，支持网络图片资源和本地图片资源地址(不支持svg类型的图片)。
repeat：设置背景图片的重复样式，默认不重复。当设置的背景图片为透明底色图片，且同时设置了backgroundColor时，二者叠加显示，背景颜色在最底部。
.2.7.3、backgroundImageSize—背景图片大小设置
设置背景图像的高度和宽度。当输入为{width: Length, height: Length}对象时，如果只设置一个属性，则第二个属性保持图片原始宽高比进行调整。默认保持原图的比例不变。
width和height取值范围： [0, +∞)
默认值：ImageSize.Auto
说明：
设置为小于0的值时，按值为0显示。当设置了height未设置width时，width根据图片原始宽高比进行调整。
.2.7.4、backgroundImagePosition—设置背景图在组件中显示位置，即相对于组件左上角的坐标
默认值：{x: 0,y: 0}
x和y值设置百分比时，偏移量是相对组件自身宽高计算的。
.2.8、透明度设置
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-opacity-0000001427902432-V3
.2.8.1、opacity—元素的不透明度
取值范围为0到1，1表示不透明，0表示完全透明, 达到隐藏组件效果，但是在布局中占位。
说明：
子组件可以继承父组件的此属性。默认值：1
.2.9、显隐控制
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-visibility-0000001428061704-V3
.2.9.1、visibility—控制当前组件显示或隐藏
根据具体场景需要可使用条件渲染代替。
默认值：Visibility.Visible
.2.10、禁用控制
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-enable-0000001427584828-V3
组件是否可交互，可交互状态下响应点击事件、触摸事件、拖拽事件、按键事件、焦点事件和鼠标事件。
.2.10.1、enabled—是否启用
值为true表示组件可交互，响应点击等操作。
值为false表示组件不可交互，不响应点击等操作。
默认值：true
.2.11、浮层
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-overlay-0000001427744788-V3
设置组件的遮罩文本。
.2.11.1、overlay—在当前组件上，增加遮罩文本
value: 遮罩文本内容。
options: 文本定位，align设置文本相对于组件的方位，offset为文本基于自身左上角的偏移量。文本默认处于组件左上角。
两者都设置时效果重叠，文本相对于组件方位定位后再基于当前位置文本的左上角进行偏移。
默认值：options：{align: Alignment.TopStart,offset: { x: 0, y: 0}}
.2.12、Z序控制
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-z-order-0000001478181381-V3
组件的Z序，设置组件的堆叠顺序。
.2.12.1、zIndex—同一容器中兄弟组件显示层级关系
zIndex值越大，显示层级越高，即zIndex值大的组件会覆盖在zIndex值小的组件上方
Stack容器内子组件不设置zIndex的效果
Stack容器子组件设置zIndex后效果
.2.13、图形变换
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-transformation-0000001478341109-V3
用于对组件进行旋转、平移、缩放、矩阵变换等操作。
.2.13.1、rotate—可使组件在以组件左上角为坐标原点的坐标系中进行旋转（坐标系如下图所示）
其中，(x, y, z）指定一个矢量，作为旋转轴。
- angle：旋转角度。取值为正时相对于旋转轴方向顺时针转动，取值为负时相对于旋转轴方向逆时针转动。取值可为string类型，如’90deg’。
- centerX和centerY用于指定旋转的中心点。
旋转轴和旋转中心点都基于坐标系设定，组件发生位移时，坐标系不会随之移动。
默认值:{x: 0,y: 0,z: 0,centerX: ‘50%’,centerY: ‘50%’}
.2.13.2、translate—可使组件在以组件左上角为坐标原点的坐标系中进行移动（坐标系如下图所示）
其中，x，y，z的值分别表示在对应轴移动的距离，值为正时表示向对应轴的正向移动，值为负时表示向对应轴的反向移动。移动距离支持数字和字符串（比如’10px’，‘10%’）两种类型。
默认值:{x: 0,y: 0,z: 0}
.2.13.3、scale—可以分别设置X轴、Y轴、Z轴的缩放比例
默认值为1，同时可以通过centerX和centerY设置缩放的中心点。
默认值:{x: 1,y: 1,z: 1,centerX:‘50%’,centerY:‘50%’}
.2.13.4、transform—设置当前组件的变换矩阵
.2.14、图像效果
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-image-effect-0000001478061673-V3
设置组件的模糊，阴影效果以及设置图片的图像效果。
.2.14.1、blur—为当前组件添加内容模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊
取值范围：[0, +∞)
.2.14.2、backdropBlur—为当前组件添加背景模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊
取值范围：[0, +∞)
.2.14.3、shadow—为当前组件添加阴影效果
入参为模糊半径(必填)、阴影的颜色(可选，默认为灰色)、X轴的偏移量(可选，默认为0)，Y轴的偏移量(可选，默认为0)，偏移量单位为px
.2.14.4、grayscale—为当前组件添加灰度效果
值定义为灰度转换的比例，入参1.0则完全转为灰度图像，入参则0.0图像无变化，入参在0.0和1.0之间时，效果呈线性变化。（百分比)
取值范围：[0, 1]
说明：
设置小于0的值时，按值为0处理，设置大于1的值时，按值为1处理。
.2.14.5、brightness—为当前组件添加高光效果
入参为高光比例，值为1时没有效果，小于1时亮度变暗，0为全黑，大于1时亮度增加，数值越大亮度越大。
取值范围：[0, +∞)
说明：
设置小于0的值时，按值为0处理。
.2.14.6、saturate—为当前组件添加饱和度效果
饱和度为颜色中的含色成分和消色成分(灰)的比例，入参为1时，显示原图像，大于1时含色成分越大，饱和度越大；小于1时消色成分越大，饱和度越小。（百分比）
.2.14.7、contrast—为当前组件添加对比度效果
入参为对比度的值。值为1时，显示原图，大于1时，值越大对比度越高，图像越清晰醒目，小于1时，值越小对比度越低，当对比度为0时，图像变为全灰。（百分比）
取值范围：[0, +∞)
说明：
设置小于0的值时，按值为0处理。
.2.14.8、invert—反转输入的图像
入参为图像反转的比例，值为1时完全反转，值为0则图像无变化。（百分比）
取值范围：[0, 1]
说明：
设置小于0的值时，按值为0处理。
.2.14.9、sepia—将图像转换为深褐色
入参为图像反转的比例。值为1则完全是深褐色的，值为0图像无变化。 （百分比）
.2.14.10、hueRotate—色相旋转效果，输入参数为旋转角度
取值范围：(-∞, +∞)
说明：
色调旋转360度会显示原始颜色。先将色调旋转180 度，然后再旋转-180度会显示原始颜色。数据类型为number时，值为90和’90deg’效果一致。
.2.14.11、colorBlend—为当前组件添加颜色叠加效果，入参为叠加的颜色
.2.15、形状裁剪(圆角等其他操作处理)
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-sharp-clipping-0000001477981173-V3
用于对组件进行裁剪、遮罩处理。
.2.15.1、clip—参数为相应类型的组件，按指定的形状对当前组件进行裁剪；参数为boolean类型时，设置是否按照父容器边缘轮廓进行裁剪
默认值：false
.2.15.2、mask—在当前组件上加上指定形状的遮罩
.2.16、文本样式设置
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-text-style-0000001427902436-V3
针对包含文本元素的组件，设置文本样式。
.2.16.1、fontColor—设置字体颜色
.2.16.2、fontSize—设置字体大小
Length为number类型时，使用fp单位。字体默认大小16。不支持设置百分比字符串。
.2.16.3、fontStyle—设置字体样式
默认值：FontStyle.Normal
.2.16.4、fontWeight—设置文本的字体粗细
number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、“bolder”、“lighter”、“regular”、“medium”，分别对应FontWeight中相应的枚举值。
默认值：FontWeight.Normal
.2.16.5、fontFamily—设置字体列表
默认字体’HarmonyOS Sans’，当前支持’HarmonyOS Sans’字体和注册自定义字体。
.2.16.6、lineHeight—设置文本的文本行高
设置值不大于0时，不限制文本行高，自适应字体大小，Length为number类型时单位为fp。
.2.16.7、decoration—设置文本装饰线样式及其颜色
默认值：{type: TextDecorationType.None,color：Color.Black}
.2.17、栅格设置
https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-universal-attributes-grid-0000001428061712-V3
栅格布局的列宽、列间距由距离最近的GridContainer父组件决定。使用栅格属性的组件树上至少需要有1个GridContainer容器组件。
.2.17.1、gridSpan—默认占用列数
指useSizeType属性没有设置对应尺寸的列数（span)时，占用的栅格列数。
说明：
设置了栅格span属性，组件的宽度由栅格布局决定。
默认值：1
.2.17.2、gridOffset—默认偏移列数
指useSizeType属性没有设置对应尺寸的偏移(offset)时， 当前组件沿着父组件Start方向，偏移的列数，也就是当前组件位于第n列。
说明：
- 配置该属性后，当前组件在父组件水平方向的布局不再跟随父组件原有的布局方式，而是沿着父组件的Start方向偏移一定位移。
- 偏移位移 = （列宽 + 间距）* 列数。
- 设置了偏移(gridOffset)的组件之后的兄弟组件会根据该组件进行相对布局，类似相对布局。
默认值：0
图1 设备宽度为SM
图2 设备宽度为MD
图3 设备宽度为LG
图4 单独设置gridSpan和gridOffset在特定屏幕大小下的效果与useSizeType效果一致
