Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
OpenHarmony
Docs
提交
6076c518
D
Docs
项目概览
OpenHarmony
/
Docs
12 个月 前同步成功
通知
159
Star
292
Fork
28
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
D
Docs
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
未验证
提交
6076c518
编写于
3月 20, 2023
作者:
O
openharmony_ci
提交者:
Gitee
3月 20, 2023
浏览文件
操作
浏览文件
下载
差异文件
!16162 add AppRecovery enhance multi-mission recover function docs
Merge pull request !16162 from zhancaijin/master
上级
b207beea
e7d9b943
变更
5
隐藏空白更改
内联
并排
Showing
5 changed file
with
165 addition
and
13 deletion
+165
-13
zh-cn/application-dev/dfx/apprecovery-guidelines.md
zh-cn/application-dev/dfx/apprecovery-guidelines.md
+41
-10
zh-cn/application-dev/dfx/figures/20230315112155.png
zh-cn/application-dev/dfx/figures/20230315112155.png
+0
-0
zh-cn/application-dev/dfx/figures/20230315112235.png
zh-cn/application-dev/dfx/figures/20230315112235.png
+0
-0
zh-cn/application-dev/reference/apis/js-apis-app-ability-appRecovery.md
...ion-dev/reference/apis/js-apis-app-ability-appRecovery.md
+60
-3
zh-cn/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-ability.md
...otes/changelogs/OpenHarmony_4.0.5.2/changelogs-ability.md
+64
-0
未找到文件。
zh-cn/application-dev/dfx/apprecovery-guidelines.md
浏览文件 @
6076c518
...
...
@@ -5,29 +5,48 @@
应用在运行中不可避免会产生一些非预期的行为,如运行时抛出未处理的异常和错误,违反框架的调用/运行约束等。
系统默认对异常的处理方式为进程退出,如果应用使用过程中产生了用户数据,直接退出可能会导致用户工作中断,数据丢失。
如果
使用应用故障恢复相关接口,则可对临时数据进行保存,应用退出后会重启应用并恢复先前的状态和数据,能给用户带来更好的使用体验
。
如果
应用使能了应用恢复功能,并对临时数据进行保存,应用非预期退出后的下一次启动会恢复先前的状态和数据,给用户更连贯的使用体验。这里状态包括应用的页面栈以及onSaveState接口中保存的数据
。
目前该接口仅支持单进程单Ability的Stage模型应用开发。
API 9上的应用恢复接口支持单Ability的Stage模型应用开发。支持JsError故障时的状态保存与自动重启。
API 10在API 9的基础上新增支持多Ability的Stage模型应用开发。支持AppFreeze故障时的状态保存回调。支持应用被管控模式杀死后,下次启动的状态恢复。
## 接口说明
应用故障恢复接口由appRecovery模块提供,开发者可以通过import引入,详见
[
开发示例
](
#开发示例
)
。
本文档描述的为API9版本的接口行为,后续接口行为变更会更新本文档。
应用故障恢复接口由appRecovery模块提供,开发者可以通过import引入,详见
[
开发示例
](
#开发示例
)
。
### 应用恢复接口功能介绍
| 接口名称 | 说明 |
| ------------------------------------------------------------ | ---------------------------------------------------- |
| enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void; | 使能应用恢复功能。|
| saveAppState(): boolean; | 主动保存当前应用中Ability的状态。 |
| restartApp(): void; | 重启当前进程,如果有已经保存的Ability状态,会在Ability的OnCreate生命周期回调的want参数中的wantParam属性传入。 |
| enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void;
<sup>
9+
</sup>
| 使能应用恢复功能,参数按顺序填入。该接口调用后,应用从启动器启动时第一个Ability支持恢复。|
| saveAppState(): boolean;
<sup>
9+
</sup>
| 主动保存当前应用中支持恢复的Ability的状态。 |
| restartApp(): void;
<sup>
9+
</sup>
| 重启当前进程,并启动由
**setRestartWant**
指定的Ability,如果未指定,将重新拉起处于前台且支持恢复的Ability。 |
| saveAppState(context?: UIAbilityContext): boolean;
<sup>
10+
</sup>
| 主动保存由Context指定的Ability状态。 |
| setRestartWant(want: Want): void;
<sup>
10+
</sup>
| 设置主动调用
**restartApp**
以及
**RestartFlag**
不为
**NO_RESTART**
时重启的Ability。该Ability必须在同一个包名下,且必须为
**UiAbility**
。 |
由于
本接口为故障处理时使用,
不会返回异常,需要开发者熟悉使用的场景。
由于
上述接口可能在故障处理时使用,所以
不会返回异常,需要开发者熟悉使用的场景。
**enableAppRecovery:**
需要在应用初始化阶段调用,比如AbilityStage的OnCreate调用赋能。具体其各参数定义详见
[
参数说明
](
../reference/apis/js-apis-app-ability-appRecovery.md
)
。
**saveAppState:**
调用后框架会回调Ability的onSaveState方法,如果在onSaveState方法中同意保存数据,则会将相关数据及Ability的页面栈持久化到应用的本地缓存。
**saveAppState:**
调用后框架会回调
**当前进程中所有支持恢复的Ability**
的onSaveState方法,如果在onSaveState方法中同意保存数据,则会将相关数据及Ability的页面栈持久化到应用的本地缓存。如果需要保存指定Ability,则需要指定Ability对应的Context。
**setRestartWant:**
指定由appRecovery发起重启的Ability。
**restartApp:**
调用后框架会杀死当前应用进程,并重新拉起由
**setRestartWant**
指定的Ability,其中启动原因为APP_RECOVERY。API 9以及未使用
**setRestartWant**
指定Ability的场景,会拉起最后一个支持恢复且在前台的Ability,如果当前前台的Ability不支持恢复,则应用表现闪退。如果重启的Ability存在已经保存的状态,这些状态数据会在Ability的OnCreate生命周期回调的want参数中作为wantParam属性传入。
### 应用恢复状态管理示意
从API 10起,应用恢复的场景不仅局限于异常时自动重启。所以需要理解应用何时会加载恢复的状态。
一句话概括就是
**如果应用任务的上次退出不是由用户发起的,且应用存在用于恢复的状态,应用下一次由用户拉起时的启动原因会被设为APP_RECOVERY,并清理该任务的恢复状态。**
应用恢复状态标识会在状态保存接口主动或者被动调用时设置。在该任务正常退出或者消费了该状态时清理。正常退出目前包括用户按
**后退键退出**
以及用户
**清理最近任务**
。
![
应用恢复状态管理示意
](
./figures/20230315112155.png
)
**restartApp:**
调用后框架会杀死当前应用进程,并重新拉起处于前台的Ability,其中启动原因为APP_RECOVERY。
### 应用卡死的状态保存及恢复
API 10开始支持应用卡死时的状态保存。JsError故障时,onSaveState接口在主线程进行回调。对于AppFreeze故障,主线程可能处于卡死的状态,onSaveState会在非主线程进行回调。其主要流程如下图:
![
应用卡死状态保存恢复示意
](
./figures/20230315112235.png
)
由于卡死时的回调不在JS线程上执行,onSaveState回调中的代码建议不要使用import进来的Native动态库,禁止访问主线程创建的thread_local对象。
### 框架故障管理流程示意
...
...
@@ -52,7 +71,7 @@
| 故障名称 | 故障监听 | 状态保存 | 自动重启 | 日志查询 |
| ----------|--------- |--------- |--------- |--------- |
|
[
JS_CRASH
](
../reference/apis/js-apis-faultLogger.md#faulttype
)
| 支持|支持|支持|支持|
|
[
APP_FREEZE
](
../reference/apis/js-apis-faultLogger.md#faulttype
)
| 不支持|
不
支持|支持|支持|
|
[
APP_FREEZE
](
../reference/apis/js-apis-faultLogger.md#faulttype
)
| 不支持|支持|支持|支持|
|
[
CPP_CRASH
](
../reference/apis/js-apis-faultLogger.md#faulttype
)
| 不支持|不支持|不支持|支持|
这里状态保存指的是故障时状态保存,对于应用卡死场景,开发者可以采用定时保存状态或者在Ability切入后台后自动保存的方式最大限度的保护用户数据。
...
...
@@ -77,6 +96,18 @@ export default class MyAbilityStage extends AbilityStage {
appRecovery
.
SaveModeFlag
.
SAVE_WITH_FILE
);
}
}
```
### 配置支持恢复的Ability
Ability的配置清单一般的名字为module.json5。
```
json
{
"abilities"
:
[
{
"name"
:
"EntryAbility"
,
"recoverable"
:
true
,
}]
}
```
### 数据保存和恢复
...
...
zh-cn/application-dev/dfx/figures/20230315112155.png
0 → 100644
浏览文件 @
6076c518
38.6 KB
zh-cn/application-dev/dfx/figures/20230315112235.png
0 → 100644
浏览文件 @
6076c518
34.6 KB
zh-cn/application-dev/reference/apis/js-apis-app-ability-appRecovery.md
浏览文件 @
6076c518
...
...
@@ -4,7 +4,7 @@ appRecovery模块提供了应用在故障状态下的恢复能力。
> **说明:**
>
> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
当前版本仅支持单进程中单Ability的应用恢复
。
> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
API9仅支持单进程中单Ability的应用恢复。API10支持进程中包含多个Ability的场景
。
## 导入模块
```
ts
...
...
@@ -51,7 +51,7 @@ import appRecovery from '@ohos.app.ability.appRecovery';
enableAppRecovery(restart?:
[
RestartFlag
](
#apprecoveryrestartflag
)
, saveOccasion?:
[
SaveOccasionFlag
](
#apprecoverysaveoccasionflag
)
, saveMode?:
[
SaveModeFlag
](
#apprecoverysavemodeflag
)
) : void;
使能应用恢复功能,参数按顺序填入。
使能应用恢复功能,参数按顺序填入。
该接口调用后,应用从启动器启动时第一个Ability支持恢复。
**系统能力**
:SystemCapability.Ability.AbilityRuntime.Core
...
...
@@ -84,7 +84,14 @@ export default class MyAbilityStage extends AbilityStage {
restartApp(): void;
重启当前App进程,可以配合
[
errorManager
](
js-apis-app-ability-errorManager.md
)
相关接口使用。
重启当前进程,并拉起应用启动时第一个Ability,如果该Ability存在已经保存的状态,这些状态数据会在Ability的OnCreate生命周期回调的want参数中作为wantParam属性传入。
API10时将启动由
[
setRestartWant
](
#apprecoverysetrestartwant
)
指定的Ability。如果没有指定则按以下规则启动:
\
如果当前应用前台的Ability支持恢复,则重新拉起该Ability。
\
如果存在多个支持恢复的Ability处于前台,则只拉起最后一个。
\
如果没有Ability处于前台,则不拉起。
可以配合
[
errorManager
](
js-apis-app-ability-errorManager.md
)
相关接口使用。
**系统能力**
:SystemCapability.Ability.AbilityRuntime.Core
...
...
@@ -142,3 +149,53 @@ try {
console
.
error
(
'
error: ${paramError.code}, ${paramError.message}
'
);
}
```
## appRecovery.saveAppState<sup>10+</sup>
saveAppState(context?: UIAbilityContext): boolean;
主动保存Ability的状态,这个状态将在下次恢复启动时使用。可以配合
[
errorManager
](
js-apis-app-ability-errorManager.md
)
相关接口使用
**系统能力**
:SystemCapability.Ability.AbilityRuntime.Core
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| boolean | 保存成功与否。true:保存成功,false:保存失败。 |
**示例:**
```
ts
import
appRecovery
from
'
@ohos.app.ability.appRecovery
'
;
onBackground
()
{
hilog
.
info
(
0x0000
,
'
[demo]
'
,
'
%{public}s
'
,
'
EntryAbility onBackground
'
);
appRecovery
.
saveAppState
(
this
.
context
)
}
```
## appRecovery.setRestartWant<sup>10+</sup>
setRestartWant(want: Want): void;
设置下次恢复主动拉起场景下的Ability。该Ability必须为当前包下的UIAbility。
**系统能力**
:SystemCapability.Ability.AbilityRuntime.Core
**示例:**
```
ts
import
appRecovery
from
'
@ohos.app.ability.appRecovery
'
;
Button
(
"
启动到恢复Ability
"
)
.
fontSize
(
40
)
.
fontWeight
(
FontWeight
.
Bold
)
.
onClick
(()
=>
{
// set restart want
let
want
=
{
bundleName
:
"
ohos.samples.recovery
"
,
abilityName
:
"
RecoveryAbility
"
};
appRecovery
.
setRestartWant
(
want
);
})
```
\ No newline at end of file
zh-cn/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-ability.md
0 → 100644
浏览文件 @
6076c518
# 元能力子系统ChangeLog
## cl.ability.appRecovery新增saveAppState接口
新增接口saveAppState(context?: UIAbilityContext): boolean;
**变更影响**
基于OpenHarmony4.0.5.2及之后的SDK版本开发的应用,可以使用saveAppState接口传入指定Ability Context,实现主动保存指定的Ability状态。
**关键接口/组件变更**
@ohos.app.ability.appRecovery.d.ts中新增saveAppState接口。
| 模块名 | 类名 | 方法/属性/枚举/常量 | 变更类型 |
| -- | -- | -- | -- |
| @ohos.app.ability.appRecovery.d.ts | appRecovery | saveAppState(context?: UIAbilityContext): boolean; | 新增 |
**适配指导**
通过调用saveAppState传入UIAbility Context参数主动保存此指定的Ability的状态。
```
ts
import
appRecovery
from
'
@ohos.app.ability.appRecovery
'
;
onBackground
()
{
hilog
.
info
(
0x0000
,
'
[demo]
'
,
'
%{public}s
'
,
'
EntryAbility onBackground
'
);
appRecovery
.
saveAppState
(
this
.
context
)
}
```
## cl.ability.appRecovery新增setRestartWant接口
新增接口setRestartWant(want: Want): void;
**变更影响**
基于OpenHarmony4.0.5.2及之后的SDK版本开发的应用,可以使用setRestartWant接口设置下次由恢复主动拉起场景下的Ability。
**关键接口/组件变更**
@ohos.app.ability.appRecovery.d.ts中新增setRestartWant接口。
| 模块名 | 类名 | 方法/属性/枚举/常量 | 变更类型 |
| -- | -- | -- | -- |
| @ohos.app.ability.appRecovery.d.ts | appRecovery | setRestartWant(want: Want): void; | 新增 |
**适配指导**
通过调用setRestartWant设置下次恢复到的指定Ability。
```
ts
import
appRecovery
from
'
@ohos.app.ability.appRecovery
'
;
Button
(
"
启动到恢复Ability
"
)
.
fontSize
(
40
)
.
fontWeight
(
FontWeight
.
Bold
)
.
onClick
(()
=>
{
// set restart want
let
want
=
{
bundleName
:
"
ohos.samples.recovery
"
,
abilityName
:
"
RecoveryAbility
"
};
appRecovery
.
setRestartWant
(
want
);
})
```
\ No newline at end of file
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录