未验证 提交 75bc6f31 编写于 作者: O openharmony_ci 提交者: Gitee

!15244 Add a new scenario: Starting a UIAbility with specified window mode.

Merge pull request !15244 from zyjhandsome/master
...@@ -55,7 +55,7 @@ ...@@ -55,7 +55,7 @@
- [任务管理场景介绍](mission-management-overview.md) - [任务管理场景介绍](mission-management-overview.md)
- [任务管理与启动模式](mission-management-launch-type.md) - [任务管理与启动模式](mission-management-launch-type.md)
- [页面栈及任务链](page-mission-stack.md) - [页面栈及任务链](page-mission-stack.md)
- [设置任务快照的图标和名称](mission-set-icon-name-for-task-snapshot) - [设置任务快照的图标和名称](mission-set-icon-name-for-task-snapshot.md)
- [Stage模型应用配置文件](config-file-stage.md) - [Stage模型应用配置文件](config-file-stage.md)
- FA模型开发指导 - FA模型开发指导
- [FA模型开发概述](fa-model-development-overview.md) - [FA模型开发概述](fa-model-development-overview.md)
......
# 使用显式Want启动Ability # 使用显式Want启动Ability
在应用使用场景中,当用户在应用内点击某个按钮时,经常需要拉起指定UIAbility组件来完成某些特定任务。在启动UIAbility时,指定了abilityName和bundleName参数,可以使用显式Want方式启动UIAbility。显式Want的使用
在应用使用场景中,当用户在应用内点击某个按钮时,经常需要拉起指定UIAbility组件来完成某些特定任务。在启动UIAbility时,指定了abilityName和bundleName参数,可以使用显示Want方式启动UIAbility。显示Want的使用请参见[启动应用内的UIAbility](uiability-intra-device-interaction.md#启动应用内的uiability) 针对应用的特定任务,用户需要通过点击应用内的按钮来启动指定的UIAbility组件。在启动UIAbility时,需要提供abilityName和bundleName参数,并使用显式Want方式来启动。关于如何使用显式Want方式启动应用内的UIAbility,请参见[启动应用内的UIAbility](uiability-intra-device-interaction.md#启动应用内的uiability)
# 使用隐式Want打开网址 # 使用隐式Want打开网址
以打开浏览器为例,假设设备上安装了一个或多个浏览器应用。为了使浏览器应用能够正常工作,需要在[module.json5配置文件](../quick-start/module-configuration-file.md)进行配置,具体配置如下:
## 前提条件
设备上安装了一个或多个浏览器。
浏览器应用中通过module.json5配置如下:
```json ```json
"skills": [ {
{ "module": {
"entities": [ // ...
"entity.system.browsable" "abilities": [
// ...
],
"actions": [
"ohos.want.action.viewData"
// ...
],
"uris": [
{
"scheme": "https",
"host": "www.test.com",
"port": "8080",
// prefix matching
"pathStartWith": "query",
"type": "text/*"
},
{ {
"scheme": "http",
// ... // ...
"skills": [
{
"entities": [
"entity.system.home",
"entity.system.browsable"
// ...
],
"actions": [
"action.system.home",
"ohos.want.action.viewData"
// ...
],
"uris": [
{
"scheme": "https",
"host": "www.test.com",
"port": "8080",
// prefix matching
"pathStartWith": "query",
"type": "text/*"
},
{
"scheme": "http",
// ...
}
// ...
]
}
]
} }
// ...
] ]
}, }
] }
``` ```
在调用方UIAbility中,使用隐式Want方式启动浏览器应用。
## 开发步骤 ```ts
import common from '@ohos.app.ability.common';
1. 在自定义函数implicitStartAbility内使用**隐式Want**启动Ability。 function implicitStartAbility() {
let context = getContext(this) as common.UIAbilityContext;
```ts let wantInfo = {
async implicitStartAbility() { // uncomment line below if wish to implicitly query only in the specific bundle.
try { // bundleName: "com.example.myapplication",
let want = { "action": "ohos.want.action.viewData",
// uncomment line below if wish to implicitly query only in the specific bundle. // entities can be omitted.
// bundleName: "com.example.myapplication", "entities": ["entity.system.browsable"],
"action": "ohos.want.action.viewData", "uri": "https://www.test.com:8080/query/student",
// entities can be omitted. "type": "text/plain"
"entities": [ "entity.system.browsable" ], }
"uri": "https://www.test.com:8080/query/student", context.startAbility(wantInfo).then(() => {
"type": "text/plain" // ...
} }).catch((err) => {
let context = getContext(this) as common.UIAbilityContext; // ...
await context.startAbility(want) })
console.info(`explicit start ability succeed`) }
} catch (error) { ```
console.info(`explicit start ability failed with ${error.code}`)
}
}
```
匹配过程如下:
1. want内action不为空,且被skills内action包括,匹配成功。
2. want内entities不为空,且被skills内entities包括,匹配成功。
3. skills内uris拼接为`https://www.test.com:8080/query*` (\*为通配符)包含want内uri,匹配成功。
4. want内type不为空,且被skills内type包含,匹配成功。 匹配过程分析:
2. 当有多个匹配应用时,会被应用选择器展示给用户进行选择。 1. 调用方传入的want参数的action不为空,待匹配Ability的skills配置中的actions不为空且包含调用方传入的want参数的action,action匹配成功。
2. 调用方传入的want参数的entities不为空,待匹配Ability的skills配置中的entities不为空且包含调用方传入的want参数的entities,entities匹配成功。
3. 待匹配Ability的skills配置中内uris拼接为`https://www.test.com:8080/query*` (其中*表示通配符),包含调用方传入的want参数的uri,uri匹配成功。
4. 调用方传入的want参数的type不为空,待匹配Ability的skills配置中的type不为空且包含调用方传入的want参数的type,type匹配成功。
![stage-want1](figures/stage-want1.png) 当有多个匹配应用时,会被应用选择器展示给用户进行选择。 示意效果如下图所示。
![](figures/ability-startup-with-implicit-want2.png)
# 应用间使用Want分享数据 # 应用间使用Want分享数据
在应用使用场景中,用户经常需要将应用内的数据(如文字、图片等)分享至其他应用以供进一步处理。以分享PDF文件为例,本文将介绍如何使用Want来实现应用间的数据分享。
在应用使用场景中,用户经常需要将一个应用内的数据(如文字、图片等)分享至另一个应用内继续操作。下面以PDF文件分享为例,介绍应用间使用Want分享数据的方法。 数据分享需要使用两个UIAbility组件(分享方和被分享方)以及一个系统组件(应用选择框)。当分享方使用`startAbility()`方法发起数据分享时,系统会隐式匹配所有支持接收分享数据类型的应用,并将其展示给用户以供选择。用户选择应用后,系统将启动该应用来完成数据分享操作。
在本文中,我们将使用按钮的形式触发分享操作,但实际开发中并不限于此。本文主要介绍如何配置Want以实现数据分享的功能。
## 前提条件
本文中涉及的两个Action为:
1. 数据分享涉及2个UIAbility组件(分享方和被分享方)和1个系统部件(应用选择框)。当分享方通过startAbility接口发起数据分享后,将拉起应用选择框。其将**隐式匹配并展示**所有支持接受分享数据类型的应用,由用户主动选取,并由系统拉起点击应用完成数据的分享。
- `ohos.want.action.select`:用于启动应用选择框。
2. 在本章节中,将继续以按钮形式来触发分享,实际开发场景中并不局限于此,此章节着重讲解分享时Want的配置。 - `ohos.want.action.sendData`:用于发送单个数据记录。此Action用于将数据传递给分享方应用。
3. 本章节涉及的action: ## 分享方
- ACTION_SELECT (ohos.want.action.select):指示显示应用程序选择框的操作。用于拉起应用选择框。
- ACTION_SEND_DATA (ohos.want.action.sendData):指示发送单个数据记录的操作。用于传递数据至分享方。 为了实现数据分享功能,分享方需要先拉起应用选择框并将要分享的数据传递给被分享方应用。因此,在分享方的代码中需要嵌套使用两层Want。在第一层中,使用隐式Want和`ohos.want.action.select`的action来启动应用选择框。在第二层Want中,声明要传递给被分享方应用的数据。
具体来说,可以将要分享的数据放在自定义字段`parameters`中,然后将包含`ohos.want.action.sendData`的action和`parameters`字段的Want作为第二层Want传递给应用选择框。被分享方应用可以通过获取参数`parameters`来获取分享的数据。
## 开发步骤
```ts
- 分享方 import common from '@ohos.app.ability.common';
1. Stage模型下经常会遇到需要分享文件的场景,在这种场景下我们需要使用[文件描述符(FD)](../reference/apis/js-apis-fileio.md#fileioopensync)来传递文件。此示例中,默认已获取分享文件的路径。
let fileType = 'application/pdf';
```ts let fileName = 'TestFile.pdf';
import fileIO from '@ohos.fileio'; let fileFd = -1; // 需要获取被分享文件的FD
let fileSize; // 需要获取被分享文件的大小
// let path = ...
// file open where path is a variable contains the file path. function implicitStartAbility() {
let fileFd = fileIO.openSync(path, 0o102, 0o666); let context = getContext(this) as common.UIAbilityContext;
``` let wantInfo = {
2. 在前提条件中介绍了分享的流程。分享方需先拉起应用选择框,并将数据分享给应用选择框,并由应用选择框代理传递至被分享方,完成分享。因此分享方的Want需使用2层嵌套,在第1层中使用隐式Want并配合“ohos.want.action.select”action拉起应用选择框,并在自定义字段parameters内声明一个完整的want作为第2层,其中声明传递给被分享方的数据。 // This action is used to implicitly match the application selctor.
action: 'ohos.want.action.select',
```ts // This is the custom parameter in the first layer of want
import wantConstant from '@ohos.app.ability.wantConstant'; // which is intended to add info to application selector.
parameters: {
// let path = ... // The MIME type of pdf
// let fileFd = ... "ability.picker.type": fileType,
// let fileSize = ... "ability.picker.fileNames": [fileName],
let want = { "ability.picker.fileSizes": [fileSize],
// This action is used to implicitly match the application selctor. // This a nested want which will be directly send to the user selected application.
action: wantConstant.Action.ACTION_SELECT, "ability.want.params.INTENT": {
// This is the custom parameter in the first layer of want "action": "ohos.want.action.sendData",
// which is intended to add info to application selector. "type": "application/pdf",
parameters: { "parameters": {
// The MIME type of pdf "keyFd": { "type": "FD", "value": fileFd }
"ability.picker.type": "application/pdf", }
"ability.picker.fileNames": [path],
"ability.picker.fileSizes": [fileSize],
// This a nested want which will be directly send to the user selected application.
"ability.want.params.INTENT": {
"action": "ohos.want.action.sendData",
"type": "application/pdf",
"parameters": {
"keyFd": {"type": "FD", "value": fileFd}
}
}
}
} }
``` }
}
以上代码中使用Want自定义字段paramters,其中第一层paramters中的“ability.picker.\*”字段用于传递展示信息给应用选择器,具体字段表示为: context.startAbility(wantInfo).then(() => {
// ...
- "ability.picker.type":应用选择器根据该字段渲染相应的文件类型图标。 }).catch((err) => {
- "ability.picker.fileNames":应用选择器根据该字段展示文件名。 // ...
- "ability.picker.fileSizes":应用选择器根据该字段展示文件大小。以字节为单位。 })
- "ability.picker.fileNames"与"ability.picker.fileSizes"为数组,其有一一对应关系。 }
```
例如:当"ability.picker.type"为“application/pdf”,"ability.picker.fileNames"为“["接口文档.pdf"]”,"ability.picker.fileSizes"为“[350 \* 1024]”时,应用选择器将以下形式展示。
> **说明:**
![stage-want2](figures/stage-want2.png) >
> 目前仅支持使用文件描述符(FD)格式分享数据。获取被分享文件的文件描述符和文件名,请参考[文件管理](../reference/apis/js-apis-file-fs.md)相关接口。
示例代码中“ability.want.params.INTENT”字段是一个嵌套Want,内部所含action、type等字段将由应用选择器进行隐式匹配,具体隐式匹配规则可参考[隐式Want匹配原理](explicit-implicit-want-mappings.md#隐式want匹配原理)。当用户选择具体应用后,“ability.want.params.INTENT”字段的嵌套Want将传递至所选应用。
在以上代码中,使用了自定义字段`parameters`。其中,一级参数`parameters`中的字段`ability.picker.*`用于向应用选择器传递展示信息,具体字段如下:
- 被分享方:
1. 上文中提到,应用选择器通过“ability.want.params.INTENT”字段进行隐式匹配。因此被分享方Ability配置文件内(stage模型下的module.json5)skills字段需配置如下。 - `ability.picker.type`:用于渲染相应的文件类型图标。
- `ability.picker.fileNames`:用于展示文件名。
```ts - `ability.picker.fileSizes`:用于展示文件大小,单位为字节。
"skills": [ - `ability.picker.fileNames``ability.picker.fileSizes`是数组,两者一一对应。
{
"entities": [ 效果示意如下图所示。
![](figures/ability-startup-with-implicit-want2.png)
## 被分享方
为了使分享的内容能够在被分享方识别,需要在被分享方UIAbility的[module.json5配置文件](../quick-start/module-configuration-file.md)中的skills标签进行相应的配置。其中,`actions`字段和`uris`内的`type`字段分别与分享方Want参数中`ability.want.params.INTENT`内的`action``type`字段进行匹配。
```json
{
"module": {
// ...
"abilities": [
{
// ...
"skills": [
{
// ... // ...
], "actions": [
"actions": [ "action.system.home",
"ohos.want.action.sendData" "ohos.want.action.sendData"
// ... // ...
], ],
"uris": [ "uris": [
{ {
"type": "application/pdf" "type": "application/pdf"
}, },
// ... ]
] }
}, ]
]
```
其中"actions"字段和“uris”内“type”字段分别与“ability.want.params.INTENT”内“action”,“type”字段匹配。
注意:当前文件传递不支持uri方式传递,仅支持FD方式,但隐式匹配中,Want内的“type”字段需与被分享方配置文件skills内“uris”字段下的“type”字段匹配,因此skills内的“uris”字段建议只声明“type”字段,增加“host”,“port”等字段在上述示例中将匹配失败。因为应用选择框通过“ability.want.params.INTENT”发起隐式匹配,所以在“ability.want.params.INTENT”字段内增加uri字段,且与skills内的“uris”字段匹配时,仍可匹配成功且传递额外数据。
2. 应用选择器拉起被分享方后,系统将调用其“onCreate”接口,并传入“ability.want.params.INTENT”至其入参want内。
```ts
onCreate(want, launchParam) {
// note when keyFd is undefined, app crash will happen.
if (want["parameters"]["keyFd"] !== undefined) {
// receive file descriptor
let fd = want["parameters"]["keyFd"].value;
// ...
}
} }
``` ]
}
}
```
当用户选择分享的应用后,嵌套在`ability.want.params.INTENT`字段中的Want参数将会传递给所选应用。被分享方的UIAbility被启动后,可以在其[onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate)或者[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)回调中获取传入的Want参数信息。
获取到的Want参数信息示例如下,可以使用被分享文件的文件描述符(FD)进行相应操作。
```json
{
"deviceId": "",
"bundleName": "com.example.myapplication",
"abilityName": "EntryAbility",
"moduleName": "entry",
"uri": "",
"type": "application/pdf",
"flags": 0,
"action": "ohos.want.action.sendData",
"parameters": {
"component.startup.newRules": true,
"keyFd": {
"type": "FD",
"value": 36
},
"mime-type": "application/pdf",
"moduleName": "entry",
"ohos.aafwk.param.callerPid": 3488,
"ohos.aafwk.param.callerToken": 537379209,
"ohos.aafwk.param.callerUid": 20010014
},
"entities": []
}
```
...@@ -5,7 +5,7 @@ ...@@ -5,7 +5,7 @@
默认情况下任务快照的图标和名称采用的是[module.json5配置文件](../quick-start/module-configuration-file.md)[abilities标签](../quick-start/module-configuration-file.md#abilities标签)中的icon和label字段,如下图所示。 默认情况下任务快照的图标和名称采用的是[module.json5配置文件](../quick-start/module-configuration-file.md)[abilities标签](../quick-start/module-configuration-file.md#abilities标签)中的icon和label字段,如下图所示。
图1 UIAbility对应的任务快照 图1 UIAbility对应的任务快照
<img src="figures/mission-list-recent.png" alt="mission-list-recent" height="400" /> ![](figures/mission-list-recent.png)
也可以使用[UIAbilityContext.setMissionIcon()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon)[UIAbilityContext.setMissionLabel()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel)方法,根据需要自定义任务快照的图标和名称。例如,对于UIAbility的标准实例启动模式,可以根据不同的功能配置相应的任务快照的图标和名称。 也可以使用[UIAbilityContext.setMissionIcon()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon)[UIAbilityContext.setMissionLabel()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel)方法,根据需要自定义任务快照的图标和名称。例如,对于UIAbility的标准实例启动模式,可以根据不同的功能配置相应的任务快照的图标和名称。
...@@ -28,7 +28,7 @@ this.context.setMissionIcon(imagePixelMap, (err) => { ...@@ -28,7 +28,7 @@ this.context.setMissionIcon(imagePixelMap, (err) => {
效果示意如下图所示。 效果示意如下图所示。
图2 设置任务快照的图标 图2 设置任务快照的图标
<img src="figures/mission-set-task-snapshot-icon.png" alt="mission-set-task-snapshot-icon" height="400" /> ![](figures/mission-set-task-snapshot-icon.png)
## 设置任务快照的名称 ## 设置任务快照的名称
...@@ -36,13 +36,13 @@ this.context.setMissionIcon(imagePixelMap, (err) => { ...@@ -36,13 +36,13 @@ this.context.setMissionIcon(imagePixelMap, (err) => {
```ts ```ts
this.context.setMissionLabel('test').then(() => { this.context.setMissionLabel('test').then(() => {
console.log('setMissionLabel succeeded.'); console.info('setMissionLabel succeeded.');
}).catch((err) => { }).catch((err) => {
console.log(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`); console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`);
}); });
``` ```
效果示意如下图所示。 效果示意如下图所示。
图3 设置任务快照的名称 图3 设置任务快照的名称
<img src="figures/mission-set-task-snapshot-label.png" alt="mission-set-task-snapshot-label" height="400" /> ![](figures/mission-set-task-snapshot-label.png)
\ No newline at end of file \ No newline at end of file
# 订阅系统环境变量的变化 # 订阅系统环境变量的变化
在应用程序运行期间,设备的系统配置(例如系统的语言环境、屏幕方向等)可能会发生变化。例如,用户更改系统语言设置时,应用程序可以自动根据新的语言设置更新用户界面的语言;当用户将设备旋转到横屏或者竖屏时,应用程序可以重新布局用户界面,以适应屏幕方向和尺寸。 系统环境变量是指:在应用程序运行期间,终端设备的系统设置(例如系统的语言环境、屏幕方向等)发生变化。
开发者通过订阅系统环境变化,可以使应用程序及时感知这种变化,并作出相应处理,从而提供更好的用户体验。例如,用户更改系统语言设置时,应用程序可以自动根据新的语言设置更新用户界面的语言;当用户将设备旋转到横屏或者竖屏时,应用程序可以重新布局用户界面,以适应屏幕方向和尺寸。
系统配置的变化通常由“设置”中的选项或“控制中心”中的图标触发。订阅系统环境变量变化,可以使应用程序更加智能地响应系统环境变化,从而提供更好的用户体验。查看当前支持订阅变化的系统环境变量,请参见[Configuration](../reference/apis/js-apis-app-ability-configuration.md) 系统配置的变化通常由“设置”中的选项或“控制中心”中的图标触发。订阅系统环境变量变化,可以使应用程序更加智能地响应系统环境变化,从而提供更好的用户体验。查看当前支持订阅变化的系统环境变量,请参见[Configuration](../reference/apis/js-apis-app-ability-configuration.md)
......
...@@ -15,6 +15,8 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 ...@@ -15,6 +15,8 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳
- [启动其他应用的UIAbility并获取返回结果](#启动其他应用的uiability并获取返回结果) - [启动其他应用的UIAbility并获取返回结果](#启动其他应用的uiability并获取返回结果)
- [启动UIAbility指定窗口模式(仅对系统应用开放)](#启动uiability指定窗口模式仅对系统应用开放)
- [启动UIAbility的指定页面](#启动uiability的指定页面) - [启动UIAbility的指定页面](#启动uiability的指定页面)
- [通过Call调用实现UIAbility交互(仅对系统应用开放)](#通过call调用实现uiability交互仅对系统应用开放) - [通过Call调用实现UIAbility交互(仅对系统应用开放)](#通过call调用实现uiability交互仅对系统应用开放)
...@@ -201,9 +203,8 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 ...@@ -201,9 +203,8 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳
}) })
``` ```
效果示意如下图所示,点击“打开PDF文档”时,会弹出选择框供用户选择。 效果示意如下图所示,点击“打开PDF文档”时,会弹出选择框供用户选择。
![](figures/uiability-intra-device-interaction.png)
![uiability-intra-device-interaction](figures/uiability-intra-device-interaction.png)
3. 在文档应用使用完成之后,如需要停止当前UIAbility实例,通过调用[terminateSelf()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)方法实现。 3. 在文档应用使用完成之后,如需要停止当前UIAbility实例,通过调用[terminateSelf()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)方法实现。
...@@ -307,6 +308,55 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 ...@@ -307,6 +308,55 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳
}) })
``` ```
## 启动UIAbility指定窗口模式(仅对系统应用开放)
当用户打开应用时,应用程序会以不同的窗口模式进行展示,即启动UIAbility的窗口模式。应用程序可以启动为全屏模式,悬浮窗模式或分屏模式。
全屏模式是指应用程序启动后,占据整个屏幕,用户无法同时查看其他窗口或应用程序。全屏模式通常适用于那些要求用户专注于特定任务或界面的应用程序。
悬浮窗模式是指应用程序启动后,以浮动窗口的形式显示在屏幕上,用户可以轻松切换到其他窗口或应用程序。悬浮窗通常适用于需要用户同时处理多个任务的应用程序。
分屏模式允许用户在同一屏幕上同时运行两个应用程序,其中一个应用程序占据屏幕左侧/上侧的一部分,另一个应用程序占据右侧/下侧的一部分。分屏模式主要用于提高用户的多任务处理效率。
使用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法启动UIAbility时,可以通过在入参中增加[StartOptions](../reference/apis/js-apis-app-ability-startOptions.md)参数的windowMode属性来配置启动UIAbility的窗口模式。
> **说明:**
>
> 1. 如果在使用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法启动UIAbility时,入参中未指定[StartOptions](../reference/apis/js-apis-app-ability-startOptions.md)参数的windowMode属性,那么UIAbility将以系统默认的窗口展示形态启动。
> 2. 为了确保启动的UIAbility展示形态能够被支持,需要在该UIAbility对应的[module.json5配置文件](../quick-start/module-configuration-file.md)中[abilities标签](../quick-start/module-configuration-file.md#abilities标签)的supportWindowMode字段确认启动的展示形态被支持。
以下是具体的操作步骤,以悬浮窗模式为例,假设需要从EntryAbility的页面中启动FuncAbility:
1. 在调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,增加[StartOptions](../reference/apis/js-apis-app-ability-startOptions.md)参数。
2.[StartOptions](../reference/apis/js-apis-app-ability-startOptions.md)参数中设置`windowMode`字段为`WINDOW_MODE_FLOATING`,表示启动的UIAbility将以悬浮窗的形式展示。
示例中的context的获取方式请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)
```ts
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
let wantInfo = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.myapplication',
abilityName: 'FuncAbility',
moduleName: 'module1', // moduleName非必选
parameters: { // 自定义信息
info: '来自EntryAbility Index页面',
},
}
let options = {
windowMode: AbilityConstant.WindowMode.WINDOW_MODE_FLOATING
}
// context为调用方UIAbility的UIAbilityContext
this.context.startAbility(wantInfo, options).then(() => {
// ...
}).catch((err) => {
// ...
})
```
效果示意如下图所示。
![](figures/start-uiability-floating-window.png)
## 启动UIAbility的指定页面 ## 启动UIAbility的指定页面
......
...@@ -17,8 +17,7 @@ singleton启动模式为单实例模式,也是默认情况下的启动模式 ...@@ -17,8 +17,7 @@ singleton启动模式为单实例模式,也是默认情况下的启动模式
每次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,如果应用进程中该类型的UIAbility实例已经存在,则复用系统中的UIAbility实例。系统中只存在唯一一个该UIAbility实例,即在最近任务列表中只存在一个该类型的UIAbility实例。 每次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,如果应用进程中该类型的UIAbility实例已经存在,则复用系统中的UIAbility实例。系统中只存在唯一一个该UIAbility实例,即在最近任务列表中只存在一个该类型的UIAbility实例。
**图1** 单实例模式演示效果 **图1** 单实例模式演示效果
![uiability-launch-type1](figures/uiability-launch-type1.png) ![uiability-launch-type1](figures/uiability-launch-type1.png)
> **说明**:应用的UIAbility实例已创建,该UIAbility配置为单实例模式,再次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法启动该UIAbility实例。由于启动的还是原来的UIAbility实例,并未重新创建一个新的UIAbility实例,此时只会进入该UIAbility的[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)回调,不会进入其[onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate)和[onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)生命周期回调。 > **说明**:应用的UIAbility实例已创建,该UIAbility配置为单实例模式,再次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法启动该UIAbility实例。由于启动的还是原来的UIAbility实例,并未重新创建一个新的UIAbility实例,此时只会进入该UIAbility的[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)回调,不会进入其[onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate)和[onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)生命周期回调。
...@@ -45,8 +44,7 @@ singleton启动模式为单实例模式,也是默认情况下的启动模式 ...@@ -45,8 +44,7 @@ singleton启动模式为单实例模式,也是默认情况下的启动模式
standard启动模式为标准实例模式,每次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,都会在应用进程中创建一个新的该类型UIAbility实例。即在最近任务列表中可以看到有多个该类型的UIAbility实例。这种情况下可以将UIAbility配置为standard(标准实例模式)。 standard启动模式为标准实例模式,每次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,都会在应用进程中创建一个新的该类型UIAbility实例。即在最近任务列表中可以看到有多个该类型的UIAbility实例。这种情况下可以将UIAbility配置为standard(标准实例模式)。
**图2** 标准实例模式演示效果 **图2** 标准实例模式演示效果
![standard-mode](figures/standard-mode.png) ![standard-mode](figures/standard-mode.png)
standard启动模式的开发使用,在[module.json5配置文件](../quick-start/module-configuration-file.md)中的`launchType`字段配置为`standard`即可。 standard启动模式的开发使用,在[module.json5配置文件](../quick-start/module-configuration-file.md)中的`launchType`字段配置为`standard`即可。
...@@ -71,14 +69,13 @@ standard启动模式的开发使用,在[module.json5配置文件](../quick-sta ...@@ -71,14 +69,13 @@ standard启动模式的开发使用,在[module.json5配置文件](../quick-sta
specified启动模式为指定实例模式,针对一些特殊场景使用(例如文档应用中每次新建文档希望都能新建一个文档实例,重复打开一个已保存的文档希望打开的都是同一个文档实例)。 specified启动模式为指定实例模式,针对一些特殊场景使用(例如文档应用中每次新建文档希望都能新建一个文档实例,重复打开一个已保存的文档希望打开的都是同一个文档实例)。
**图3** 指定实例模式演示效果 **图3** 指定实例模式演示效果
![uiability-launch-type2](figures/uiability-launch-type2.png) ![uiability-launch-type2](figures/uiability-launch-type2.png)
例如有两个UIAbility:EntryAbility和SpecifiedAbility,SpecifiedAbility配置为specified启动模式,需要从EntryAbility的页面中启动SpecifiedAbility。 例如有两个UIAbility:EntryAbility和SpecifiedAbility,SpecifiedAbility配置为指定实例模式启动,需要从EntryAbility的页面中启动SpecifiedAbility。
1. 在SpecifiedAbility中,将[module.json5配置文件](../quick-start/module-configuration-file.md)`launchType`字段配置为`specified` 1. 在SpecifiedAbility中,将[module.json5配置文件](../quick-start/module-configuration-file.md)`launchType`字段配置为`specified`
```json ```json
{ {
"module": { "module": {
...@@ -93,9 +90,8 @@ specified启动模式为指定实例模式,针对一些特殊场景使用( ...@@ -93,9 +90,8 @@ specified启动模式为指定实例模式,针对一些特殊场景使用(
} }
``` ```
2. 在UIAbility实例创建之前,允许开发者为该实例创建一个唯一的字符串Key,创建的UIAbility实例绑定Key之后,后续每次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,都会询问应用使用哪个Key对应的UIAbility实例来响应[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)请求。 2. 在创建UIAbility实例之前,开发者可以为该实例指定一个唯一的字符串Key,这样在调用[startAbility()](.../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,应用就可以根据指定的Key来识别响应请求的UIAbility实例。在EntryAbility中,调用[startAbility()](.../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,可以在`want`参数中增加一个自定义参数,例如`instanceKey`,以此来区分不同的UIAbility实例。
在EntryAbility中,调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法时,在[want参数](want-overview.md)中,增加一个自定义参数来区别UIAbility实例,例如增加一个`instanceKey`自定义参数。
```ts ```ts
// 在启动指定实例模式的UIAbility时,给每一个UIAbility实例配置一个独立的Key标识 // 在启动指定实例模式的UIAbility时,给每一个UIAbility实例配置一个独立的Key标识
// 例如在文档使用场景中,可以用文档路径作为Key标识 // 例如在文档使用场景中,可以用文档路径作为Key标识
...@@ -119,10 +115,11 @@ specified启动模式为指定实例模式,针对一些特殊场景使用( ...@@ -119,10 +115,11 @@ specified启动模式为指定实例模式,针对一些特殊场景使用(
// ... // ...
}) })
``` ```
3. 运行时由UIAbility内部业务决定是否创建多实例,如果匹配有该UIAbility实例的Key,则直接拉起与之绑定的UIAbility实例,否则创建一个新的UIAbility实例。 3. 由于SpecifiedAbility的启动模式被配置为指定实例启动模式,因此在SpecifiedAbility启动之前,会先进入对应的AbilityStage的[onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)生命周期回调中,以获取该UIAbility实例的Key值。然后系统会自动匹配,如果存在与该UIAbility实例匹配的Key,则会启动与之绑定的UIAbility实例,并进入该UIAbility实例的[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)回调函数;否则会创建一个新的UIAbility实例,并进入该UIAbility实例的[onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate)回调函数和[onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)回调函数。
由于SpecifiedAbility的启动模式配置为了指定实例启动模式,在SpecifiedAbility启动之前,会先进入其对应的AbilityStage的[onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)生命周期回调中,解析传入的want参数,获取`instanceKey`自定义参数。根据业务需要通过AbilityStage的[onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)生命周期回调返回一个字符串Key标识。[如果返回的Key对应一个已启动的UIAbility](mission-management-launch-type.md#fig14520125175314),则会将之前的UIAbility拉回前台并获焦,而不创建新的实例,否则创建新的实例并启动。
示例代码中,通过实现[onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)生命周期回调函数,解析传入的`want`参数,获取自定义参数`instanceKey`。业务逻辑会根据这个参数返回一个字符串Key,用于标识当前UIAbility实例。如果返回的Key已经对应一个已启动的UIAbility实例,系统会将该UIAbility实例拉回前台并获焦,而不会创建新的实例。如果返回的Key没有对应已启动的UIAbility实例,则系统会创建新的UIAbility实例并启动。
```ts ```ts
import AbilityStage from '@ohos.app.ability.AbilityStage'; import AbilityStage from '@ohos.app.ability.AbilityStage';
...@@ -139,19 +136,17 @@ specified启动模式为指定实例模式,针对一些特殊场景使用( ...@@ -139,19 +136,17 @@ specified启动模式为指定实例模式,针对一些特殊场景使用(
} }
} }
``` ```
> **说明:** > **说明:**
> >
> 1. 应用的UIAbility实例已创建,该UIAbility配置为指定实例模式,再次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法启动该UIAbility实例,且[AbilityStage](../reference/apis/js-apis-app-ability-abilityStage.md)的[onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)回调匹配到一个已创建的UIAbility实例。由于启动的还是原来的UIAbility实例,并未重新创建一个新的UIAbility实例,此时再次启动该UIAbility时,只会进入该UIAbility的[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)回调,不会进入其[onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate)和[onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)生命周期回调。 > 1. 当应用的UIAbility实例已经被创建,并且配置为指定实例模式时,如果再次调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法启动该UIAbility实例,且[AbilityStage](../reference/apis/js-apis-app-ability-abilityStage.md)的[onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)回调匹配到一个已创建的UIAbility实例,则系统会启动原来的UIAbility实例,并且不会重新创建一个新的UIAbility实例。此时,该UIAbility实例的[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)回调会被触发,而不会触发[onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate)和[onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)生命周期回调。
> 2. DevEco Studio默认工程中未自动生成AbilityStage,AbilityStage文件的创建请参见[AbilityStage组件容器](abilitystage.md)。 > 2. DevEco Studio默认工程中未自动生成AbilityStage,AbilityStage文件的创建请参见[AbilityStage组件容器](abilitystage.md)。
例如在文档应用中,可以对不同的文档实例内容绑定不同的Key值。当每次新建文档的时候,可以传入不同的新Key值(如可以将文件的路径作为一个Key标识),此时AbilityStage中启动UIAbility时都会创建一个新的UIAbility实例;当新建的文档保存之后,回到桌面,或者新打开一个已保存的文档,回到桌面,此时再次打开该已保存的文档,此时AbilityStage中再次启动该UIAbility时,打开的仍然是之前原来已保存的文档界面。 例如在文档应用中,可以为不同的文档实例内容绑定不同的Key值。每次新建文档时,可以传入一个新的Key值(例如可以将文件的路径作为一个Key标识),此时AbilityStage中启动UIAbility时都会创建一个新的UIAbility实例;当新建的文档保存之后,回到桌面,或者新打开一个已保存的文档,回到桌面,此时再次打开该已保存的文档,此时AbilityStage中再次启动该UIAbility时,打开的仍然是之前原来已保存的文档界面。
以如下步骤所示进行举例说明。 以如下步骤所示进行举例说明。
1. 打开文件A,对应启动一个新的UIAbility实例,例如启动“UIAbility实例1”。
1. 打开`文件A`,对应启动一个新的UIAbility实例,例如启动`UIAbility实例1`
2. 在最近任务列表中关闭文件A的进程,此时UIAbility实例1被销毁,回到桌面,再次打开文件A,此时对应启动一个新的UIAbility实例,例如启动“UIAbility实例2”。 2. 在最近任务列表中关闭`文件A`的任务进程,此时`UIAbility实例1`被销毁,回到桌面,再次打开`文件A`,此时对应启动一个新的UIAbility实例,例如启动`UIAbility实例2`
3. 回到桌面,打开`文件B`,此时对应启动一个新的UIAbility实例,例如启动`UIAbility实例3`
3. 回到桌面,打开文件B,此时对应启动一个新的UIAbility实例,例如启动“UIAbility实例3”。 4. 回到桌面,再次打开`文件A`,此时仍然启动之前的`UIAbility实例2`,因为系统会自动匹配UIAbility实例的Key值,如果存在与之匹配的Key,则会启动与之绑定的UIAbility实例。在此例中,之前启动的`UIAbility实例2``文件A`绑定的Key是相同的,因此系统会拉回`UIAbility实例2`并让其获焦,而不会创建新的实例。
4. 回到桌面,再次打开文件A,此时对应启动的还是之前的“UIAbility实例2”。
...@@ -118,7 +118,8 @@ ...@@ -118,7 +118,8 @@
应用需要获取用户的隐私信息或使用系统能力时,例如获取位置信息、访问日历、使用相机拍摄照片或者录制视频等,需要向用户申请授权。此时应用申请的权限包括了`user_grant`类型权限,需要先通过权限校验,判断当前调用者是否具备相应权限。当权限校验结果显示当前应用尚未被授权该权限时,再通过动态弹框授权方式给用户提供手动授权入口。示意效果如下图所示。 应用需要获取用户的隐私信息或使用系统能力时,例如获取位置信息、访问日历、使用相机拍摄照片或者录制视频等,需要向用户申请授权。此时应用申请的权限包括了`user_grant`类型权限,需要先通过权限校验,判断当前调用者是否具备相应权限。当权限校验结果显示当前应用尚未被授权该权限时,再通过动态弹框授权方式给用户提供手动授权入口。示意效果如下图所示。
![](figures/permission-read_calendar.jpeg) 图1 向用户申请授权
![](figures/permission-read_calendar.png)
> **说明**:每次访问受目标权限保护的接口前,都需要调用[requestPermissionsFromUser()](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9)接口请求权限,用户在动态授予后可能通过设置取消应用的权限,因此不能把之前授予的授权状态持久化。 > **说明**:每次访问受目标权限保护的接口前,都需要调用[requestPermissionsFromUser()](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9)接口请求权限,用户在动态授予后可能通过设置取消应用的权限,因此不能把之前授予的授权状态持久化。
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册