OpenHarmony应用开发-FA模型切换Stage模型指导

素年锦时静待君丶
发布于 2023-4-11 16:41
浏览
1收藏

版本:v3.2 Beta5

模型切换概述

本文介绍如何将一个FA模型开发的声明式范式应用切换到Stage模型,您需要完成如下动作:

  • 工程切换:新建一个Stage模型的应用工程。

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

  • ​组件切换​​:PageAbility/ServiceAbility/DataAbility切换为UIAbility和ExtensionAbility(图片仅展示了FA模型的PageAbility切换成Stage模型的UIAbility:下图左侧为FA模型,app.ets为FA模型的PageAbility组件;下图右侧为Stage模型,EntryAbility.ts为Stage模型的UIAbility组件)。

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

  • ​卡片切换​:将FA模型的FormAbility切换为Stage模型的FormExtensionAbility(下图中的Service Widget在FA中为FormAbility,在Stage中为FormExtensionAbility)。

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

  • ​API切换​:将FA模型应用中使用到的FAModelOnly接口切换为Stage模型下的推荐接口和写法。

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

配置文件的差异

FA模型应用在​​config.json文件​​中描述应用的基本信息,一个应用工程中可以创建多个Module,每个Module中都有一份config.json文件。config.json由app、deviceConfig和module三部分组成,app标签用于配置应用级别的属性,如果一个应用有多个Module,需要由开发者保证各个config.json文件中app标签配置的一致性。

Stage模型应用在​​app.json5​​​和​​module.json​​文件中描述应用的基本信息,和FA模型应用类似,一个Stage模型应用工程中同样可以创建多个[Module],但是一个应用工程中仅存在一份app.json5,用于配置应用级别的属性,对每个Module都生效;每个Module中都有一份module.json5配置文件,用于配置Module级别的属性,仅对当前Module生效。

图1 配置文件差异

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

app和deviceConfig的切换

为了便于开发者维护应用级别的属性配置,Stage模型将config.json中的app和deviceConfig标签提取到了app.json5中进行配置,并对部分标签名称进行了修改,具体差异见下表。

表1 配置文件app标签差异对比

配置项

FA模型配置文件config.json中app标签

Stage模型配置文件app.json5中app标签

应用的版本号

“version”: {

“code”: 1,

}

“versionCode”: 1 ,

标识版本号的文字描述,用于向用户展示

“version”: {

“name”: “1.0.0”,

}

“versionName” : “1.0.0” ,

标识应用可兼容的最低版本号

“version”: {

“minCompatibleVersionCode”: 1,

}

“minCompatibleVersionCode” : 1 ,

运行应用所需要的最低API版本

“apiVersion”: {

“compatible”: 7,

}

“minAPIVersion” : 7 ,

应用运行所需的目标API版本

“apiVersion”: {

“target”: 8,

}

“targetApiVersion” : 8 ,

应用运行所需的目标API版本的类型

“apiVersion”: {

“releaseType”: Release,

}

“apiReleaseType”: “Release” ,

app.json5中对原先config.json中的​​deviceConfig​​​标签进行了重构,将deviceConfig下的标签的设备信息整合到了​​app.json5​​的app标签下,具体差异见下表

表2 配置文件deviceConfig标签差异对比

FA中deviceConfig标签

描述

stage模型中

差异比对

deviceConfig标签

deviceConfig标签配置了设备信息

/

Stage模型中没有该标签,直接在app标签下配置设备信息

process

标识应用或者Ability的进程名。如果在deviceConfig标签下配置了process标签,则该应用的所有Ability都运行在这个进程中。如果在abilities标签下也为某个Ability配置了process标签,则该Ability就运行在这个进程中。

/

Stage模型不支持配置进程名称

keepAlive

标识应用是否始终保持运行状态,仅支持系统应用配置,三方应用配置不生效。

/

Stage模型不支持系统应用模型管控方式变更

supportBackup

标识应用是否支持备份和恢复。

/

Stage模型不支持

compressNativeLibs

标识libs库是否以压缩存储的方式打包到HAP包。

/

Stage模型不支持

network

标识网络安全性配置。

/

Stage模型不支持

module的切换

从FA模型切换到Stage模型时,开发者需要将config.json文件module标签下的配置迁移到module.json5配置文件module标签下,具体差异见下列表格。

表1 FA模型module标签与Stage模型module标签差异对比

FA标签

标签说明

对应的Stage标签

差异说明

mainAbility

服务中心图标露出的ability,常驻进程拉起时会启动mainAbility。

mainElement

标签名称变更,Stage模型不在使用.符号。

package

标识HAP的包结构名称,在应用内保证唯一性。

/

Stage模型使用name来保证应用唯一性。

name

标识HAP的类名

/

FA模型中实际未使能,Stage模型没有与之对应的标签。

supportedModes

标识应用支持的运行模式,当前只定义了驾驶模式(drive)

/

Stage模型已废弃。

distro对象中的moduleName

标识当前HAP的名称

distro对象中的moduleName

name

标签变更。

distro对象中的moduleType

标识当前HAP的类型,包括两种类型:entry和feature。另外,如果表示HAR包类型,请设置为har

type

标签变更。

distro对象中的installationFree

标识当前HAP是否支持免安装特性

installationFree

标签变更。

distro对象中的deliveryWithInstall

标识当前HAP是否支持随应用安装

deliveryWithInstall

标签变更。

metaData

标识HAP的元信息

metadata

具体差异如​​表2​​。

abilities

标识当前模块内的所有Ability

abilities

具体差异如​​表5​​。

js

标识基于ArkUI框架开发的JS模块集合,其中的每个元素代表一个JS模块的信息

pages

Stage模型在module标签下保留该对象中的pages,window配置与pages的下一级。

shortcuts

标识应用的快捷方式信息

shortcut_config.json文件

在开发视图的resources/base/profile下面定义配置文件shortcut_config.json。

reqPermissions

标识应用运行时向系统申请的权限

requestPermissions

标签名称变更。

colorMode

标识应用自身的颜色模式

/

Stage模型不支持。

distroFilter

标识应用的分发规则

distroFilter_config.json文件

Stage模型在开发视图的resources/base/profile下面定义配置文件distroFilter_config.json。

reqCapabilities

标识运行应用程序所需的设备能力

/

Stage模型不支持。

commonEvents

公共事件

common_event_config.json文件

Stage模型在开发视图的resources/base/profile下面定义配置文件common_event_config.json。

entryTheme

此标签标识OpenHarmony内部主题的关键字

/

Stage模型不支持。

表2 FA模型metaData和Stage中metadata对比

FA标签

标签说明

对应的Stage模型标签

差异对比

parameters

标识调用Ability时所有调用参数的元信息

/

Stage模型不支持。

results

标识Ability返回值的元信息

/

Stage模型不支持。

customizeData

该标签标识父级组件的自定义元信息,Parameters和results在application不可配

metadata

具体差异见​​表3​​。

表3 FA模型metaData的customizeData和Stage中metadata对比

FA标签

标签说明

对应的Stage模型标签

差异对比

name

标识数据项的键名称。字符串最大长度为255字节

name

无。

value

标识数据项的值。字符串最大长度为255字节。

value

无。

extra

标识当前custom数据的格式,取值为表示extra的资源值。

resource

标签变更。具体实例见​​表4​​。

表4 FA模型metaData和Stage中metadata示例

FA模型示例

Stage模型示例

“meteData”: {

“customizeDate”: [{

“name”: “label”,

“value”: “string”,

“extra”: “$string:label”,

}]

}

“meteData”: [{

“name”: “label”,

“value”: “string”,

“resource”: “$string:label”,

}]

表5 FA模型和Stage中abilities差异对比

FA模型的abilities对象标签

描述

Stage模型中abilities对象标签

差异对比

process

运行应用程序或Ability的进程名称

/

Stage模型不支持abilities中配置,在module标签下配置process

uri

标识Ability的统一资源标识符

/

Stage模型不支持

deviceCapability

标识Ability运行时要求设备具有的能力,采用字符串数组的格式表示

/

Stage模型不支持

metaData

该标签标识ability的元信息。

metadata

具体差异如​​表2​

type

标识Ability的类型

/

Stage模型不支持

grantPermission

指定是否可以向Ability内任何数据授予权限

/

abilities内不支持;

readPermission

标识读取Ability的数据所需的权限。该标签仅适用于data类型的Ability

/

abilities内不支持;在extensionAbilities标签中支持

writePermission

标识向Ability写数据所需的权限

/

abilities内不支持;在extensionAbilities标签中支持

configChanges

标识Ability关注的系统配置集合

/

Stage模型不支持

mission

标识Ability指定的任务栈

/

Stage模型不支持

targetAbility

标识当前Ability重用的目标Ability

/

Stage模型不支持

multiUserShared

标识Ability是否支持多用户状态进行共享,该标签仅适用于data类型的Ability

/

Stage模型不支持

supportPipMode

标识Ability是否支持用户进入PIP模式(用于在页面最上层悬浮小窗口,俗称"画中画",常见于视频播放等场景)

/

Stage模型不支持

formsEnabled

标识Ability是否支持卡片(forms)功能

/

Stage模型不支持

forms

标识服务卡片的属性。该标签仅当formsEnabled为"true"时,才能生效

form_config.json文件

Stage模型在开发视图的resources/base/profile下面定义配置文件form_config.json

srcLanguage

Ability开发语言的类型

/

Stage模型不支持

srcPath

该标签标识Ability对应的JS组件代码路径

srcEntrance

该标签标识ability所对应的js代码路径。

uriPermission

标识该Ability有权访问的应用程序数据

/

Stage模型不支持

PageAbility切换

FA模型中PageAbility对应Stage模型中的UIAbility。切换步骤如下。

  1. 在Stage应用中​​创建UIAbility​​。
  2. 将FA应用中PageAbility的代码迁移到新创建的UIAbility中。 FA应用中PageAbility和Stage应用中的UIAbility生命周期基本一致,两者的生命周期详细对比见下表。

FA的PageAbility

Stage的UIAbility

对应关系描述

onCreate(): void

onCreate(want: Want, param: AbilityConstant.LaunchParam): void

两者的意义和调用时机一致,Stage模型在回调中新增了参数,方便开发者在创建的时候获取启动相关的数据。

NA

onWindowStageCreate(windowStage: window.WindowStage): void

Stage模型新增,窗口创建时由系统回调。

onActive(): void

on(eventType: ‘windowStageEvent’, callback: Callback<WindowStageEventType>): void;

WindowStageEventType.ACTIVE

两者的意义和调用时机一致。Stage模型下移动到了窗口对象中。

onShow(): void

onForeground(): void

两者的意义和调用时机一致,参数也一致。

onNewWant(want: Want): void

onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void

两者的意义和调用时机一致,Stage模型多了LaunchParam参数来告知应用启动原因。

onInactive(): void

on(eventType: ‘windowStageEvent’, callback: Callback<WindowStageEventType>): void;

WindowStageEventType.INACTIVE

两者的意义和调用时机一致。Stage模型下移动到了窗口对象中。

onHide(): void

onBackground(): void

两者的意义和调用时机一致,参数也一致。

NA

onWindowStageDestroy(): void

Stage模型新增,窗口销毁时由系统回调。

onDestroy(): void

onDestroy(): void

两者的意义和调用时机一致,参数也一致。

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

  1. 对迁移过来的代码进行调整,主要有以下两部分。 1、指定加载页面的方式不同。
  • 在FA模型中,通过在config.json中设置页面信息来配置需要加载的页面。
  • 在Stage模型中,则是通过在onWindowStageCreate回调中调用windowStage.loadContent实现对页面的加载。

例如,开发者希望Ability启动后加载"pages/Index"页面,在FA模型中,开发者需要在config.json中加入如下代码:

"pages" : [
    "pages/Index"
]

在Stage模型中,则在MainAbility中实现如下接口:

import Window from '@ohos.window'

onWindowStageCreate(windowStage: Window.WindowStage) {
    // Main window is created, set main page for this ability
    windowStage.loadContent('pages/Index', (err, data) => {
        if (err.code) {
            console.error("loadContent failed")
            return;
        }
    });
}

ServiceAbility切换

FA模型中的ServiceAbility对应Stage模型中的ServiceExtensionAbility。Stage模型下的ServiceExtensionAbility为系统API,只有系统应用才可以创建。因此,FA模型的ServiceAbility的切换,对于系统应用和三方应用策略有所不同。下面分别介绍这两种场景。

系统应用ServiceAbility切换

目前系统提供了ServiceExtensionAbility供系统应用使用。切换步骤和PageAbility基本一致。

  1. 在Stage应用中​​创建ServiceExtensionAbility​​。
  2. 将FA应用中ServiceAbility的业务代码迁移到新创建的ServiceExtensionAbility中。 ServiceAbility和ServiceExtensionAbility生命周期对比见下表。

FA的ServiceAbility

Stage的ServiceExtensionAbility

对比描述

onStart(): void

onCreate(want: Want): void

两者调用时机一致,Stage模型下增加了入参want以便开发者在创建时获取参数。

onCommand(want: Want, startId: number): void

onRequest(want: Want, startId: number): void

两者意义和调用时机一致,参数也一致。

onConnect(want: Want): rpc.RemoteObject

onConnect(want: Want): rpc.RemoteObject

两者意义和调用时机一致,参数也一致。

onDisconnect(want: Want): void

onDisconnect(want: Want): void

两者意义和调用时机一致,参数也一致。

onReconnect(want: Want): void

onReconnect(want: Want): void

两者意义和调用时机一致,参数也一致。

onStop(): void

onDestroy(): void

两者意义和调用时机一致,参数也一致。

三方应用ServiceAbility切换

Stage模型下三方应用不能对其他三方提供服务,应用可以根据具体业务选择切换方案。

业务类型

切换策略

对其他三方应用提供服务

需根据业务场景匹配到系统对应的场景化​​ExtensionAbility​​。

应用内:前台运行时公共使用

可以将该组件代码抽取成公共模块供其他组件使用。

应用内:进入后台时继续运行

可以将此服务切换为​​后台任务​​,可参考如下示例。

DataAbility切换

FA模型中的DataAbility对应Stage模型中的DataShareExtensionAbility。

与ServiceExtensionAbility类似,Stage模型下的DataShareExtensionAbility为系统API,只有系统应用才可以创建。因此,FA模型的DataAbility的切换,对于系统应用和三方应用策略有所不同。下面分别介绍这两种场景。

系统应用DataAbility切换至DataShareExtensionAbility

迁移步骤和PageAbility基本一致。

  1. 在Stage应用中创建DataShareExtensionAbility。
  2. 将FA应用中DataAbility的业务代码迁移到新创建的DataShareExtensionAbility中。 DataAbility和DataShareExtensionAbility生命周期对比见下表。

FA的DataAbility

Stage的DataShareExtensionAbility

对比描述

onInitialized?(info: AbilityInfo): void

onCreate?(want: Want, callback:

AsyncCallback<void>): void

两者调用时机一致,函数名即入参都不一样,Stage模型下增加了入参want以便开发者在创建时获取参数。

update?(uri: string, valueBucket: rdb.ValuesBucket, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void

update?(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void

两者意义和调用时机一致,参数顺序和参数类型略有不同,需要简单改造。

query?(uri: string, columns: Array<string>, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<ResultSet>): void

query?(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void;

两者意义和调用时机一致,参数顺序和参数类型略有不同,需要简单改造。

delete?(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void

delete?(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):

两者意义和调用时机一致,参数类型略有不同,需要简单改造。

normalizeUri?(uri: string, callback: AsyncCallback<string>): void

normalizeUri?(uri: string, callback: AsyncCallback<string>): void

两者意义和调用时机一致,参数也一致。

batchInsert?(uri: string, valueBuckets: Array<rdb.ValuesBucket>, callback: AsyncCallback<number>): void

batchInsert?(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void

两者意义和调用时机一致,参数类型略有不同,需要简单改造。

denormalizeUri?(uri: string, callback: AsyncCallback<string>): void

denormalizeUri?(uri: string, callback: AsyncCallback<string>): void

两者意义和调用时机一致,参数也一致。

insert?(uri: string, valueBucket: rdb.ValuesBucket, callback: AsyncCallback<number>): void

insert?(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void

两者意义和调用时机一致,参数类型略有不同,需要简单改造。

openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void

NA

Stage模型不支持uri跨进程访问,建议通过​​want携带FD和文件信息​​进行跨进程文件访问

getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void

NA

Stage模型不支持uri跨进程访问,建议通过​​want携带FD和文件信息​​进行跨进程文件访问

getType?(uri: string, callback: AsyncCallback<string>): void

NA

Stage模型不支持uri跨进程访问,建议通过​​want携带FD和文件信息​​进行跨进程文件访问

executeBatch?(ops: Array<DataAbilityOperation>, callback: AsyncCallback<Array<DataAbilityResult>>): void

NA

DataShareExtensonAbility不提供该接口,开发者需根据业务功能重新实现。

call?(method: string, arg: string, extras: PacMap, callback: AsyncCallback<PacMap>): void

NA

DataShareExtensonAbility不提供该接口,开发者需根据业务功能重新实现。

三方应用DataAbility改造为公共模块

Stage模型三方应用不能对其他三方提供数据,应用需要根据具体业务选择切换方案。

DataAbility业务类型

切换DataShareExtension策略

对三方提供数据

需根据业务场景匹配到系统对应的场景化​​ExtensionAbility​​。

应用内使用的数据

对应用内其他组件提供数据,建议提取公共模块。

卡片切换

卡片切换主要包含如下三部分:

  • 卡片页面布局:FA模型卡片和Stage模型卡片的布局都采用类web范式开发可以直接复用。
  • 卡片配置文件:FA模型的卡片配置在config.json中,Stage卡片配置在module.json5和form_config.json中(如下图1和图2)。
  • 卡片业务逻辑:FA模型和Stage模型在卡片入口文件以及生命周期存在细微的差异(如下图3和图4)。

配置项

FA模型

Stage模型

配置项位置

formAbility和forms配置都在config.json文件里

一级目录module.json5配置文件中配置extensionAbilities(针对formExtensionAbility的配置),二级目录form_config.json文件中配置forms(针对formExtensionAbility里包含的forms的详细配置)

卡片代码路径

srcPath,不带文件名

srcEntrance,带文件名

语言

srcLanguage支持配置为js或ets

无此配置项,只支持ets

是否使能卡片

formsEnabled

无,type配置项配置为form即使能

ability类型

type:service

type:form

二级目录配置标签

metadata:包含name、value、resource。其中resource用于指向卡片二级目录form_config.json文件的位置

入口配置差异示意图1:

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

卡片信息配置差异示意图2:

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

入口及生命周期

FA模型

Stage模型

入口文件

srcPath指向的目录下的form.ts

srcEntrance指向的文件

生命周期

export default

import FormExtension from ‘@ohos.app.form.FormExtensionAbility’;

export default class FormAbility extends FormExtension

入口文件差异示意图3:

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区

生命周期差异示意图4( 生命周期回调均一致,不需要调整):

OpenHarmony应用开发-FA模型切换Stage模型指导-鸿蒙开发者社区



文章转载自:​​https://docs.openharmony.cn/pages/v3.2Beta/zh-cn/application-dev/application-models/widget-switch.md/​

分类
已于2023-4-11 16:41:42修改
1
收藏 1
回复
举报
回复
    相关推荐