OpenHarmony应用开发-PageAbility组件开发指导
版本:v3.2 Beta5
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同样通过featureAbility中的startAbility接口实现。
除引入’@ohos.ability.featureAbility’外,还需引入’@ohos.distributedHardware.deviceManager’,通过DeviceManager(该组件在OpenHarmony上提供帐号无关的分布式设备的认证组网能力)的getTrustedDeviceListSync接口(获取信任设备列表)获取远端的deviceId,写入want中,用于启动远程PageAbility。
由于当前DeviceManager的getTrustedDeviceListSync接口仅对系统应用开放,故现阶段非系统应用无法获取其他设备信息,无远程启动设备选择入口,远程启动Ability开发。
表1 featureAbility接口说明
接口名 | 接口描述 |
startAbility(parameter: StartAbilityParameter) | 启动Ability。 |
startAbilityForResult(parameter: StartAbilityParameter) | 启动Ability,并在该Ability被销毁时返回执行结果。 |
表2 deviceManager接口说明
接口名 | 接口描述 |
getTrustedDeviceListSync(): Array<DeviceInfo> | 同步获取所有可信设备列表。 |
在跨设备场景下,启动远程PageAbility首先需要向用户申请数据同步的权限,相关接口说明如下:
表3 AtManager接口说明
接口名 | 接口描述 |
checkAccessToken(tokenID: number, permissionName: string) : Promise<GrantStatus> | 校验应用是否授予权限。使用Promise异步回调。返回值GrantStatus。建议使用checkAccessToken代替verifyAccessToken(已废弃),verifyAccessToken从API version 9开始不再维护。 |
表4 context接口说明
接口名 | 接口描述 |
requestPermissionsFromUser(permissions: Array<string>, requestCode: number, resultCallback: AsyncCallback< PermissionRequestResult>): void | 以callback形式从系统请求某些权限,详见对应接口文档。 |
如下示例代码展示了向用户申请数据同步权限的方法:
import abilityAccessCtrl from "@ohos.abilityAccessCtrl";
import featureAbility from '@ohos.ability.featureAbility';
import bundle from '@ohos.bundle.bundleManager';
async function RequestPermission() {
console.info('RequestPermission begin');
let array: Array<string> = ["ohos.permission.DISTRIBUTED_DATASYNC"];
let bundleFlag = 0;
let tokenID = undefined;
let userID = 100;
let appInfo = await bundle.getApplicationInfo('ohos.samples.etsDemo', bundleFlag, userID);
tokenID = appInfo.accessTokenId;
let atManager = abilityAccessCtrl.createAtManager();
let requestPermissions: Array<string> = [];
for (let i = 0;i < array.length; i++) {
let result = await atManager.verifyAccessToken(tokenID, array[i]);
console.info("checkAccessToken result:" + JSON.stringify(result));
if (result != abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
requestPermissions.push(array[i]);
}
}
console.info("requestPermissions:" + JSON.stringify(requestPermissions));
if (requestPermissions.length == 0 || requestPermissions == []) {
return;
}
let context = featureAbility.getContext();
context.requestPermissionsFromUser(requestPermissions, 1, (error, data)=>{
console.info("data:" + JSON.stringify(data));
console.info("data requestCode:" + data.requestCode);
console.info("data permissions:" + data.permissions);
console.info("data authResults:" + data.authResults);
});
console.info('RequestPermission end');
}
在获取数据同步权限后,需要获取可信设备列表,进行设备选择。
如下示例展示了通过getTrustedDeviceListSync获取可信设备列表,选择设备的方法。
import deviceManager from '@ohos.distributedHardware.deviceManager';
let dmClass;
function getDeviceManager() {
deviceManager.createDeviceManager('ohos.example.distributedService', (error, dm) => {
if (error) {
console.info('create device manager failed with ' + error)
}
dmClass = dm;
})
}
function getRemoteDeviceId() {
if (typeof dmClass === 'object' && dmClass != null) {
let list = dmClass.getTrustedDeviceListSync();
if (typeof (list) == 'undefined' || typeof (list.length) == 'undefined') {
console.info("MainAbility onButtonClick getRemoteDeviceId err: list is null");
return;
}
console.info("MainAbility onButtonClick getRemoteDeviceId success:" + list[0].deviceId);
return list[0].deviceId;
} else {
console.info("MainAbility onButtonClick getRemoteDeviceId err: dmClass is null");
}
}
设备选择完成后,通过调用startAbility接口,显式启动远程PageAbility。
如下示例展示了通过startAbility显式启动远程PageAbility的方法。
import featureAbility from '@ohos.ability.featureAbility';
function onStartRemoteAbility() {
console.info('onStartRemoteAbility begin');
let params;
let wantValue = {
bundleName: 'ohos.samples.etsDemo',
abilityName: 'ohos.samples.etsDemo.RemoteAbility',
deviceId: getRemoteDeviceId(), // getRemoteDeviceId的定义在前面的示例代码中
parameters: params
};
console.info('onStartRemoteAbility want=' + JSON.stringify(wantValue));
featureAbility.startAbility({
want: wantValue
}).then((data) => {
console.info('onStartRemoteAbility finished, ' + JSON.stringify(data));
});
console.info('onStartRemoteAbility end');
}
启动指定页面
当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中使用featureAbility的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生命周期回调中通过featureAbility的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的组件,例如系统桌面、语音助手、搜索助手等。