开发环境

IDE:DevEco Studio 3.0 Release(Build Version: 3.0.0.993)

SDK:Api Version 8和9

Ability框架

概述

Ability是应用所具备能力的抽象,也是应用程序的重要组成部分。Ability是系统调度应用的最小单元,是能够完成一个独立功能的组件。一个应用可以包含一个或多个Ability。

类型

Ability的类型存在差异:

Ability框架模型具有两种形态:

  • FA模型

    API 8及其更早版本的应用程序只能使用FA模型进行开发。FA模型将Ability分为FA(Feature Ability)和PA(Particle Ability)两种类型,其中其中FA支持PageAbility,PA支持ServiceAbility、DataAbility、以及FormAbility。

  • Stage模型

    从API 9开始,Ability框架引入了Stage模型作为第二种应用框架形态,Stage模型将Ability分为PageAbility和ExtensionAbility两大类,其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等一系列ExtensionAbility,以便满足更多的使用场景。

基础用法

FA模型

PageAbility

PageAbility是具备ArkUI实现的Ability,是开发者具体可见并可以与之交互的Ability实例。开发者通过DevEco Studio创建Ability时,DevEco Studio会自动创建相关模板代码。 PageAbility相关能力通过单独的featureAbility实现,生命周期相关回调则通过app.js/app.ets中各个回调函数实现。

创建PageAbility
  1. 首次创建工程,打开DevEco Studio选择Create Project(如果在已有的工程界面创建新工程,则选择File->New->Create Project),然后选择OpenHarmony下的Empty Ability模板,点击Next进行下一步配置。

 

  1. 进入工程配置界面,按默认参数设置即可,点击Finish,工具会自动生成示例代码和相关资源,等待工程创建成功。

 

  1. 工程创建成功后生成一个默认的PageAbility,名为MainAbility。

 

  1. 如需在工程中创建多个PageAbility,点击File->New->Ability->Page Ability即可。

 

featureAbility接口说明
接口名 描述
void: startAbility(parameter: StartAbilityParameter) 启动Ability。
Context: getContext(): 获取应用Context。
void: terminateSelf() 结束Ability。
bool: hasWindowFocus() 是否获取焦点。
启动PageAbility

使用featureAbility.startAbility方法可以启动本地设备的PageAbility。

  1. 导入模块

import featureAbility from '@ohos.ability.featureAbility'
  1. 调用featureAbility.startAbility方法,由该方法的Want传递bundleName和abilityName属性来启动PageAbility。

  • bundleName:表示包名称。可在config.json中的app字段查看bundleName,或者通过File->Project Structure查看。

  • abilityName:表示待启动的Ability名称,由config.json中的package字段与abilities字段下的name字段组成。

featureAbility.startAbility({
	want: {
		bundleName: "com.samples.myapplication",
        // FA模型abilityName由config.json中的package + Ability name组成
		abilityName: "com.samples.myapplication.MainAbility"
	}
});

ServiceAbility

基于Service模板的Ability(以下简称“Service”),主要用于后台运行任务(如执行音乐播放、文件下载等),但不提供用户UI交互界面。Service可由其他应用或Ability启动。即使用户切换到其他应用,Service仍将在后台继续运行。

接口说明

Service中相关生命周期API功能介绍

接口名 描述
onStart?(): void 该方法在创建Service的时候调用,用于Service的初始化。在Service的整个生命周期只会调用一次,调用时传入的Want应为空。
onCommand?(want: Want, startId: number): void 在Service创建完成之后调用,该方法在客户端每次启动该Service时都会调用,开发者可以在该方法中做一些调用统计、初始化类的操作。
onConnect?(want: Want): rpc.RemoteObject 在Ability和Service连接时调用。
onDisconnect?(want: Want): void 在Ability与绑定的Service断开连接时调用。
onStop?(): void 在Service销毁时调用。开发者应通过实现此方法来清理资源,如关闭线程、注册的侦听器等。
创建与注册Service
  1. 在工程中,选择File->New->Ability->Service Ability,点击Finish,成功创建ServiceAbility,默认生成service.ts文件。

 

  1. 重写Service的生命周期方法,来添加其他Ability请求与ServiceAbility交互时的处理方法。

// service.ts
import hilog from '@ohos.hilog';

export default {
    onStart() {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onStart');
    },
    onStop() {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onStop');
    },
    onCommand(want, startId) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onCommand');
    },
    onConnect(want) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onConnect');
        return null;
    },
    onDisconnect(want) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility OnDisConnect');
    }
};
  1. 注册Service。FA模型在创建ServiceAbility时已在config.json中自动注册,注册类型type为service,只需手动添加visible字段并设置为true。

config.json配置样例

// config.json
"module": {
    ...
    "abilities": [
      ...
      {
        "name": ".ServiceAbility",
        "srcLanguage": "ets",
        "srcPath": "ServiceAbility",
        "icon": "$media:icon",
        "description": "$string:ServiceAbility_desc",
        "type": "service",
        "visible": true
      }
      ...
    ]
    ...
}

Json重要字段

字段名 备注说明  
"name" Ability名称,对应Ability派生的Service类名。  
"type" Ability类型,Service对应的Ability类型为”service“。  
"visible" 指定能力是否可被其他应用调用,默认值为false,设置为true时,Service才能与其他应用进行调用。  
启动Service

Ability为开发者提供了startAbility()方法来启动另外一个Ability,因为Service也是Ability的一种,开发者同样可以通过将want传递给该方法来启动Service,通过构造包含bundleName与abilityName的Want对象来设置目标Service信息。

启动本地设备Service示例如下:

import featureAbility from '@ohos.ability.featureAbility';

featureAbility.startAbility({
    want:
        {
            bundleName: "com.samples.myapplication",
            // FA模型abilityName由config.json中的package + Ability name组成
            abilityName: "com.samples.myapplication.ServiceAbility",
        }
    }
); 

执行上述代码后,Ability将通过startAbility()方法来启动Service。

  • 如果Service尚未运行,则系统会先调用onStart()来初始化Service,再回调Service的onCommand()方法来启动Service。

  • 如果Service正在运行,则系统会直接回调Service的onCommand()方法来启动Service。

连接Service

如果Service需要与Page Ability或其他应用的Service Ability进行交互,则须创建用于连接的Connection。Service支持其他Ability通过connectAbility()方法将当前Ability连接到指定ServiceAbility。在使用connectAbility()处理回调时,需要传入目标Service的Want与ConnectOptions远程对象实例。

ConnectOptions远程对象实例提供了以下方法:

  • onConnect():处理连接Service成功的回调。

  • onDisconnect():处理Service异常死亡的回调。

  • onFailed():处理连接Service失败的回调。

创建连接本地Service回调实例以及连接本地Service的示例如下:

import prompt from '@ohos.prompt';
import featureAbility from '@ohos.ability.featureAbility';
// 导入rpc进程通信模块
import rpc from "@ohos.rpc";

connectService() {
    // ConnectOptions远程对象实例
    let connectOptions = {
        // 连接成功时回调
        onConnect: function onConnectCallback(element, proxy) {
            console.log(`onConnectLocalService onConnectDone element:${element}`)
            if (proxy === null) {
                prompt.showToast({
                    message: 'Connect service failed'
                })
                return
            }
            // 携带客户端调用参数的MessageParcel对象
            let data = rpc.MessageParcel.create()
            // 接收应答数据的MessageParcel对象
            let reply = rpc.MessageParcel.create()
            // 本次请求的同异步模式,默认为TF_SYNC同步调用
            let option = new rpc.MessageOption()
            // 将字符串值写入MessageParcel实例
            data.writeString("connect")
            // 以同步模式向服务端发送MessageParcel消息,发送的消息代码为1,同步模式下该接口将等待服务端的响应,直到请求超时,响应的结果在reply中
            proxy.sendRequest(1, data, reply, option).then((result) => {
                console.log(`sendRequest: ${result}`);
                // 客户端以reply从MessageParcel实例中读取服务端处理后的字符串值
                let msg = reply.readString();
                console.log(`sendRequest msg: ${msg}`);
            }).catch((err) => {
                console.log(`sendRequest error: ${err}`);
            });
            prompt.showToast({
                message: "Connect service success"
            })
        },
        // 连接断开时回调
        onDisconnect: function onDisconnectCallback(element) {
            console.log(`onConnectLocalService onDisconnectDone element:${element}`)
            prompt.showToast({
                message: "Disconnect service success"
            })
        },
        // 连接失败时回调
        onFailed: function onFailedCallback(code) {
            console.log(`onConnectLocalService onFailed errCode:${code}`)
            prompt.showToast({
                message: "Connect local service onFailed"
            })
        }
    }
    // want参数
    let want = {
        bundleName: 'com.samples.myapplication',
        // FA模型abilityName由config.json中的package + Ability name组成
        abilityName: 'com.samples.myapplication.ServiceAbility'
    };
    // 连接本地Service
    featureAbility.connectAbility(want, connectOptions);
}

同时,Service服务端也需要在onConnect()时返回IRemoteObject,从而定义与Service进行通信的接口。OpenHarmony提供了IRemoteObject的默认实现,可以通过继承rpc.RemoteObject来创建自定义的实现类。

Service服务端把自身的实例返回给调用侧的代码示例如下:

// service.ts
import rpc from '@ohos.rpc';
import hilog from '@ohos.hilog';

// 实现远程对象,服务提供者必须继承RemoteObject类
class FirstServiceAbilityStub extends rpc.RemoteObject {
    // 用于创建RemoteObject实例的构造函数,参数des为指定接口描述符
    constructor(des: any) {
        super(des)
    }
    // sendRequest请求的响应处理函数,服务端在该函数里处理请求,回复结果
    onRemoteRequest(code, data, reply, option) {
        console.log(`onRemoteRequest called`)
        // 判断客户端发送过来的消息代码是否为1
        if (code === 1) {
            // 从MessageParcel实例中读取由客户端写入的字符串值
            let string = data.readString()
            console.log(`string=${string}`)
            // 将读取的字符串作拆分和排序处理
            let result = Array.from(string).sort().join('')
            console.log(`result=${result}`)
            // 将处理后的字符串值写入MessageParcel实例
            reply.writeString(result)
        } else {
            console.log(`unknown request code`)
        }
        return true;
    }
};

export default {
    onStart() {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onStart');
    },
    onStop() {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onStop');
    },
    onCommand(want, startId) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onCommand');
    },
    onConnect(want) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility onConnect');
        // 返回RemoteObject对象与描述符
        return new FirstServiceAbilityStub('first ts service stub');
    },
    onDisconnect(want) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'ServiceAbility OnDisConnect');
    }
};

DataAbility

基于Data模板的Ability(以下简称“Data”),有助于应用管理其自身和其他应用存储数据的访问,并提供与其他应用共享数据的方法,但不提供用户UI交互界面。Data既可用于同设备不同应用的数据共享,也支持跨设备不同应用的数据共享。

Data提供方可以自定义数据的增、删、改、查,以及文件打开等功能,并对外提供这些接口。

接口说明

Data中相关生命周期API功能介绍

接口名 描述
onInitialized?(info: AbilityInfo): void 在Ability初始化调用,通过此回调方法执行RDB等初始化操作。
update?(uri: string, valueBucket: rdb.ValuesBucket, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void 更新数据库中的数据。
query?(uri: string, columns: Array<string>, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<ResultSet>): void 查询数据库中的数据。
delete?(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void 删除一条或多条数据。
normalizeUri?(uri: string, callback: AsyncCallback<string>): void 对uri进行规范化。一个规范化的uri可以支持跨设备使用、持久化、备份和还原等,当上下文改变时仍然可以引用到相同的数据项。
batchInsert?(uri: string, valueBuckets: Array<rdb.ValuesBucket>, callback: AsyncCallback<number>): void 向数据库中插入多条数据。
denormalizeUri?(uri: string, callback: AsyncCallback<string>): void 将一个由normalizeUri生产的规范化URI转换成非规范化的uri。
insert?(uri: string, valueBucket: rdb.ValuesBucket, callback: AsyncCallback<number>): void 向数据中插入一条数据。
openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void 打开一个文件。
getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void 获取文件的MIME类型。
getType?(uri: string, callback: AsyncCallback<string>): void 获取uri指定数据相匹配的MIME类型。
executeBatch?(ops: Array<DataAbilityOperation>, callback: AsyncCallback<Array<DataAbilityResult>>): void 批量操作数据库中的数据。
call?(method: string, arg: string, extras: PacMap, callback: AsyncCallback<PacMap>): void 自定义方法。
创建与注册Data
  1. 在工程中,选择File->New->Ability->Data Ability,点击Finish,成功创建DataAbility,默认生成data.ts文件。

 

  1. 在data.ts文件中,实现Data的insert、query、update、delete等相关接口的业务内容,保证能够满足数据库存储业务的基本需求。batchInsert与executeBatch接口在系统中实现遍历逻辑,依赖insert、query、update、delete接口逻辑,来实现数据的批量处理。

创建Data示例如下:

// data.ts
import hilog from '@ohos.hilog';
import featureAbility from '@ohos.ability.featureAbility';
// 导入DataAbility谓词相关模块
import dataAbility from '@ohos.data.dataAbility';
// 导入rdb关系数据库模块
import dataRdb from '@ohos.data.rdb';

// 表名
const TABLE_NAME = 'book';
// 库的配置信息:库名称
const STORE_CONFIG = { name: 'book.db' };
// 表结构
const SQL_CREATE_TABLE = 'CREATE TABLE IF NOT EXISTS book(id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, introduction TEXT NOT NULL)';
// rdb库对象
let rdbStore: dataRdb.RdbStore = undefined;

export default {
    // 初始化库和表
    onInitialized(abilityInfo) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'DataAbility onInitialized');
        // 获取应用上下文
        let context = featureAbility.getContext();
        // 获取一个相关的RdbStore,操作关系型数据库
        dataRdb.getRdbStore(context, STORE_CONFIG, 1).then((store) => {
            console.info('DataAbility getRdbStore callback');
            // 执行包含指定参数但不返回值的SQL语句
            store.executeSql(SQL_CREATE_TABLE, null);
            // 把获得的数据库存入本地变量,防止后面多次操作读取创建
            rdbStore = store;
        });
    },
    // 向数据库中插入一条数据
    insert(uri, valueBucket, callback) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'DataAbility insert');
        rdbStore.insert(TABLE_NAME, valueBucket, callback);
    },
    // 向数据库中插入多条数据
    batchInsert(uri, valueBuckets, callback) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'DataAbility batchInsert');
        for (let i = 0; i < valueBuckets.length; i++) {
            console.info('DataAbility batch insert i=' + i)
            if (i < valueBuckets.length - 1) {
                rdbStore.insert(TABLE_NAME, valueBuckets[i], (err: any, num: number) => {
                    console.info('DataAbility batch insert ret=' + num)
                })
            } else {
                rdbStore.insert(TABLE_NAME, valueBuckets[i], callback)
            }
        }
    },
    // 查询数据库中的数据
    query(uri, columns, predicates, callback) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'DataAbility query');
        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates);
        rdbStore.query(rdbPredicates, columns, callback);
    },
    // 更新数据库中的数据
    update(uri, valueBucket, predicates, callback) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'DataAbility update');
        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates);
        rdbStore.update(valueBucket, rdbPredicates, callback);
    },
    // 删除一条或多条数据
    delete(uri, predicates, callback) {
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'DataAbility delete');
        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates);
        rdbStore.delete(rdbPredicates, callback);
    }
};
  1. 注册Data。FA模型在创建DataAbility时已在config.json中自动注册,注册类型type为data,visible字段需手动添加并设置为true。注册后会生成默认权限defPermissions字段,表明调用Data之前须配置这些权限,添加reqPermissions字段设置相应权限。

config.json配置样例

"module": {
    "package": "com.samples.myapplication",
    ...
    "abilities": [
        ... 
        {
            "name": ".DataAbility",
            "srcLanguage": "ets",
            "srcPath": "DataAbility",
            "icon": "$media:icon",
            "description": "$string:DataAbility_desc",
            "type": "data",
            "uri": "dataability://com.samples.myapplication.DataAbility",
            "visible": true
        }
    ],
    ...
    "defPermissions": [
        {
        	"name": "com.example.entry.DataAbilityShellProvider.PROVIDER"
    	}
    ],
    "reqPermissions": [
        {
        	"name": "com.example.entry.DataAbilityShellProvider.PROVIDER"
    	}
    ]
    ...
}

Json重要字段

字段名 备注说明
"name" Ability名称,对应Ability派生的Data类名。
"type" Ability类型,Data对应的Ability类型为”data“。
"uri" 通信使用的uri。URL后缀由"package"字段和"name"字段组成。
"visible" 指定能力是否可被其他应用调用,默认值为false,设置为true时,Data才能与其他应用进行通信传输数据。
"defPermissions" 表示应用程序默认需要的权限,调用者在调用Data之前必须获取相应权限。
访问Data

需导入基础模块,以及获取与Data子模块通信的uri字符串。基础模块包括:

  • @ohos.ability.featureAbility

  • @ohos.data.dataability

  • @ohos.data.rdb

  1. 创建工具接口类对象。

import featureAbility from '@ohos.ability.featureAbility';
import dataAbility from '@ohos.data.dataAbility';
import dataRdb from '@ohos.data.rdb';

// 定义数据访问uri常量
// 注意:作为参数传递的uri,比config.json中定义的uri多了一个"/",因为在第二个与第三个"/"中间,存在一个DeviceID的参数
let BASE_URI = "dataability:///com.example.entry.DataAbility";
// 获取dataAbilityHelper,用来协助其他Ability访问DataAbility的工具类。
let DA_HELPER = featureAbility.acquireDataAbilityHelper(BASE_URI);
// 定义表的列名
const COLUMNS = ['id', 'name', 'introduction'];
// 获取谓词
let predicates = new dataAbility.DataAbilityPredicates();
  1. 构建数据库相关的RDB数据。

// 创建一个BookModel数据模型
export class BookModel {
  id: number
  name: string
  introduction: string

  constructor(id: number, name: string, introduction: string) {
    this.id = id;
    this.name = name;
    this.introduction = introduction;
  }
}

//初始化测试数据
export function initValuesBuckets() {
  let valuesBuckets = [
    { 'name': 'Book name1', 'introduction': 'Book introduction1' },
    { 'name': 'Book name2', 'introduction': 'Book introduction2' },
    { 'name': 'Book name3', 'introduction': 'Book introduction3' }];
  return valuesBuckets;
}

// 将数据转换为BookModel数组,用于处理DA_HELPER返回的数据。
// 获取一个BookModel的数据列表
export function getListFromResultSet(resultSet) {
  let bookList = [];
  for (let i = 0;i < resultSet.rowCount; i++) {
    //按照构造函数进行封装
    let book = new BookModel(
        resultSet.getDouble(resultSet.getColumnIndex('id'))
      , resultSet.getString(resultSet.getColumnIndex('name'))
      , resultSet.getString(resultSet.getColumnIndex('introduction')));
    //添加到列表中
    bookList.push(book);
  }
  return bookList;
}

let valuesBucket = { 'name': 'Book name', 'introduction': 'Book introduction' };
let valuesBuckets = [
    { 'name': 'Book name1', 'introduction': 'Book introduction1' },
    { 'name': 'Book name2', 'introduction': 'Book introduction2' },
    { 'name': 'Book name3', 'introduction': 'Book introduction3' }
];
  1. 调用insert方法向指定的Data子模块插入数据。

let bookList: Array<BookModel> = [];

let valuesBucket = { name: 'Book name', introduction: 'Book introduction' };
DA_HELPER.insert(BASE_URI, valuesBucket, predicates).then((data) => {
    console.log("DAHelper insert result: " + data);
    bookList.push({ id: data, name: 'Book name', introduction: 'Book introduction' });
}).catch((err) => {
    console.log('DAHelper insert fail: ' + err);
});
  1. 调用delete方法删除Data子模块中指定的数据。

let book: BookModel = null;

predicates.equalTo('id', book.id);
DA_HELPER.delete(BASE_URI, predicates).then((data) => {
    console.log("DAHelper delete result: " + data);
}).catch((err) => {
    console.log('DAHelper delete fail: ' + err);
});
  1. 调用update方法更新指定Data子模块中的数据。

let book: BookModel = null;

predicates.equalTo('id', book.id);
let valuesBucket = {
    'name': book.name,
    'introduction': book.introduction
};
DA_HELPER.update(BASE_URI, valuesBucket, predicates).then((data) => {
    console.log("DAHelper update result: " + data);
}).catch((err) => {
    console.log('DAHelper update fail: ' + err);
});
  1. 调用query方法在指定的Data子模块中查找数据。

let bookList: Array<BookModel> = [];

//根据名字或介绍模糊匹配
predicates.contains('name', 'Book name1')
	.or()
    .contains('introduction', 'Book introduction1');
DA_HELPER.query(BASE_URI, COLUMNS, predicates).then((data) => {
    console.log("DAHelper query result: " + data);
    bookList = getListFromResultSet(resultSet);
}).catch((err) => {
    console.log('DAHelper query fail: ' + err);
});
  1. 调用batchInsert方法向指定的数据子模块批量插入数据。

let valuesBuckets = initValuesBuckets();

DA_HELPER.batchInsert(BASE_URI, valuesBuckets, predicates).then((data) => {
    console.log("DAHelper batchInsert result: " + data);
}).catch((err) => {
    console.log('DAHelper batchInsert fail: ' + err);
});

Stage模型

Ability开发指导

开发Stage模型应用时,需要在module.json5和app.json配置文件中对应用的包结构进行声明。基于Stage模型的Ability应用开发,主要涉及如下功能逻辑:

  • 创建支持使用屏幕浏览及人机交互的Ability应用,包括实现Ability的生命周期、获取Ability配置信息、向用户申请授权及环境变化通知等场景。

  • 启动Ability应用,包括相同设备启动Ability、跨设备启动Ability以及指定页面启动Ability等场景。

  • 通用组件Call功能。

  • 连接、断开ServiceExtensionAbility。

  • 应用迁移。

创建Ability
  1. 点击Create Project,选择OpenHarmony下的Empty Ability模板,点击Next进行下一步配置。在工程配置项中, "Compile API"选择"9","Model"默认为"Stage",其他参数可保持默认设置。点击Finish,工具会自动生成示例代码和相关资源,等待工程创建成功。

  1. 工程创建成功后生成默认的Ability,名为MainAbility。

 

启动Ability

应用可以通过this.context获取Ability实例的上下文,进而使用AbilityContext中的StartAbility相关接口启动Ability。启动Ability由Wan传递bundleName和abilityName属性,通过callback形式或promise形式实现。

  • bundleName:表示包名称。可在AppScope->app.json5中查看bundleName,或者通过File->Project Structure查看。

  • abilityName:表示待启动的Ability名称。

启动本地设备Ability示例如下:

// MainAbility.ts
import hilog from '@ohos.hilog';
import Ability from '@ohos.application.Ability';
import Window from '@ohos.window';

export default class MainAbility extends Ability {
    ...
    onWindowStageCreate(windowStage: Window.WindowStage) {
        // Main window is created, set main page for this ability
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
        
        // want参数配置
		let want = {
            bundleName: "com.samples.myapplication",
            abilityName: "MainAbility"
        };
        // 拉起指定的Ability
        this.context.startAbility(want).then((data) => {
            console.log("Succeed to start ability with data: " + JSON.stringify(data))
        }).catch((error) => {
            console.error("Failed to start ability with error: " + JSON.stringify(error))
        });

        windowStage.loadContent('pages/index', (err, data) => {
            if (err.code) {
                hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.ERROR);
                hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
                return;
            }
            hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
            hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
        });
    }
	...
};

ExtensionAbility机制

ExtensionAbility是Stage模型中新增的扩展组件的基类,一般用于处理无界面的任务,生命周期较简单,没有前后台生命周期。

不同于用于页面展示的Ability,ExtensionAbility提供的是一种受限的服务运行环境。ExtensionAbility具有如下特点:

  • 独立于主进程的单独进程运行,与主进程无IPC,共享一个存储沙箱。

  • 独立的Context提供基于业务场景的api能力。

  • 由系统触发创建,应用不能直接创建。

  • ExtensionAbility和进程的生命周期受系统管理。

ServiceExtensionAbility开发指导

ServiceExtensionAbility是ExtensionAbility的扩展类。开发者可以自定义类继承ServiceExtensionAbility,通过重写基类中相关生命周期方法,来做初始化、连接中、断开连接时相关业务逻辑操作。

接口说明

ServiceExtensionAbility中相关生命周期API功能介绍

接口名 描述
onCreate(want: Want): void 首次调用startAbility、connectAbility时触发,执行初始化业务逻辑操作。
onRequest(want: Want, startId: number): void 每次调用startAbility拉起服务都会触发,首次调用时startId为1,重复调用时startId会递增。
onConnect(want: Want): rpc.RemoteObject 调用connectAbility拉起服务时触发,重复调用不会再次触发,除非调用disconnectAbility解除绑定后再调用;onConnect返回一个进程通信类RemoteObject,用于和客户端进行通信。
onDestroy(): void 调用停止当前Ability的接口terminateSelf时触发,执行资源清理等操作。
onDisconnect(want: Want): void 调用disconnectAbility断开服务连接时触发,Extension如果是用connectAbility拉起的,并且已经没有其他应用绑定这个Extension,则会触发onDestroy生命周期销毁组件。
创建与注册ServiceExtensionAbility
  1. 在ets目录下选择New->Directory创建ServiceExtAbility目录,然后在ServiceExtAbility目录选择New->ts File创建ServiceExtAbility.ts文件。

 

  1. 在ServiceExtAbility.ts文件中自定义类继承ServiceExtensionAbility,重写基类回调函数。

说明:'@ohos.application.ServiceExtensionAbility'模块从SDK 3.2.5.5版本起,被提取到了full-sdk当中,使用时需手动下载并安装full-sdk。

// ServiceExtAbility.ts
import ServiceExtensionAbility from '@ohos.application.ServiceExtensionAbility';

export default class ServiceExtAbility extends ServiceExtensionAbility {
    onCreate(want) {
        console.log(`onCreate, want: ${want.abilityName}`);
    }
    onRequest(want, startId) {
        console.log(`onRequest, want: ${want.abilityName}`);
    }
    onConnect(want) {
        console.log(`onConnect , want: ${want.abilityName}`);
        return null;
    }
    onDisconnect(want) {
        console.log(`onDisconnect, want: ${want.abilityName}`);
    }
    onDestroy() {
        console.log(`onDestroy`);
    }
}
  1. 注册ServiceExtensionAbility。在配置文件module.json5中进行注册,手动添加"extensionAbilities"配置项,将注册类型type设置为service。

module.json5配置样例

"module": {
    ...
    "extensionAbilities": [
        {
        	"name": "ServiceExtAbility",
            "srcEntrance": "./ets/ServiceExtAbility/ServiceExtAbility.ts",
        	"icon": "$media:icon",
        	"description": "service",
        	"type": "service",
        	"visible": true     	
    	}
    ]
    ...
}
启动ServiceExtensionAbility

应用通过this.context获取Ability实例的上下文,调用startAbility()方法来启动本地ServiceExtensionAbility,该方法的Want传递bundleName和abilityName属性。将this.context挂载到全局对象globalThis上,用于外部自定义方法调用AbilityContext中的startAbility接口。

启动本地设备ServiceExtensionAbility示例如下:

// index.ets
@Entry
@Component
struct Index {
    private context = getContext(this) as any;

    startService() {
        // want参数配置
        let want = {
      		bundleName: "com.samples.myapplication",
      		abilityName: "ServiceExtAbility"
    	};
        // 拉起指定的ServiceExtensionAbility
        this.context.startAbility(want).then((data) => {
            console.log(`startAbility success: ${JSON.stringify(data)}`);
        }).catch((error) => {
            console.error(`startAbility failed: ${JSON.stringify(error)}`);
        })
    }

    build() {
        ...
    }
}
连接ServiceExtensionAbility

由this.context获取Ability实例的上下文,调用connectAbility方法连接本地ServiceExtensionAbility,由该方法的Want传递连接目标的bundleName和abilityName属性,ConnectOptions远程对象实例提供onConnect()、onDisconnect()和onFailed()方法,用于监听不同连接状态并回调。

创建连接本地ServiceExtensionAbility回调实例以及连接本地ServiceExtensionAbility的示例如下:

import prompt from '@ohos.prompt';
// 导入rpc进程通信模块
import rpc from '@ohos.rpc';

connectService() {
    // ConnectOptions远程对象实例
    let connectOptions = {
        // 连接成功时回调
        onConnect: function onConnectCallback(element, proxy) {
            console.log(`onConnectLocalService onConnectDone element:${element} proxy:${proxy}`);
            if (proxy === null) {
                prompt.showToast({
                    message: 'Connect service failed'
                })
                return;
            }
            // 携带客户端调用参数的MessageParcel对象
            let data = rpc.MessageParcel.create();
            // 接收应答数据的MessageParcel对象
            let reply = rpc.MessageParcel.create();
            // 本次请求的同异步模式,默认为TF_SYNC同步调用
            let option = new rpc.MessageOption();
            // 将两个整数值写入MessageParcel实例
            data.writeInt(100);
            data.writeInt(200);
            // 以同步模式向服务端发送MessageParcel消息,发送的消息代码为1,同步模式下该接口将等待服务端的响应,直到请求超时,响应的结果在reply中
            proxy.sendRequest(1, data, reply, option).then((result) => {
                console.log(`sendRequest: ${result}`);
                // 客户端以reply从MessageParcel实例中读取服务端处理后的整数值
                let msg = reply.readInt();
                console.log(`sendRequest msg: ${msg}`);
            }).catch((err) => {
                console.log(`sendRequest error: ${err}`);
            });
            prompt.showToast({
                message: "Connect service success"
            })
        },
        // 连接断开时回调
        onDisconnect: function onDisconnectCallback(element) {
            console.log(`onConnectLocalService onDisconnectDone element:${element}`);
            prompt.showToast({
                message: "Disconnect service success"
            })
        },
        // 连接失败时回调
        onFailed: function onFailedCallback(code) {
            console.log(`onConnectLocalService onFailed errCode:${code}`);
            prompt.showToast({
                message: "Connect local service onFailed"
            })
        }
    }
    // want参数配置
    let want = {
        bundleName: 'com.samples.myapplication',
        abilityName: 'ServiceExtAbility'
    };
    // 连接指定的ServiceExtensionAbility
    this.context.connectAbility(want, connectOptions);
}

ServiceExtensionAbility服务端通过继承rpc.RemoteObject来创建自定义的实现类StubTest,在onConnect()中返回RemoteObject对象与描述符参数。在StubTest类中调用onRemoteRequest()方法响应客户端发送的请求,并对数据作处理。

Service服务端把自身的实例返回给调用侧的代码示例如下:

// ServiceExtAbility.ts
import ServiceExtensionAbility from '@ohos.application.ServiceExtensionAbility';
import rpc from '@ohos.rpc';

// 实现远程对象,服务提供者必须继承RemoteObject类
class StubTest extends rpc.RemoteObject {
    // 用于创建RemoteObject实例的构造函数,参数des为指定接口描述符
    constructor(des) {
        super(des);
    }
    // sendRequest请求的响应处理函数,服务端在该函数里处理请求,回复结果
    onRemoteRequest(code, data, reply, option) {
        console.log(`onRemoteRequest`);
        // 判断客户端发送过来的消息代码是否为1
        if (code === REQUEST_VALUE) {
            // 从MessageParcel实例中读取由客户端写入的整数值
            let dataFirst = data.readInt();
            let dataSecond = data.readInt();
            // 将读取的整数值相加并写入MessageParcel实例
            reply.writeInt(dataFirst + dataSecond);
            console.log(`onRemoteRequest: dataFirst: ${dataFirst}, dataSecond: ${dataSecond}`);
        }
        return true;
    }
}

export default class ServiceExtAbility extends ServiceExtensionAbility {
    onCreate(want) {
        console.log(`onCreate, want: ${want.abilityName}`);
    }
    onRequest(want, startId) {
        console.log(`onRequest, want: ${want.abilityName}`);
    }
    onConnect(want) {
        console.log(`onConnect , want: ${want.abilityName}`);
        // 返回RemoteObject对象与描述符
        return new StubTest("test");
    }
    onDisconnect(want) {
        console.log(`onDisconnect, want: ${want.abilityName}`);
    }
    onDestroy() {
        console.log(`onDestroy`);
    }
}

Ability间的跳转

应用场景描述

实现Ability之间的跳转将调用startAbility()方法,此方法根据want参数传递Abillity名称,拉起指定的Ability,达到跳转效果。

说明:Ability跳转效果需在设备上验证。

FA模型Ability跳转

  1. 在工程中,选择File->New->Ability->Page Ability,新建一个PageAbility命名为MainAbilitySecond,并在其pages目录选择New->Page新建second.ets页面。目录结构如下:

 

  1. 在MainAbility/pages/index.ets中导入featureAbility模块。

import featureAbility from '@ohos.ability.featureAbility';
  1. 在MainAbility/pages/index.ets页面添加Button组件,给Butom添加文本、样式和点击事件,在点击事件中调用featureAbility.startAbility拉起指定的Ability实现跳转。startAbility中的want参数主要传递bundleName和abilityName,在want中添加parameters参数,设置路由url为指定页面,点击Button按钮即可跳转到MainAbilitySecond的指定页面。

说明:want中如果不添加parameters参数,则默认指向Ability的index页面。

// MainAbility/pages/index.ets
import featureAbility from '@ohos.ability.featureAbility';

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        Button() {
          Text('to MainAbilitySecond')
            .fontSize(25)
            .fontWeight(FontWeight.Bolder)
        }
        .height(60)
        .onClick(() => {
          let parameter = {
            want: {
              bundleName: "com.samples.myapplication",
              // FA模型abilityName由config.json中的package + Ability name组成
              abilityName: "com.samples.myapplication.MainAbilitySecond",
              parameters: {
                url: 'pages/second'
              }
            }
          }
          featureAbility.startAbility(parameter).then((data) => {
            console.info('startAbility successful. Data: ' + JSON.stringify(data))
          }).catch((error) => {
            console.error('startAbility failed. Cause: ' + JSON.stringify(error))
          })
        })
      }
      .width('100%')
    }
    .height('100%')
  }
}

Stage模型Ability跳转

  1. 在工程中,选择File->New->Ability,新建一个Ability命名为MainAbilitySecond,在pages目录选择New->Page新建second.ets。目录结构如下:

  1. 将MainAbilitySecond.ts页面中loadContent方法加载的主页面改为pages/second,与MainAbility中加载的index主页面区分开。

// MainAbilitySecond.ts
import hilog from '@ohos.hilog';
import Ability from '@ohos.application.Ability'
import Window from '@ohos.window'

export default class MainAbilitySecond extends Ability {
    ...
    onWindowStageCreate(windowStage: Window.WindowStage) {
        // Main window is created, set main page for this ability
        hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
        
        // 默认指向pages/index,这里修改为pages/second
        windowStage.loadContent('pages/second', (err, data) => {
            if (err.code) {
                hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.ERROR);
                hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
                return;
            }
            hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO);
            hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
        });
    }
	...
}
  1. 在MainAbility/pages/index.ets页面添加Button组件,给Butom添加文本、样式和点击事件,创建context对象获取应用上下文, 并调用startAbility拉起指定的Ability实现跳转。其中startAbility的want参数传递bundleName和abilityName。

// MainAbility/pages/index.ets
@Entry
@Component
struct Index {
  private context = getContext(this) as any;

  build() {
    Row() {
      Column() {
        Button() {
          Text('to MainAbilitySecond')
            .fontSize(25)
            .fontWeight(FontWeight.Bolder)
        }
        .height(60)
        .onClick(() => {
          let want = {
            bundleName: "com.samples.myapplication",
            abilityName: "MainAbilitySecond"
          }
          this.context.startAbility(want).then((data) => {
            console.info('startAbility successful. Data: ' + JSON.stringify(data))
          }).catch((error) => {
            console.error('startAbility failed. Cause: ' + JSON.stringify(error))
          })
        })
      }
      .width('100%')
    }
    .height('100%')
  }
}

Ability生命周期

生命周期差异对比

FA模型与Stage模型的Ability生命周期存在差异:

生命周期接口说明

FA模型生命周期回调函数

接口名 描述
onCreate() Ability第一次启动创建Ability时调用onCreate方法,开发者可以在该方法里做一些应用初始化工作。
onActive() Ability切换到前台,并且已经获取焦点时调用onActive方法。
onInactive() Ability失去焦点时调用onInactive方法,Ability在进入后台状态时会先失去焦点,再进入后台。
onHide() Ability由前台切换到后台不可见状态时调用onHide方法,此时用户在屏幕看不到该Ability。
onShow() Ability由后台不可见状态切换到前台可见状态调用onShow方法,此时用户在屏幕可以看到该Ability。
onDestroy() 应用退出,销毁Ability对象前调用onDestroy方法,开发者可以在该方法里做一些回收资源、清空缓存等应用退出前的准备工作。

Stage模型生命周期回调函数

接口名 描述
onCreate(want: Want, param: AbilityConstant.LaunchParam): void Ability生命周期回调,Ability启动时被调用。
onWindowStageCreate(windowStage: window.WindowStage): void Ability生命周期回调,创建window stage时被调用,应用开发者可通过window.WindowStage的接口执行页面加载等操作。
onForeground(): void Ability生命周期回调,Ability切换至前台时被调用。
onBackground(): void Ability生命周期回调,Ability切换至后台时被调用。
onWindowStageDestroy(): void Ability生命周期回调,销毁window stage时被调用。
onDestroy(): void Ability生命周期回调,Ability销毁时被调用。

Ability启动模式

FA模型启动模式

FA模型Ability支持单实例和多实例两种启动模式,在config.json中通过launchType配置项,配置具体的启动模式;如果不配置,则默认为standard模式。

启动模式 描述 说明
singleton 单实例 系统中只存在唯一一个实例,startAbility时,如果已存在,则复用系统中的唯一一个实例。
standard 多实例 每次startAbility调用都会启动一个新的实例。

Stage模型启动模式

Stage模型Ability支持单实例、多实例和指定实例3种启动模式,在module.json5中默认没有launchType配置项,需手动添加;如果不添加,则默认为singleton模式。

启动模式 描述 说明
singleton 单实例 系统中只存在唯一一个实例,startAbility时,如果已存在,则复用系统中的唯一一个实例。
standard 多实例 每次startAbility调用都会启动一个新的实例。
specified 指定实例 运行时由ability内部业务决定是否创建多实例。

module.json5示例:

{
  "module": {
    "abilities": [
      {
        ...
        "launchType": "standard"
        ...
      }
    ]
  }
}

参考文献

[1] OpenHarmony Ability开发. https://gitee.com/openharmony/docs/tree/master/zh-cn/application-dev/ability

[2] OpenHarmony接口开发. https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/Readme-CN.md#/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-inputmethod-extension-ability.md

 

Logo

社区规范:仅讨论OpenHarmony相关问题。

更多推荐