HarmonyOS Developer FA模型开发指导
FA模型开发概述
基于FA模型开发应用时,在应用模型部分,涉及如下开发过程。
表1 FA模型开发流程
任务 | 简介 | 相关指导 |
应用组件开发 | 本章节介绍了如何使用FA模型的PageAbility、ServiceAbility、DataAbility以及服务卡片进行应用开发。 | |
进程间通信 | 本章节介绍了FA模型的进程模型以及几种常用的进程间通信方式。 | 公共事件 后台服务 |
线程间通信 | 本章节介绍了FA模型的线程模型以及几种常用的线程间通信方式。 | 线程间通信 |
应用配置文件 | 本章节介绍FA模型中应用配置文件的开发要求。 |
FA模型应用组件
应用/组件级配置
开发者在开发应用时,需要配置应用的一些标签,例如应用的包名、图标等标识特征的属性。这一章节描述了开发者在开发应用时需要配置的一些关键标签。
- 应用包名配置
应用包名需在config.json文件中app标签下配置bundleName字段,该字段用于指定应用的包名,需保证唯一性。包名是由字母、数字、下划线(_)和点号(.)组成的字符串,必须以字母开头。支持的字符串长度为7~127字节。包名通常采用反向域名形式表示(例如,"com.example.myapplication")。建议第一级为域名后缀"com",第二级为厂商/个人名,也可以采用多级。应用名称配置可以参考app标签说明。 - 应用图标和标签配置
FA模型不支持直接配置应用图标和标签,会以符合规则的PageAbility的图标和标签作为应用图标和标签。PageAbility的图标和标签配置请参见PageAbility组件配置。需在config.json文件的abilities标签下配置icon字段,标签值为资源文件的索引。图标需要在配置IDE的资源文件中,路径为/resource/base/media。取值示例:$media:ability_icon。标签值为资源文件的索引,标识Ability对用户显示的名称。取值可以是Ability名称,也可以是对该名称的资源索引,以支持多语言。如果在该Ability的skills属性中,actions的取值包含 "action.system.home",entities取值中包含"entity.system.home",则该Ability的icon和label将同时作为应用的icon和label。如果存在多个符合条件的Ability,则取位置靠前的Ability的icon和label作为应用的icon和label。应用图标和标签配置可以参考ablities标签说明。
"abilities": [
"icon": "$media:icon",
"label": "$string:MainAbility_label",
"skills": [
{
"entities": ["entity.system.home"],
"actions": ["action.system.home"]
}
]
// ...
}
- 应用版本声明配置
应用版本声明配置需在config.json中的app标签下配置version字段,以说明应用当前的版本号和版本名称以及应用能够兼容的最低历史版本号。应用版本配置说明可以参考version标签说明。 - Module支持的设备类型配置
Module支持的设备类型需要在config.json文件中配置deviceType字段,如果deviceType标签中添加了某种设备,则表明当前的module支持在改设备上运行。具体的deviceType配置规则可以参考deviceType标签说明。 - 组件权限申请配置
组件权限申请配置需在confog.json中的module标签下配置reqPermission字段。来声明需要申请权限的名称,申请权限的原因以及权限使用的场景。组件权限申请可以参考reqPermission标签说明。
PageAbility组件开发指导
PageAbility组件概述
PageAbility是包含UI界面、提供展示UI能力的应用组件,主要用于与用户交互。
开发者通过DevEco Studio开发平台创建PageAbility时,DevEco Studio会自动创建相关模板代码。PageAbility相关能力通过单独的featureAbility实现,生命周期相关回调则通过app.js/app.ets中各个回调函数实现。
PageAbility组件配置
PageAbility的相关配置在config.json配置文件的"module"对象的"abilities"对象中,"icon"属性表示Ability图标资源文件的索引,"lable"属性表示Ability对用户显示的名称,"skills"属性表示Ability能够接收的want的特征。
表1 PageAbility部分配置项说明
属性名称 | 含义 | 数据类型 | 是否可缺省 |
icon | 表示Ability图标资源文件的索引。取值示例:$media:ability_icon。如果在该Ability的skills属性中,actions的取值包含 "action.system.home",entities取值中包含"entity.system.home",则该Ability的icon将同时作为应用的icon。如果存在多个符合条件的Ability,则取位置靠前的Ability的icon作为应用的icon。 说明:应用的"icon"和"label"是用户可感知配置项,需要区别于当前所有已有的应用"icon"或"label"(至少有一个不同)。 | 字符串 | 可缺省,缺省值为空。 |
label | 表示Ability对用户显示的名称。取值可以是Ability名称,也可以是对该名称的资源索引,以支持多语言。如果在该Ability的skills属性中,actions的取值包含 "action.system.home",entities取值中包含"entity.system.home",则该Ability的label将同时作为应用的label。如果存在多个符合条件的Ability,则取位置靠前的Ability的label作为应用的label。 说明: 应用的"icon"和"label"是用户可感知配置项,需要区别于当前所有已有的应用"icon"或"label"(至少有一个不同)。该标签为资源文件中定义的字符串的引用,或以"{}"包括的字符串。该标签最大长度为255字节。 | 字符串 | 可缺省,缺省值为空。 |
skills | 表示Ability能够接收的want的特征。 | 对象数组 | 可缺省,缺省值为空。 |
PageAbility的生命周期
PageAbility生命周期是PageAbility被调度到INACTIVE、ACTIVE、BACKGROUND等各个状态的统称。PageAbility生命周期流转及状态说明见如下图1、表1所示。
图1 PageAbility生命周期流转
表1 PageAbility生命周期状态说明
生命周期状态 | 生命周期状态说明 |
UNINITIALIZED | 未初始状态,为临时状态,PageAbility被创建后会由UNINITIALIZED状态进入INITIAL状态。 |
INITIAL | 初始化状态,也表示停止状态,表示当前PageAbility未运行,PageAbility被启动后由INITIAL态进入INACTIVE状态。 |
INACTIVE | 失去焦点状态,表示当前窗口已显示但是无焦点状态。 |
ACTIVE | 前台激活状态,表示当前窗口已显示,并获取焦点。 |
BACKGROUND | 后台状态,表示当前PageAbility退到后台,PageAbility在被销毁后由BACKGROUND状态进入INITIAL状态,或者重新被激活后由BACKGROUND状态进入ACTIVE状态。 |
应用开发者可以在app.js/app.ets中重写生命周期相关回调函数,PageAbility生命周期相关回调函数见下表。
表2 PageAbility生命周期回调接口说明
接口名 | 接口描述 |
onCreate() | Ability第一次启动创建Ability时调用onCreate方法,开发者可以在该方法里做一些应用初始化工作。 |
onDestroy() | 应用退出,销毁Ability对象前调用onDestroy方法,开发者可以在该方法里做一些回收资源、清空缓存等应用退出前的准备工作。 |
onActive() | Ability切换到前台,并且已经获取焦点时调用onActive方法。 |
onInactive() | Ability失去焦点时调用onInactive方法,Ability在进入后台状态时会先失去焦点,再进入后台。 |
onShow() | Ability由后台不可见状态切换到前台可见状态调用onShow方法,此时用户在屏幕可以看到该Ability。 |
onHide() | Ability由前台切换到后台不可见状态时调用onHide方法,此时用户在屏幕看不到该Ability。 |
PageAbility生命周期回调与生命周期状态的关系如下图所示。
图2 PageAbility生命周期回调与生命周期状态的关系
说明
1、PageAbility的生命周期回调均为同步接口。
2、目前app.js环境中仅支持onCreate和onDestroy回调,app.ets环境支持全量生命周期回调。
PageAbility的启动模式
启动模式对应PageAbility被启动时的行为,支持单实例模式、标准模式两种启动模式。
表1 PageAbility的启动模式
启动模式 | 描述 | 说明 |
singleton | 单实例模式 | 每次调用startAbility方法时,如果应用进程中该类型的Ability实例已经存在,则复用已有的实例,系统中只存在唯一一个实例。表现为在最近任务列表中只有一个Ability实例。 典型场景:当用户打开视频播放应用并观看视频,回到桌面后,再次打开视频播放应用,应用仍为回到桌面之前正在观看的视频。 |
standard | 标准模式 | 缺省启动模式。每次调用startAbility方法时,都会在应用进程中创建一个新的Ability实例。表现为在最近任务列表中可以看到有多个该类型的Ability实例。 典型场景:当用户打开文档应用,选择新建文档的时候,每次点击新建文档,都会创建一个新的文档任务,在最近任务列表中可以看到多个新建的文档任务。 |
应用开发者可在config.json配置文件中通过“launchType”配置启动模式。示例如下:
{
"module": {
// ...
"abilities": [
{
// singleton: 单实例模式
// standard: 标准模式
"launchType": "standard",
// ...
}
]
}
}
启动PageAbility时,对于标准启动模式(多实例启动模式)以及单实例启动模式首次启动,PageAbility生命周期回调均会被触发。单实例非首次启动时不会再触发onCreate()接口,而是触发onNewWant(),onNewWant()的说明如下表2所示。
表2 单实例启动模式特有的回调函数说明
接口名 | 接口描述 |
onNewWant(want: Want) | 单实例启动模式,PageAbility非首次启动时调用onNewWant方法,开发者可以在该方法中获取want,进而根据want做进一步处理。例如,单实例PageAbility迁移场景,指定页面拉起PageAbility场景。 |
创建PageAbility
开发者需要重写app.js/app.ets中的生命周期回调函数,开发者通过DevEco Studio开发平台创建PageAbility时,DevEco Studio会在app.js/app.ets中默认生成onCreate()和onDestroy()方法,其他方法需要开发者自行实现。接口说明参见前述章节,创建PageAbility示例如下:
export default {
onCreate() {
console.info('Application onCreate')
},
onDestroy() {
console.info('Application onDestroy')
},
onShow() {
console.info('Application onShow')
},
onHide() {
console.info('Application onHide')
},
onActive() {
console.info('Application onActive')
},
onInactive() {
console.info('Application onInactive')
},
onNewWant() {
console.info('Application onNewWant')
},
}
PageAbility创建成功后,其abilities相关的配置项在config.json中体现,一个名字为MainAbility的config.json配置文件示例如下:
{
"abilities": [
{
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}
],
"orientation": "unspecified",
"visible": true,
"srcPath": "MainAbility",
"name": ".MainAbility",
"srcLanguage": "ets",
"icon": "$media:icon",
"description": "$string:MainAbility_desc",
"formsEnabled": false,
"label": "$string:MainAbility_label",
"type": "page",
"launchType": "singleton"
}
]
}
FA模型中,可以通过featureAbility的getContext接口获取应用上下文,进而使用上下文提供的能力。
表1 featureAbility接口说明
接口名 | 接口描述 |
getContext() | 获取应用上下文。 |
通过getContext获取应用上下文并获取分布式目录的示例如下:
import featureAbility from '@ohos.ability.featureAbility'
import fileIo from '@ohos.fileio'
(async () => {
let dir: string
try {
console.info('Begin to getOrCreateDistributedDir')
dir = await featureAbility.getContext().getOrCreateDistributedDir()
console.info('distribute dir is ' + dir)
} catch (error) {
console.error('getOrCreateDistributedDir failed with ' + error)
}
let fd: number;
let path = dir + "/a.txt";
fd = fileIo.openSync(path, 0o2 | 0o100, 0o666);
fileIo.close(fd);
})()
启动本地PageAbility
PageAbility相关的能力通过featureAbility提供,启动本地Ability通过featureAbility中的startAbility接口实现。
表1 featureAbility接口说明
接口名 | 接口描述 |
startAbility(parameter: StartAbilityParameter) | 启动Ability。 |
startAbilityForResult(parameter: StartAbilityParameter) | 启动Ability,并在该Ability被销毁时返回执行结果。 |
如下示例通过startAbility显式启动PageAbility。启动Ability的参数包含want,关于want的说明详见对象间信息传递载体Want,相应的,隐式启动与显式启动也不在此赘述。
import featureAbility from '@ohos.ability.featureAbility'
(async () => {
try {
console.info('Begin to start ability')
let param = {
want: {
bundleName: "com.example.myapplication",
moduleName: "entry",
abilityName: "com.example.myapplication.MainAbility"
}
}
await featureAbility.startAbility(param)
console.info(`Start ability succeed`)
}
catch (error) {
console.error('Start ability failed with ' + error)
}
})()
停止PageAbility
停止PageAbility通过featureAbility中的terminateSelf接口实现。
表1 featureAbility接口说明
接口名 | 接口描述 |
terminateSelf() | 停止Ability。 |
terminateSelfWithResult(parameter: AbilityResult) | 设置该PageAbility停止时返回给调用者的结果及数据并停止Ability。 |
如下示例展示了停止Ability的方法。
import featureAbility from '@ohos.ability.featureAbility'
(async () => {
try {
console.info('Begin to terminateSelf')
await featureAbility.terminateSelf()
console.info('terminateSelf succeed')
}
catch (error) {
console.error('terminateSelf failed with ' + error)
}
})()
启动指定页面
当PageAbility的启动模式设置为单例时(具体设置方法和典型场景示例见PageAbility的启动模式,缺省情况下是单实例模式),若PageAbility已被拉起,再次启动PageAbility会触发onNewWant回调(即非首次拉起)。应用开发者可以通过want传递启动参数,例如开发者希望指定页面启动PageAbility,可以通过want中的parameters参数传递pages信息,具体示例代码如下:
调用方PageAbility的app.ets中或者page中,使用startAbility再次拉起PageAbility,通过want中的uri参数传递页面信息:
import featureAbility from '@ohos.ability.featureAbility';
async function restartAbility() {
let wantInfo = {
bundleName: "com.sample.MyApplication",
abilityName: "MainAbility",
parameters: {
page: "pages/second"
}
};
featureAbility.startAbility({
want: wantInfo
}).then((data) => {
console.info('restartAbility success.');
});
}
在目标端PageAbility的onNewWant回调中获取包含页面信息的want参数:
export default {
onNewWant(want) {
globalThis.newWant = want
}
}
在目标端页面的自定义组件中获取包含页面信息的want参数并根据uri做路由处理:
import router from '@ohos.router'
@Entry
@Component
struct Index {
@State message: string = 'Router Page'
newWant = undefined
onPageShow() {
console.info('Index onPageShow')
let newWant = globalThis.newWant
if (newWant.hasOwnProperty("page")) {
router.push({ url: newWant.page });
globalThis.newWant = undefined
}
}
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
当PageAbility的启动模式设置为标准模式或为首次启动单例模式的PageAbility时(具体设置方法和典型场景示例见PageAbility的启动模式),在调用方PageAbility中,通过want中的parameters参数传递要启动的指定页面的pages信息,调用startAbility()方法启动PageAbility。被调用方可以在onCreate中使用featrueAbility的getWant方法获取want,再通过调用router.push实现启动指定页面。
调用方的页面中实现按钮点击触发startAbility方法启动目标端PageAbility,startAbility方法的入参want中携带指定页面信息,示例代码如下:
import featureAbility from '@ohos.ability.featureAbility'
@Entry
@Component
struct Index {
@State message: string = 'Hello World'
build() {
// ...
Button("startAbility")
.onClick(() => {
featureAbility.startAbility({
want: {
bundleName: "com.exm.myapplication",
abilityName: "com.exm.myapplication.MainAbility",
parameters: { page: "pages/page1" }
}
}).then((data) => {
console.info("startAbility finish");
}).catch((err) => {
console.info("startAbility failed errcode:" + err.code)
})
})
// ...
Button("page2")
.onClick(() => {
featureAbility.startAbility({
want: {
bundleName: "com.exm.myapplication",
abilityName: "com.exm.myapplication.MainAbility",
parameters: { page: "pages/page2" }
}
}).then((data) => {
console.info("startAbility finish");
}).catch((err) => {
console.info("startAbility failed errcode:" + err.code)
})
})
// ...
}
}
目标端PageAbility的onCreate生命周期回调中通过featrueAbility的getWant方法获取want,并对参数进行解析,实现指定页面拉起:
import featureAbility from '@ohos.ability.featureAbility';
import router from '@ohos.router';
export default {
onCreate() {
featureAbility.getWant().then((want) => {
if (want.parameters.page) {
router.push({
url: want.parameters.page
})
}
})
},
onDestroy() {
// ...
},
}
窗口属性
具体获取窗口实例、设置窗口属性的接口描述及示例见接口文档。
申请授权
应用需要获取用户的隐私信息或使用系统能力时,例如获取位置信息、使用相机拍摄照片或录制视频等,需要向用户申请授权。
在开发过程中,首先需要明确涉及的敏感权限并在config.json中声明需要的权限,同时通过接口requestPermissionsFromUser以动态弹窗的方式向用户申请授权。
在config.json声明需要的权限,在module下添加"reqPermissions",并写入对应权限。
如申请访问日历权限,需要申请ohos.permission.READ_CALENDAR权限,配置方式请参阅访问控制授权申请指导。
对应config.json文件的示例代码如下所示:
{
"module": {
// ...
"reqPermissions": [
{
"name": "ohos.permission.READ_CALENDAR"
// ...
}
]
}
}
通过动态弹窗向用户申请授权:
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
let permissions: Array<string> = ['ohos.permission.READ_CALENDAR']
context.requestPermissionsFromUser(permissions, 1).then((data) => {
console.info("Succeed to request permission from user with data: " + JSON.stringify(data))
}).catch((error) => {
console.info("Failed to request permission from user with error: " + JSON.stringify(error))
})
跳转规则
一般情况下,应用中的界面跳转由用户触发,应用本身通过startAbility启动跳转其他界面。
PageAbility作为可见Ability,可以通过startAbility启动有界面的且对外可见的Ability。
应用可通过在config.json中设置"abilities"中的"visible"属性设置Ability是否可由其他应用的组件启动,"visible"属性的具体参数和意义如下表所示。
表1 visible属性说明
属性名称 | 描述 | 是否可缺省 |
visible | 表示Ability是否可以被其他应用调用。 true:该Ability可以被任何应用调用。 false:该Ability只能被同一应用的其他组件调用。 | 可缺省,缺省时默认属性值为"false"。 |
如果需设置当前Ability可由任何应用访问,对应config.json文件的示例代码如下所示:
{
"module": {
// ...
"abilities": [
{
"visible": "true",
// ...
}
]
}
}
如果应用中的Ability包含skills过滤器,建议此属性设置为"true",以允许其他应用通过隐式调用启动该Ability。如果此属性设为"false",其他应用尝试启动该Ability时系统会返回PERMISSION_DENIED。这种情况下系统应用可以通过申请START_INVISIBLE_ABILITY权限启动visible为false的组件,例如系统桌面、语音助手、搜索助手等。