fa-pageability.md 8.2 KB
Newer Older
1
# PageAbility开发指导
Z
zhaoyuan 已提交
2

G
guyuanzhang 已提交
3 4
## 概述
### 功能简介
R
RayShih 已提交
5
PageAbility是具备ArkUI实现的Ability,是开发者具体可见并可以交互的Ability实例。开发者通过IDE创建Ability时,IDE会自动创建相关模板代码。PageAbility相关能力通过单独的featureAbility实现,生命周期相关回调则通过app.js/app.ets中各个回调函数实现。
Z
zhaoyuan 已提交
6

G
guyuanzhang 已提交
7
### PageAbility的生命周期
Z
zhaoyuan 已提交
8

R
RayShih 已提交
9
**PageAbility生命周期介绍**(Ability Life Cycle):
Z
zhaoyuan 已提交
10

R
RayShih 已提交
11 12 13
PageAbility生命周期是PageAbility被调度到INACTIVE、ACTIVE、BACKGROUND等各个状态的统称。

PageAbility生命周期流转如下图所示:
Z
zhaoyuan 已提交
14 15 16 17 18 19

![PageAbility-Lifecycle](figures/page-ability-lifecycle.png)


**Ability生命周期状态说明:**

R
RayShih 已提交
20
  - **UNINITIALIZED**:未初始状态,为临时状态,PageAbility被创建后会由UNINITIALIZED状态进入INITIAL状态。
Z
zhaoyuan 已提交
21

R
RayShih 已提交
22
  - **INITIAL**:初始化状态,也表示停止状态,表示当前PageAbility未运行,PageAbility被启动后由INITIAL态进入INACTIVE状态。
Z
zhaoyuan 已提交
23

G
guyuanzhang 已提交
24
  - **INACTIVE**:失去焦点状态,表示当前窗口已显示但是无焦点状态。
Z
zhaoyuan 已提交
25

G
guyuanzhang 已提交
26
  - **ACTIVE**:前台激活状态,表示当前窗口已显示,并获取焦点。
Z
zhaoyuan 已提交
27

R
RayShih 已提交
28
  - **BACKGROUND**:后台状态,表示当前PageAbility退到后台,PageAbility在被销毁后由BACKGROUND状态进入INITIAL状态,或者重新被激活后由BACKGROUND状态进入ACTIVE状态。
Z
zhaoyuan 已提交
29

R
RayShih 已提交
30
**PageAbility生命周期回调与生命周期状态的关系如下图所示:**
Z
zhaoyuan 已提交
31

Z
zengyawen 已提交
32
![fa-pageAbility-lifecycle](figures/fa-pageAbility-lifecycle.png)
Z
zhaoyuan 已提交
33

G
guyuanzhang 已提交
34
PageAbility提供命周期回调,开发者可以在`app.js/app.ets`中重写生命周期相关回调函数 。目前`app.js`环境中仅支持onCreate和onDestroy回调,`app.ets`环境支持全量生命周期回调。
G
guyuanzhang 已提交
35

C
caochunlei 已提交
36
### 启动模式
X
xuchenghua 已提交
37
ability支持单实例和多实例两种启动模式。
C
caochunlei 已提交
38
在config.json中通过launchType配置项,可以配置具体的启动模式,其中:
C
caochunlei 已提交
39 40 41

| 启动模式     | 描述     |说明             |
| ----------- | -------  |---------------- |
42
| standard    | 多实例   | 每次startAbility都会启动一个新的实例 |
C
caochunlei 已提交
43 44
| singleton   | 单实例   | 系统中只存在唯一一个实例,startAbility时,如果已存在,则复用系统中的唯一一个实例 |

X
xuchenghua 已提交
45
缺省情况下是singleton模式。
C
caochunlei 已提交
46 47


G
guyuanzhang 已提交
48 49
## 开发指导
### featureAbility接口说明
G
guyuanzhang 已提交
50

G
guyuanzhang 已提交
51
**表1** featureAbility接口介绍
G
guyuanzhang 已提交
52

G
guyuanzhang 已提交
53 54 55 56 57 58
| 接口名                                              | 描述            |
| --------------------------------------------------- | --------------- |
| void startAbility(parameter: StartAbilityParameter) | 启动Ability     |
| Context getContext():                               | 获取应用Context |
| void terminateSelf()                                | 结束Ability     |
| bool hasWindowFocus()                               | 是否获取焦点    |
G
guyuanzhang 已提交
59

Z
zhaoyuan 已提交
60

G
guyuanzhang 已提交
61
### 启动本地PageAbility
Z
zhaoyuan 已提交
62

R
RayShih 已提交
63
**导入模块**
Z
zhaoyuan 已提交
64

R
RayShih 已提交
65 66
```js
  import featureAbility from '@ohos.ability.featureAbility'
Z
zhaoyuan 已提交
67
```
R
RayShih 已提交
68 69

**示例**
Z
zhaoyuan 已提交
70 71

```javascript
R
RayShih 已提交
72 73
  import featureAbility from '@ohos.ability.featureAbility'
  featureAbility.startAbility({
Z
zengyawen 已提交
74 75 76 77 78 79
  want:
  {
    action: "",
    entities: [""],
    type: "",
    deviceId: "",
G
guyuanzhang 已提交
80 81 82
    bundleName: "com.example.myapplication",
    /* FA模型中abilityName由package + Ability name组成 */
    abilityName: "com.example.entry.secondAbility",
Z
zengyawen 已提交
83 84
    uri: ""
  },
R
RayShih 已提交
85 86
  },
  );
Z
zengyawen 已提交
87
```
R
RayShih 已提交
88

89
### 启动远程PageAbility(当前仅对系统应用开放)
90
>说明:由于DeviceManager的getTrustedDeviceListSync接口仅对系统应用开放,当前启动远程PageAbility仅支持系统应用
Z
zhaoyuan 已提交
91

R
RayShih 已提交
92
**导入模块**
Z
zhaoyuan 已提交
93 94

```
R
RayShih 已提交
95 96
  import featureAbility from '@ohos.ability.featureAbility'
  import deviceManager from '@ohos.distributedHardware.deviceManager';
Z
zhaoyuan 已提交
97 98
```

R
RayShih 已提交
99
**示例**
100
```ts
R
RayShih 已提交
101
  function onStartRemoteAbility() {
102
  console.info('onStartRemoteAbility begin');
103
  let params;
104
  let wantValue = {
105 106 107 108 109 110 111 112 113 114 115 116
    bundleName: 'ohos.samples.etsDemo',
    abilityName: 'ohos.samples.etsDemo.RemoteAbility',
    deviceId: 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');
R
RayShih 已提交
117
  }
118
```
R
RayShih 已提交
119 120

从DeviceManager获取`deviceId`,具体示例代码如下:
R
RayShih 已提交
121

122
```ts
R
RayShih 已提交
123
  import deviceManager from '@ohos.distributedHardware.deviceManager';
124
  let dmClass;
R
RayShih 已提交
125
  function getRemoteDeviceId() {
126
    if (typeof dmClass === 'object' && dmClass != null) {
127
        let list = dmClass.getTrustedDeviceListSync();
128 129 130 131 132 133 134 135 136
        if (typeof (list) == 'undefined' || typeof (list.length) == 'undefined') {
            console.log("MainAbility onButtonClick getRemoteDeviceId err: list is null");
            return;
        }
        console.log("MainAbility onButtonClick getRemoteDeviceId success:" + list[0].deviceId);
        return list[0].deviceId;
    } else {
        console.log("MainAbility onButtonClick getRemoteDeviceId err: dmClass is null");
    }
R
RayShih 已提交
137
  }
138
```
R
RayShih 已提交
139

140
在跨设备场景下,需要向用户申请数据同步的权限。具体示例代码如下:
R
RayShih 已提交
141

142
```ts
143
  import abilityAccessCtrl from "@ohos.abilityAccessCtrl";
R
RayShih 已提交
144 145
  import bundle from '@ohos.bundle';
  async function RequestPermission() {
146
  console.info('RequestPermission begin');
147
  let array: Array<string> = ["ohos.permission.DISTRIBUTED_DATASYNC"];
148 149 150 151
  let bundleFlag = 0;
  let tokenID = undefined;
  let userID = 100;
  let  appInfo = await bundle.getApplicationInfo('ohos.samples.etsDemo', bundleFlag, userID);
152
  tokenID = appInfo.accessTokenId;
153
  let atManager = abilityAccessCtrl.createAtManager();
154 155
  let requestPermissions: Array<string> = [];
  for (let i = 0;i < array.length; i++) {
156
    let result = await atManager.verifyAccessToken(tokenID, array[i]);
157
    console.info("verifyAccessToken result:" + JSON.stringify(result));
158 159 160 161 162
    if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
    } else {
      requestPermissions.push(array[i]);
    }
  }
163
  console.info("requestPermissions:" + JSON.stringify(requestPermissions));
164 165 166 167 168
  if (requestPermissions.length == 0 || requestPermissions == []) {
    return;
  }
  let context = featureAbility.getContext();
  context.requestPermissionsFromUser(requestPermissions, 1, (data)=>{
169 170 171 172
    console.info("data:" + JSON.stringify(data));
    console.info("data requestCode:" + data.requestCode);
    console.info("data permissions:" + data.permissions);
    console.info("data authResults:" + data.authResults);
173
  });
174
  console.info('RequestPermission end');
R
RayShih 已提交
175
  }
G
guyuanzhang 已提交
176
```
R
RayShih 已提交
177

G
guyuanzhang 已提交
178
### 生命周期接口说明
R
RayShih 已提交
179

G
guyuanzhang 已提交
180 181 182 183
**表2** 生命周期回调函数介绍

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

R
RayShih 已提交
191
**示例**
R
RayShih 已提交
192

R
RayShih 已提交
193 194
开发者需要重写`app.js/app.ets`中相关生命周期回调函数,IDE模板默认生成`onCreate()``onDestroy()`方法,其他方法需要开发者自行实现。

G
guyuanzhang 已提交
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
```javascript
export default {
  onCreate() {
    console.info('Application onCreate')
  },
  onDestroy() {
    console.info('Application onDestroy')
  },
  onShow(){
    console.info('Application onShow')
  },
  onHide(){
    console.info('Application onHide')
  },
  onInactive(){
    console.info('Application onInactive')
  },
  onActive(){
    console.info('Application onActive')
  },
}
```
217 218
## 相关实例
针对PageAbility开发,有以下相关实例可供参考:
G
guyuanzhang 已提交
219

G
ge-yafang 已提交
220
- [`DMS`:分布式Demo(eTS)(API8)](https://gitee.com/openharmony/app_samples/tree/master/ability/DMS)