提交 3340cd39 编写于 作者: Z zengyawen 提交者: Gitee

Merge branch 'master' of gitee.com:openharmony/docs into master

Signed-off-by: Nzengyawen <zengyawen1@huawei.com>
......@@ -384,7 +384,7 @@ zh-cn/application-dev/reference/apis/js-apis-lightweightmap.md @gongjunsong @ge-
zh-cn/application-dev/reference/apis/js-apis-lightweightset.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-linkedlist.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-list.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-logs.md @huaweimaxuchu @ningningW @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-logs.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-media.md @liuyuehua1 @zengyawen @xxb-wzy @currydavids
zh-cn/application-dev/reference/apis/js-apis-medialibrary.md @panqinxu @zengyawen @bubble_mao @jinhaihw
zh-cn/application-dev/reference/apis/js-apis-mediaquery.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
......@@ -456,7 +456,7 @@ zh-cn/application-dev/reference/apis/js-apis-system-vibrate.md @hellohyh001 @nin
zh-cn/application-dev/reference/apis/js-apis-telephony-data.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-testRunner.md @inter515 @littlejerry1 @RayShih @inter515 @jiyong
zh-cn/application-dev/reference/apis/js-apis-thermal.md @aqxyjay @zengyawen @aqxyjay @alien0208
zh-cn/application-dev/reference/apis/js-apis-timer.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-timer.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-touchevent.md @mayunteng_1 @ningningW @cococoler @alien0208
zh-cn/application-dev/reference/apis/js-apis-treemap.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-treeset.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
......
......@@ -63,7 +63,7 @@ For details about how to use DevEco Studio to start the test framework, see [Ope
**Example**
```javascript
import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry';
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
......@@ -87,11 +87,11 @@ abilityDelegator.addAbilityMonitor(monitor).then(() => {
**Modules to Import**
```javascript
import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry';
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
```
```javascript
var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator()
```
### Starting an Ability and Listening for the Ability State
......
......@@ -25,7 +25,7 @@ Carry out the following operations to develop the widget provider based on the [
1. Implement lifecycle callbacks by using the **LifecycleForm** APIs.
2. Create a **FormBindingData** instance.
3. Update a widget by using the **FormProvider** APIs.
4. Develop the widget UI pages.
4. Develop the widget UI page.
## Available APIs
......@@ -231,7 +231,7 @@ You should override **onDestroy** to implement widget data deletion.
}
```
For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
For details about how to implement persistent data storage, see [Data Persistence by User Preferences](../database/data-persistence-by-preferences.md).
The **Want** object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
......@@ -402,3 +402,5 @@ The code snippet is as follows:
}
}
```
<!--no_check-->
\ No newline at end of file
......@@ -6,7 +6,7 @@ Ability continuation is to continue the current mission of an application, inclu
## Available APIs
The following table lists the APIs used for ability continuation. For details about the APIs, see [Ability](../reference/apis/js-apis-application-ability.md).
The following table lists the APIs used for ability continuation. For details about the APIs, see [UIAbility](../reference/apis/js-apis-app-ability-uiAbility.md).
**Table 1** Ability continuation APIs
......@@ -48,12 +48,9 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
}
```
- Configure the application startup type.
If **launchType** is set to **standard** in the **module.json5** file, the application is of the multi-instance launch type. During ability continuation, regardless of whether the application is already open, the target starts the application and restores the UI page. If **launchType** is set to **singleton**, the application is of the singleton launch type. If the application is already open, the target clears the existing page stack and restores the UI page. For more information, see "Launch Type" in [Ability Development](./stage-ability.md).
If **launchType** is set to **multiton** in the **module.json5** file, the application is of the multi-instance launch type. During ability continuation, regardless of whether the application is already open, the target starts the application and restores the UI page. If **launchType** is set to **singleton**, the application is of the singleton launch type. If the application is already open, the target clears the existing page stack and restores the UI page. For more information, see "Launch Type" in [Ability Development](./stage-ability.md).
Configure a multi-instance application as follows:
......@@ -62,7 +59,7 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
"module": {
"abilities": [
{
"launchType": "standard"
"launchType": "multiton"
}
]
}
......@@ -83,8 +80,6 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
}
```
- Apply for the distributed permissions.
Declare the **DISTRIBUTED_DATASYNC** permission in the **module.json5** file for the application.
......@@ -96,8 +91,6 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
},
```
This permission must be granted by the user in a dialog box when the application is started for the first time. To enable the application to display a dialog box to ask for the permission, add the following code to **onWindowStageCreate** of the **Ability** class:
```javascript
......@@ -139,7 +132,6 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
2. Implement the **onContinue()** API.
The **onContinue()** API is called by the initiator to save the UI component state variables and memory data and prepare for continuation. After the application completes the continuation preparation, the system must return either **OnContinueResult.AGREE(0)** to accept the continuation request or an error code to reject the request. If this API is not implemented, the system rejects the continuation request by default.
......@@ -155,7 +147,7 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
You can obtain the target device ID (identified by the key **targetDevice**) and the version number (identified by the key **version**) of the application installed on the target device from the **wantParam** parameter of this API. The version number can be used for compatibility check. If the current application version is incompatible with that on the target device, **OnContinueResult.MISMATCH** can be returned to reject the continuation request.
Example
Example:
```javascript
onContinue(wantParam : {[key: string]: any}) {
......@@ -168,8 +160,6 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
}
```
3. Implement the continuation logic in the **onCreate()** or **onNewWant()** API.
The **onCreate()** API is called by the target. When the ability is started on the target device, this API is called to instruct the application to synchronize the memory data and UI component state, and triggers page restoration after the synchronization is complete. If the continuation logic is not implemented, the ability will be started in common startup mode and the page cannot be restored.
......@@ -178,11 +168,9 @@ The code snippets provided below are all from [Sample](https://gitee.com/openhar
After data restore is complete, call **restoreWindowStage** to trigger page restoration.
You can also use **want.parameters.version** in the **want** parameter to obtain the application version number of the initiator.
Example
Example:
```javascript
import UIAbility from '@ohos.app.ability.UIAbility';
......@@ -211,7 +199,7 @@ For a singleton ability, use **onNewWant()** to achieve the same implementation.
Use distributed objects.
Distributed objects allow cross-device data synchronization like local variables. For two devices that form a Super Device, when data in the distributed data object of an application is added, deleted, or modified on a device, the data for the same application is also updated on the other device. Both devices can listen for the data changes and online and offline states of the other. For details, see [Distributed Data Object Development](../database/database-distributedobject-guidelines.md).
Distributed objects allow cross-device data synchronization like local variables. For two devices that form a Super Device, when data in the distributed data object of an application is added, deleted, or modified on a device, the data for the same application is also updated on the other device. Both devices can listen for the data changes and online and offline states of the other. For details, see [Sharing Distributed Data Objects](../database/data-sync-of-distributed-data-object.md).
In the ability continuation scenario, the distributed data object is used to synchronize the memory data from the local device to the target device.
......@@ -249,8 +237,6 @@ In the ability continuation scenario, the distributed data object is used to syn
});
```
- The target device obtains the session ID from **onCreate()**, creates a distributed object, and associates the distributed object with the session ID. In this way, the distributed object can be synchronized. Before calling **restoreWindowStage**, ensure that all distributed objects required for continuation have been associated.
```javascript
......@@ -283,8 +269,6 @@ In the ability continuation scenario, the distributed data object is used to syn
}
```
### More Information
1. Timeout
......@@ -294,15 +278,13 @@ In the ability continuation scenario, the distributed data object is used to syn
2. By default, the system supports page stack information migration, which means that the page stack of the initiator will be automatically migrated to the target device. No adaptation is required.
### Restrictions
1. The continuation must be performed between the same ability, which means the same bundle name, module name, and ability name. For details, see [Application Package Structure Configuration File](../quick-start/module-configuration-file.md).
2. Currently, the application can only implement the continuation capability. The continuation action must be initiated by the system.
### Best Practice
For better user experience, you are advised to use the **wantParam** parameter to transmit data smaller than 100 KB and use distributed objects to transmit data larger than 100 KB.
<!--no_check-->
\ No newline at end of file
......@@ -12,8 +12,8 @@ An ability can be launched in the **standard**, **singleton**, or **specified**
| Launch Type | Description |Action |
| ----------- | ------- |---------------- |
| standard | Standard mode | A new instance is started each time an ability starts.|
| singleton | Singleton mode | The ability has only one instance in the system. If an instance already exists when an ability is started, that instance is reused.|
| multiton | Multi-instance mode| A new instance is started each time an ability starts.|
| singleton | Singleton mode | Default type. The ability has only one instance in the system. If an instance already exists when an ability is started, that instance is reused.|
| specified | Instance-specific| The internal service of an ability determines whether to create multiple instances during running.|
By default, the singleton mode is used. The following is an example of the **module.json5** file:
......@@ -39,7 +39,7 @@ The table below describes the APIs provided by the **AbilityStage** class, which
|onAcceptWant(want: Want): string|Called when a specified ability is started.|
|onConfigurationUpdated(config: Configuration): void|Called when the global configuration is updated.|
The table below describes the APIs provided by the **Ability** class. For details about the APIs, see [Ability](../reference/apis/js-apis-application-ability.md).
The table below describes the APIs provided by the **Ability** class. For details about the APIs, see [UIAbility](../reference/apis/js-apis-app-ability-uiAbility.md).
**Table 2** Ability APIs
......@@ -190,7 +190,7 @@ export default class EntryAbility extends UIAbility {
```
## Starting an Ability
### Available APIs
The **Ability** class has the **context** attribute, which belongs to the **AbilityContext** class. The **AbilityContext** class has the **abilityInfo**, **currentHapModuleInfo**, and other attributes as well as the APIs used for starting abilities. For details, see [AbilityContext](../reference/apis/js-apis-ability-context.md).
The **Ability** class has the **context** attribute, which belongs to the **AbilityContext** class. The **AbilityContext** class has the **abilityInfo**, **currentHapModuleInfo**, and other attributes as well as the APIs used for starting abilities. For details, see [AbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md).
**Table 3** AbilityContext APIs
|API|Description|
......@@ -207,7 +207,7 @@ The **Ability** class has the **context** attribute, which belongs to the **Abil
An application can obtain the context of an **Ability** instance through **this.context** and then use the **startAbility** API in the **AbilityContext** class to start the ability. The ability can be started by specifying **Want**, **StartOptions**, and **accountId**, and the operation result can be returned using a callback or **Promise** instance. The sample code is as follows:
```ts
let context = this.context
var want = {
let want = {
"deviceId": "",
"bundleName": "com.example.MyApplication",
"abilityName": "EntryAbility"
......@@ -224,7 +224,7 @@ context.startAbility(want).then(() => {
In the cross-device scenario, you must specify the ID of the remote device. The sample code is as follows:
```ts
let context = this.context
var want = {
let want = {
"deviceId": getRemoteDeviceId(),
"bundleName": "com.example.MyApplication",
"abilityName": "EntryAbility"
......@@ -239,9 +239,9 @@ Obtain the ID of a specified device from **DeviceManager**. The sample code is a
```ts
import deviceManager from '@ohos.distributedHardware.deviceManager';
function getRemoteDeviceId() {
if (typeof dmClass === 'object' && dmClass != null) {
var list = dmClass.getTrustedDeviceListSync();
if (typeof (list) == 'undefined' || typeof (list.length) == 'undefined') {
if (typeof dmClass === 'object' && dmClass !== null) {
let list = dmClass.getTrustedDeviceListSync();
if (typeof (list) === 'undefined' || typeof (list.length) === 'undefined') {
console.log("EntryAbility onButtonClick getRemoteDeviceId err: list is null");
return;
}
......
......@@ -31,12 +31,12 @@ The ability call process is as follows:
> Currently, only system applications can use the ability call.
## Available APIs
The table below describes the ability call APIs. For details, see [Ability](../reference/apis/js-apis-application-ability.md#caller).
The table below describes the ability call APIs. For details, see [UIAbility](../reference/apis/js-apis-app-ability-uiAbility.md#caller).
**Table 2** Ability call APIs
|API|Description|
|:------|:------|
|startAbilityByCall(want: Want): Promise\<Caller>|Starts an ability in the foreground (through the **want** configuration) or background (default) and obtains the **Caller** object for communication with the ability. For details, see [AbilityContext](../reference/apis/js-apis-ability-context.md#abilitycontextstartabilitybycall) or **ServiceExtensionContext**.|
|startAbilityByCall(want: Want): Promise\<Caller>|Starts an ability in the foreground (through the **want** configuration) or background (default) and obtains the **Caller** object for communication with the ability. For details, see [AbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartabilitybycall) or **ServiceExtensionContext**.|
|on(method: string, callback: CalleeCallBack): void|Callback invoked when the callee ability registers a method.|
|off(method: string): void|Callback invoked when the callee ability deregisters a method.|
|call(method: string, data: rpc.Sequenceable): Promise\<void>|Sends agreed sequenceable data to the callee ability.|
......@@ -47,40 +47,45 @@ The table below describes the ability call APIs. For details, see [Ability](../r
## How to Develop
The procedure for developing the ability call is as follows:
1. Create a callee ability.
2. Access the callee ability.
### Creating a Callee Ability
For the callee ability, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use **on()** to register a listener. When data does not need to be received, use **off()** to deregister the listener.
**1. Configure the ability launch type.**
1. **Configure the ability launch type.**
Set **launchType** of the callee ability to **singleton** in the **module.json5** file.
|JSON Field|Description|
|:------|:------|
|"launchType"|Ability launch type. Set this parameter to **singleton**.|
|JSON Field|Description|
|:------|:------|
|"launchType"|Ability launch type. Set this parameter to **singleton**.|
An example of the ability configuration is as follows:
```json
"abilities":[{
An example of the ability configuration is as follows:
```json
"abilities":[{
"name": ".CalleeAbility",
"srcEntrance": "./ets/CalleeAbility/CalleeAbility.ts",
"srcEntry": "./ets/CalleeAbility/CalleeAbility.ts",
"launchType": "singleton",
"description": "$string:CalleeAbility_desc",
"icon": "$media:icon",
"label": "$string:CalleeAbility_label",
"visible": true
}]
```
**2. Import the Ability module.**
```ts
import Ability from '@ohos.app.ability.UIAbility'
```
**3. Define the agreed sequenceable data.**
"exported": true
}]
```
2. **Import the UIAbility module.**
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
```
3. **Define the agreed sequenceable data.**
The data formats sent and received by the caller and callee abilities must be consistent. In the following example, the data formats are number and string. The code snippet is as follows:
```ts
export default class MySequenceable {
```ts
export default class MySequenceable {
num: number = 0
str: string = ""
......@@ -100,16 +105,18 @@ export default class MySequenceable {
this.str = messageParcel.readString()
return true
}
}
```
**4. Implement Callee.on and Callee.off.**
}
```
4. **Implement Callee.on and Callee.off.**
The time to register a listener for the callee ability depends on your application. The data sent and received before the listener is registered and that after the listener is deregistered are not processed. In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate** of the ability and deregistered in **onDestroy**. After receiving sequenceable data, the application processes the data and returns the data result. You need to implement processing based on service requirements. The code snippet is as follows:
```ts
const TAG: string = '[CalleeAbility]'
const MSG_SEND_METHOD: string = 'CallSendMsg'
function sendMsgCallback(data) {
```ts
const TAG: string = '[CalleeAbility]'
const MSG_SEND_METHOD: string = 'CallSendMsg'
function sendMsgCallback(data) {
console.log('CalleeSortFunc called')
// Obtain the sequenceable data sent by the caller ability.
......@@ -120,9 +127,9 @@ function sendMsgCallback(data) {
// Process the data.
// Return the sequenceable data result to the caller ability.
return new MySequenceable(receivedData.num + 1, `send ${receivedData.str} succeed`)
}
}
export default class CalleeAbility extends Ability {
export default class CalleeAbility extends Ability {
onCreate(want, launchParam) {
try {
this.callee.on(MSG_SEND_METHOD, sendMsgCallback)
......@@ -138,20 +145,23 @@ export default class CalleeAbility extends Ability {
console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`)
}
}
}
```
}
```
### Accessing the Callee Ability
**1. Import the Ability module.**
```ts
import Ability from '@ohos.app.ability.UIAbility'
```
**2. Obtain the Caller object.**
1. **Import the Ability module.**
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
```
2. **Obtain the Caller object.**
The **context** attribute of the ability implements **startAbilityByCall** to obtain the **Caller** object for communication. The following example uses **this.context** to obtain the **context** attribute of the ability, uses **startAbilityByCall** to start the callee ability, obtain the **Caller** object, and register the **onRelease** listener of the caller ability. You need to implement processing based on service requirements. The code snippet is as follows:
```ts
// Register the onRelease listener of the caller ability.
private regOnRelease(caller) {
```ts
// Register the onRelease listener of the caller ability.
private regOnRelease(caller) {
try {
caller.on("release", (msg) => {
console.log(`caller onRelease is called ${msg}`)
......@@ -160,9 +170,9 @@ private regOnRelease(caller) {
} catch (error) {
console.log(`caller register OnRelease failed with ${error}`)
}
}
}
async onButtonGetCaller() {
async onButtonGetCaller() {
try {
this.caller = await context.startAbilityByCall({
bundleName: 'com.samples.CallApplication',
......@@ -177,11 +187,13 @@ async onButtonGetCaller() {
} catch (error) {
console.log(`get caller failed with ${error}`)
}
}
```
}
```
In the cross-device scenario, you need to specify the ID of the peer device. The code snippet is as follows:
```ts
async onButtonGetRemoteCaller() {
```ts
async onButtonGetRemoteCaller() {
var caller = undefined
var context = this.context
......@@ -202,13 +214,15 @@ async onButtonGetRemoteCaller() {
}).catch((error) => {
console.error(`get remote caller failed with ${error}`)
})
}
```
}
```
Obtain the ID of the peer device from **DeviceManager**. Note that the **getTrustedDeviceListSync** API is open only to system applications. The code snippet is as follows:
```ts
import deviceManager from '@ohos.distributedHardware.deviceManager';
var dmClass;
function getRemoteDeviceId() {
```ts
import deviceManager from '@ohos.distributedHardware.deviceManager';
var dmClass;
function getRemoteDeviceId() {
if (typeof dmClass === 'object' && dmClass != null) {
var list = dmClass.getTrustedDeviceListSync()
if (typeof (list) == 'undefined' || typeof (list.length) == 'undefined') {
......@@ -220,13 +234,15 @@ function getRemoteDeviceId() {
} else {
console.log("EntryAbility onButtonClick getRemoteDeviceId err: dmClass is null")
}
}
```
}
```
In the cross-device scenario, your application must also apply for the data synchronization permission from end users. The code snippet is as follows:
```ts
import abilityAccessCtrl from '@ohos.abilityAccessCtrl.d.ts';
requestPermission() {
```ts
import abilityAccessCtrl from '@ohos.abilityAccessCtrl.d.ts';
requestPermission() {
let context = this.context
let permissions: Array<string> = ['ohos.permission.DISTRIBUTED_DATASYNC']
let atManager = abilityAccessCtrl.createAtManager();
......@@ -235,29 +251,32 @@ requestPermission() {
}).catch((error) => {
console.log("Failed to request permission from user with error: "+ JSON.stringify(error))
})
}
```
**3. Send agreed sequenceable data.**
}
```
3. **Send agreed sequenceable data.**
The sequenceable data can be sent to the callee ability with or without a return value. The method and sequenceable data must be consistent with those of the callee ability. The following example describes how to send data to the callee ability. The code snippet is as follows:
```ts
const MSG_SEND_METHOD: string = 'CallSendMsg'
async onButtonCall() {
```ts
const MSG_SEND_METHOD: string = 'CallSendMsg'
async onButtonCall() {
try {
let msg = new MySequenceable(1, 'origin_Msg')
await this.caller.call(MSG_SEND_METHOD, msg)
} catch (error) {
console.log(`caller call failed with ${error}`)
}
}
```
}
```
In the following, **CallWithResult** is used to send data **originMsg** to the callee ability and assign the data processed by the **CallSendMsg** method to **backMsg**. The code snippet is as follows:
```ts
const MSG_SEND_METHOD: string = 'CallSendMsg'
originMsg: string = ''
backMsg: string = ''
async onButtonCallWithResult(originMsg, backMsg) {
```ts
const MSG_SEND_METHOD: string = 'CallSendMsg'
originMsg: string = ''
backMsg: string = ''
async onButtonCallWithResult(originMsg, backMsg) {
try {
let msg = new MySequenceable(1, originMsg)
const data = await this.caller.callWithResult(MSG_SEND_METHOD, msg)
......@@ -270,13 +289,15 @@ async onButtonCallWithResult(originMsg, backMsg) {
} catch (error) {
console.log(`caller callWithResult failed with ${error}`)
}
}
```
**4. Release the Caller object.**
}
```
4. **Release the Caller object.**
When the **Caller** object is no longer required, use **release()** to release it. The code snippet is as follows:
```ts
releaseCall() {
```ts
releaseCall() {
try {
this.caller.release()
this.caller = undefined
......@@ -284,5 +305,5 @@ releaseCall() {
} catch (error) {
console.log(`caller release failed with ${error}`)
}
}
```
}
```
\ No newline at end of file
......@@ -135,7 +135,7 @@ To create a widget in the stage model, you need to implement lifecycle callbacks
| Name | Description | Data Type | Default Value Allowed |
| ----------- | ------------------------------------------------------------ | ---------- | -------------------- |
| name | Name of the Extension ability. This field must be specified. | String | No |
| srcEntrance | Path of the Extension ability lifecycle code. This field must be specified.| String | No |
| srcEntry | Path of the Extension ability lifecycle code. This field must be specified.| String | No |
| description | Description of the Extension ability. The value can be a string or a resource index to descriptions in multiple languages.| String | Yes (initial value: left empty)|
| icon | Index of the Extension ability icon file. | String | Yes (initial value: left empty)|
| label | Descriptive information about the Extension ability presented externally. The value can be a string or a resource index to the description.| String | Yes (initial value: left empty)|
......@@ -150,7 +150,7 @@ To create a widget in the stage model, you need to implement lifecycle callbacks
```json
"extensionAbilities": [{
"name": "FormAbility",
"srcEntrance": "./ets/FormAbility/FormAbility.ts",
"srcEntry": "./ets/FormAbility/FormAbility.ts",
"label": "$string:form_FormAbility_label",
"description": "$string:form_FormAbility_desc",
"type": "form",
......@@ -242,7 +242,7 @@ You should override **onDestroy** to implement widget data deletion.
}
```
For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md).
For details about how to implement persistent data storage, see [Application Data Persistence Overview](../database/app-data-persistence-overview.md).
The **Want** object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary.
......@@ -366,7 +366,7 @@ You can set router and message events for components on a widget. The router eve
1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file.
2. Set the router event.
- **action**: **"router"**, which indicates a router event.
- **abilityName**: target ability name, for example, **EntryAbility**, which is the default UIAbility name in DevEco Studio for the stage model.
- **abilityName**: target ability name, for example, **EntryAbility**, which is the default main ability name in DevEco Studio for the stage model.
- **params**: custom parameters of the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the EntryAbility in the stage model, you can obtain **want** and its **parameters** field.
3. Set the message event.
- **action**: **"message"**, which indicates a message event.
......@@ -413,3 +413,5 @@ The code snippet is as follows:
}
}
```
<!--no_check-->
\ No newline at end of file
......@@ -33,8 +33,8 @@ OpenHarmony does not support creation of a Service Extension ability for third-p
"icon": "$media:icon",
"description": "service",
"type": "service",
"visible": true,
"srcEntrance": "./ets/ServiceExtAbility/ServiceExtAbility.ts"
"exported": true,
"srcEntry": "./ets/ServiceExtAbility/ServiceExtAbility.ts"
}]
```
......
......@@ -24,6 +24,8 @@ First thing first, familiarize yourself with the two cornerstone frameworks in O
All applications should be developed on top of these frameworks.
Then, equip yourself for developing the key features, with the following guidelines:
- [Web](web/web-component-overview.md)
- [Notification](notification/Readme-EN.md)
- [Window Manager](windowmanager/Readme-EN.md)
- [WebGL](webgl/Readme-EN.md)
......@@ -32,6 +34,7 @@ Then, equip yourself for developing the key features, with the following guideli
- [Connectivity](connectivity/Readme-EN.md)
- [Telephony Service](telephony/Readme-EN.md)
- [Data Management](database/Readme-EN.md)
- [File Management](file-management/Readme-EN.md)
- [Task Management](task-management/Readme-EN.md)
- [Device Management](device/Readme-EN.md)
- [Device Usage Statistics](device-usage-statistics/Readme-EN.md)
......@@ -40,7 +43,6 @@ Then, equip yourself for developing the key features, with the following guideli
- [Application Test](application-test/Readme-EN.md)
- [IDL Specifications and User Guide](IDL/idl-guidelines.md)
- [Using Native APIs in Application Projects](napi/Readme-EN.md)
- [File Management](file-management/medialibrary-overview.md)
### Tools
......@@ -70,3 +72,5 @@ They are organized as follows:
### Readme
For details about the principles and basic information of each subsystem, see the README file in [docs/en/readme](../readme).
<!--no_check-->
\ No newline at end of file
......@@ -4,7 +4,7 @@ The application development documents provide reference for you to develop appli
The documents are carefully organized as follows:
### Getting Started
## Getting Started
[Here](quick-start/start-overview.md) you'll learn how to quickly get started with OpenHarmony application development.
......@@ -12,7 +12,7 @@ Browse the documents on the instructions for quickly building your first applica
Check out the development fundamentals, which comprise descriptions of the package structure configuration file for OpenHarmony applications and the instructions for use of resource files.
### Development
## Development
To facilitate your application development, we provide development guidelines for key features.
......@@ -24,14 +24,17 @@ First thing first, familiarize yourself with the two cornerstone frameworks in O
All applications should be developed on top of these frameworks.
Then, equip yourself for developing the key features, with the following guidelines:
- [Web](web/web-component-overview.md)
- [Notification](notification/notification-overview.md)
- [Window Manager](windowmanager/window-overview.md)
- [WebGL](webgl/webgl-overview.md)
- [Media](media/audio-overview.md)
- [Media](media/media-application-overview.md)
- [Security](security/userauth-overview.md)
- [Connectivity](connectivity/ipc-rpc-overview.md)
- [Telephony Service](telephony/telephony-overview.md)
- [Data Management](database/database-mdds-overview.md)
- [Data Management](database/data-mgmt-overview.md)
- [File Management](file-management/file-management-overview.md)
- [Task Management](task-management/background-task-overview.md)
- [Device](device/usb-overview.md)
- [Device Usage Statistics](device-usage-statistics/device-usage-statistics-overview.md)
......@@ -40,32 +43,29 @@ Then, equip yourself for developing the key features, with the following guideli
- [Application Test](application-test/arkxtest-guidelines.md)
- [OpenHarmony IDL Specifications and User Guide](IDL/idl-guidelines.md)
- [Using Native APIs in Application Projects](napi/napi-guidelines.md)
- [File Management](file-management/medialibrary-overview.md)
### Tools
## Tools
DevEco Studio is a high-performance integrated development environment (IDE) recommended for developing OpenHarmony applications.
[Here](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-deveco-studio-overview-0000001263280421) you can learn everything about DevEco Studio, including how to use this tool to create a project and sign, debug, and run an application.
### Hands-On Tutorials
## Hands-On Tutorials
To make you better understand how functions work together and jumpstart your application development projects, we provide stripped-down, real-world [samples](https://gitee.com/openharmony/applications_app_samples/blob/master/README.md) and [codelabs](https://gitee.com/openharmony/codelabs).
### API References
## API References
API references encompass all components and APIs available in OpenHarmony, helping you use and integrate APIs more effectively.
They are organized as follows:
- [Component Reference (TypeScript-based Declarative Development Paradigm)](reference/arkui-ts/Readme-EN.md)
- [Component Reference (JavaScript-based Web-like Development Paradigm)](reference/arkui-js/Readme-EN.md)
- [JS Service Widget UI Components](reference/js-service-widget-ui/Readme-EN.md)
- [JS and TS APIs](reference/apis/js-apis-ability-dataUriUtils.md)
- [Component Reference (TypeScript-based Declarative Development Paradigm)](reference/arkui-ts/ts-components-summary.md)
- [Component Reference (JavaScript-compatible Web-like Development Paradigm-ArkUI.Full)](reference/arkui-js/js-components-common-attributes.md)
- [Component Reference (JavaScript-compatible Web-like Development Paradigm-ArkUI.Lite)](reference/arkui-js-lite/js-framework-file.md)
- [JS Service Widget UI Components](reference/js-service-widget-ui/js-service-widget-file.md)
- [JS and TS APIs](reference/apis/development-intro.md)
- Native APIs
- [Standard Library](reference/native-lib/third_party_libc/musl.md)
- [Node_API](reference/native-lib/third_party_napi/napi.md)
<!--no_check-->
\ No newline at end of file
......@@ -189,7 +189,7 @@ The following steps describe how to use the text drawing and display feature of
OH_Drawing_CreateFontCollection());
OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
// Set the text content.
const char* text = "OpenHarmony\n";
const char* text = "Hello World\n";
OH_Drawing_TypographyHandlerAddText(handler, text);
OH_Drawing_TypographyHandlerPopTextStyle(handler);
OH_Drawing_Typography* typography = OH_Drawing_CreateTypography(handler);
......
......@@ -6,11 +6,10 @@ The **BundleStatusCallback** module provides callbacks for bundle status changes
>
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## BundleStatusCallback<sup>(deprecated)<sup>
> This API is deprecated since API version 9. You are advised to use [bundleMonitor](js-apis-bundleMonitor.md) instead.
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**System capability**: SystemCapability.BundleManager.BundleFramework
......
......@@ -34,7 +34,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -62,7 +62,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -94,7 +94,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -121,7 +121,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -153,7 +153,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -179,7 +179,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -210,7 +210,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -236,7 +236,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -267,7 +267,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -293,7 +293,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......
......@@ -42,7 +42,7 @@ SystemCapability.BundleManager.DistributedBundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -71,7 +71,7 @@ SystemCapability.BundleManager.DistributedBundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -103,7 +103,7 @@ SystemCapability.BundleManager.DistributedBundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -132,7 +132,7 @@ SystemCapability.BundleManager.DistributedBundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......
......@@ -426,7 +426,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Return value**
......@@ -462,7 +462,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -499,7 +499,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -540,7 +540,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -584,7 +584,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -626,7 +626,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -671,7 +671,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -699,7 +699,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -754,7 +754,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......@@ -794,7 +794,7 @@ SystemCapability.BundleManager.BundleFramework
**System API**
This is a system API and cannot be called by third-party applications.
This is a system API.
**Parameters**
......
......@@ -26,7 +26,7 @@ import Want from '@ohos.app.ability.Want';
| entities | Array\<string> | No| Additional category information (such as browser and video player) of the ability. It is a supplement to the **action** field for implicit Want. and is used to filter ability types.|
| uri | string | No| Data carried. This field is used together with **type** to specify the data type. If **uri** is specified in a Want, the Want will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.|
| type | string | No| MIME type, that is, the type of the file to open, for example, **'text/xml'** and **'image/*'**. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com.|
| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>- **ohos.aafwk.param.callerToken**: token of the caller.<br>- **ohos.aafwk.param.callerUid**: UID in [BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information.<br>- **component.startup.newRules**: whether to enable the new control rule.<br>- **moduleName**: module name of the caller. No matter what this field is set to, the correct module name will be sent to the peer.<br>- **ohos.dlp.params.sandbox**: available only for DLP files. |
| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>- **ohos.aafwk.param.callerBundleName**: bundle name of the caller.<br>- **ohos.aafwk.param.callerToken**: token of the caller.<br>- **ohos.aafwk.param.callerUid**: UID in [BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information.<br>- **component.startup.newRules**: whether to enable the new control rule.<br>- **moduleName**: module name of the caller. No matter what this field is set to, the correct module name will be sent to the peer.<br>- **ohos.dlp.params.sandbox**: available only for DLP files.|
| [flags](js-apis-ability-wantConstant.md#wantconstantflags) | number | No| How the **Want** object will be handled. By default, a number is passed in.<br>For example, **wantConstant.Flags.FLAG_ABILITY_CONTINUATION** specifies whether to start the ability in cross-device migration scenarios.|
**Example**
......@@ -34,6 +34,7 @@ import Want from '@ohos.app.ability.Want';
- Basic usage: called in a UIAbility object, as shown in the example below. For details about how to obtain the context, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
```ts
let context = ...; // UIAbilityContext
let want = {
'deviceId': '', // An empty deviceId indicates the local device.
'bundleName': 'com.example.myapplication',
......@@ -41,16 +42,17 @@ import Want from '@ohos.app.ability.Want';
'moduleName': 'entry' // moduleName is optional.
};
this.context.startAbility(want, (err) => {
context.startAbility(want, (err) => {
// Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability.
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
});
```
- Data is transferred through user-defined fields. The following data types are supported (called in a UIAbility object, as shown in the example below. For details about how to obtain the context, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).)
- Currently, the following data types are supported: string, number, Boolean, object, array, and file descriptor (FD).
* String
```ts
let context = ...; // UIAbilityContext
let want = {
bundleName: 'com.example.myapplication',
abilityName: 'FuncAbility',
......@@ -59,12 +61,13 @@ import Want from '@ohos.app.ability.Want';
},
};
this.context.startAbility(want, (err) => {
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
context.startAbility(want, (err) => {
console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
});
```
* Number
```ts
let context = ...; // UIAbilityContext
let want = {
bundleName: 'com.example.myapplication',
abilityName: 'FuncAbility',
......@@ -74,12 +77,13 @@ import Want from '@ohos.app.ability.Want';
},
};
this.context.startAbility(want, (err) => {
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
context.startAbility(want, (err) => {
console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
});
```
* Boolean
```ts
let context = ...; // UIAbilityContext
let want = {
bundleName: 'com.example.myapplication',
abilityName: 'FuncAbility',
......@@ -88,12 +92,13 @@ import Want from '@ohos.app.ability.Want';
},
};
this.context.startAbility(want, (err) => {
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
context.startAbility(want, (err) => {
console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
});
```
* Object
```ts
let context = ...; // UIAbilityContext
let want = {
bundleName: 'com.example.myapplication',
abilityName: 'FuncAbility',
......@@ -107,12 +112,13 @@ import Want from '@ohos.app.ability.Want';
},
};
this.context.startAbility(want, (err) => {
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
context.startAbility(want, (err) => {
console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
});
```
* Array
```ts
let context = ...; // UIAbilityContext
let want = {
bundleName: 'com.example.myapplication',
abilityName: 'FuncAbility',
......@@ -124,19 +130,21 @@ import Want from '@ohos.app.ability.Want';
},
};
this.context.startAbility(want, (err) => {
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
context.startAbility(want, (err) => {
console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
});
```
* File descriptor (FD)
* FD
```ts
import fileio from '@ohos.fileio';
import fs from '@ohos.file.fs';
let context = ...; // UIAbilityContext
let fd;
try {
fd = fileio.openSync('/data/storage/el2/base/haps/pic.png');
} catch(e) {
console.error('openSync fail: ${JSON.stringify(e)}');
fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd;
} catch(err) {
console.error(`Failed to openSync. Code: ${err.code}, message: ${err.message}`);
}
let want = {
'deviceId': '', // An empty deviceId indicates the local device.
......@@ -148,7 +156,7 @@ import Want from '@ohos.app.ability.Want';
}
};
this.context.startAbility(want, (err) => {
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
context.startAbility(want, (err) => {
console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`);
});
```
......@@ -24,7 +24,7 @@ Sets the disposed status for an application. This API uses a promise to return t
**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -75,7 +75,7 @@ Sets the disposed status for an application. This API uses an asynchronous callb
**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -122,7 +122,7 @@ Obtains the disposed status of an application. This API uses a promise to return
**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -171,7 +171,7 @@ Obtains the disposed status of an application. This API uses an asynchronous cal
**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -216,7 +216,7 @@ Deletes the disposed status for an application. This API uses a promise to retur
**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -265,7 +265,7 @@ Deletes the disposed status for an application. This API uses an asynchronous ca
**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......
......@@ -24,9 +24,9 @@ import Want from '@ohos.application.Want';
| uri | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.|
| type | string | No | MIME type, that is, the type of the file to open, for example, **'text/xml'** and **'image/*'**. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com. |
| flags | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-ability-wantConstant.md#wantconstantflags).|
| action | string | No | Action to take, such as viewing and sharing application details. In implicit **Want**, you can define this attribute and use it together with **uri** or **parameters** to specify the operation to be performed on the data. For details, see [action](js-apis-ability-wantConstant.md#wantconstantaction). For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](application-models/explicit-implicit-want-mappings.md). |
| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>- **ohos.aafwk.param.callerToken**: token of the caller.<br>- **ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo1), that is, the application UID in the bundle information.<br>- **component.startup.newRules**: whether to enable the new control rule.<br>- **moduleName**: module name of the caller. No matter what this field is set to, the correct module name will be sent to the peer.<br>- **ohos.dlp.params.sandbox**: available only for DLP files. |
| entities | Array\<string> | No | Additional category information (such as browser and video player) of the ability. It is a supplement to the **action** field for implicit Want. and is used to filter ability types. For details, see [entity](js-apis-app-ability-wantConstant.md#wantconstantentity). |
| action | string | No | Action to take, such as viewing and sharing application details. In implicit **Want**, you can define this attribute and use it together with **uri** or **parameters** to specify the operation to be performed on the data. For details, see [action](js-apis-ability-wantConstant.md#wantconstantaction). For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](../../application-models/explicit-implicit-want-mappings.md). |
| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>- **ohos.aafwk.param.callerToken**: token of the caller.<br>- **ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo), that is, the application UID in the bundle information.<br>- **component.startup.newRules**: whether to enable the new control rule.<br>- **moduleName**: module name of the caller. No matter what this field is set to, the correct module name will be sent to the peer.<br>- **ohos.dlp.params.sandbox**: available only for DLP files. |
| entities | Array\<string> | No | Additional category information (such as browser and video player) of the ability. It is a supplement to the **action** field for implicit Want. and is used to filter ability types. For details, see [entity](js-apis-ability-wantConstant.md#wantconstantentity). |
**Example**
......@@ -108,10 +108,10 @@ import Want from '@ohos.application.Want';
```
* File descriptor (FD)
```ts
import fileio from '@ohos.fileio';
import fs from '@ohos.file.fs';
let fd;
try {
fd = fileio.openSync('/data/storage/el2/base/haps/pic.png');
fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd;
} catch(e) {
console.error('openSync fail: ${JSON.stringify(e)}');
}
......
# @ohos.arkui.drawableDescriptor (DrawableDescriptor)
The **DrawableDescriptor** module provides APIs for obtaining **pixelMap** objects, including the foreground, background, mask, and layered icons.
> **NOTE**
>
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer.
## Modules to Import
```js
import { DrawableDescriptor, LayeredDrawableDescriptor } from '@ohos.arkui.drawableDescriptor';
```
## DrawableDescriptor.constructor
constructor()
Creates a **DrawableDescriptor** or **LayeredDrawableDescriptor** object. The globalization API [getDrawableDescriptor](js-apis-resource-manager.md##getdrawabledescriptor) or [getDrawableDescriptorByName](js-apis-resource-manager.md##getdrawabledescriptorbyname) is required for object construction.
**System API**: This is a system API.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
### DrawableDescriptor
Creates a **DrawableDescriptor** object when the passed resource ID or name belongs to a common image.
### LayeredDrawableDescriptor
Creates a **LayeredDrawableDescriptor** object when the passed resource ID or name belongs to a JSON file that contains foreground and background resources.
**Example**
```js
@Entry
@Component
struct Index {
private resManager = getContext().resourceManager
let drawable1 = resManager.getDrawableDescriptor($r('app.media.icon').id)
let drawable2 = resManager.getDrawableDescriptorByName(icon)
let layeredDrawable1 = resManager.getDrawableDescriptor($r('app.media.file').id)
let layeredDrawable1 = resManager.getDrawableDescriptor(file)
}
```
## DrawableDescriptor.getPixelMap
getPixelMap(): image.PixelMap;
Obtains this **pixelMap** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------------- | ---------------- |
| [image.PixelMap](../apis/js-apis-image.md#pixelmap7) | **pixelMap** object.|
**Example**
```js
@State pixmap: PixelMap = drawable1.getPixelMap();
```
## LayeredDrawableDescriptor.getPixelMap
getPixelMap(): image.PixelMap;
Obtains the **pixelMap** object where the foreground, background, and mask are blended and cropped.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------------- | ---------------- |
| [image.PixelMap](../apis/js-apis-image.md#pixelmap7) | **pixelMap** object.|
**Example**
```js
@State pixmap: PixelMap = layeredDrawable1.getPixelMap();
```
## LayeredDrawableDescriptor.getForeground
getForeground(): DrawableDescriptor;
Obtains the **DrawableDescriptor** object of the foreground.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------------- | ---------------- |
| [DrawableDescriptor](#drawabledescriptor) | **DrawableDescriptor** object.|
**Example**
```js
@State drawable: DrawableDescriptor = layeredDrawable1.getForeground();
```
## LayeredDrawableDescriptor.getBackground
getBackground(): DrawableDescriptor;
Obtains the **DrawableDescriptor** object of the background.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------------- | ---------------- |
| [DrawableDescriptor](#drawabledescriptor) | **DrawableDescriptor** object.|
**Example**
```js
@State drawable: DrawableDescriptor = layeredDrawable1.getBackground();
```
## LayeredDrawableDescriptor.getMask
getMask(): DrawableDescriptor;
Obtains the **DrawableDescriptor** object of the mask.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------------- | ---------------- |
| [DrawableDescriptor](#drawabledescriptor) | **DrawableDescriptor** object.|
**Example**
```js
@State drawable: DrawableDescriptor = layeredDrawable1.getMask();
```
<!--no_check-->
\ No newline at end of file
......@@ -22,7 +22,7 @@ ohos.permission.INSTALL_BUNDLE
SystemCapability.BundleManager.BundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -72,7 +72,7 @@ ohos.permission.INSTALL_BUNDLE
SystemCapability.BundleManager.BundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -121,7 +121,7 @@ ohos.permission.INSTALL_BUNDLE
SystemCapability.BundleManager.BundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -162,7 +162,7 @@ Describes the parameters required for bundle installation, recovery, or uninstal
**System capability**: SystemCapability.BundleManager.BundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
| Name | Type | Readable| Writable| Description |
| ----------- | ------- | ---- | ---- | ------------------ |
......@@ -176,12 +176,12 @@ Describes the bundle installation or uninstall status.
**System capability**: SystemCapability.BundleManager.BundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
| Name | Type | Readable| Writable| Description |
| ------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------ |
| status | bundle.[InstallErrorCode](js-apis-Bundle.md#installerrorcode) | Yes | No | Installation or uninstall error code. The value must be defined in [InstallErrorCode](js-apis-Bundle.md#installerrorcode)|
| statusMessage | string | Yes | No | Installation or uninstall status message. <br>**SUCCESS**: install_succeed<br>**STATUS_INSTALL_FAILURE**: Installation failed (no installation file exists).<br>**STATUS_INSTALL_FAILURE_ABORTED**: Installation aborted.<br>**STATUS_INSTALL_FAILURE_INVALID**: Invalid installation parameter.<br>**STATUS_INSTALL_FAILURE_CONFLICT**: Installation conflict. (The basic information of the application to update is inconsistent with that of the existing application.)<br>**STATUS_INSTALL_FAILURE_STORAGE**: Failed to store the bundle information.<br>**STATUS_INSTALL_FAILURE_INCOMPATIBLE**: Installation incompatibility. (A downgrade occurs or the signature information is incorrect.)<br>**STATUS_UNINSTALL_FAILURE**: Uninstallation failed. (The application to be uninstalled is not found.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation aborted. (This error code is not in use.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation conflict. (Failed to uninstall a system application or end the application process.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_TIMEOUT**: Installation failed. (Download timed out.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_FAILED**: Installation failed. (Download failed.)<br>**STATUS_RECOVER_FAILURE_INVALID**: Failed to restore the pre-installed application.<br>**STATUS_ABILITY_NOT_FOUND**: Ability not found.<br>**STATUS_BMS_SERVICE_ERROR**: BMS service error.<br>**STATUS_FAILED_NO_SPACE_LEFT**: Insufficient device space.<br>**STATUS_GRANT_REQUEST_PERMISSIONS_FAILED**: Application authorization failed.<br>**STATUS_INSTALL_PERMISSION_DENIED**: No installation permission.<br>**STATUS_UNINSTALL_PERMISSION_DENIED**: No uninstallation permission. |
| statusMessage | string | Yes | No | Installation or uninstall status message. <br>**SUCCESS**: install_succeed<br>**STATUS_INSTALL_FAILURE**: Installation failed (no installation file exists).<br>**STATUS_INSTALL_FAILURE_ABORTED**: Installation aborted.<br>**STATUS_INSTALL_FAILURE_INVALID**: Invalid installation parameter.<br>**STATUS_INSTALL_FAILURE_CONFLICT**: Installation conflict. (The basic information of the application to update is inconsistent with that of the existing application.)<br>**STATUS_INSTALL_FAILURE_STORAGE**: Failed to store the bundle information.<br>**STATUS_INSTALL_FAILURE_INCOMPATIBLE**: Installation incompatibility. (A downgrade occurs or the signature information is incorrect.)<br>**STATUS_UNINSTALL_FAILURE**: Uninstallation failed. (The application to be uninstalled is not found.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation aborted. (This error code is not in use.)<br>**STATUS_UNINSTALL_FAILURE_ABORTED**: Uninstallation conflict. (Failed to uninstall a system application or end the application process.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_TIMEOUT**: Installation failed. (Download timed out.)<br>**STATUS_INSTALL_FAILURE_DOWNLOAD_FAILED**: Installation failed. (Download failed.)<br>**STATUS_RECOVER_FAILURE_INVALID**: Failed to restore the pre-installed application.<br>**STATUS_ABILITY_NOT_FOUND**: Ability not found.<br>**STATUS_BMS_SERVICE_ERROR**: BMS service error.<br>**STATUS_FAILED_NO_SPACE_LEFT**: Insufficient device space.<br>**STATUS_GRANT_REQUEST_PERMISSIONS_FAILED**: Application authorization failed.<br>**STATUS_INSTALL_PERMISSION_DENIED**: No installation permission.<br>**STATUS_UNINSTALL_PERMISSION_DENIED**: No uninstallation permission.|
## Obtaining the Sandbox Path
For the FA model, the sandbox path of a bundle can be obtained using the APIs in [Context](js-apis-inner-app-context.md). For the stage model, the sandbox path can be obtained using the attribute in [Context](js-apis-inner-application-uiAbilityContext.md#abilitycontext). The following describes how to obtain the sandbox path.
......
......@@ -12,7 +12,7 @@ The **LauncherAbilityInfo** module provides information about the launcher abili
**System capability**: SystemCapability.BundleManager.BundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
| Name | Type | Readable| Writable| Description |
| --------------- | ---------------------------------------------------- | ---- | ---- | -------------------------------------- |
......
......@@ -12,7 +12,7 @@ The **PermissionDef** module provides permission details defined in the configur
**System capability**: SystemCapability.BundleManager.BundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
| Name | Type | Readable| Writable| Description |
| -------------- | ------ | ---- | ---- | -------------- |
......
......@@ -12,11 +12,10 @@ The **RemoteAbilityInfo** module provides information about a remote ability.
**System capability**: SystemCapability.BundleManager.DistributedBundleFramework
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
| Name | Type | Readable| Writable| Description |
| ----------- | -------------------------------------------- | ---- | ---- | ----------------------- |
| elementName | [ElementName](js-apis-bundle-ElementName.md) | Yes | No | Element name information of the ability. |
| label | string | Yes | No | Ability name. |
| icon | string | Yes | No | Icon of the ability.|
......@@ -10,7 +10,7 @@ The **LauncherAbilityInfo** module defines the ability information of the home s
**System capability**: SystemCapability.BundleManager.BundleFramework.Launcher
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
| Name | Type | Readable| Writable| Description |
| --------------- | ----------------------------------------------------------- | ---- | ---- | ------------------------------------ |
......
......@@ -98,12 +98,12 @@ Enumerates the types of Extension abilities.
| Name| Value| Description|
|:----------------:|:---:|-----|
| FORM | 0 | [FormExtensionAbility](../../application-models/widget-development-stage.md): provides APIs for widget development.|
| FORM | 0 | [FormExtensionAbility](../../application-models/service-widget-overview.md): provides APIs for widget development.|
| WORK_SCHEDULER | 1 | [WorkSchedulerExtensionAbility](../../task-management/work-scheduler-dev-guide.md): enables applications to execute non-real-time tasks when the system is idle.|
| INPUT_METHOD | 2 | [InputMethodExtensionAbility](js-apis-inputmethod-extension-ability.md): provides APIs for developing input method applications.|
| SERVICE | 3 | [ServiceExtensionAbility](../../application-models/serviceextensionability.md): enables applications to run in the background and provide services.|
| ACCESSIBILITY | 4 | [AccessibilityExtensionAbility](js-apis-application-accessibilityExtensionAbility.md): provides accessibility for access to and operations on the UI.|
| DATA_SHARE | 5 | [DataShareExtensionAbility](../../database/database-datashare-guidelines.md): enables applications to read and write data.|
| DATA_SHARE | 5 | [DataShareExtensionAbility](../../database/share-data-by-datashareextensionability.md): enables applications to read and write data.|
| FILE_SHARE | 6 | FileShareExtensionAbility: enables file sharing between applications. This ability is reserved.|
| STATIC_SUBSCRIBER| 7 | [StaticSubscriberExtensionAbility](js-apis-application-staticSubscriberExtensionAbility.md): provides APIs for processing static events, such as the startup event.|
| WALLPAPER | 8 | WallpaperExtensionAbility: provides APIs to implement the home screen wallpaper. This ability is reserved.|
......@@ -113,6 +113,7 @@ Enumerates the types of Extension abilities.
| THUMBNAIL | 13 | ThumbnailExtensionAbility: provides thumbnails for files. This ability is reserved.|
| PREVIEW | 14 | PreviewExtensionAbility: provides APIs for file preview so that other applications can be embedded and displayed in the current application. This ability is reserved.|
| PRINT<sup>10+</sup> | 15 | PrintExtensionAbility: provides APIs for printing images. Printing documents is not supported yet.|
| DRIVER<sup>10+</sup> | 18 | DriverExtensionAbility: provides APIs for the peripheral driver. This type of ability is not supported yet.|
| UNSPECIFIED | 255 | No type is specified. It is used together with **queryExtensionAbilityInfo** to query all types of Extension abilities.|
......@@ -187,7 +188,7 @@ Enumerates the display orientations of the ability. This attribute applies only
| AUTO_ROTATION_PORTRAIT_RESTRICTED |11|Switched-determined auto rotation in the vertical direction.|
| LOCKED |12|Locked.|
### CompatiblePolicy
### CompatiblePolicy<sup>10+</sup>
Defines the version compatibility type of the shared library.
......@@ -3069,3 +3070,167 @@ try {
hilog.error(0x0000, 'testTag', 'getAllSharedBundleInfo failed. Cause: %{public}s', err.message);
}
```
### bundleManager.getAppProvisionInfo<sup>10+</sup>
getAppProvisionInfo(bundleName: string, callback: AsyncCallback\<[AppProvisionInfo](js-apis-bundleManager-AppProvisionInfo.md)\>): void;
Obtains the provision configuration file information based on the given bundle name. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| bundleName | string | Yes | Bundle name.|
| callback | AsyncCallback\<[AppProvisionInfo](js-apis-bundleManager-AppProvisionInfo.md)\> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is the provision configuration file information obtained.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | -------------------------------------- |
| 17700001 | The specified bundleName is not found. |
**Example**
```ts
import bundleManager from '@ohos.bundle.bundleManager';
import hilog from '@ohos.hilog';
let bundleName = "com.ohos.myapplication";
try {
bundleManager.getAppProvisionInfo(bundleName, (err, data) => {
if (err) {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed: %{public}s', err.message);
} else {
hilog.info(0x0000, 'testTag', 'getAppProvisionInfo successfully: %{public}s', JSON.stringify(data));
}
});
} catch (err) {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed: %{public}s', err.message);
}
```
### bundleManager.getAppProvisionInfo<sup>10+</sup>
getAppProvisionInfo(bundleName: string, userId: number, callback: AsyncCallback\<[AppProvisionInfo](js-apis-bundleManager-AppProvisionInfo.md)\>): void;
Obtains the provision configuration file information based on the given bundle name and user ID. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| bundleName | string | Yes | Bundle name.|
| userId | number | Yes| User ID, which can be obtained by calling [getOsAccountLocalId](js-apis-osAccount.md#getosaccountlocalid9).|
| callback | AsyncCallback\<[AppProvisionInfo](js-apis-bundleManager-AppProvisionInfo.md)\> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is the provision configuration file information obtained.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | -------------------------------------- |
| 17700001 | The specified bundleName is not found. |
| 17700004 | The specified user ID is not found. |
**Example**
```ts
import bundleManager from '@ohos.bundle.bundleManager';
import hilog from '@ohos.hilog';
let bundleName = "com.ohos.myapplication";
let userId = 100;
try {
bundleManager.getAppProvisionInfo(bundleName, userId, (err, data) => {
if (err) {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed: %{public}s', err.message);
} else {
hilog.info(0x0000, 'testTag', 'getAppProvisionInfo successfully: %{public}s', JSON.stringify(data));
}
});
} catch (err) {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed: %{public}s', err.message);
}
```
### bundleManager.getAppProvisionInfo<sup>10+</sup>
getAppProvisionInfo(bundleName: string, userId?: number): Promise\<[AppProvisionInfo](js-apis-bundleManager-AppProvisionInfo.md)\>;
Obtains the provision configuration file information based on the given bundle name and user ID. This API uses a promise to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| bundleName | string | Yes| Bundle name.|
| userId | number | No| User ID, which can be obtained by calling [getOsAccountLocalId](js-apis-osAccount.md#getosaccountlocalid9).|
**Return value**
| Type | Description |
| ------------------------------------------------------------ | ----------------------------------- |
| Promise\<[AppProvisionInfo](js-apis-bundleManager-AppProvisionInfo.md)\> | Promise used to return the provision configuration file obtained.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | -------------------------------------- |
| 17700001 | The specified bundleName is not found. |
| 17700004 | The specified user ID is not found. |
**Example**
```ts
import bundleManager from '@ohos.bundle.bundleManager';
import hilog from '@ohos.hilog';
let bundleName = "com.ohos.myapplication";
let userId = 100;
try {
bundleManager.getAppProvisionInfo(bundleName).then((data) => {
hilog.info(0x0000, 'testTag', 'getAppProvisionInfo successfully. Data: %{public}s', JSON.stringify(data));
}).catch(err => {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed. Cause: %{public}s', err.message);
});
} catch (err) {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed. Cause: %{public}s', err.message);
}
try {
bundleManager.getAppProvisionInfo(bundleName, userId).then((data) => {
hilog.info(0x0000, 'testTag', 'getAppProvisionInfo successfully. Data: %{public}s', JSON.stringify(data));
}).catch(err => {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed. Cause: %{public}s', err.message);
});
} catch (err) {
hilog.error(0x0000, 'testTag', 'getAppProvisionInfo failed. Cause: %{public}s', err.message);
}
```
<!--no_check-->
\ No newline at end of file
......@@ -24,7 +24,7 @@ For details, see [Permission Levels](../../security/accesstoken-overview.md).
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
| Name | Template | Readable| Writable| Description |
| ---------- | ------ | ---- | ---- | -------------------------- |
......@@ -39,7 +39,7 @@ Subscribes to bundle installation, uninstall, and update events.
**Required permissions**: ohos.permission.LISTEN_BUNDLE_CHANGE
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
......@@ -72,7 +72,7 @@ Unsubscribes from bundle installation, uninstall, and update events.
**Required permissions**: ohos.permission.LISTEN_BUNDLE_CHANGE
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
......
......@@ -109,7 +109,7 @@ Obtains the default application based on a system-defined application type or a
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -165,7 +165,7 @@ Obtains the default application of a user based on a system-defined application
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -217,7 +217,7 @@ Obtains the default application based on a system-defined application type or a
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -266,7 +266,7 @@ Sets the default application based on a system-defined application type or a fil
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -338,7 +338,7 @@ Sets the default application for a user based on a system-defined application ty
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -399,7 +399,7 @@ Sets the default application based on a system-defined application type or a fil
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -458,7 +458,7 @@ Resets the default application based on a system-defined application type or a f
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -508,7 +508,7 @@ Resets the default application for a user based on a system-defined application
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......@@ -559,7 +559,7 @@ Resets the default application based on a system-defined application type or a f
**System capability**: SystemCapability.BundleManager.BundleFramework.DefaultApp
**System API**: This is a system API and cannot be called by third-party applications.
**System API**: This is a system API.
**Parameters**
......
......@@ -291,6 +291,63 @@ try {
}
```
## display.on('privateModeChange')<sup>10+</sup>
on(type: 'privateModeChange', callback: Callback&lt;boolean&gt;): void
Subscribes to privacy mode changes of this display. When there is a privacy window in the foreground of the display, the display is in privacy mode, and the content in the privacy window cannot be captured or recorded.
**System API**: This is a system API.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at 'privateModeChange', indicating the event of display privacy mode changes.|
| callback | Callback&lt;boolean&gt; | Yes | Callback used to return whether the privacy mode of the display is changed. The value **true** means that the display changes to the privacy mode, and **false** means the opposite.|
**Example**
```js
let callback = (data) => {
console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
try {
display.on("privateModeChange", callback);
} catch (exception) {
console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
}
```
## display.off('privateModeChange')<sup>10+</sup>
off(type: 'privateModeChange', callback?: Callback&lt;boolean&gt;): void
Unsubscribes from privacy mode changes of this display. When there is a privacy window in the foreground of the display, the display is in privacy mode, and the content in the privacy window cannot be captured or recorded.
**System API**: This is a system API.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'privateModeChange'**, indicating the event of display private mode changes.|
| callback | Callback&lt;boolean&gt; | No | Callback used to return whether the privacy mode of the display is changed. The value **true** means that the display changes to the privacy mode, and **false** means the opposite.|
**Example**
```js
try {
display.off("privateModeChange");
} catch (exception) {
console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
}
```
## display.getDefaultDisplay<sup>(deprecated)</sup>
getDefaultDisplay(callback: AsyncCallback&lt;Display&gt;): void
......
......@@ -80,9 +80,9 @@ image.createPixelMap(color, opts, (error, pixelmap) => {
## PixelMap<sup>7+</sup>
Provides APIs to read or write image pixel map data and obtain image pixel map information. Before calling any API in **PixelMap**, you must use **createPixelMap** to create a **PixelMap** object.
Provides APIs to read or write image pixel map data and obtain image pixel map information. Before calling any API in **PixelMap**, you must use **createPixelMap** to create a **PixelMap** object. Currently, the maximum size of a serialized pixel map is 128 MB. A larger size will cause a display failure. The size is calculated as follows: Width * Height * Number of bytes occupied by each pixel.
### Attributes
### Attributes
**System capability**: SystemCapability.Multimedia.Image.Core
......@@ -950,7 +950,7 @@ Creates an **ImageSource** instance based on the URI.
```js
// Stage model
const context = getContext(this);
const path = context.getCacheDir() + "/test.jpg";
const path = context.cacheDir() + "/test.jpg";
const imageSourceApi = image.createImageSource(path);
```
......@@ -2729,7 +2729,7 @@ Describes image properties.
## PropertyKey<sup>7+</sup>
Describes the exchangeable image file format (EXIF) information of an image.
Describes the exchangeable image file format (EXIF) data of an image.
**System capability**: SystemCapability.Multimedia.Image.Core
......
......@@ -15,9 +15,9 @@ Want is a carrier for information transfer between objects (application componen
| abilityName | string | No | Name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.|
| uri | string | No | URI. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.|
| type | string | No | MIME type, that is, the type of the file to open, for example, **'text/xml'** and **'image/*'**. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com. |
| flags | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-ability-wantConstant.md#wantconstantflags). |
| action | string | No | Action to take, such as viewing and sharing application details. In implicit Want, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data. For details, see [action](js-apis-app-ability-wantConstant.md#wantconstantaction). For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](../../application-models/explicit-implicit-want-mappings.md). |
| parameters | {[key: string]: Object} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>**ohos.aafwk.param.callerToken**: token of the caller.<br>- **ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo1), that is, the application UID in the bundle information.<br>- **component.startup.newRules**: whether to enable the new control rule.<br>- **moduleName**: module name of the caller. No matter what this field is set to, the correct module name will be sent to the peer.<br>- **ohos.dlp.params.sandbox**: available only for DLP files. |
| flags | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-ability-wantConstant.md#wantconstantflags).|
| action | string | No | Action to take, such as viewing and sharing application details. In implicit Want, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data. For details, see [action](js-apis-ability-wantConstant.md#wantconstantaction). For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](../../application-models/explicit-implicit-want-mappings.md). |
| parameters | {[key: string]: Object} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>- **ohos.aafwk.param.callerToken**: token of the caller.<br>**ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo), that is, the application UID in the bundle information.<br>- **component.startup.newRules**: whether to enable the new control rule.<br>- **moduleName**: module name of the caller. No matter what this field is set to, the correct module name will be sent to the peer.<br>- **ohos.dlp.params.sandbox**: available only for DLP files. |
| entities | Array\<string> | No | Additional category information (such as browser and video player) of the target ability. It is a supplement to **action** in implicit Want and is used to filter ability types. For details, see [entity](js-apis-app-ability-wantConstant.md#wantconstantentity). |
| moduleName<sup>9+</sup> | string | No | Module to which the ability belongs.|
......@@ -41,12 +41,12 @@ Want is a carrier for information transfer between objects (application componen
- Passing a file descriptor (FD) (called in the UIAbility object, where context in the example is the context object of the UIAbility):
```ts
import fileio from '@ohos.fileio';
import fs from '@ohos.file.fs';
// ...
let fd;
try {
fd = fileio.openSync('/data/storage/el2/base/haps/pic.png');
fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd;
} catch(e) {
console.error('openSync fail: ${JSON.stringify(e)}');
}
......
......@@ -46,26 +46,21 @@ Starts an ability. This API uses an asynchronous callback to return the result.
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000010 | Can not operation with continue flag. |
| 16000011 | Context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000051 | Network error. The network is abnormal. |
| 16000052 | Free install not support. The application does not support freeinstall |
| 16000053 | Not top ability. The application is not top ability. |
| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
| 16000055 | Free install timeout. |
| 16000056 | Can not free install other ability. |
| 16000057 | Not support cross device free install. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -118,26 +113,21 @@ Starts an ability. This API uses a promise to return the result.
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000010 | Can not operation with continue flag. |
| 16000011 | Context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000051 | Network error. The network is abnormal. |
| 16000052 | Free install not support. The application does not support freeinstall |
| 16000053 | Not top ability. The application is not top ability. |
| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
| 16000055 | Free install timeout. |
| 16000056 | Can not free install other ability. |
| 16000057 | Not support cross device free install. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -170,7 +160,7 @@ Starts an ability. This API uses a promise to return the result.
startAbility(want: Want, options: StartOptions, callback: AsyncCallback&lt;void&gt;): void
Starts an ability. This API uses an asynchronous callback to return the result.
Starts an ability with the start options specified. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -188,26 +178,21 @@ Starts an ability. This API uses an asynchronous callback to return the result.
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000010 | Can not operation with continue flag. |
| 16000011 | Context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000051 | Network error. The network is abnormal. |
| 16000052 | Free install not support. The application does not support freeinstall |
| 16000053 | Not top ability. The application is not top ability. |
| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
| 16000055 | Free install timeout. |
| 16000056 | Can not free install other ability. |
| 16000057 | Not support cross device free install. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -245,7 +230,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -264,27 +249,21 @@ Observe the following when using this API:
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000006 | Can not cross user operations. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000010 | Can not operation with continue flag. |
| 16000011 | Context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000051 | Network error. The network is abnormal. |
| 16000052 | Free install not support. The application does not support freeinstall |
| 16000053 | Not top ability. The application is not top ability. |
| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
| 16000055 | Free install timeout. |
| 16000056 | Can not free install other ability. |
| 16000057 | Not support cross device free install. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -320,7 +299,7 @@ Starts an ability with the account ID and start options specified. This API uses
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -340,27 +319,21 @@ Observe the following when using this API:
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000006 | Can not cross user operations. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000010 | Can not operation with continue flag. |
| 16000011 | Context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000051 | Network error. The network is abnormal. |
| 16000052 | Free install not support. The application does not support freeinstall |
| 16000053 | Not top ability. The application is not top ability. |
| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
| 16000055 | Free install timeout. |
| 16000056 | Can not free install other ability. |
| 16000057 | Not support cross device free install. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -400,7 +373,7 @@ Starts an ability with the account ID specified. This API uses a promise to retu
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -425,27 +398,21 @@ Observe the following when using this API:
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000006 | Can not cross user operations. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000010 | Can not operation with continue flag. |
| 16000011 | Context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000051 | Network error. The network is abnormal. |
| 16000052 | Free install not support. The application does not support freeinstall |
| 16000053 | Not top ability. The application is not top ability. |
| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
| 16000055 | Free install timeout. |
| 16000056 | Can not free install other ability. |
| 16000057 | Not support cross device free install. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -497,18 +464,16 @@ Starts a new ServiceExtensionAbility. This API uses an asynchronous callback to
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -561,18 +526,16 @@ Starts a new ServiceExtensionAbility. This API uses a promise to return the resu
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -623,19 +586,16 @@ Starts a new ServiceExtensionAbility with the account ID specified. This API use
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000006 | Can not cross user operations. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -693,19 +653,16 @@ Starts a new ServiceExtensionAbility with the account ID specified. This API use
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000006 | Can not cross user operations. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -754,15 +711,15 @@ Stops a ServiceExtensionAbility in the same application. This API uses an asynch
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -815,15 +772,15 @@ Stops a ServiceExtensionAbility in the same application. This API uses a promise
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -874,16 +831,15 @@ Stops a ServiceExtensionAbility in the same application with the account ID spec
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000006 | Can not cross user operations. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -940,16 +896,15 @@ Stops a ServiceExtensionAbility in the same application with the account ID spec
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000006 | Can not cross user operations. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000011 | Context does not exist. |
| 16200001 | Caller released. The caller has been released. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -997,12 +952,14 @@ Terminates this ability. This API uses an asynchronous callback to return the re
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000011 | Context does not exist. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -1038,12 +995,14 @@ Terminates this ability. This API uses a promise to return the result.
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000011 | Context does not exist. |
| 16000050 | Internal Error. |
| 16000001 | The specified ability does not exist. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -1084,14 +1043,13 @@ Connects this ability to a ServiceExtensionAbility.
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000011 | Context does not exist. |
| 16000005 | The specified process does not have the permission. |
| 16000011 | The context does not exist. |
| 16000050 | Internal Error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1145,15 +1103,13 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Ability type error. The specified ability type is wrong. |
| 16000004 | Visibility verification failed. |
| 16000006 | Can not cross user operations. |
| 16000011 | Context does not exist. |
| 16000005 | The specified process does not have the permission. |
| 16000011 | The context does not exist. |
| 16000050 | Internal Error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1202,13 +1158,11 @@ Disconnects this ability from a ServiceExtensionAbility and after the successful
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000003 | Input error. The specified id does not exist. |
| 16000011 | Context does not exist. |
| 16000011 | The context does not exist. |
| 16000050 | Internal Error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1259,13 +1213,11 @@ Disconnects this ability from a ServiceExtensionAbility and after the successful
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000003 | Input error. The specified id does not exist. |
| 16000011 | Context does not exist. |
| 16000011 | The context does not exist. |
| 16000050 | Internal Error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1299,7 +1251,7 @@ Starts an ability in the foreground or background and obtains the caller object
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -1322,16 +1274,17 @@ Observe the following when using this API:
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | The application does not have permission to call the interface. |
| 401 | Invalid input parameter. |
| 16000001 | Input error. The specified ability name does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Visibility verification failed. |
| 16000005 | Static permission denied. The specified process does not have the permission. |
| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | Crowdtest App Expiration. |
| 16000009 | Can not start ability in wukong mode. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000011 | The context does not exist. |
| 16000050 | Internal Error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......
......@@ -29,7 +29,7 @@ Starts an ability. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -54,12 +54,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -92,7 +93,7 @@ Starts an ability with the start options specified. This API uses an asynchronou
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -118,12 +119,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -160,7 +162,7 @@ Starts an ability. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -191,12 +193,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -235,7 +238,7 @@ Starts an ability. This API uses an asynchronous callback to return the result w
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -260,12 +263,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -302,7 +306,7 @@ Starts an ability with the start options specified. This API uses an asynchronou
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -328,12 +332,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -374,7 +379,7 @@ Starts an ability. This API uses a promise to return the result when the ability
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -406,12 +411,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -447,7 +453,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
......@@ -477,12 +483,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -518,7 +525,7 @@ Starts an ability with the start options and account ID specified. This API uses
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
......@@ -549,12 +556,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -593,7 +601,7 @@ Starts an ability with the account ID specified. This API uses a promise to retu
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
......@@ -629,12 +637,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -693,6 +702,8 @@ Starts a ServiceExtensionAbility. This API uses an asynchronous callback to retu
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -747,6 +758,8 @@ Starts a ServiceExtensionAbility. This API uses a promise to return the result.
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -805,6 +818,8 @@ Starts a ServiceExtensionAbility with the account ID specified. This API uses an
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -863,6 +878,8 @@ Starts a ServiceExtensionAbility with the account ID specified. This API uses a
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -917,6 +934,8 @@ Stops a ServiceExtensionAbility in the same application. This API uses an asynch
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -970,6 +989,8 @@ Stops a ServiceExtensionAbility in the same application. This API uses a promise
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1027,6 +1048,8 @@ Stops a ServiceExtensionAbility with the account ID specified in the same applic
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1084,6 +1107,8 @@ Stops a ServiceExtensionAbility with the account ID specified in the same applic
| 16000050 | Internal error. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1135,6 +1160,8 @@ Terminates this ability. This API uses an asynchronous callback to return the re
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1180,6 +1207,8 @@ Terminates this ability. This API uses a promise to return the result.
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1226,6 +1255,8 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1288,6 +1319,8 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1348,6 +1381,8 @@ Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERV
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1414,6 +1449,8 @@ Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERV
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1469,11 +1506,11 @@ Disconnects this ability from a ServiceExtensionAbility and after the successful
| ID| Error Message|
| ------- | -------------------------------- |
| 16000001 | The specified ability does not exist. |
| 16000005 | The specified process does not have the permission. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1517,11 +1554,11 @@ Disconnects this ability from a ServiceExtensionAbility and after the successful
| ID| Error Message|
| ------- | -------------------------------- |
| 16000001 | The specified ability does not exist. |
| 16000005 | The specified process does not have the permission. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1554,7 +1591,7 @@ Starts an ability in the foreground or background and obtains the caller object
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -1581,15 +1618,12 @@ Observe the following when using this API:
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
Start an ability in the background.
......@@ -1661,7 +1695,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
......@@ -1691,12 +1725,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1732,7 +1767,7 @@ Starts an ability with the account ID and start options specified. This API uses
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
......@@ -1763,12 +1798,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1807,7 +1843,7 @@ Starts an ability with the account ID specified. This API uses a promise to retu
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
......@@ -1837,12 +1873,13 @@ Observe the following when using this API:
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000017 | The previous ability is starting, wait start later. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1887,6 +1924,15 @@ Sets a label for this UIAbility in the mission. This API uses an asynchronous ca
| label | string | Yes| Label of the ability to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Error codes**
| ID| Error Message|
| ------- | -------------------------------- |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1922,6 +1968,8 @@ Sets a label for this UIAbility in the mission. This API uses a promise to retur
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -1955,6 +2003,8 @@ Sets an icon for this ability in the mission. This API uses an asynchronous call
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -2010,6 +2060,8 @@ Sets an icon for this ability in the mission. This API uses a promise to return
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -2057,6 +2109,8 @@ Restores the WindowStage data in the UIAbility.
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -2083,7 +2137,8 @@ Checks whether this UIAbility is in the terminating state.
| ID| Error Message|
| ------- | -------------------------------- |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
......@@ -2100,7 +2155,7 @@ Starts a ServiceExtensionAbility that supports modal dialog boxes. After the Ser
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -2112,6 +2167,26 @@ Observe the following when using this API:
| want |[Want](js-apis-application-want.md) | Yes| Want information about the target ServiceExtensionAbility.|
| result | AsyncCallback&lt;[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md)&gt; | Yes| Callback used to return the result.|
**Error codes**
| ID| Error Message|
| ------- | -------------------------------- |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......@@ -2147,7 +2222,7 @@ Starts a ServiceExtensionAbility that supports modal dialog boxes. After the Ser
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**System capability**: SystemCapability.Ability.AbilityRuntime.Core
......@@ -2165,6 +2240,26 @@ Observe the following when using this API:
| -------- | -------- |
| Promise&lt;[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md)&gt; | Promise used to return the result.
**Error codes**
| ID| Error Message|
| ------- | -------------------------------- |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
| 16000004 | Can not start invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
| 16000009 | An ability cannot be started or stopped in Wukong mode. |
| 16000010 | The call with the continuation flag is forbidden. |
| 16000011 | The context does not exist. |
| 16000050 | Internal error. |
| 16000053 | The ability is not on the top of the UI. |
| 16000055 | Installation-free timed out. |
| 16200001 | The caller has been released. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
......
......@@ -14,16 +14,19 @@ import InputMethodSubtype from '@ohos.InputMethodSubtype';
## Attributes
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**System capability**: SystemCapability.MiscServices.InputMethodFramework
| Name| Type| Readable| Writable| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- | -------- |
| label | string | Yes| No| No| Label of the input method subtype.|
| name | string | Yes| No| Yes| Name of the input method subtype.|
| labelId<sup>10+</sup> | string | Yes| No| No| Label ID of the input method subtype.|
| name | string | Yes| No| Yes| Bundle name of the input method.|
| id | string | Yes| No| Yes| ID of the input method subtype.|
| mode | string | Yes| No| No| Mode of the input method subtype, including **upper** (uppercase) and **lower** (lowercase).|
| locale | string | Yes| No| Yes| Locale of the input method subtype.|
| language | string | Yes| No| Yes| Language of the input method subtype.|
| icon | string | Yes| No| No| Icon of the input method subtype.|
| iconId | number | Yes| No| No| Icon ID of the input method subtype.|
| extra | object | Yes| Yes| Yes| Extra information of the input method subtype.|
| extra | object | Yes| Yes| No| Extra information of the input method subtype.<br>**NOTE**<br>This parameter is optional since API version 10.|
# @ohos.inputMethod (Input Method Framework)
The **inputMethod** module provides an input method framework, which can be used to hide the keyboard, obtain the list of installed input methods, display the dialog box for input method selection, and more.
The **inputMethod** module is oriented to common foreground applications (third-party applications and system applications such as Notes, Messaging, and Settings). It provides input method control and management capabilities, including displaying or hiding the soft keyboard, switching between input methods, and obtaining the list of all input methods.
> **NOTE**
>
......@@ -33,10 +33,11 @@ Describes the input method application attributes.
| -------- | -------- | -------- | -------- | -------- |
| name<sup>9+</sup> | string | Yes| No| Internal name of the input method. Mandatory.|
| id<sup>9+</sup> | string | Yes| No| Unique ID of the input method. Mandatory.|
| label<sup>9+</sup> | string | Yes| No| External display name of the input method. Optional.|
| label<sup>9+</sup> | string | Yes| No| External name of the input method. Optional.|
| labelId<sup>10+</sup> | string | Yes| No| External ID of the input method. Optional.|
| icon<sup>9+</sup> | string | Yes| No| Icon of the input method. Optional.|
| iconId<sup>9+</sup> | number | Yes| No| Icon ID of the input method. Optional.|
| extra<sup>9+</sup> | object | Yes| Yes| Extra information about the input method. Mandatory.|
| extra<sup>9+</sup> | object | Yes| Yes| Extra information about the input method. Optional.<br>**NOTE**<br>This parameter is optional since API version 10.|
| packageName<sup>(deprecated)</sup> | string | Yes| No| Name of the input method package. Mandatory.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 9. You are advised to use **name**.|
| methodId<sup>(deprecated)</sup> | string | Yes| No| Unique ID of the input method. Mandatory.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 9. You are advised to use **id**.|
......@@ -231,7 +232,7 @@ switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallb
Switches to another subtype of the current input method. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) <br>**NOTE**<br>Since API version 10, this permission is not required if the caller is the current input method.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
......@@ -239,7 +240,7 @@ Switches to another subtype of the current input method. This API uses an asynch
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.|
| target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md)| Yes| Input method subtype to switch to.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
**Error codes**
......@@ -256,9 +257,9 @@ For details about the error codes, see [Input Method Framework Error Codes](../e
```js
try {
inputMethod.switchCurrentInputMethodSubtype({
id: "com.example.kikakeyboard",
label: "ServiceExtAbility",
name: "",
id: "ServiceExtAbility",
label: "",
name: "com.example.kikakeyboard",
mode: "upper",
locale: "",
language: "",
......@@ -287,7 +288,7 @@ switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise&lt;boolean&
Switches to another subtype of the current input method. This API uses a promise to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications)
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY (available only to system applications) <br>**NOTE**<br>Since API version 10, this permission is not required if the caller is the current input method.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
......@@ -295,7 +296,7 @@ Switches to another subtype of the current input method. This API uses a promise
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
|target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.|
|target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md)| Yes| Input method subtype to switch to.|
**Return value**
......@@ -317,9 +318,9 @@ For details about the error codes, see [Input Method Framework Error Codes](../e
```js
try {
inputMethod.switchCurrentInputMethodSubtype({
id: "com.example.kikakeyboard",
label: "ServiceExtAbility",
name: "",
id: "ServiceExtAbility",
label: "",
name: "com.example.kikakeyboard",
mode: "upper",
locale: "",
language: "",
......@@ -352,7 +353,7 @@ Obtains the current input method subtype.
| Type | Description |
| -------------------------------------------- | ------------------------ |
| [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype) | Current input method subtype.|
| [InputMethodSubtype](./js-apis-inputmethod-subtype.md) | Current input method subtype.|
**Example**
......@@ -375,7 +376,7 @@ Switches to a specified subtype of a specified input method. This API uses an as
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.|
|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.|
|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md)| Yes| Input method subtype to switch to.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true**. Otherwise, **err** is an error object.|
**Error codes**
......@@ -391,25 +392,9 @@ For details about the error codes, see [Input Method Framework Error Codes](../e
```js
let im = inputMethod.getCurrentInputMethod();
let inputMethodProperty = {
packageName: im.packageName,
methodId: im.methodId,
name: im.packageName,
id: im.methodId,
extra: {}
}
let imSubType = inputMethod.getCurrentInputMethodSubtype();
try {
inputMethod.switchCurrentInputMethodAndSubtype(inputMethodProperty, {
id: "com.example.kikakeyboard",
label: "ServiceExtAbility",
name: "",
mode: "upper",
locale: "",
language: "",
icon: "",
iconId: 0,
extra: {}
}, (err,result) => {
inputMethod.switchCurrentInputMethodAndSubtype(im, imSubType, (err,result) => {
if (err !== undefined) {
console.error('Failed to switchCurrentInputMethodAndSubtype: ' + JSON.stringify(err));
return;
......@@ -440,7 +425,7 @@ Switches to a specified subtype of a specified input method. This API uses a pro
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.|
|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| Yes| Input method subtype to switch to.|
|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md)| Yes| Input method subtype to switch to.|
**Return value**
......@@ -461,25 +446,9 @@ For details about the error codes, see [Input Method Framework Error Codes](../e
```js
let im = inputMethod.getCurrentInputMethod();
let inputMethodProperty = {
packageName: im.packageName,
methodId: im.methodId,
name: im.packageName,
id: im.methodId,
extra: {}
}
let imSubType = inputMethod.getCurrentInputMethodSubtype();
try {
inputMethod.switchCurrentInputMethodAndSubtype(inputMethodProperty, {
id: im.packageName,
label: im.methodId,
name: "",
mode: "upper",
locale: "",
language: "",
icon: "",
iconId: 0,
extra: {}
}).then((result) => {
inputMethod.switchCurrentInputMethodAndSubtype(im, imSubType).then((result) => {
if (result) {
console.info('Succeeded in switching currentInputMethodAndSubtype.');
} else {
......@@ -886,7 +855,7 @@ inputMethodController.off('selectByRange');
on(type: 'selectByMovement', callback: Callback&lt;Movement&gt;): void
Enables listening for the selection-by-cursor-movement event. This API uses an asynchronous callback to return the result.
Enables listening for the select-by-cursor-movement event. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
......@@ -894,7 +863,7 @@ Enables listening for the selection-by-cursor-movement event. This API uses an a
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>The value **selectByMovement** indicates the selection-by-cursor-movement event.|
| type | string | Yes | Listening type.<br>The value **selectByMovement** indicates the select-by-cursor-movement event.|
| callback | Callback&lt;[Movement](./js-apis-inputmethod-InputMethodCommon.md#movement)&gt; | Yes | Callback used to return the range of the text to be selected.<br>Your application needs to select the text in the returned range in the text box.|
**Example**
......@@ -909,7 +878,7 @@ inputMethodController.on('selectByMovement', (movement) => {
off(type: 'selectByMovement'): void
Disables listening for the selection-by-cursor-movement event.
Disables listening for the select-by-cursor-movement event.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
......@@ -917,7 +886,7 @@ Disables listening for the selection-by-cursor-movement event.
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>The value **selectByMovement** indicates the selection-by-cursor-movement event.|
| type | string | Yes | Listening type.<br>The value **selectByMovement** indicates the select-by-cursor-movement event.|
**Example**
......@@ -942,7 +911,7 @@ Enables listening for the input method and subtype change event. This API uses a
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>The value **'imeChange'** indicates the input method and subtype change event.|
| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)) => void | Yes| Callback used to return the input method attributes and subtype.|
| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md)) => void | Yes| Callback used to return the input method attributes and subtype.|
**Example**
......@@ -965,7 +934,7 @@ Disables listening for the input method and subtype change event. This API uses
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>The value **'imeChange'** indicates the input method and subtype change event.|
| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)) => void | No| Callback used to return the input method attributes and subtype.|
| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md)) => void | No| Callback used to return the input method attributes and subtype.|
**Example**
......@@ -986,7 +955,7 @@ Obtains all subtypes of a specified input method. This API uses an asynchronous
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| inputMethodProperty | InputMethodProperty| Yes| Input method to which the subtypes belong.|
| callback | AsyncCallback&lt;Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>&gt; | Yes| Callback used to return all subtypes of the specified input method.|
| callback | AsyncCallback&lt;Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>&gt; | Yes| Callback used to return all subtypes of the specified input method.|
**Error codes**
......@@ -1038,7 +1007,7 @@ Obtains all subtypes of a specified input method. This API uses a promise to ret
| Type | Description |
| ----------------------------------------------------------- | ---------------------- |
| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Promise used to return all subtypes of the specified input method.|
| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | Promise used to return all subtypes of the specified input method.|
**Error codes**
......@@ -1082,7 +1051,7 @@ Obtains all subtypes of this input method. This API uses an asynchronous callbac
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| callback | AsyncCallback&lt;Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>&gt; | Yes | Callback used to return all subtypes of the current input method.|
| callback | AsyncCallback&lt;Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>&gt; | Yes | Callback used to return all subtypes of the current input method.|
**Error codes**
......@@ -1121,7 +1090,7 @@ Obtains all subtypes of this input method. This API uses a promise to return the
| Type | Description |
| ----------------------------------------------------------- | ---------------------- |
| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Promise used to return all subtypes of the current input method.|
| Promise<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | Promise used to return all subtypes of the current input method.|
**Error codes**
......
# @ohos.inputMethodEngine (Input Method Service)
The **inputMethodEngine** module streamlines the interactions between input methods and applications. By calling APIs of this module, applications can be bound to input method services to accept text input, request the keyboard to display or hide, listen for the input method status, and much more.
The **inputMethodEngine** module is oriented to input method applications (including system and third-party input method applications). With the APIs of this module, input method applications are able to create soft keyboard windows, insert or delete characters, select text, and listen for physical keyboard events.
> **NOTE**
>
......@@ -56,15 +56,15 @@ Provides the constant values of function keys, edit boxes, and the cursor.
getInputMethodAbility(): InputMethodAbility
Obtains an **InputMethodEngine** instance.
Obtains an [InputMethodAbility](#inputmethodability) instance for the input method. The input method can use the obtained instance to subscribe to a soft keyboard display/hide request event, create/destroy an input method panel, and the like.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Return value**
| Type | Description |
| --------------------------------------- | ------------ |
| [InputMethodAbility](#inputmethodability) | **InputMethodEngine** instance obtained.|
| ----------------------------------------- | ------------------ |
| [InputMethodAbility](#inputmethodability) | **InputMethodAbility** instance.|
**Example**
......@@ -76,15 +76,15 @@ let InputMethodAbility = inputMethodEngine.getInputMethodAbility();
getKeyboardDelegate(): KeyboardDelegate
Obtains a **KeyboardDelegate** instance.
Obtains a [KeyboardDelegate](#keyboarddelegate) instance for the input method. The input method can use the obtained instance to subscribe to a physical keyboard event, text selection change event, and more.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Return value**
| Type | Description |
| ------------------------------------- | ---------------- |
| [KeyboardDelegate](#keyboarddelegate) | **KeyboardDelegate** instance obtained.|
| ------------------------------------- | ------------------------ |
| [KeyboardDelegate](#keyboarddelegate) | **KeyboardDelegate** instance.|
**Example**
......@@ -96,7 +96,7 @@ let KeyboardDelegate = inputMethodEngine.getKeyboardDelegate();
getInputMethodEngine(): InputMethodEngine
Obtains an **InputMethodEngine** instance.
Obtains an [InputMethodEngine](#inputmethodengine-1) instance for the input method. The input method can use the obtained instance to subscribe to a soft keyboard display/hide request event.
> **NOTE**
>
......@@ -107,8 +107,8 @@ Obtains an **InputMethodEngine** instance.
**Return value**
| Type | Description |
| --------------------------------------- | ------------ |
| [InputMethodEngine](#inputmethodengine-1) | **InputMethodEngine** instance obtained.|
| ----------------------------------------- | ------------------ |
| [InputMethodEngine](#inputmethodengine-1) | **InputMethodAbility** instance.|
**Example**
......@@ -120,7 +120,7 @@ let InputMethodEngine = inputMethodEngine.getInputMethodEngine();
createKeyboardDelegate(): KeyboardDelegate
Obtains a **KeyboardDelegate** instance.
Obtains a [KeyboardDelegate](#keyboarddelegate) instance for the input method. The input method can use the obtained instance to subscribe to a physical keyboard event, text selection change event, and more.
> **NOTE**
>
......@@ -131,8 +131,8 @@ Obtains a **KeyboardDelegate** instance.
**Return value**
| Type | Description |
| ------------------------------------- | ---------------- |
| [KeyboardDelegate](#keyboarddelegate) | **KeyboardDelegate** instance obtained.|
| ------------------------------------- | ------------------------ |
| [KeyboardDelegate](#keyboarddelegate) | **KeyboardDelegate** instance.|
**Example**
......@@ -157,7 +157,7 @@ Enables listening for the input method binding event. This API uses an asynchron
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.|
| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclient)) => void | Yes| Callback used to return the **KeyboardController** and **TextInputClient** instances.|
| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclientdeprecated)) => void | Yes| Callback used to return the **KeyboardController** and **TextInputClient** instances.|
**Example**
......@@ -181,7 +181,7 @@ Cancels listening for the input method binding event.
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| type | string | Yes | Listening type.<br>The value **'inputStart'** indicates the input method binding event.|
| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclient)) => void | No| Callback used to return the **KeyboardController** and **TextInputClient** instances.|
| callback | (kbController: [KeyboardController](#keyboardcontroller), textInputClient: [TextInputClient](#textinputclientdeprecated)) => void | No| Callback used to return the **KeyboardController** and **TextInputClient** instances.|
**Example**
......@@ -195,7 +195,7 @@ inputMethodEngine.getInputMethodEngine().off('inputStart', (kbController, textIn
on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void
Enables listening for a keyboard event. This API uses an asynchronous callback to return the result.
Enables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
......@@ -221,7 +221,7 @@ inputMethodEngine.getInputMethodEngine().on('keyboardHide', () => {
off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void
Disables listening for a keyboard event. This API uses an asynchronous callback to return the result.
Disables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
......@@ -478,6 +478,186 @@ inputMethodEngine.getInputMethodAbility().off('setSubtype', () => {
});
```
### createPanel<sup>10+</sup>
createPanel(ctx: BaseContext, info: PanelInfo, callback: AsyncCallback\<Panel>): void
Creates an input method panel. This API can be called only by input method applications and system applications with the system_core permission. Only one SOFT_KEYBOARD panel and one STATUS_BAR panel can be created for a single input method application. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ----------- | ---- | ------------------------ |
| ctx | [BaseContext](./js-apis-inner-application-baseContext.md) | Yes | Context of the current input method.|
| info | [PanelInfo](#panelinfo10) | Yes | Information about the input method panel.|
| callback | AsyncCallback\<[Panel](#panel10)> | Yes | Callback used to return the result. If the operation is successful, the created input method panel is returned. |
**Error codes**
| Error Code ID | Error Message |
| ---------- | ----------------------------- |
| 12800004 | not an input method extension |
**Example**
```js
let panelInfo: inputMethodEngine.PanelInfo = {
panelType: SOFT_KEYBOARD,
panelFlag: FLG_FIXED
}
try {
inputMethodEngine.getInputMethodAbility().createPanel(this.context, panelInfo, (err, panel) => {
if (err !== undefined) {
console.log('Failed to create panel, err: ' + JSON.stringify(err));
return;
}
console.log('Succeed in creating panel.');
})
} catch(err) {
console.log('Failed to create panel, err: ' + JSON.stringify(err));
}
```
### createPanel<sup>10+</sup>
createPanel(ctx: BaseContext, info: PanelInfo): Promise\<Panel>
Creates an input method panel. This API can be called only by input method applications and system applications with the system_core permission. Only one SOFT_KEYBOARD panel and one STATUS_BAR panel can be created for a single input method application. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ----------- | ---- | ------------------------ |
| ctx | [BaseContext](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-inner-application-baseContext.md) | Yes | Context of the current input method.|
| info | [PanelInfo](#panelinfo10) | Yes | Information about the input method panel.|
**Return value**
| Type | Description |
| ------- | ------------------------------------------------------------------ |
| Promise\<[Panel](#panel10)> | Promise used to return the result. If the operation is successful, the created input method panel is returned. |
**Error codes**
| Error Code ID | Error Message |
| ---------- | ----------------------------- |
| 12800004 | not an input method extension |
**Example**
```js
let panelInfo: inputMethodEngine.PanelInfo = {
panelType: SOFT_KEYBOARD,
panelFlag: FLG_FIXED
}
inputMethodEngine.getInputMethodAbility().createPanel(this.context, panelInfo).then((panel) => {
console.log('Succeed in creating panel.');
}).catch((err) => {
console.log('Failed to create panel, err: ' + JSON.stringify(err));
})
```
### destroyPanel<sup>10+</sup>
destroyPanel(panel: Panel, callback: AsyncCallback\<void>): void;
Destroys an input method panel. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ----------- | ---- | ------------------------ |
| panel | [Panel](#panel10) | Yes | Input method panel to destroy.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
**Example**
```js
let panelInfo: inputMethodEngine.PanelInfo = {
panelType: SOFT_KEYBOARD,
panelFlag: FLG_FIXED
}
try {
inputMethodEngine.getInputMethodAbility().createPanel(this.context, panelInfo, (err, panel) => {
if (err !== undefined) {
console.log('Failed to create panel, err: ' + JSON.stringify(err));
return;
}
globalThis.inputMethodPanel = panel;
console.log('Succeed in creating panel.');
})
} catch(err) {
console.log('Failed to create panel, err: ' + JSON.stringify(err));
}
try {
inputMethodEngine.getInputMethodAbility().destroyPanel(globalThis.inputMethodPanel, (err) => {
if(err !== undefined) {
console.log('Failed to destroy panel, err: ' + JSON.stringify(err));
return;
}
console.log('Succeed in destroying panel.');
})
} catch(err) {
console.log('Failed to destroy panel, err: ' + JSON.stringify(err));
}
```
### destroyPanel<sup>10+</sup>
destroyPanel(panel: Panel): Promise\<void>;
Destroys an input method panel. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| ---------| ----------- | ---- | ------------------------ |
| panel | [Panel](#panel10) | Yes | Input method panel to destroy. |
**Return value**
| Type | Description |
| ------- | -------------------------------------------------------------------- |
| Promise\<void> | Promise that returns no value.|
**Example**
```js
let panelInfo: inputMethodEngine.PanelInfo = {
panelType: SOFT_KEYBOARD,
panelFlag: FLG_FIXED
}
try {
inputMethodEngine.getInputMethodAbility().createPanel(this.context, panelInfo, (err, panel) => {
if (err !== undefined) {
console.log('Failed to create panel, err: ' + JSON.stringify(err));
return;
}
globalThis.inputMethodPanel = panel;
console.log('Succeed in creating panel.');
})
} catch(err) {
console.log('Failed to create panel, err: ' + JSON.stringify(err));
}
try {
inputMethodEngine.getInputMethodAbility().destroyPanel(globalThis.inputMethodPanel).then(() => {
console.log('Succeed in destroying panel.');
}).catch((err) => {
console.log('Failed to destroy panel, err: ' + JSON.stringify(err));
});
} catch (err) {
console.log('Failed to destroy panel, err: ' + JSON.stringify(err));
}
```
## KeyboardDelegate
In the following API examples, you must first use **[getKeyboardDelegate](#inputmethodenginegetkeyboarddelegate9)** to obtain a **KeyboardDelegate** instance, and then call the APIs using the obtained instance.
......@@ -684,6 +864,455 @@ inputMethodEngine.getKeyboardDelegate().off('textChange', (text) => {
});
```
## Panel<sup>10+</sup>
In the following API examples, you must first use **[createPanel](#createpanel10)** to obtain a **Panel** instance, and then call the APIs using the obtained instance.
### setUiContent<sup>10+</sup>
setUiContent(path: string, callback: AsyncCallback\<void>): void
Loads content from a page to this panel. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| path | string | Yes | Path of the page from which the content will be loaded.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
```js
try {
panel.setUiContent('pages/page2/page2', (err) => {
if (err) {
console.error('Failed to set the content. err:' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting the content.');
});
} catch (exception) {
console.error('Failed to set the content. err:' + JSON.stringify(exception));
}
```
### setUiContent<sup>10+</sup>
setUiContent(path: string): Promise\<void>
Loads content from a page to this panel. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| path | string | Yes | Path of the page from which the content will be loaded.|
**Return value**
| Type | Description |
| ------- | ------------------------------ |
| Promise\<void> | Promise that returns no value. |
**Example**
```js
try {
let promise = panel.setUiContent('pages/page2/page2');
promise.then(() => {
console.info('Succeeded in setting the content.');
}).catch((err) =>{
console.error('Failed to set the content. err: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to set the content. err: ' + JSON.stringify(exception));
}
```
### setUiContent<sup>10+</sup>
setUiContent(path: string, storage: LocalStorage, callback: AsyncCallback\<void>): void
Loads content from a page linked to LocalStorage to this panel. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| path | string | Yes | Path of the page from which the content will be loaded.|
| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | Storage unit that provides storage for mutable and immutable state variables in the application.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
```js
let storage = new LocalStorage();
storage.setOrCreate('storageSimpleProp',121);
try {
panel.setUiContent('pages/page2/page2', storage, (err) => {
if (err) {
console.error('Failed to set the content. err:' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting the content.');
});
} catch (exception) {
console.error('Failed to set the content. err:' + JSON.stringify(exception));
}
```
### setUiContent<sup>10+</sup>
setUiContent(path: string, storage: LocalStorage): Promise\<void>
Loads content from a page linked to LocalStorage to this panel. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| path | string | Yes | Path of the page from which the content will be loaded.|
| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | Storage unit that provides storage for mutable and immutable state variables in the application.|
**Return value**
| Type | Description |
| ------- | ------------------------------ |
| Promise\<void> | Promise that returns no value. |
**Example**
```js
let storage = new LocalStorage();
storage.setOrCreate('storageSimpleProp',121);
try {
let promise = panel.setUiContent('pages/page2/page2');
promise.then(() => {
console.info('Succeeded in setting the content.');
}).catch((err) =>{
console.error('Failed to set the content. err: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to set the content. err: ' + JSON.stringify(exception));
}
```
### resize<sup>10+</sup>
resize(width: number, height: number, callback: AsyncCallback\<void>): void
Resizes this panel. This API uses an asynchronous callback to return the result.
The panel width cannot exceed the screen width, and the panel height cannot be higher than half of the screen height.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| width | number | Yes | Target width of the panel, in pixels.|
| height | number | Yes | Target height of the panel, in pixels.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
```js
try {
panel.resize(500, 1000, (err) => {
if (err) {
console.error('Failed to change the panel size. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in changing the panel size.');
});
} catch (exception) {
console.error('Failed to change the panel size. Cause:' + JSON.stringify(exception));
}
```
### resize<sup>10+</sup>
resize(width: number, height: number): Promise\<void>;
Resizes this panel. This API uses a promise to return the result.
The panel width cannot exceed the screen width, and the panel height cannot be higher than half of the screen height.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| width | number | Yes | Target width of the panel, in pixels.|
| height | number | Yes | Target height of the panel, in pixels.|
**Return value**
| Type | Description |
| ------- | ------------------------------ |
| Promise<void> | Promise that returns no value. |
**Example**
```js
try {
let promise = panel.resize(500, 1000);
promise.then(() => {
console.info('Succeeded in changing the panel size.');
}).catch((err) =>{
console.error('Failed to change the panel size. err: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to change the panel size. err: ' + JSON.stringify(exception));
}
```
### moveTo<sup>10+</sup>
moveTo(x: number, y: number, callback: AsyncCallback\<void>): void
Moves this panel to the specified position. This API uses an asynchronous callback to return the result.
This API does not work on panels in the FLG_FIXED state.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| x | number | Yes | Distance to move along the x-axis, in px. A positive value indicates moving rightwards.|
| y | number | Yes | Distance to move along the y-axis, in pixels. A positive value indicates moving downwards.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
```js
try {
panel.moveTo(300, 300, (err) =>{
if (err) {
console.error('Failed to move the panel. err:' + JSON.stringify(err));
return;
}
console.info('Succeeded in moving the panel.');
});
} catch (exception) {
console.error('Failed to move the panel. err:' + JSON.stringify(exception));
}
```
### moveTo<sup>10+</sup>
moveTo(x: number, y: number): Promise\<void>
Moves this panel to the specified position. This API uses a promise to return the result.
This API does not work on panels in the FLG_FIXED state.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| x | number | Yes | Distance to move along the x-axis, in pixels. A positive value indicates moving rightwards.|
| y | number | Yes | Distance to move along the y-axis, in pixels. A positive value indicates moving downwards.|
**Return value**
| Type | Description |
| ------- | ------------------------------ |
| Promise<void> | Promise that returns no value. |
**Example**
```js
try {
let promise = windowClass.moveTo(300, 300);
promise.then(() => {
console.info('Succeeded in moving the panel.');
}).catch((err) =>{
console.error('Failed to move the panel. Cause: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to move the panel. Cause:' + JSON.stringify(exception));
}
```
### show<sup>10+</sup>
show(callback: AsyncCallback\<void>): void
Displays this panel. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
```js
panel.show((err) => {
if (err) {
console.error('Failed to show the panel. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in showing the panel.');
});
```
### show<sup>10+</sup>
show(): Promise\<void>
Displays this panel. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Return value**
| Type | Description |
| ------- | ------------------------------ |
| Promise\<void> | Promise that returns no value. |
**Example**
```js
let promise = panel.show();
promise.then(() => {
console.info('Succeeded in showing the panel.');
}).catch((err) =>{
console.error('Failed to show the panel. err: ' + JSON.stringify(err));
});
```
### hide<sup>10+</sup>
hide(callback: AsyncCallback\<void>): void
Hides this panel. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
```js
panel.hide((err) => {
if (err) {
console.error('Failed to hide the panel. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in hiding the panel.');
});
```
### hide<sup>10+</sup>
hide(): Promise\<void>
Hides this panel. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Return value**
| Type | Description |
| ------- | ------------------------------ |
| Promise\<void> | Promise that returns no value. |
**Example**
```js
let promise = panel.hide();
promise.then(() => {
console.info('Succeeded in hiding the panel.');
}).catch((err) =>{
console.error('Failed to hide the panel. err: ' + JSON.stringify(err));
});
```
### on<sup>10+</sup>
on(type: 'show' | 'hide', callback: () => void): void
Enables listening for a panel visibility event. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| type | 'show'\|'hide' | Yes| Listening type.<br>- The value **'show'** indicates the panel display event.<br>- The value **'hide'** indicates the panel hiding event.|
| callback | () => void | Yes | Callback used to return the result.|
**Example**
```js
panel.on('show', () => {
console.info('Panel is showing.');
});
```
### off<sup>10+</sup>
off(type: 'show' | 'hide', callback?: () => void): void
Disables listening for a panel visibility event. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| type | 'show'/'hide' | Yes| Listening type.<br>- The value **'show'** indicates the panel display event.<br>- The value **'hide'** indicates the panel hiding event.|
| callback | () => void | No | Callback used to return the result.|
**Example**
```js
panel.off('show');
```
### changeFlag<sup>10+</sup>
changeFlag(flag: PanelFlag): void
Changes the panel state type. This API only works for SOFT_KEYBOARD panels.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| flag | [PanelFlag](#panelflag10) | Yes| State type of the panel to switch to.|
**Example**
```js
let panelFlag = inputMethodEngine.getInputMethodAbility().PanelFlag.FLG_FIXED;
panel.changeFlag(panelFlag);
```
## KeyboardController
In the following API examples, you must first use **[on('inputStart')](#oninputstart9)** to obtain a **KeyboardController** instance, and then call the APIs using the obtained instance.
......@@ -1752,6 +2381,39 @@ Describes the attribute of a key.
| keyCode | number | Yes | No | Key value.|
| keyAction | number | Yes | No | Key status.|
## PanelFlag<sup>10+</sup>
Enumerates the state types of the input method panel.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
| Name | Value| Description |
| ------------ | -- | ------------------ |
| FLG_FIXED | 0 | Fixed state type.|
| FLG_FLOATING | 1 | Floating state type.|
## PanelType<sup>10+</sup>
Enumerates the types of the input method panel.
**System capability**: SystemCapability.MiscServices.InputMethodFramework
| Name | Value| Description |
| ------------ | -- | ------------------ |
| SOFT_KEYBOARD | 0 | Soft keyboard type.|
| STATUS_BAR | 1 | Status bar type.|
## PanelInfo<sup>10+</sup>
**System capability**: SystemCapability.MiscServices.InputMethodFramework
Describes the attributes of the input method panel.
| Name | Type| Readable| Writable| Description |
| --------- | -------- | ---- | ---- | ------------ |
| type | number | Yes | Yes | Type of the panel.|
| flag | number | Yes | Yes | State type of the panel.|
## TextInputClient<sup>(deprecated)</sup>
> **NOTE**
......@@ -2250,3 +2912,4 @@ textInputClient.getEditorAttribute().then((editorAttribute) => {
console.error('Failed to getEditorAttribute: ' + JSON.stringify(err));
});
```
<!--no_check-->
......@@ -3,7 +3,7 @@
The **bundle.installer** module provides APIs for you to install, uninstall, and recover bundles on devices.
> **NOTE**
>
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
......@@ -150,6 +150,64 @@ try {
console.error('getBundleInstaller failed. Cause: ' + error.message);
}
```
## BundleInstaller.install
install(hapFilePaths: Array&lt;string&gt;, callback: AsyncCallback&lt;void&gt;): void;
Installs a bundle. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.INSTALL_BUNDLE
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
| hapFilePaths | Array&lt;string&gt; | Yes | Paths where the HAP files of the bundle are stored, which are the data directories. If only one directory is passed, the HAP files in the directory must belong to the same bundle and have the same signature.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------ |
| 17700010 | Failed to install the HAP because the HAP fails to be parsed. |
| 17700011 | Failed to install the HAP because the HAP signature fails to be verified. |
| 17700012 | Failed to install the HAP because the HAP path is invalid or the HAP is too large. |
| 17700015 | Failed to install the HAPs because they have different configuration information. |
| 17700016 | Failed to install the HAP because of insufficient system disk space. |
| 17700017 | Failed to install the HAP since the version of the HAP to install is too early. |
| 17700018 | Failed to install because the dependent module does not exist. |
| 17700031 | Failed to install the HAP because the overlay check of the HAP is failed. |
| 17700036 | Failed to install the HSP because lacks appropriate permissions. |
| 17700039 | Failed to install because disallow install a shared bundle by hapFilePaths. |
| 17700041 | Failed to install because enterprise device management disallow install. |
**Example**
```ts
import installer from '@ohos.bundle.installer';
let hapFilePaths = ['/data/storage/el2/base/haps/entry/files/'];
try {
installer.getBundleInstaller().then(data => {
data.install(hapFilePaths, err => {
if (err) {
console.error('install failed:' + err.message);
} else {
console.info('install successfully.');
}
});
}).catch(error => {
console.error('getBundleInstaller failed. Cause: ' + error.message);
});
} catch (error) {
console.error('getBundleInstaller failed. Cause: ' + error.message);
}
```
## BundleInstaller.install
......@@ -210,9 +268,9 @@ try {
installer.getBundleInstaller().then(data => {
data.install(hapFilePaths, installParam)
.then((data) => {
console.info('install success: ' + JSON.stringify(data));
console.info('install successfully: ' + JSON.stringify(data));
}).catch((error) => {
console.error('install failed:' + err.message);
console.error('install failed:' + error.message);
});
}).catch(error => {
console.error('getBundleInstaller failed. Cause: ' + error.message);
......@@ -248,6 +306,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ------------------------------------------------------------ |
| 17700001 | The specified bundle name is not found. |
| 17700004 | The specified user ID is not found. |
| 17700020 | The specified bundle is pre-installed bundle which cannot be uninstalled. |
| 17700040 | The specified bundle is a shared bundle which cannot be uninstalled. |
......@@ -280,11 +339,11 @@ try {
}
```
## BundleInstaller.uninstall<sup>10+</sup>
## BundleInstaller.uninstall
uninstall(uninstallParam: UninstallParam, callback : AsyncCallback\<void>) : void ;
uninstall(bundleName: string, callback: AsyncCallback&lt;void&gt;): void;
Uninstalls a shared bundle. This API uses an asynchronous callback to return the result.
Uninstalls a bundle. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
......@@ -295,9 +354,9 @@ Uninstalls a shared bundle. This API uses an asynchronous callback to return the
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| uninstallParam | [UninstallParam](#uninstallparam10) | Yes | Parameters required for the uninstall. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.|
| ---------- | ---------------------------------------------------- | ---- | ---------------------------------------------- |
| bundleName | string | Yes | Name of the target bundle. |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.|
**Error codes**
......@@ -305,21 +364,19 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ------------------------------------------------------------ |
| 17700001 | The specified bundle name is not found. |
| 17700020 | The specified bundle is pre-installed bundle which cannot be uninstalled. |
| 17700037 | The version of shared bundle is dependent on other applications. |
| 17700038 | The specified shared bundle does not exist. |
| 17700040 | The specified bundle is a shared bundle which cannot be uninstalled. |
**Example**
```ts
import installer from '@ohos.bundle.installer';
let uninstallParam = {
bundleName : "com.ohos.demo",
};
let bundleName = 'com.ohos.demo';
try {
installer.getBundleInstaller().then(data => {
data.uninstall(uninstallParam, err => {
data.uninstall(bundleName, err => {
if (err) {
console.error('uninstall failed:' + err.message);
} else {
......@@ -333,12 +390,11 @@ try {
console.error('getBundleInstaller failed. Cause: ' + error.message);
}
```
## BundleInstaller.uninstall
## BundleInstaller.uninstall<sup>10+</sup>
uninstall(uninstallParam: UninstallParam) : Promise\<void>;
uninstall(bundleName: string, installParam?: InstallParam) : Promise\<void\>;
Uninstalls a shared bundle. This API uses a promise to return the result.
Uninstalls a bundle. This API uses a promise to return the result.
**System API**: This is a system API.
......@@ -349,13 +405,14 @@ Uninstalls a shared bundle. This API uses a promise to return the result.
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ----------------------------------- | ---- | ---------------------------- |
| uninstallParam | [UninstallParam](#uninstallparam10) | Yes | Parameters required for the uninstall.|
| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ |
| bundleName | string | Yes | Name of the target bundle. |
| installParam | [InstallParam](#installparam) | No | Parameters required for the uninstall. |
**Return value**
| Type | Description |
| ------------- | -------------------------------------- |
| --------------- | -------------------------------------- |
| Promise\<void\> | Promise that returns no value.|
**Error codes**
......@@ -364,26 +421,28 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ------------------------------------------------------------ |
| 17700001 | The specified bundle name is not found. |
| 17700004 | The specified userId is not existed. |
| 17700020 | The specified bundle is pre-installed bundle which cannot be uninstalled. |
| 17700037 | The version of shared bundle is dependent on other applications. |
| 17700038 | The specified shared bundle does not exist. |
| 17700040 | The specified bundle is a shared bundle which cannot be uninstalled. |
**Example**
```ts
import installer from '@ohos.bundle.installer';
let uninstallParam = {
bundleName : "com.ohos.demo",
let bundleName = 'com.ohos.demo';
let installParam = {
userId: 100,
isKeepData: false,
installFlag: 1,
};
try {
installer.getBundleInstaller().then(data => {
data.uninstall(uninstallParam, err => {
if (err) {
console.error('uninstall failed:' + err.message);
} else {
console.info('uninstall successfully.');
}
data.uninstall(bundleName, installParam)
.then((data) => {
console.info('uninstall successfully: ' + JSON.stringify(data));
}).catch((error) => {
console.error('uninstall failed:' + error.message);
});
}).catch(error => {
console.error('getBundleInstaller failed. Cause: ' + error.message);
......@@ -397,7 +456,7 @@ try {
recover(bundleName: string, installParam: InstallParam, callback: AsyncCallback&lt;void&gt;): void;
Recovers a bundle. This API uses an asynchronous callback to return the result.
Rolls back a bundle to the initial installation state. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
......@@ -410,7 +469,7 @@ Recovers a bundle. This API uses an asynchronous callback to return the result.
| Name | Type | Mandatory| Description |
| ---------- | ---------------------------------------------------- | ---- | ---------------------------------------------- |
| bundleName | string | Yes | Name of the target bundle. |
| installParam | [InstallParam](#installparam) | Yes | Parameters required for the recovering. |
| installParam | [InstallParam](#installparam) | Yes | Parameters required for the recovery. |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.|
**Error codes**
......@@ -419,6 +478,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ----------------------------------- |
| 17700001 | The specified bundle name is not found. |
| 17700004 | The specified user ID is not found. |
**Example**
......@@ -449,6 +509,229 @@ try {
}
```
## BundleInstaller.recover
recover(bundleName: string, callback: AsyncCallback&lt;void&gt;): void;
Rolls back a bundle to the initial installation state. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.INSTALL_BUNDLE
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ---------------------------------------------------- | ---- | ---------------------------------------------- |
| bundleName | string | Yes | Name of the target bundle. |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | ----------------------------------- |
| 17700001 | The specified bundle name is not found. |
**Example**
```ts
import installer from '@ohos.bundle.installer';
let bundleName = 'com.ohos.demo';
try {
installer.getBundleInstaller().then(data => {
data.recover(bundleName, err => {
if (err) {
console.error('recover failed:' + err.message);
} else {
console.info('recover successfully.');
}
});
}).catch(error => {
console.error('getBundleInstaller failed. Cause: ' + error.message);
});
} catch (error) {
console.error('getBundleInstaller failed. Cause: ' + error.message);
}
```
## BundleInstaller.recover
recover(bundleName: string, installParam?: InstallParam) : Promise\<void\>;
Rolls back a bundle to the initial installation state. This API uses a promise to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.INSTALL_BUNDLE
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ |
| bundleName | string | Yes | Name of the target bundle. |
| installParam | [InstallParam](#installparam) | No | Parameters required for the recovery. |
**Return value**
| Type | Description |
| --------------- | -------------------------------------- |
| Promise\<void\> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | ----------------------------------- |
| 17700001 | The specified bundle name is not found. |
| 17700004 | The specified user ID is not found. |
**Example**
```ts
import installer from '@ohos.bundle.installer';
let bundleName = 'com.ohos.demo';
let installParam = {
userId: 100,
isKeepData: false,
installFlag: 1,
};
try {
installer.getBundleInstaller().then(data => {
data.recover(bundleName, installParam)
.then((data) => {
console.info('recover successfully: ' + JSON.stringify(data));
}).catch((error) => {
console.error('recover failed:' + error.message);
});
}).catch(error => {
console.error('getBundleInstaller failed. Cause: ' + error.message);
});
} catch (error) {
console.error('getBundleInstaller failed. Cause: ' + error.message);
}
```
## BundleInstaller.uninstall<sup>10+</sup>
uninstall(uninstallParam: UninstallParam, callback : AsyncCallback\<void>) : void ;
Uninstalls a shared bundle. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.INSTALL_BUNDLE
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| uninstallParam | [UninstallParam](#uninstallparam10) | Yes | Parameters required for the uninstall. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------ |
| 17700020 | The specified bundle is pre-installed bundle which cannot be uninstalled. |
| 17700037 | The version of shared bundle is dependent on other applications. |
| 17700038 | The specified shared bundle does not exist. |
**Example**
```ts
import installer from '@ohos.bundle.installer';
let uninstallParam = {
bundleName : "com.ohos.demo",
};
try {
installer.getBundleInstaller().then(data => {
data.uninstall(uninstallParam, err => {
if (err) {
console.error('uninstall failed:' + err.message);
} else {
console.info('uninstall successfully.');
}
});
}).catch(error => {
console.error('getBundleInstaller failed. Cause: ' + error.message);
});
} catch (error) {
console.error('getBundleInstaller failed. Cause: ' + error.message);
}
```
## BundleInstaller.uninstall<sup>10+</sup>
uninstall(uninstallParam: UninstallParam) : Promise\<void>;
Uninstalls a shared bundle. This API uses a promise to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.INSTALL_BUNDLE
**System capability**: SystemCapability.BundleManager.BundleFramework.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ----------------------------------- | ---- | ---------------------------- |
| uninstallParam | [UninstallParam](#uninstallparam10) | Yes | Parameters required for the uninstall.|
**Return value**
| Type | Description |
| ------------- | -------------------------------------- |
| Promise\<void\> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------ |
| 17700020 | The specified bundle is pre-installed bundle which cannot be uninstalled. |
| 17700037 | The version of shared bundle is dependent on other applications. |
| 17700038 | The specified shared bundle does not exist. |
**Example**
```ts
import installer from '@ohos.bundle.installer';
let uninstallParam = {
bundleName : "com.ohos.demo",
};
try {
installer.getBundleInstaller().then(data => {
data.uninstall(uninstallParam, err => {
if (err) {
console.error('uninstall failed:' + err.message);
} else {
console.info('uninstall successfully.');
}
});
}).catch(error => {
console.error('getBundleInstaller failed. Cause: ' + error.message);
});
} catch (error) {
console.error('getBundleInstaller failed. Cause: ' + error.message);
}
```
## HashParam
Defines the hash parameters for bundle installation and uninstall.
......@@ -477,7 +760,7 @@ Defines the parameters that need to be specified for bundle installation, uninst
| isKeepData | boolean | No | Whether to retain the data directory during bundle uninstall.|
| hashParams | Array<[HashParam](#hashparam)> | No| Hash parameters. |
| crowdtestDeadline| number | No |End date of crowdtesting.|
| sharedBundleDirPaths | Array\<String> | No|Paths of the shared bundle files.|
| sharedBundleDirPaths<sup>10+</sup> | Array\<String> | No|Paths of the shared bundle files.|
## UninstallParam<sup>10+</sup>
......
......@@ -29,7 +29,7 @@ Obtains the launcher ability information based on the given bundle name and user
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- | -------------- |
| bundleName | string | Yes | Bundle name of the application.|
| bundleName | string | Yes | Bundle name.|
| userId | number | Yes | User ID.|
**Return value**
......@@ -45,7 +45,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17700001 | The specified bundle name is not found. |
| 17700004 | The specified userId is not found. |
| 17700004 | The specified user ID is not found. |
**Example**
......@@ -55,12 +55,13 @@ import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
try {
launcherBundleManager.getLauncherAbilityInfo('com.example.demo', 100, (errData, data) => {
if (errData !== null) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
}
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
} else {
console.log("data is " + JSON.stringify(data));
}
})
} catch (errData) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
}
```
......@@ -80,7 +81,7 @@ Obtains the launcher ability information based on the given bundle name and user
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- | -------------- |
| bundleName | string | Yes | Bundle name of the application.|
| bundleName | string | Yes | Bundle name.|
| userId | number | Yes | User ID.|
**Return value**
......@@ -96,7 +97,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17700001 | The specified bundle name is not found. |
| 17700004 | The specified userId is not found. |
| 17700004 | The specified user ID is not found. |
**Example**
......@@ -107,10 +108,10 @@ try {
launcherBundleManager.getLauncherAbilityInfo("com.example.demo", 100).then(data => {
console.log("data is " + JSON.stringify(data));
}).catch (errData => {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
})
} catch (errData) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
}
```
......@@ -144,7 +145,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17700004 | The specified userId is not found. |
| 17700004 | The specified user ID is not found. |
Example
......@@ -154,12 +155,13 @@ import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
try {
launcherBundleManager.getAllLauncherAbilityInfo(100, (errData, data) => {
if (errData !== null) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
}
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
} else {
console.log("data is " + JSON.stringify(data));
}
});
} catch (errData) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
}
```
## launcherBundlemanager.getAllLauncherAbilityInfo<sup>9+</sup>
......@@ -192,7 +194,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| -------- | ---------------------------------------- |
| 17700004 | The specified userId is not found. |
| 17700004 | The specified user ID is not found. |
**Example**
......@@ -203,10 +205,10 @@ try {
launcherBundleManager.getAllLauncherAbilityInfo(100).then(data => {
console.log("data is " + JSON.stringify(data));
}).catch (errData => {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
});
} catch (errData) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
}
```
......@@ -224,7 +226,7 @@ Obtains the shortcut information of the current user based on the given bundle n
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- | -------------- |
| bundleName | string | Yes | Bundle name of the application.|
| bundleName | string | Yes | Bundle name.|
**Return value**
......@@ -248,12 +250,13 @@ import launcherBundleManager from '@ohos.bundle.launcherBundleManager';
try {
launcherBundleManager.getShortcutInfo("com.example.demo", (errData, data) => {
if (errData !== null) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
}
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
} else {
console.log("data is " + JSON.stringify(data));
}
});
} catch (errData) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
}
```
......@@ -271,7 +274,7 @@ Obtains the shortcut information of the current user based on the given bundle n
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- | -------------- |
| bundleName | string | Yes | Bundle name of the application.|
| bundleName | string | Yes | Bundle name.|
**Return value**
......@@ -296,9 +299,9 @@ try {
launcherBundleManager.getShortcutInfo("com.example.demo").then(data => {
console.log("data is " + JSON.stringify(data));
}).catch (errData => {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
});
} catch (errData) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
console.error(`errData is errCode:${errData.code} message:${errData.message}`);
}
```
......@@ -239,7 +239,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| ------ | -------------------------------------- |
| 17700002 | The specified module name is not found. |
| 17700032 | he specified bundle does not contain any overlay module. |
| 17700032 | The specified bundle does not contain any overlay module. |
| 17700033 | The specified module is not an overlay module. |
**Example**
......@@ -415,7 +415,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| ------ | -------------------------------------- |
| 17700001 | The specified bundleName is not found |
| 17700001 | The specified bundleName is not found. |
| 17700002 | The specified module name is not found. |
| 17700032 | The specified bundle does not contain any overlay module. |
| 17700033 | The specified module is not an overlay module. |
......@@ -462,7 +462,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| ------ | -------------------------------------- |
| 17700001 | The specified bundleName is not found |
| 17700001 | The specified bundleName is not found. |
| 17700002 | The specified module name is not found. |
| 17700032 | The specified bundle does not contain any overlay module. |
| 17700033 | The specified module is not an overlay module. |
......@@ -511,7 +511,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| ------ | -------------------------------------- |
| 17700001 | The specified bundleName is not found |
| 17700001 | The specified bundleName is not found. |
| 17700002 | The specified module name is not found. |
| 17700032 | The specified bundle does not contain any overlay module. |
| 17700033 | The specified module is not an overlay module. |
......@@ -557,7 +557,7 @@ Obtains the information about modules with the overlay feature in another applic
| Type | Description |
| ------------------------- | ------------------ |
| Promise\<Array\<OverlayModuleInfo>> | Promise used to return the array of overlay module information obtained.|
| Promise\<Array\<OverlayModuleInfo>> | Promise used to return the result, which is an array of **OverlayModuleInfo** objects.|
**Error codes**
......@@ -565,7 +565,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| ------ | -------------------------------------- |
| 17700001 | The specified bundleName is not found |
| 17700001 | The specified bundleName is not found. |
| 17700002 | The specified module name is not found. |
| 17700034 | The specified module is an overlay module. |
| 17700035 | The specified bundle is an overlay bundle. |
......@@ -612,7 +612,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| ------ | -------------------------------------- |
| 17700001 | The specified bundleName is not found |
| 17700001 | The specified bundleName is not found. |
| 17700002 | The specified module name is not found. |
| 17700034 | The specified module is an overlay module. |
| 17700035 | The specified bundle is an overlay bundle. |
......@@ -661,7 +661,7 @@ For details about the error codes, see [Bundle Error Codes](../errorcodes/errorc
| ID| Error Message |
| ------ | -------------------------------------- |
| 17700001 | The specified bundleName is not found |
| 17700001 | The specified bundleName is not found. |
| 17700002 | The specified module name is not found. |
| 17700034 | The specified module is an overlay module. |
| 17700035 | The specified bundle is an overlay bundle. |
......
......@@ -28,15 +28,6 @@ Since API version 9, this API is supported in ArkTS widgets.
| max | number | No | - When set to a value greater than 0, this parameter indicates the maximum value in the **values** list.<br>- When set to a value equal to or smaller than 0, this parameter indicates the sum of values in the **values** list. The values are displayed in proportion.<br>Default value: **100**|
| type<sup>8+</sup> | [DataPanelType](#datapaneltype) | No| Type of the data panel (dynamic modification is not supported).<br>Default value: **DataPanelType.Circle**|
## Attributes
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type | Description |
| ----------- | ------- | -------------------------------------------- |
| closeEffect | boolean | Whether to disable the rotation effect for the component.<br>Default value: **false**|
## DataPanelType
......@@ -48,6 +39,50 @@ Since API version 9, this API is supported in ArkTS widgets.
| Circle | Circle data panel.|
## Attributes
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type| Mandatory| Description|
| ------------- | ------- | ---- | -------- |
| closeEffect | boolean | Yes| Whether to disable the rotation effect for the component.<br>Default value: **false**.|
| valueColors<sup>10+</sup> | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | Yes| Array of data segment colors. A value of the **ResourceColor** type indicates a solid color, and A value of the **LinearGradient** type indicates a color gradient.|
| trackBackgroundColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | Yes| Background color.|
| strokeWidth<sup>10+</sup> | [Length](ts-types.md#Length) | Yes| Stroke width of the border.|
| trackShadow<sup>10+</sup> | [DataPanelShadowOption](#datapanelshadowoption10) | Yes| Shadow style. If this attribute is not set, the shadow effect is disabled.|
## DataPanelShadowOption<sup>10+</sup>
| Name | Type| Mandatory| Description|
| ------------- | ------- | ---- | -------- |
| radius | number \| [Resource](ts-types.md#resource)| No| Shadow blur radius.<br>Default value: **5vp**|
| colors | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | No| Array of shadow colors for data segments.<br>Default value: same as the value of **valueColors**.|
| offsetX | number \| [Resource](ts-types.md#resource)| No| Offset on the x-axis.<br>Default value: **5vp**|
| offsetY | number \| [Resource](ts-types.md#resource)| No| Offset on the y-axis.<br>Default value: **5vp**|
## LinearGradient<sup>10+</sup>
Describes the linear gradient.
LinearGradient(colorStops: ColorStop[])
| Name | Type| Mandatory| Description|
| ------------- | ------- | ---- | -------- |
| colorStops | [ColorStop](#colorstop10)[] | Yes| Gradient colors and color stops.|
## ColorStop<sup>10+</sup>
Describes the gradient color stop.
| Name | Type| Mandatory| Description|
| ------------- | ------- | ---- | -------- |
| color | [ResourceColor](ts-types.md#resourcecolor) | Yes| Color value.|
| offset | [Length](ts-types.md#Length) | Yes| Gradient color stop (proportion value between 0 and 1).|
## Example
```ts
......
......@@ -20,33 +20,45 @@ Creates a date picker in the given date range.
**Parameters**
| Name| Type| Mandatory | Description|
| -------- | -------- | ------------- | -------- |
| start | Date | No | Start date of the picker.<br>Default value: **Date('1970-1-1')**|
| Name | Type| Mandatory | Description |
| -------- | ---- | ---- | -------------------------------------- |
| start | Date | No | Start date of the picker.<br>Default value: **Date('1970-1-1')** |
| end | Date | No | End date of the picker.<br>Default value: **Date('2100-12-31')**|
| selected | Date | No | Date of the selected item.<br>Default value: current system date |
## Attributes
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type | Description |
| ------| -------------- | -------- |
| -------------------------------- | ---------------------------------------- | ---------------------------------------- |
| lunar | boolean | Whether to display the lunar calendar.<br>- **true**: Display the lunar calendar.<br>- **false**: Do not display the lunar calendar.<br>Default value: **false**|
| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width for the top and bottom items. |
| textStyle<sup>10+</sup> | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items. |
| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width of the selected item. |
## PickerTextStyle<sup>10+</sup>
| Name | Type | Mandatory | Description |
| ----- | ---------------------------------------- | ---- | ------------------------- |
| color | [ResourceColor](ts-types.md#resourcecolor) | No | Font color. |
| font | [Font](ts-types.md#font) | No | Text style. Only the font size and font width are supported.|
## Events
| Name| Description|
| -------- | -------- |
In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
| Name | Description |
| ---------------------------------------- | ----------- |
| onChange(callback: (value: DatePickerResult) =&gt; void) | Triggered when a date is selected.|
## DatePickerResult
| Name| Type| Description|
| -------- | -------- | -------- |
| year | number | Year of the selected date.|
| Name | Type | Description |
| ----- | ------ | --------------------------- |
| year | number | Year of the selected date. |
| month | number | Month of the selected date. The value ranges from 0 to 11. The value **0** indicates January, and **11** indicates December.|
| day | number | Day of the selected date.|
| day | number | Day of the selected date. |
## Example
......@@ -63,7 +75,7 @@ struct DatePickerExample {
build() {
Column() {
Button('Switch Calendar')
.margin({ top: 30 })
.margin({ top: 30, bottom: 30 })
.onClick(() => {
this.isLunar = !this.isLunar
})
......
......@@ -19,7 +19,7 @@ Not supported
## APIs
Image(src: string | PixelMap | Resource)
Image(src: PixelMap | ResourceStr | DrawableDescriptor)
Obtains an image from the specified source for subsequent rendering and display.
......@@ -27,16 +27,16 @@ Since API version 9, this API is supported in ArkTS widgets.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| src | string\| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | Yes | Image source. Both local and online images are supported.<br>When using an image referenced using a relative path, for example, **Image("common/test.jpg")**, the **\<Image>** component cannot be called across bundles or modules. Therefore, you are advised to use **\$r** to reference image resources that need to be used globally.<br>- The following image formats are supported: PNG, JPG, BMP, SVG, GIF.<br>\- Base64 strings are supported. The value format is data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data], where [base64 data] is a Base64 string.<br/>\- Strings with the **datashare://** path prefix are supported, which are used to access the image path provided by a Data ability. Before loading images, the application must [request the required permissions](../../file-management/medialibrary-overview.md#requesting-permissions).<br/>\- Strings with the **file:///data/storage** prefix are supported, which are used to read image resources in the **files** folder in the installation directory of the application. Ensure that the application has the read permission to the files in the specified path.<br/>- ArkTS widgets do not support the **http://**, **datashare://**, or **file://data/storage** path prefixes.<br>- ArkTS widgets do not support the [PixelMap](../apis/js-apis-image.md#pixelmap7) type.|
| Name | Type | Mandatory | Description |
| ---- | ---------------------------------------- | ---- | ---------------------------------------- |
| src | [PixelMap](../apis/js-apis-image.md#pixelmap7) \|ResourceStr\| [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | Yes | Image source. Both local and online images are supported.<br>When using an image referenced using a relative path, for example, **Image("common/test.jpg")**, the **\<Image>** component cannot be called across bundles or modules. Therefore, you are advised to use **\$r** to reference image resources that need to be used globally.<br>- The following image formats are supported: PNG, JPG, BMP, SVG, GIF.<br>\- Base64 strings are supported. The value format is data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data], where [base64 data] is a Base64 string.<br/>\- Strings with the **datashare://** path prefix are supported, which are used to access the image path provided by a Data ability.<br/>\- Strings with the **file:///data/storage** prefix are supported, which are used to read image resources in the **files** folder in the installation directory of the application. Ensure that the application has the read permission to the files in the specified path.<br/>\- [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) objects are supported.<br/>**NOTE**<br/>- ArkTS widgets support GIF images, but the images are played only once when they are displayed.<br/>- ArkTS widgets do not support the **http://**, **datashare://**, or **file://data/storage** path prefixes.<br>- ArkTS widgets do not support the [PixelMap](../apis/js-apis-image.md#pixelmap7) type.|
## Attributes
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type | Description |
| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
| ------------------------ | ---------------------------------------- | ---------------------------------------- |
| alt | string \| [Resource](ts-types.md#resource)| Placeholder image displayed during loading. Local images are supported.<br>Since API version 9, this API is supported in ArkTS widgets.|
| objectFit | [ImageFit](ts-appendix-enums.md#imagefit) | Image scale mode.<br>Default value: **ImageFit.Cover**<br>Since API version 9, this API is supported in ArkTS widgets.|
| objectRepeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | Whether the image is repeated.<br>Default value: **ImageRepeat.NoRepeat**<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>This attribute is not applicable to SVG images.|
......@@ -49,12 +49,13 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| autoResize | boolean | Whether to resize the image source used for drawing based on the size of the display area during image decoding. This resizing can help reduce the memory usage.<br>Default value: **true**<br>Since API version 9, this API is supported in ArkTS widgets.|
| syncLoad<sup>8+</sup> | boolean | Whether to load the image synchronously. By default, the image is loaded asynchronously. During synchronous loading, the UI thread is blocked and the placeholder diagram is not displayed.<br>Default value: **false**<br>Since API version 9, this API is supported in ArkTS widgets.|
| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether the image can be copied. (SVG images cannot be copied.)<br>When **copyOption** is set to a value other than **CopyOptions.None**, the image can be copied in various manners, such as long pressing, right-clicking, or pressing Ctrl+C.<br>Default value: **CopyOptions.None**<br>This API is supported in ArkTS widgets.|
| colorFilter<sup>9+</sup> | [ColorFilter](ts-types.md#colorfilter9) | Color filter of the image.<br>This API is supported in ArkTS widgets.|
| colorFilter<sup>9+</sup> | [ColorFilter](ts-types.md#colorfilter9) | Color filter of the image.<br>This API is supported in ArkTS widgets. |
| draggable<sup>9+</sup> | boolean | Whether the image is draggable. This attribute cannot be used together with the [onDragStart](ts-universal-events-drag-drop.md) event.<br>Default value: **false**<br>This API is supported in ArkTS widgets.|
> **NOTE**
>
> To use shortcut keys to copy the image, the image must be in focus. To enable the image to gain focus, set both the **focusable** and **focusOnTouch** attributes to **true**.
>
> For SVG images, only the following tags are included in the supported list: **svg**, **rect**, **circle**, **ellipse**, **path**, **line**, **polyline**, **polygon**, and **animate**.
### ImageInterpolation
......@@ -82,10 +83,10 @@ Since API version 9, this API is supported in ArkTS widgets.
In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
| Name | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,<br> componentHeight: number, loadingStatus: number }) =&gt; void) | Triggered when an image is successfully loaded. The size of the loaded image is returned.<br>- **width**: width of the image, in pixels.<br>- **height**: height of the image, in pixels.<br>- **componentWidth**: width of the container component, in pixels.<br>- **componentHeight**: height of the container component, in pixels.<br>- **loadingStatus**: image loading status. The value **1** means that the image is successfully loaded, and **0** means the opposite.<br>Since API version 9, this API is supported in ArkTS widgets. |
| onError(callback: (event?: { componentWidth: number, componentHeight: number , message<sup>9+</sup>: string }) =&gt; void) | Triggered when an exception occurs during image loading.<br>- **componentWidth**: width of the container component, in pixels.<br>- **componentHeight**: height of the container component, in pixels.<br>Since API version 9, this API is supported in ArkTS widgets. |
| onFinish(event: () =&gt; void) | Triggered when the animation playback in the loaded SVG image is complete. If the animation is an infinite loop, this callback is not triggered.<br>Since API version 9, this API is supported in ArkTS widgets. |
| ---------------------------------------- | ---------------------------------------- |
| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,<br> componentHeight: number, loadingStatus: number }) =&gt; void) | Triggered when an image is successfully loaded. The size of the loaded image is returned.<br>- **width**: width of the image, in pixels.<br>- **height**: height of the image, in pixels.<br>- **componentWidth**: width of the container component, in pixels.<br>- **componentHeight**: height of the container component, in pixels.<br>- **loadingStatus**: image loading status.<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>The value **1** means that the image is successfully loaded, and **0** means the opposite.|
| onError(callback: (event?: { componentWidth: number, componentHeight: number , message<sup>9+</sup>: string }) =&gt; void) | Triggered when an exception occurs during image loading.<br>- **componentWidth**: width of the container component, in pixels.<br>- **componentHeight**: height of the container component, in pixels.<br>Since API version 9, this API is supported in ArkTS widgets.|
| onFinish(event: () =&gt; void) | Triggered when the animation playback in the loaded SVG image is complete. If the animation is an infinite loop, this callback is not triggered.<br>Since API version 9, this API is supported in ArkTS widgets.|
## Example
......@@ -163,7 +164,7 @@ struct ImageExample1 {
### Loading Online Images
The default network timeout period is 5 minutes for loading online images. When using an online image, you are advised to use **alt** to configure the placeholder image displayed during loading. If more flexible network configuration is required, use the [HTTP](../../connectivity/http-request.md) module in the SDK to send a network request, and then decode the returned data into a **PixelMap** in the **\<Image>** component. For details about image development, see [Image Development](../../media/image.md). The code snippet is as follows:
The default network timeout period is 5 minutes for loading online images. When using an online image, you are advised to use **alt** to configure the placeholder image displayed during loading. If more flexible network configuration is required, you can use the [HTTP](../../connectivity/http-request.md) tool provided in the SDK to send a network request, and then decode the returned data into **PixelMap** objects in the **\<Image>** component. For details about image development, see [Image Processing](../../media/image-overview.md). The code snippet is as follows:
```tsx
// @ts-nocheck
......@@ -371,7 +372,7 @@ import context from '@ohos.app.ability.common';
struct LoadImageExample {
@State resourcesPath: string = ''
@State sandboxPath: string = ''
context: context.UIAbility = getContext(this) as context.UIAbilityContext
context: context.UIAbilityContext = getContext(this) as context.UIAbilityContext
build() {
Column() {
......@@ -398,6 +399,12 @@ struct LoadImageExample {
Image(this.resourcesPath)
.width(100)
.height(100)
.colorFilter([
0.30, 0.59, 0.11, 0, 0,
0.30, 0.59, 0.11, 0, 0,
0.30, 0.59, 0.11, 0, 0,
0, 0, 0, 1.0, 0
])
Text(`Sandbox image path: ${this.sandboxPath}`)
.fontSize(20)
.margin({ bottom: 10 })
......@@ -409,3 +416,4 @@ struct LoadImageExample {
}
}
```
<!--no_check-->
\ No newline at end of file
......@@ -22,7 +22,9 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| Name | Type | Description |
| -------- | ------------------------- | ---------------------------------------------------------------- |
| fontSize | [Length](ts-types.md#length) | Font size that applies to all texts in the menu. When **Length** is of the number type, the unit is fp.|
| fontSize<sup>deprecated</sup> | [Length](ts-types.md#length) | Font size of the menu text. When **Length** is of the number type, the unit is fp.<br>This API is deprecated since API version 10. You are advised to use **font** instead.|
| font<sup>10+</sup> | [Font](ts-types.md#font) | Font style of the menu text.|
| fontColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | Font color of the menu text.|
## Example
......
......@@ -23,21 +23,25 @@ MenuItem(value?: MenuItemOptions| CustomBuilder)
## MenuItemOptions
| Name | Type | Mandatory| Description |
| --------- | ---------------------------------------- | ---- | -------------------------------------- |
| --------- | ------------------------------------------- | ---- | -------------------------------------- |
| startIcon | [ResourceStr](ts-types.md#resourcestr) | No | Path to the icon displayed on the left of the menu item. |
| content | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the menu item. |
| content | [ResourceStr](ts-types.md#resourcestr) | No | Content of the menu item. |
| endIcon | [ResourceStr](ts-types.md#resourcestr) | No | Path to the icon displayed on the right of the menu item. |
| labelInfo | [ResourceStr](ts-types.md#resourcestr) | No | Information about the ending label, for example, shortcut **Ctrl+C**. |
| labelInfo | [ResourceStr](ts-types.md#resourcestr) | No | Information about the ending label, for example, shortcut **Ctrl+C**.|
| builder | [CustomBuilder](ts-types.md#custombuilder8) | No | Builder for a level-2 menu. |
## Attributes
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type| Description |
| ---------- | -------- | ---------------------------------------- |
| Name | Type | Description |
| ------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| selected | boolean | Whether the menu item is selected.<br>Default value: **false** |
| selectIcon | boolean | Whether to display the icon of the menu item being selected.|
| selectIcon | boolean \| [ResourceStr](ts-types.md#resourcestr)<sup>10+</sup> | Whether to display the selected icon for a menu item is selected.<br>Default value: **false**<br>**true**: When a menu item is selected, the default tick icon is displayed.<br>**false**: When a menu item is selected, no icon is displayed.<br>**ResourceStr**: When a menu item is selected, the specified icon is displayed.|
| contentFont<sup>10+</sup> | [Font](ts-types.md#font) | Font style of the menu item content. |
| contentFontColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | Font color of the menu item content. |
| labelFont<sup>10+</sup> | [Font](ts-types.md#font) | Font style of the menu item label. |
| labelFontColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | Font color of the menu item label. |
## Events
......
......@@ -5,6 +5,8 @@ The **\<QRCode>** component is used to display a QR code.
> **NOTE**
>
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
>
> The number of pixels of the **\<QRCode>** component is subject to the content. If the component size is not large enough, the content may fail to be displayed. In this case, you need to resize the component.
## Child Components
......@@ -22,7 +24,7 @@ Since API version 9, this API is supported in ArkTS widgets.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| value | string | Yes| Content of the QR code.|
| value | string | Yes| Content of the QR code. A maximum of 256 characters are supported. If the number of characters exceeds 256, the first 256 characters are used.|
## Attributes
......
......@@ -20,8 +20,8 @@ TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: Tex
| Name | Type | Mandatory | Description |
| ----------------------- | ---------------------------------------- | ---- | -------------- |
| placeholder | [ResourceStr](ts-types.md#resourcestr) | No | Placeholder text displayed when there is no input. |
| text | [ResourceStr](ts-types.md#resourcestr) | No | Current text input. |
| placeholder | [ResourceStr](ts-types.md#resourcestr) | No | Placeholder text displayed when there is no input. It is not displayed once there is any input. |
| text | [ResourceStr](ts-types.md#resourcestr) | No | Current text input.<br>If the component has [stateStyles](ts-universal-attributes-polymorphic-style.md) or any other attribute that may trigger updating configured, you are advised to bind the state variable to the text in real time through the **onChange** event,<br>so as to prevent display errors when the component is updated. |
| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | No | Text area controller.|
......@@ -30,9 +30,9 @@ TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: Tex
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type | Description |
| ------------------------ | ---------------------------------------- | ---------------------------------------- |
| ------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | Placeholder text color. |
| placeholderFont | [Font](ts-types.md#font) | Placeholder text style. |
| placeholderFont | [Font](ts-types.md#font) | Placeholder text style, including the font size, font width, font family, and font style. Currently, only the default font family is supported.|
| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Horizontal alignment of the text.<br>Default value: **TextAlign.Start**|
| caretColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the caret in the text box. |
| inputFilter<sup>8+</sup> | {<br>value: [ResourceStr](ts-types.md#resourcestr),<br>error?: (value: string) => void<br>} | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are filtered out. The specified regular expression can match single characters, but not strings.<br>- **value**: regular expression to set.<br>- **error**: filtered-out content to return when regular expression matching fails.|
......@@ -40,7 +40,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
> **NOTE**
>
> The default value of the universal attribute [padding](ts-universal-attributes-size.md) is as follows: { top: 8 vp, right: 16 vp, bottom: 16 vp, left: 8 vp }
> The default value of the universal attribute [padding](ts-universal-attributes-size.md) is as follows: <br>{<br> top: 8 vp,<br> right: 16 vp,<br> bottom: 8 vp,<br> left: 16 vp<br> }
## Events
......@@ -50,9 +50,10 @@ In addition to the [universal events](ts-universal-events-click.md), the followi
| Name | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| onChange(callback: (value: string) =&gt; void) | Triggered when the input in the text box changes.<br>- **value**: text entered. |
| onCopy<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be copied.|
| onCut<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be cut.|
| onPaste<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be pasted.|
| onEditChange(callback: (isEditing: boolean) =&gt; void)<sup>10+</sup> | Triggered when the input status changes. When the cursor is placed in the text box, it is in the editing state. Otherwise, it is in the non-editing state. If the value of **isEditing** is **true**, text input is in progress. |
| onCopy<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be copied. |
| onCut<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be cut. |
| onPaste<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be pasted. |
## TextAreaController<sup>8+</sup>
......@@ -102,6 +103,7 @@ struct TextAreaExample {
build() {
Column() {
TextArea({
text: this.text,
placeholder: 'The text area can hold an unlimited amount of text. input your word...',
controller: this.controller
})
......
......@@ -21,7 +21,7 @@ TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: Te
| Name | Type | Mandatory | Description |
| ----------------------- | ---------------------------------------- | ---- | --------------- |
| placeholder | [ResourceStr](ts-types.md#resourcestr) | No | Placeholder text displayed when there is no input. |
| text | [ResourceStr](ts-types.md#resourcestr) | No | Current text input. |
| text | [ResourceStr](ts-types.md#resourcestr) | No | Current text input.<br>If the component has [stateStyles](ts-universal-attributes-polymorphic-style.md) or any other attribute that may trigger updating configured, you are advised to bind the state variable to the text in real time through the **onChange** event,<br>so as to prevent display errors when the component is updated. |
| controller<sup>8+</sup> | [TextInputController](#textinputcontroller8) | No | Text input controller.|
......@@ -34,7 +34,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| type | [InputType](#inputtype) | Input box type.<br>Default value: **InputType.Normal** |
| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | Placeholder text color.|
| placeholderFont | [Font](ts-types.md#font) | Placeholder text font.|
| enterKeyType | [EnterKeyType](#enterkeytype) | Type of the Enter key. Only the default value is supported.<br>Default value: **EnterKeyType.Done**|
| enterKeyType | [EnterKeyType](#enterkeytype) | Type of the Enter key. Currently, only the default value is supported.<br>Default value: **EnterKeyType.Done**|
| caretColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the caret in the text box. |
| maxLength | number | Maximum number of characters in the text input. |
| inputFilter<sup>8+</sup> | {<br>value: [ResourceStr](ts-types.md#resourcestr),<br>error?: (value: string) =&gt; void<br>} | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are filtered out. The regular expression can match single characters, but not strings.<br>- **value**: regular expression to set.<br>- **error**: filtered-out content to return when regular expression matching fails.|
......@@ -43,12 +43,12 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| style<sup>9+</sup> | [TextInputStyle](#textinputstyle9) | Text input style.<br>Default value: **TextInputStyle.Default**|
| textAlign<sup>9+</sup> | [TextAlign](ts-appendix-enums.md#textalign) | Alignment mode of the text in the text box.<br>Default value: **TextAlign.Start** |
| selectedBackgroundColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | Background color of the selected text.|
| caretStyle<sup>10+</sup> | {<br>caretWidth: [Length](ts-types.md#length)<br>} | Caret style. |
| caretStyle<sup>10+</sup> | {<br>width: [Length](ts-types.md#length)<br>} | Caret style. |
| caretPosition<sup>10+</sup> | number | Caret position.|
> **NOTE**
>
> The default value of the universal attribute [padding](ts-universal-attributes-size.md) is as follows: <br>{<br> top: 8 vp,<br> right: 16 vp,<br> bottom: 16 vp,<br> left: 8 vp<br> }
> The default value of the universal attribute [padding](ts-universal-attributes-size.md) is as follows: { top: 8 vp, right: 16 vp, bottom: 8 vp, left: 16 vp }
## EnterKeyType
......@@ -65,8 +65,8 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| Name | Description |
| ------------------ | ------------- |
| Normal | Normal input mode.<br>The value can contain digits, letters, underscores (_), spaces, and special characters.|
| Password | Password input mode. |
| Email | Email address input mode.|
| Password | Password input mode. The value can contain digits, letters, underscores (_), spaces, and special characters. An eye icon is used to show or hide the password, and the password is hidden behind dots by default.|
| Email | Email address input mode. The value can contain digits, letters, underscores (_), and at signs (@). Only one at sign (@) is allowed.|
| Number | Digit input mode. |
| PhoneNumber<sup>9+</sup> | Phone number input mode.<br>The value can contain digits, plus signs (+), hyphens (-), asterisks (*), and number signs (#). The length is not limited.|
......@@ -83,13 +83,13 @@ In addition to the [universal events](ts-universal-events-click.md), the followi
| Name | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| onChange(callback: (value: string) =&gt; void) | Triggered when the input changes.<br>**value**: text content.|
| onSubmit(callback: (enterKey: EnterKeyType) =&gt; void) | Triggered when the Enter key on the keyboard is pressed. The return value is the current type of the Enter key.<br>**enterKeyType**: type of the Enter key. For details, see [EnterKeyType](#enterkeytype).|
| onEditChanged(callback: (isEditing: boolean) =&gt; void)<sup>(deprecated)</sup> | Triggered when the input status changes. Since API version 8, **onEditChange** is recommended.|
| onEditChange(callback: (isEditing: boolean) =&gt; void)<sup>8+</sup> | Triggered when the input status changes. If the value of **isEditing** is **true**, text input is in progress. |
| onCopy(callback:(value: string) =&gt; void)<sup>8+</sup> | Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be copied.|
| onCut(callback:(value: string) =&gt; void)<sup>8+</sup> | Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be cut.|
| onPaste(callback:(value: string) =&gt; void)<sup>8+</sup> | Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be pasted.|
| onChange(callback: (value: string) =&gt; void) | Triggered when the input changes.<br>**value**: text content.<br>This event is triggered when any of the following conditions is met:<br>1. Keyboard input is received.<br>2. Paste and cut is performed.<br>3. Ctrl+V is pressed. |
| onSubmit(callback: (enterKey: EnterKeyType) =&gt; void) | Triggered when the Enter key on the keyboard is pressed. The return value is the current type of the Enter key.<br>**enterKeyType**: type of the Enter key. For details, see [EnterKeyType](#enterkeytype). |
| onEditChanged(callback: (isEditing: boolean) =&gt; void)<sup>(deprecated)</sup> | Triggered when the input status changes. Since API version 8, **onEditChange** is recommended. |
| onEditChange(callback: (isEditing: boolean) =&gt; void)<sup>8+</sup> | Triggered when the input status changes. When the cursor is placed in the text box, it is in the editing state. Otherwise, it is in the non-editing state. If the value of **isEditing** is **true**, text input is in progress. |
| onCopy(callback:(value: string) =&gt; void)<sup>8+</sup> | Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be copied. |
| onCut(callback:(value: string) =&gt; void)<sup>8+</sup> | Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be cut. |
| onPaste(callback:(value: string) =&gt; void)<sup>8+</sup> | Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be pasted. |
## TextInputController<sup>8+</sup>
......@@ -135,7 +135,7 @@ struct TextInputExample {
build() {
Column() {
TextInput({ placeholder: 'input your word...', controller: this.controller })
TextInput({ text: this.text, placeholder: 'input your word...', controller: this.controller })
.placeholderColor(Color.Grey)
.placeholderFont({ size: 14, weight: 400 })
.caretColor(Color.Blue)
......@@ -144,6 +144,9 @@ struct TextInputExample {
.margin(20)
.fontSize(14)
.fontColor(Color.Black)
.inputFilter('[a-z]', (e) => {
console.log(JSON.stringify(e))
})
.onChange((value: string) => {
this.text = value
})
......
......@@ -14,7 +14,7 @@ Not supported
## APIs
TextPicker(options?: {range: string[]|Resource, selected?: number, value?: string})
TextPicker(options?: {range: string[]|Resource|TextPickerRangeContent[], selected?: number, value?: string})
Creates a text picker based on the selection range specified by **range**.
......@@ -22,15 +22,27 @@ Creates a text picker based on the selection range specified by **range**.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| range | string[] \| [Resource](ts-types.md#resource)| Yes| Data selection range of the picker.|
| range | string[] \| [Resource](ts-types.md#resource)\|[TextPickerRangeContent](#textpickerrangecontent10)[]<sup>10+</sup> | Yes| Data selection range of the picker. This parameter cannot be set to an empty array. If set to an empty array, it will not be displayed. If it is dynamically changed to an empty array, the current value remains displayed.|
| selected | number | No| Index of the default item in the range.<br>Default value: **0**|
| value | string | No| Value of the default item in the range. The priority of this parameter is lower than that of **selected**.<br>Default value: value of the first item|
| value | string | No| Value of the default item in the range. The priority of this parameter is lower than that of **selected**.<br>Default value: value of the first item<br>**NOTE**\<br>This parameter works only for a text list. It does not work for an image list or a list consisting of text and images.|
## TextPickerRangeContent<sup>10+</sup>
| Name| Type | Mandatory| Description |
| ------ | -------------------------------------------------------- | ---- | ---------- |
| icon | string \| [Resource](ts-types.md#resource) | Yes | Image resource.|
| text | string \| [Resource](ts-types.md#resource) | No | Text information.|
## Attributes
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name| Type| Description|
| -------- | -------- | -------- |
| defaultPickerItemHeight | number \| string | Height of each item in the picker.|
| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width for the top and bottom items.|
| textStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items.|
| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of the selected item.|
## Events
......@@ -38,7 +50,7 @@ In addition to the [universal events](ts-universal-events-click.md), the followi
| Name| Description|
| -------- | -------- |
| onChange(callback: (value: string, index: number) =&gt; void) | Triggered when an item in the picker is selected.<br>- **value**: value of the selected item.<br>- **index**: index of the selected item.|
| onChange(callback: (value: string, index: number) =&gt; void) | Triggered when an item in the picker is selected.<br>- **value**: value of the selected item.<br>**NOTE**<br>For a text list or a list consisting of text and images, **value** indicates the text value of the selected item. For an image list, **value** is empty.<br>- **index**: index of the selected item. |
## Example
......
# TimePicker
The **\<TimePicker>** component allows users to select a time from the given range.
The **\<TimePicker>** component allows users to select a time (with the hour and minute) from the given range.
> **NOTE**
>
......@@ -20,20 +20,25 @@ Creates a time picker, which is in 24-hour format by default.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| selected | Date | No| Time of the selected item.<br>Default value: current system time|
| Name | Type| Mandatory | Description |
| -------- | ---- | ---- | ------------------------ |
| selected | Date | No | Time of the selected item.<br>Default value: current system time|
## Attributes
| Name| Type| Description|
| -------- | -------- | -------- |
| useMilitaryTime | boolean | Whether to display time in 24-hour format. The value cannot be modified dynamically.<br>Default value: **false**|
In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
| Name | Type | Description |
| -------------------------------- | ---------------------------------------- | ----------------------------------- |
| useMilitaryTime | boolean | Whether to display time in 24-hour format. The value cannot be modified dynamically.<br>Default value: **false**|
| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width for the top and bottom items. |
| textStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items. |
| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of the selected item. |
## Events
In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
| Name | Description |
| ---------------------------------------- | ----------- |
| onChange(callback: (value: TimePickerResult ) =&gt; void) | Triggered when a time is selected.|
......@@ -48,9 +53,6 @@ Creates a time picker, which is in 24-hour format by default.
## Example
### Time Picker
```ts
// xxx.ets
@Entry
......
......@@ -28,7 +28,7 @@ Since API version 9, this API is supported in ArkTS widgets.
| Name| Type | Mandatory| Description |
| ------ | ----------------------------- | ---- | ------------------------------------------------------------ |
| span | number \| GridColColumnOption | No | Number of occupied columns. If it is set to **0**, the element is not involved in layout calculation, that is, the element is not rendered.<br>Default value: **1**<br>Since API version 9, this API is supported in ArkTS widgets.|
| offset | number \| GridColColumnOption | No | Number of offset columns relative to the previous child component of the grid<br>Default value: **0**<br>Since API version 9, this API is supported in ArkTS widgets.|
| gridColOffset | number \| GridColColumnOption | No | Number of offset columns relative to the previous child component of the grid<br>Default value: **0**<br>Since API version 9, this API is supported in ArkTS widgets.|
| order | number \| GridColColumnOption | No | Sequence number of the element. Child components of the grid are sorted in ascending order based on their sequence numbers.<br>Default value: **0**<br>Since API version 9, this API is supported in ArkTS widgets.|
## GridColColumnOption
......
......@@ -21,6 +21,11 @@ Shows a date picker dialog box.
| end | Date | No| Date('2100-12-31') | End date of the picker.|
| selected | Date | No| Current system date| Selected date.|
| lunar | boolean | No| false | Whether to display the lunar calendar.|
| showTime<sup>10+</sup> | boolean | No| false | Whether to display the time item.|
| useMilitaryTime<sup>10+</sup> | boolean | No| false | Whether to display time in 24-hour format.|
| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| - | Font color, font size, and font width for the top and bottom items.|
| textStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| - | Font color, font size, and font width of all items except the top, bottom, and selected items.|
| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| - | Font color, font size, and font width of the selected item.|
| onAccept | (value: [DatePickerResult](ts-basic-components-datepicker.md#DatePickerResult)) => void | No| - | Callback invoked when the OK button in the dialog box is clicked.|
| onCancel | () => void | No| - | Callback invoked when the Cancel button in the dialog box is clicked.|
| onChange | (value: [DatePickerResult](ts-basic-components-datepicker.md#DatePickerResult)) => void | No| - | Callback invoked when the selected item in the picker changes.|
......
......@@ -17,10 +17,13 @@ Shows a text picker in the given settings.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| range | string[] \| [Resource](ts-types.md#resource) | Yes| Data selection range of the picker.|
| range | string[] \| [Resource](ts-types.md#resource)\|[TextPickerRangeContent](ts-basic-components-textpicker.md#textpickerrangecontent10)[]<sup>10+</sup> | Yes| Data selection range of the picker. This parameter cannot be set to an empty array. If set to an empty array, it will not be displayed.|
| selected | number | No| Index of the selected item.<br>Default value: **0**|
| value | string | No | Text of the selected item. This parameter does not take effect when the **selected** parameter is set. If the value is not within the range, the first item in the range is used instead.|
| defaultPickerItemHeight | number \| string | No| Height of the picker item.|
| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.|
| textStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of all items except the top, bottom, and selected items.|
| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.|
| onAccept | (value: [TextPickerResult](#textpickerresult)) => void | No| Callback invoked when the OK button in the dialog box is clicked.|
| onCancel | () => void | No| Callback invoked when the Cancel button in the dialog box is clicked.|
| onChange | (value: [TextPickerResult](#textpickerresult)) => void | No| Callback invoked when the selected item changes.|
......@@ -29,7 +32,7 @@ Shows a text picker in the given settings.
| Name| Type| Description|
| -------- | -------- | -------- |
| value | string | Text of the selected item.|
| value | string | Text of the selected item.<br>**NOTE**<br>For a text list or a list consisting of text and images, **value** indicates the text value of the selected item.<br>For an image list, **value** is empty.|
| index | number | Index of the selected item in the range.|
## Example
......
......@@ -19,6 +19,9 @@ Shows a time picker dialog box.
| -------- | -------- | -------- | -------- |
| selected | Date | No| Selected time.<br>Default value: current system time|
| useMilitaryTime | boolean | No| Whether to display time in 24-hour format. The 12-hour format is used by default.<br>Default value: **false**|
| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.|
| textStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of all items except the top, bottom, and selected items.|
| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.|
| onAccept | (value: [TimePickerResult](ts-basic-components-timepicker.md#TimePickerResult)) => void | No| Callback invoked when the OK button in the dialog box is clicked.|
| onCancel | () => void | No| Callback invoked when the Cancel button in the dialog box is clicked.|
| onChange | (value: [TimePickerResult](ts-basic-components-timepicker.md#TimePickerResult)) => void | No| Callback invoked when the selected time changes.|
......
# Menu Control
A menu – a vertical list of items – can be bound to a component and displayed by long-pressing, clicking, or right-clicking the component.
A context menu – a vertical list of items – can be bound to a component and displayed by long-pressing, clicking, or right-clicking the component.
> **NOTE**
>
......@@ -12,16 +12,35 @@ A menu – a vertical list of items – can be bound to a component and displaye
| Name | Type | Description |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| bindMenu | Array<[MenuItem](#menuitem)&gt; \| [CustomBuilder](ts-types.md#custombuilder8) | Menu bound to the component, which is displayed when you click the component. Textual and custom menu items are supported.|
| bindContextMenu<sup>8+</sup> | content: [CustomBuilder](ts-types.md#custombuilder8),<br>responseType: [ResponseType](ts-appendix-enums.md#responsetype8) | Context menu bound to the component, which is displayed when you long-press or right-click the component. Only custom menu items are supported.|
| bindMenu | content: Array<[MenuItem](#menuitem)&gt; \| [CustomBuilder](ts-types.md#custombuilder8),<br>options: [MenuOptions](#menuoptions10) | Menu bound to the component, which is displayed when you click the component. A menu item can be a combination of text and icons or a custom component.<br>**content**: array of menu item text and icons or custom components.<br>**options**: parameters of the context menu. Optional.|
| bindContextMenu<sup>8+</sup> | content: [CustomBuilder](ts-types.md#custombuilder8),<br>responseType: [ResponseType](ts-appendix-enums.md#responsetype8)<br>options: [ContextMenuOptions](#contextmenuoptions10) | Context menu bound to the component, which is displayed when the user long-presses or right-clicks the component. Only custom menu items are supported.<br>**responseType**: how the context menu triggered, which can be long-press or right-click. Mandatory. <br>**options**: parameters of the context menu. Optional.|
## MenuItem
| Name | Type | Description |
| ------ | ----------------------- | ----------- |
| value | string | Menu item text. |
| action | () =&gt; void | Action triggered when a menu item is clicked.|
| Name | Type | Mandatory| Description |
| ------------------ | -------------------------------------- | ---- | ---------------------- |
| value | string | Yes | Menu item text. |
| icon<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Menu item icon. |
| action | () =&gt; void | Yes | Action triggered when a menu item is clicked.|
## MenuOptions<sup>10+</sup>
| Name | Type | Mandatory| Description |
| ------ | -------------------------------- | ---- | ------------------------------------------------------ |
| title | string | No | Menu title. |
| offset | [Position](ts-types.md#position8) | No | Offset for showing the context menu, which should not cause the menu to extend beyond the screen.|
| placement | [Placement](ts-appendix-enums.md#placement8) | No| Preferred position of the context menu. If the set position is insufficient for holding the component, it will be automatically adjusted.<br>Default value: **Placement.Bottom**|
| onAppear | () =&gt; void | No| Callback triggered when the menu is displayed.|
| onDisappear | () =&gt; void | No| Callback triggered when the menu is hidden.|
## ContextMenuOptions<sup>10+</sup>
| Name | Type | Mandatory| Description |
| ----------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| offset | [Position](ts-types.md#position8) | No | Offset for showing the context menu, which should not cause the menu to extend beyond the screen. |
| placement | [Placement](ts-appendix-enums.md#placement8) | No | Preferred position of the context menu. If the set position is insufficient for holding the component, it will be automatically adjusted.<br>Default value: **Placement.Bottom**|
| onAppear | () =&gt; void | No | Callback triggered when the menu is displayed. |
| onDisappear | () =&gt; void | No | Callback triggered when the menu is hidden. |
## Example
......
......@@ -13,11 +13,56 @@ Shape clipping changes the visible portion of a component through clipping or ma
| Name | Type | Description |
| -----| ------------------------------------------ | ------------------------------------ |
| clip | [Circle](ts-drawing-components-circle.md) \| [Ellipse](ts-drawing-components-ellipse.md) \| [Path](ts-drawing-components-path.md) \| [Rect](ts-drawing-components-rect.md) \| boolean | Clip mode. If the value is a shape, the component is clipped based on the specified shape. If the value is of the Boolean type, it specifies whether to clip the component based on the edge outline of the parent container.<br>Default value: **false**<br>Since API version 9, this API is supported in ArkTS widgets.|
| mask | [Circle](ts-drawing-components-circle.md) \| [Ellipse](ts-drawing-components-ellipse.md) \| [Path](ts-drawing-components-path.md) \| [Rect](ts-drawing-components-rect.md) | Mask of the specified shape to add to the component.<br>Since API version 9, this API is supported in ArkTS widgets.|
| mask | [Circle](ts-drawing-components-circle.md) \| [Ellipse](ts-drawing-components-ellipse.md) \| [Path](ts-drawing-components-path.md) \| [Rect](ts-drawing-components-rect.md)\| [ProgressMask](##progressmask10) | Mask of the specified shape to add to the component.<br>Since API version 9, this API is supported in ArkTS widgets.<br>Since API version 10, this API supports the **ProgressMask** parameter.|
## ProgressMask<sup>10+</sup>
Implements a **ProgressMask** object to set the progress, maximum value, and color of the mask.
### constructor<sup>10+</sup>
constructor(value: number, total: number, color: ResourceColor)
Constructs a **ProgressMask** object.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------------------ | ---- | ------------------ |
| value | number | Yes | Current value of the progress mask.|
| total | number | Yes | Maximum value of the progress mask.|
| color | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the progress mask. |
### updateProgress<sup>10+</sup>
updateProgress(value: number): void
Updates the progress value of the progress mask.
**Parameters**
| Name| Type| Mandatory| Description |
| ------ | -------- | ---- | ------------------ |
| value | number | Yes | Current value of the progress mask.|
### updateColor<sup>10+</sup>
updateColor(value: ResourceColor): void
Updates the color of the progress mask.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------------------ | ---- | ---------------- |
| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the progress mask.|
## Example
### Example 1
```ts
// xxx.ets
@Entry
......@@ -54,3 +99,61 @@ struct ClipAndMaskExample {
```
![clipAndMask](figures/clipAndMask.PNG)
### Example 2
```ts
@Entry
@Component
struct ProgressMask {
@State progressflag1: boolean = true;
@State color: Color = 0x01006CDE;
@State value: number = 10.0;
@State progress: ProgressMask = new ProgressMask(10.0, 100.0, Color.Gray);
build() {
Column({ space: 15 }) {
Text('progress mask').fontSize(12).width('75%').fontColor('#DCDCDC')
// Add a 280px x 280px progress mask to the image.
Image($r('app.media.testImg'))
.width('500px').height('280px')
.mask(this.progress)
.animation({
duration: 2000, // Animation duration.
.curve(Curve.Linear) // Animation curve.
delay: 0, // Animation delay.
iterations: 1, // Number of playback times.
playMode: PlayMode.Normal // Animation playback mode.
}) // Animation configuration for the width and height attributes of the <Button> component.
// Update the progress value of the progress mask.
Button('updateProgress')
.onClick((event: ClickEvent) => {
this.value += 10;
this.progress.updateProgress(this.value);
}).width(200).height(50).margin(20)
// Update the color of the progress mask.
Button('updateColor')
.onClick((event: ClickEvent) => {
if (this.progressflag1) {
this.progress.updateColor(0x9fff0000);
} else {
this.progress.updateColor(0x9f0000ff);
}
this.progressflag1 = !this.progressflag1
}).width(200).height(50).margin(20)
// Restores the progress mask.
Button('click reset!')
.onClick((event: ClickEvent) => {
this.value = 0;
this.progress.updateProgress(this.value);
}).width(200).height(50).margin(20)
}
.width('100%')
.margin({ top: 15 })
}
}
```
![progressMask](figures/progressMask.PNG)
......@@ -10,12 +10,15 @@ Transformation attributes allow you to rotate, translate, scale, or transform a
| Name | Type | Description |
| --------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| rotate | {<br>x?: number,<br>y?: number,<br>z?: number,<br>angle: number \| string,<br>centerX?: number \| string,<br>centerY?: number \| string<br>} | Rotation axis. A positive angle indicates a clockwise rotation, and a negative angle indicates a counterclockwise rotation. The default value is **0**. **centerX** and **centerY** are used to set the rotation center point.<br>Default value:<br>{<br>x: 0,<br>y: 0,<br>z: 0,<br>angle: 0,<br>centerX: '50%',<br>centerY: '50%'<br>}<br>Since API version 9, this API is supported in ArkTS widgets.|
| translate | {<br>x?: number \| string,<br>y?: number \| string,<br>z? : number \| string<br>} | Translation distance along the x-, y-, and z-axis. The translation direction is determined by the positive and negative values. The value cannot be a percentage.<br>Default value:<br>{<br>x: 0,<br>y: 0,<br>z: 0<br>}<br>Since API version 9, this API is supported in ArkTS widgets.|
| --------- | ---------------------------------------- | ---------------------------------------- |
| rotate | {<br>x?: number,<br>y?: number,<br>z?: number,<br>angle: number \| string,<br>centerX?: number \| string,<br>centerY?: number \| string<br>} | How the component rotates in the coordinate system (as shown below) with the upper left corner of the component as the coordinate origin. (x, y, z) specifies a vector as the axis of rotation.<br>- **angle**: rotation angle. A positive angle indicates a clockwise rotation, and a negative angle indicates a counterclockwise rotation. The value can be of the string type, for example, **'90deg'**.<br>- **centerX** and **centerY** are used to set the center of rotation.<br>The axis and center of rotation are set based on the coordinate system, which remains where it is when the component is moved.<br>Default value:<br>{<br>x: 0,<br>y: 0,<br>z: 0,<br>centerX: '50%',<br>centerY: '50%'<br>}<br>![coordinates](figures/coordinates.png)<br>Since API version 9, this API is supported in ArkTS widgets.|
| translate | {<br>x?: number \| string,<br>y?: number \| string,<br>z? : number \| string<br>} | How the component is translated in the coordinate system (as shown below) with the upper left corner of the component as the coordinate origin. Values of **x**, **y**, and **z** indicate the translation distance along the respective axis. A positive value indicates a forward movement towards the respective axis, and a negative value indicates a backward movement towards the respective axis. The translation distance can be a number or a string (for example, **'10px'** or **'10%'**).<br>Default value:<br>{<br>x: 0,<br>y: 0,<br>z: 0<br>}<br>![coordinates](figures/coordinates.png)<br>Since API version 9, this API is supported in ArkTS widgets.|
| scale | {<br>x?: number,<br>y?: number,<br>z?: number,<br>centerX?: number \| string,<br>centerY?: number \| string<br>} | Scale ratio along the x-, y-, and z-axis. The default value is **1**. **centerX** and **centerY** are used to set the scale center point.<br>Default value:<br>{<br>x: 1,<br>y: 1,<br>z: 1,<br>centerX:'50%',<br>centerY:'50%'<br>}<br>Since API version 9, this API is supported in ArkTS widgets.|
| transform | [Matrix4Transit](../apis/js-apis-matrix4.md) | Transformation matrix of the component. |
> **NOTE**
>
> If both the **rotate** and **scale** attributes are set for a component, the values of **centerX** and **centerY** conflict. In this case, the one that is set later in time prevails.
## Example
......
......@@ -151,7 +151,7 @@ For details about the stage model, see [Stage Model Development Overview](../app
}
```
3. If a continuous task needs to be executed in the background for another application or on another device, you can create and run an ability in the background in Call mode. For details, see [Using Ability Call (Intra-Device)](../application-models/uiability-intra-device-interaction.md#using-ability-call-to-implement-uiability-interaction) and [Using Ability Call (Inter-Device)](../application-models/hop-multi-device-collaboration.md#using-cross-device-ability-call).
3. If a continuous task needs to be executed in the background for another application or on another device, you can create and run an ability in the background in Call mode. For details, see [Using Ability Call (Intra-Device)](../application-models/uiability-intra-device-interaction.md#using-call-to-implement-uiability-interaction-for-system-applications-only) and [Using Ability Call (Inter-Device)](../application-models/hop-multi-device-collaboration.md#using-cross-device-call).
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
......
......@@ -640,7 +640,7 @@ The camera driver development procedure is as follows:
### Example
There is a [ohos_camera_demo](https://gitee.com/openharmony/drivers_peripheral/tree/master/camera/hal/init) in the **/drivers/peripheral/camera/hal/init** directory. After the system is started, the executable file **ohos_camera_demo** is generated in the **/vendor/bin** directory. This demo implements basic camera capabilities such as preview and photographing.
There is a [ohos_camera_demo](https://gitee.com/openharmony/drivers_peripheral/tree/master/camera/hal/test/demo) in the **/drivers/peripheral/camera/hal/test/demo** directory. After the system is started, the executable file **ohos_camera_demo** is generated in the **/vendor/bin** directory. This demo implements basic camera capabilities such as preview and photographing.
The following uses the demo to describe how to use the HDI to implement **PreviewOn()** and **CaptureON()**.
......
# Input Method Framework Subsystem – Input Method Framework Service Changelog
## @ohos.InputMethodSubtype Change of name, label, and id
Changed the **name**, **label**, and **id** attributes since API version 9.
**Change Impact**
Applications must be adapted to the following changes.
| Name| Before Change| After Change|
| -------- | -------- | -------- |
| label | (1) Value: ID of the input method subtype.| (1) Value: Label of the input method subtype.|
| name | (1) Description: Name of the input method subtype. (2) Value: Label of the input method subtype.| (1) Description: Bundle name of the input method; (2) Value: Bundle name of the input method.|
| id | (1) Value: Bundle name of the input method.| (1) Value: ID of the input method subtype.|
**Adaptation Guide**
Update the code to adapt to the preceding changes.
# Input Method Framework Subsystem – Input Method Framework Service Changelog
## @ohos.InputMethodSubtype Change of name, label, and id
Changed the **name**, **label**, and **id** attributes since API version 9.
**Change Impact**
Applications must be adapted to the following changes.
| Name| Before Change| After Change|
| -------- | -------- | -------- |
| label | (1) Value: ID of the input method subtype.| (1) Value: Label of the input method subtype.|
| name | (1) Description: Name of the input method subtype. (2) Value: Label of the input method subtype.| (1) Description: Bundle name of the input method; (2) Value: Bundle name of the input method.|
| id | (1) Value: Bundle name of the input method.| (1) Value: ID of the input method subtype.|
**Adaptation Guide**
Update the code to adapt to the preceding changes.
# Using OpenHarmony JS and TS Third-Party Components
## Overview
OpenHarmony JS and TS third-party components are delivered in the form of OpenHarmony npm packages. Developed based on the traditional npm components, OpenHarmony npm shared packages come with specially designed project structures and configuration files. Such a package enables multiple modules or projects to share code related to OpenHarmony UI and resources. You can go to the [official npm website](https://docs.npmjs.com/about-npm) to learn about the basic functions and mechanisms of npm.
## Searching for OpenHarmony JS and TS Third-Party Components
1. Find the [OpenHarmony-TPC/tpc_resource](https://gitee.com/openharmony-tpc/tpc_resource) project on the Gitee website. You can find a component based on the directory index.
2. Visit the [OpenHarmony website](https://www.openharmony.cn/mainPlay/tpc) and search for required third-party components by type, category, or keyword.
## Installing and Using OpenHarmony JS and TS Third-Party Components
During application development, you can import JS and TS third-party components in the form of source code or OpenHarmony npm packages. Perform the following steps to import and use an OpenHarmony npm package. For details about how to import and use the source code, see **README.md** of the corresponding third-party components.
1. Configure the OpenHarmony npm environment. For details, see [Installing the OpenHarmony npm Package](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_npm_usage-en.md).
2. Under **Terminal** project, go to the **entry** directory and run the target component's command to install the component. For details about the command, see "Download and Installation" of the third-party component on the OpenHarmony website.
The following uses the installation of the [vCard component](https://growing.openharmony.cn/mainPlay/libraryMaps/vcard_595) as an example. Find the installation command in "Download and Installation" and then run the command.
![npm-usage1.png](npm-usage1.png)
![npm-usage2.png](npm-usage2.png)
3. Check for the **node_modules** file, which is automatically generated in the project folder. In this example, the downloaded third-party library is **@ohos\VCard** in the **node_modules** directory.
![npm-usage3.png](npm-usage3.png)
4. Check for the dependency configuration, which is automatically added to the **package.json** file:
```
"dependencies": {
"@ohos/vcard": "^2.0.5"
}
```
5. Import the component to the file that plans to use the component.
![npm-usage4.png](npm-usage4.png)
6. Use the APIs as you want.
![npm-usage5.png](npm-usage5.png)
# Using Third-Party JavaScript and TypeScript Components
## Overview
OpenHarmony uses a third-party JavaScript or TypeScript component in the form of a Harmony Archive (HAR), which is a static shared package that can contain JavaScript or TypeScript code, C++ libraries, resources, and configuration files. The HAR enables modules and projects to share code related to ArkUI components, resources, and more. Unlike a Harmony Ability Package (HAP), a HAR cannot be independently installed on a device. Instead, it can be referenced only as the dependency of an application module.
## Searching for a Third-Party JavaScript or TypeScript Component
1. Access the [OpenHarmony-TPC/tpc_resource](https://gitee.com/openharmony-tpc/tpc_resource) repository, and find the desired component based on the directory index.
2. Visit the [OpenHarmony website](https://growing.openharmony.cn/mainPlay/tpc) and search for required third-party components by type, category, or keyword.
## Installing and Using a Third-Party JavaScript or TypeScript Component
You can reference a third-party HAR from the ohpm repository or the local repository module.
**Referencing an HAR Installed in the ohpm Repository**
To reference an HAR in the ohpm repository, set the repository information of the third-party HAR. The default repository address on DevEco Studio is "https://repo.harmonyos.com/ohpm/". To use a custom repository address, ensure that the ohpm installation address on DevEco Studio is configured in **Environment Variables > System Variables > PATH**, and then run the following command in the **Terminal** window of DevEco Studio:
```
ohpm config set registry=your_registry1,your_registry2
```
Note: You can configure multiple repository addresses, separated by commas (,).
Then use either of the following methods to set the third-party HAR as a dependency:
- Method 1: In the **Terminal** window, run the following command to install the third-party HAR. DevEco Studio will automatically add the HAR as a dependency to the **oh-package.json5** file of the project.
```
ohpm install @ohos/lottie
```
- Method 2: Set the third-party HAR as a dependency in the **oh-package.json5** file of the project. The following is a configuration example:
```
"dependencies": { "@ohos/lottie": "^2.0.0"}
```
After the dependency is set, run the **ohpm install** command to install the HAR, which will be stored in the **oh_modules** directory of the project.
```
ohpm install
```
**Referencing Files and Resources of the Local Repository Module**
- Method 1: In the **Terminal** window, run the following command to install the third-party HAR. DevEco Studio will automatically add the HAR as a dependency to the **oh-package5.json** file of the project.
```
ohpm install ../library
```
- Method 2: Set the third-party HAR as a dependency in the **oh-package.json5** file of the project. The following is a configuration example:
```
"dependencies": {
"@ohos/library": "file:../library"
}
```
After the dependency is set, run the **ohpm install** command to install the HAR, which will be stored in the **oh_modules** directory of the project.
```
ohpm install
```
> **NOTE**
>
> Pay attention to the following points when referencing an HAR:
>- Only the dependencies declared in **dependencies** of the **oh-package.json5** file in the module and project are used as OpenHarmony dependencies and processed during compilation and building.
>- The **compileSdkVersion** of the referenced module cannot be earlier than that of the OpenHarmony ohpm third-party package on which the referenced module depends. You can view the version in the **src** > **main** > **module.json5** file of the referenced ohpm package in the **oh_modules** directory.
### Referencing an HAR HML Page
In a JavaScript project paradigm, component functions are configured in HML files. To reference an HML page in an HAR, first import the page through the **<element>** tag in the HML file of the project. The sample code is as follows:
```
<element name="comp" src="@ohos/library/src/main/js/components/index/index.hml"></element>
```
In the preceding example, **@ohos/library** indicates the name of the HAR, and the path of the HML page is the relative path in the HAR.
You can then reference the HML page based on the set element name. The sample code is as follows:
```typescript
<element name="comp" src="@ohos/library/src/main/js/components/index/index.hml"></element>
<div class="container">
<comp></comp>
<text class="title">
{{ $t('strings.hello') }} {{ title }}
</text>
</div>
```
### Referencing an HAR ArkTS Page
ArkTS is an extension of TypeScript. Therefore, the export and import syntax of ArkTS is the same as that of TypeScript. In the OpenHarmony ohpm module, use **export** to export an ArkTS page. The sample code is as follows:
```typescript
// library/src/main/ets/components/MainPage/MainPage.ets
@Entry
@Component
export struct MainPage {
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
} .height('100%')
}
}
```
Import the exported ArkTS page in other modules. The following is an example:
```typescript
// entry/MainAbility/pages/index.ets
import { MainPage } from "@ohos/library"
@Entry
@Component
struct Index {
@State message: string = 'Hello World'
build() {
Column() {
MainPage()
Row() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('10%')
}
}
```
The procedure for referencing JavaScript/TypeScript methods in the HAR is the same as that for referencing ArkTS pages. In the OpenHarmony ohpm module, export the methods through **export**. The sample code is as follows:
```typescript
// library/index.js
export function func() {
return "[ohpm] func1";
}
```
On other JavaScript/TypeScript pages, use **import** to import the exported methods. The sample code is as follows:
```typescript
// entry/src/main/js/MainAbility/pages/index/index.js
import {func} from "@ohos/library"
export default {
data: {
title: ""
},
onInit() {
this.title = func();
}
}
```
Resources in an OpenHarmony ohpm module can be referenced in another OpenHarmony ohpm module and modules that depend on the OpenHarmony ohpm module. For example, you can add string resources (defined in **string.json**, **name: hello_ohpm** in this example) and image resources (**icon_ohpm.png** in this example) to **scr/main/resources** of the OpenHarmony ohpm module, and then reference the string and image resources in the entry module, as shown below:
Currently, referencing resources in **i18n** files is not supported for the JavaScript-based web-like development paradigm.
```typescript
// entry/src/main/ets/MainAbility/pages/index.ets
@Entry
@Component
struct Index {
@State message: string = 'Hello World'
build() {
Column() {
Row() {
Text($r("app.string.hello_ohpm")) // String resource.
.fontSize(40)
.fontWeight(FontWeight.Bold)
}
.width('50%')
Image($r("app.media.icon_ohpm")) // Image resource.
}
.height('100%')
}
}
```
During compilation and building of a HAP, DevEco Studio collects resource files from the HAP module and its dependent modules. If the resource files of different modules in the same qualifiers directory have the same name, DevEco Studio overwrites the resource files based on the following priorities (in descending order):
- AppScope (supported only by the stage model of API version 9)
- Modules in the HAP file
- Dependent OpenHarmony ohpm modules
# OpenHarmony Third-Party Components
OpenHarmony third-party components are verified software that work with the OpenHarmony system to facilitate your development of OpenHarmony devices or applications. Depending on the programming language they use, these components are classified as JS and TS third-party components or C and C++ third-party components. JS and TS third-party components the JavaScript or TypeScript programming languages and are usually imported as source code or OpenHarmony npm packages. They are used in application development. C and C++ third-party components use the C and C++ programming languages and are usually imported as source code or OpenHarmony hpm packages. They are used as native APIs during application development or directly compiled in the OpenHarmony OS image during device development.
OpenHarmony third-party components are verified software that work with the OpenHarmony system to facilitate your development of OpenHarmony devices or applications. Depending on the programming language they use, these components are classified as third-party JavaScript and TypeScript components or third-party C and C++ components. The third-party JavaScript and TypeScript components use the JavaScript or TypeScript programming language and are usually imported as source code or OpenHarmony HAR files. They are used in application development. The third-party C and C++ components use the C and C++ programming language and are usually imported as source code or OpenHarmony hpm packages. They are used as native APIs during application development or directly compiled in the OpenHarmony OS image during device development.
Currently, OpenHarmony provides UI, animation, image, multimedia, file, network, security, tool, and other third-party components.
......@@ -32,7 +32,7 @@
- **Module支持的设备类型配置**
Module支持的设备类型需要在config.json文件中配置deviceType字段,如果deviceType标签中添加了某种设备,则表明当前的module支持在设备上运行。具体的deviceType配置规则可以参考[deviceType标签说明](../quick-start/module-structure.md)
Module支持的设备类型需要在config.json文件中配置deviceType字段,如果deviceType标签中添加了某种设备,则表明当前的module支持在设备上运行。具体的deviceType配置规则可以参考[deviceType标签说明](../quick-start/module-structure.md)
- **组件权限申请配置**
......
......@@ -36,14 +36,4 @@
## 跨设备同步访问控制机制
数据跨设备同步时,数据管理基于设备等级和[数据安全标签](access-control-by-device-and-data-level.md#数据安全标签)进行访问控制。规则为,数据只允许向数据安全标签不高于设备安全等级的设备同步数据,具体访问控制矩阵如下:
|设备安全级别|可同步的数据安全标签|
|---|---|
|SL1|S1|
|SL2|S1~S2|
|SL3|S1~S3|
|SL4|S1~S4|
|SL5|S1~S4|
例如,对于类似rk3568、hi3516的开发板设备,设备安全等级为SL1,若创建数据安全标签为S1的数据库,则此数据库数据可以在这些设备间同步;若创建的数据库标签为S2-S4,则不能同步。
数据跨设备同步时,数据管理基于设备等级和数据安全标签进行访问控制,具体可见[跨设备同步访问控制机制](access-control-by-device-and-data-level.md#跨设备同步访问控制机制)
......@@ -23,7 +23,7 @@
- [自定义组件](arkts-create-custom-components.md):可复用的UI单元,可组合其他组件,如上述被\@Component装饰的struct Hello。
- 系统组件:ArkUI框架中默认内置的基础和容器组件,可直接被开发者调用,比如示例中的Column 、 Text 、 Divider 、 Button。
- 系统组件:ArkUI框架中默认内置的基础和容器组件,可直接被开发者调用,比如示例中的Column、Text、Divider、Button。
- 属性方法:组件可以通过链式调用配置多项属性,如fontSize()、width()、height()、color()等。
......
# 通知服务公共事件定义
通知服务面向应用发布如下系统公共事件,应用如需订阅系统公共事件,请参考公共事件[接口文档](../js-apis-commonEventManager.md)
## COMMON_EVENT_SLOT_CHANGE
表示通知渠道或通知开关发生变化。
- 常量值:"usual.event.SLOT_CHANGE"
- 订阅方需要的权限:ohos.permission.NOTIFICATION_CONTROLLER
通知设置里修改应用的渠道参数、渠道开关,或者开启、关闭通知使能开关时,都会触发通知服务发布这个系统公共事件。
与这个公共事件相关的接口:setSlotByBundle、setNotificationEnableSlot、setNotificationEnable,这些为系统API,一般都是通知设置应用调用,具体参看[通知接口文档](../js-apis-notificationManager.md)
......@@ -24,9 +24,9 @@ import Want from '@ohos.application.Want';
| uri | string | 否 | 表示Uri描述。如果在Want中指定了Uri,则Want将匹配指定的Uri信息,包括scheme, schemeSpecificPart, authority和path信息。 |
| type | string | 否 | 表示MIME type类型描述,打开文件的类型,主要用于文管打开文件。比如:'text/xml' 、 'image/*'等,MIME定义参考:https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com。 |
| flags | number | 否 | 表示处理Want的方式。默认传数字,具体参考:[flags说明](js-apis-ability-wantConstant.md#wantconstantflags)。 |
| action | string | 否 | 表示要执行的通用操作(如:查看、分享、应用详情)。在隐式Want中,您可以定义该字段,配合uri或parameters来表示对数据要执行的操作。具体参考:[action说明](js-apis-app-ability-wantConstant.md#wantConstant.Action)。隐式Want定义及匹配规则参考:[显式Want与隐式Want匹配规则](../../application-models/explicit-implicit-want-mappings.md)。 |
| action | string | 否 | 表示要执行的通用操作(如:查看、分享、应用详情)。在隐式Want中,您可以定义该字段,配合uri或parameters来表示对数据要执行的操作。具体参考:[action说明](js-apis-ability-wantConstant.md#wantconstantaction)。隐式Want定义及匹配规则参考:[显式Want与隐式Want匹配规则](../../application-models/explicit-implicit-want-mappings.md)。 |
| parameters | {[key: string]: any} | 否 | 表示WantParams描述,由开发者自行决定传入的键值对。默认会携带以下key值:<br>ohos.aafwk.callerPid 表示拉起方的pid。<br>ohos.aafwk.param.callerToken 表示拉起方的token。<br>ohos.aafwk.param.callerUid 表示[bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo)中的uid,应用包里应用程序的uid。<br />- component.startup.newRules:表示是否启用新的管控规则。<br />- moduleName:表示拉起方的模块名,该字段的值即使定义成其他字符串,在传递到另一端时会被修改为正确的值。<br />- ohos.dlp.params.sandbox:表示dlp文件才会有。 |
| entities | Array\<string> | 否 | 表示目标Ability额外的类别信息(如:浏览器、视频播放器)。在隐式Want中是对action字段的补充。在隐式Want中,您可以定义该字段,来过滤匹配Ability类型。具体参考:[entity说明](js-apis-app-ability-wantConstant.md#wantConstant.Entity)。 |
| entities | Array\<string> | 否 | 表示目标Ability额外的类别信息(如:浏览器、视频播放器)。在隐式Want中是对action字段的补充。在隐式Want中,您可以定义该字段,来过滤匹配Ability类型。具体参考:[entity说明](js-apis-ability-wantConstant.md#wantconstantentity)。 |
**示例:**
......
......@@ -116,7 +116,7 @@ onBundleBegin : AsyncCallback&lt;string&gt;
```js
onBundleBegin: (err, bundleName) => {
if (err) {
console.error('onBundleBegin failed with err: ' + err);]
console.error('onBundleBegin failed with err: ' + err);
}
console.info('onBundleBegin success with bundleName: ' + bundleName);
}
......@@ -227,24 +227,6 @@ getLocalCapabilities(callback: AsyncCallback&lt;FileData&gt;): void
| 13900025 | No space left on device |
| 13900042 | Unknown error |
**json configuration example**
```json
{
"bundleInfos" :[{
"allToBackup" : true,
"extensionName" : "BackupExtensionAbility",
"name" : "com.example.hiworld",
"needToInstall" : false,
"spaceOccupied" : 0,
"versionCode" : 1000000,
"versionName" : "1.0.0"
}],
"deviceType" : "phone",
"systemFullName" : "OpenHarmony-4.0.0.0"
}
```
**示例:**
```js
......@@ -262,7 +244,26 @@ getLocalCapabilities(callback: AsyncCallback&lt;FileData&gt;): void
}
```
## backup.getLocalCapabilities
**返回的能力文件内容示例:**
```json
{
"bundleInfos" :[{
"allToBackup" : true,
"extensionName" : "BackupExtensionAbility",
"name" : "com.example.hiworld",
"needToInstall" : false,
"spaceOccupied" : 0,
"versionCode" : 1000000,
"versionName" : "1.0.0"
}],
"deviceType" : "phone",
"systemFullName" : "OpenHarmony-4.0.0.0"
}
```
## getLocalCapabilities
getLocalCapabilities(): Promise&lt;FileData&gt;
......@@ -289,7 +290,20 @@ getLocalCapabilities(): Promise&lt;FileData&gt;
| 13900025 | No space left on device |
| 13900042 | Unknown error |
**json configuration example**
**示例:**
```js
import fs from '@ohos.file.fs';
try {
let fileData = await backup.getLocalCapabilities();
console.info('getLocalCapabilities success');
fs.closeSync(fileData.fd);
} catch (err) {
console.error('getLocalCapabilities failed with err: ' + err);
}
```
**返回的能力文件内容示例:**
```json
{
......@@ -307,19 +321,6 @@ getLocalCapabilities(): Promise&lt;FileData&gt;
}
```
**示例:**
```js
try {
import fs from '@ohos.file.fs';
let fileData = await backup.getLocalCapabilities();
console.info('getLocalCapabilities success');
fs.closeSync(fileData.fd);
} catch (err) {
console.error('getLocalCapabilities failed with err: ' + err);
}
```
## SessionBackup
备份流程对象,用来支撑应用备份的流程。在使用前,需要先创建SessionBackup实例。
......
......@@ -15,7 +15,7 @@ import measure from '@ohos.measure'
## measure.measureText
measureText(options: MeasureOptions): double
measureText(options: MeasureOptions): number
计算指定文本单行布局下的宽度。
......
......@@ -2513,7 +2513,7 @@ off(type: 'imsRegStateChange', slotId: number, imsType: ImsServiceType, callback
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------ | ---- | -------------------------------------- |
| type | string | 是 | 通话结束时取消监听通话详情的变化。 |
| type | string | 是 | 取消监听IMS注册状态的变化。 |
| slotId | number | 是 | 卡槽ID。<br/>- 0:卡槽1<br/>- 1:卡槽2 |
| imsType | [ImsServiceType](#imsservicetype9) | 是 | IMS服务类型。 |
| callback | Callback<[ImsRegInfo](#imsreginfo9)> | 否 | 回调函数。 |
......
......@@ -744,7 +744,7 @@ try {
| id | number | 是 | 否 | 屏幕的id。 |
| parent | number | 是 | 否 | 屏幕所属群组的id。 |
| supportedModeInfo | Array&lt;[ScreenModeInfo](#screenmodeinfo)&gt; | 是 | 否 | 屏幕支持的模式集合。 |
| activeModeIndex | number | 是 | 否 | 当前屏幕所处模式索引。 |
| activeModeIndex | number | 是 | 否 | 当前屏幕所处模式索引。模式索引的当前值和值的范围,会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。 |
| orientation | [Orientation](#orientation) | 是 | 否 | 屏幕方向。 |
| sourceMode<sup>10+</sup> | [ScreenSourceMode](#screensourcemode10) | 是 | 否 | 屏幕来源模式。 |
......@@ -836,7 +836,7 @@ setScreenActiveMode(modeIndex: number, callback: AsyncCallback&lt;void&gt;): voi
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------------------------- | ---- | ------------------------------------------------------------ |
| modeIndex | number | 是 | 模式索引。 |
| modeIndex | number | 是 | 模式索引。模式索引的当前值和值的范围,会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当设置屏幕当前显示模式成功,err为undefined,否则为错误对象。 |
**错误码:**
......@@ -874,7 +874,7 @@ setScreenActiveMode(modeIndex: number): Promise&lt;void&gt;
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ---------- |
| modeIndex | number | 是 | 模式索引。 |
| modeIndex | number | 是 | 模式索引。模式索引的当前值和值的范围,会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。 |
**返回值:**
......
......@@ -31,7 +31,7 @@ on(type: SensorId.ACCELEROMETER, callback: Callback&lt;AccelerometerResponse&gt;
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- |
| type | [SensorId](#sensorid9).ACCELEROMETER | 是 | 传感器类型,该值固定为SensorId.ACCELEROMETER。 |
| callback | Callback&lt;[AccelerometerResponse](#accelerometerresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为AccelerometerResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -71,7 +71,7 @@ on(type: SensorId.ACCELEROMETER_UNCALIBRATED, callback: Callback&lt;Acceleromete
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).ACCELEROMETER_UNCALIBRATED | 是 | 传感器类型,该值固定为SensorId.ACCELEROMETER_UNCALIBRATED。 |
| callback | Callback&lt;[AccelerometerUncalibratedResponse](#accelerometeruncalibratedresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为AccelerometerUncalibratedResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -112,7 +112,7 @@ on(type: SensorId.AMBIENT_LIGHT, callback: Callback&lt;LightResponse&gt;, option
| -------- | ----------------------------------------------- | ---- | --------------------------------------------------- |
| type | [SensorId](#sensorid9).AMBIENT_LIGHT | 是 | 传感器类型,该值固定为SensorId.AMBIENT_LIGHT。 |
| callback | Callback&lt;[LightResponse](#lightresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为LightResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -148,7 +148,7 @@ on(type: SensorId.AMBIENT_TEMPERATURE, callback: Callback&lt;AmbientTemperatureR
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).AMBIENT_TEMPERATURE | 是 | 传感器类型,该值固定为SensorId.AMBIENT_TEMPERATURE。 |
| callback | Callback&lt;[AmbientTemperatureResponse](#ambienttemperatureresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为AmbientTemperatureResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -184,7 +184,7 @@ on(type: SensorId.BAROMETER, callback: Callback&lt;BarometerResponse&gt;, option
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------- |
| type | [SensorId](#sensorid9).BAROMETER | 是 | 传感器类型,该值固定为SensorId.BAROMETER。 |
| callback | Callback&lt;[BarometerResponse](#barometerresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为BarometerResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -220,7 +220,7 @@ on(type: SensorId.GRAVITY, callback: Callback&lt;GravityResponse&gt;,options?: O
| -------- | --------------------------------------------------- | ---- | ----------------------------------------------------- |
| type | [SensorId](#sensorid9).GRAVITY | 是 | 传感器类型,该值固定为SensorId.GRAVITY。 |
| callback | Callback&lt;[GravityResponse](#gravityresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为GravityResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -260,7 +260,7 @@ on(type: SensorId.GYROSCOPE, callback: Callback&lt;GyroscopeResponse&gt;,options
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------- |
| type | [SensorId](#sensorid9).GYROSCOPE | 是 | 传感器类型,该值固定为SensorId.GYROSCOPE。 |
| callback | Callback&lt;[GyroscopeResponse](#gyroscoperesponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为GyroscopeResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -301,7 +301,7 @@ on(type: SensorId.GYROSCOPE_UNCALIBRATED, callback: Callback&lt;GyroscopeUncalib
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).GYROSCOPE_UNCALIBRATED | 是 | 传感器类型,该值固定为SensorId.GYROSCOPE_UNCALIBRATED。 |
| callback | Callback&lt;[GyroscopeUncalibratedResponse](#gyroscopeuncalibratedresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为GyroscopeUncalibratedResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -342,7 +342,7 @@ on(type: SensorId.HALL, callback: Callback&lt;HallResponse&gt;, options?: Option
| -------- | --------------------------------------------- | ---- | -------------------------------------------------- |
| type | [SensorId](#sensorid9).HALL | 是 | 传感器类型,该值固定为SensorId.HALL。 |
| callback | Callback&lt;[HallResponse](#hallresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为HallResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -380,7 +380,7 @@ on(type: SensorId.HEART_RATE, callback: Callback&lt;HeartRateResponse&gt;,option
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------- |
| type | [SensorId](#sensorid9).HEART_RATE | 是 | 传感器类型,该值固定为SensorId.HEART_RATE。 |
| callback | Callback&lt;[HeartRateResponse](#heartrateresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为HeartRateResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -416,7 +416,7 @@ on(type: SensorId.HUMIDITY, callback: Callback&lt;HumidityResponse&gt;,options?:
| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------ |
| type | [SensorId](#sensorid9).HUMIDITY | 是 | 传感器类型,该值固定为SensorId.HUMIDITY。 |
| callback | Callback&lt;[HumidityResponse](#humidityresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为HumidityResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -455,7 +455,7 @@ on(type: SensorId.LINEAR_ACCELEROMETER, callback: Callback&lt;LinearAcceleromete
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).LINEAR_ACCELEROMETER | 是 | 传感器类型,该值固定为SensorId.LINEAR_ACCELEROMETER。 |
| callback | Callback&lt;[LinearAccelerometerResponse](#linearaccelerometerresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为LinearAccelerometerResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -493,7 +493,7 @@ on(type: SensorId.MAGNETIC_FIELD, callback: Callback&lt;MagneticFieldResponse&gt
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- |
| type | [SensorId](#sensorid9).MAGNETIC_FIELD | 是 | 传感器类型,该值固定为SensorId.MAGNETIC_FIELD。 |
| callback | Callback&lt;[MagneticFieldResponse](#magneticfieldresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为MagneticFieldResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -531,7 +531,7 @@ on(type: SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback: Callback&lt;MagneticFie
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).MAGNETIC_FIELD_UNCALIBRATED | 是 | 传感器类型,该值固定为SensorId.MAGNETIC_FIELD_UNCALIBRATED。 |
| callback | Callback&lt;[MagneticFieldUncalibratedResponse](#magneticfielduncalibratedresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为MagneticFieldUncalibratedResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -580,7 +580,7 @@ on(type: SensorId.ORIENTATION, callback: Callback&lt;OrientationResponse&gt;,opt
| -------- | ----------------------------------------------------------- | ---- | --------------------------------------------------------- |
| type | [SensorId](#sensorid9).ORIENTATION | 是 | 传感器类型,该值固定为SensorId.ORIENTATION。 |
| callback | Callback&lt;[OrientationResponse](#orientationresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为OrientationResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -620,7 +620,7 @@ on(type: SensorId.PEDOMETER, callback: Callback&lt;PedometerResponse&gt;, option
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------- |
| type | [SensorId](#sensorid9).PEDOMETER | 是 | 传感器类型,该值固定为SensorId.PEDOMETER。 |
| callback | Callback&lt;[PedometerResponse](#pedometerresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为PedometerResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -651,7 +651,7 @@ on(type: SensorId.PEDOMETER_DETECTION, callback: Callback&lt;PedometerDetectionR
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).PEDOMETER_DETECTION | 是 | 传感器类型,该值固定为SensorId.PEDOMETER_DETECTION。 |
| callback | Callback&lt;[PedometerDetectionResponse](#pedometerdetectionresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为PedometerDetectionResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -687,7 +687,7 @@ on(type: SensorId.PROXIMITY, callback: Callback&lt;ProximityResponse&gt;, option
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------- |
| type | [SensorId](#sensorid9).PROXIMITY | 是 | 传感器类型,该值固定为SensorId.PROXIMITY。 |
| callback | Callback&lt;[ProximityResponse](#proximityresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为ProximityResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -724,7 +724,7 @@ on(type: SensorId.ROTATION_VECTOR, callback: Callback&lt;RotationVectorResponse&
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).ROTATION_VECTOR | 是 | 传感器类型,该值固定为SensorId.ROTATION_VECTOR。 |
| callback | Callback&lt;[RotationVectorResponse](#rotationvectorresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为RotationVectorResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -764,7 +764,7 @@ on(type: SensorId.SIGNIFICANT_MOTION, callback: Callback&lt;SignificantMotionRes
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorId](#sensorid9).SIGNIFICANT_MOTION | 是 | 传感器类型,该值固定为SensorId.SIGNIFICANT_MOTION。 |
| callback | Callback&lt;[SignificantMotionResponse](#significantmotionresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为SignificantMotionResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -801,7 +801,7 @@ on(type: SensorId.WEAR_DETECTION, callback: Callback&lt;WearDetectionResponse&gt
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- |
| type | [SensorId](#sensorid9).WEAR_DETECTION | 是 | 传感器类型,该值固定为SensorId.WEAR_DETECTION。 |
| callback | Callback&lt;[WearDetectionResponse](#weardetectionresponse)&gt; | 是 | 回调函数,异步上报的传感器数据固定为WearDetectionResponse。 |
| options | [Options](#options) | 否 | 设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
**错误码**
......@@ -3851,7 +3851,7 @@ on(type: SensorType.SENSOR_TYPE_ID_ACCELEROMETER, callback: Callback&lt;Acceler
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_ACCELEROMETER | 是 | 要订阅的加速度传感器类型为SENSOR_TYPE_ID_ACCELEROMETER。 |
| callback | Callback&lt;[AccelerometerResponse](#accelerometerresponse)&gt; | 是 | 注册加速度传感器的回调函数,上报的数据类型为AccelerometerResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -3883,7 +3883,7 @@ on(type: SensorType.SENSOR_TYPE_ID_LINEAR_ACCELERATION,callback:Callback&lt;Line
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_LINEAR_ACCELERATION | 是 | 要订阅的线性加速度传感器类型为SENSOR_TYPE_ID_LINEAR_ACCELERATION。 |
| callback | Callback&lt;[LinearAccelerometerResponse](#linearaccelerometerresponse)&gt; | 是 | 注册线性加速度传感器的回调函数,上报的数据类型为LinearAccelerometerResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
### ACCELEROMETER_UNCALIBRATED<sup>(deprecated)</sup>
......@@ -3903,7 +3903,7 @@ on(type: SensorType.SENSOR_TYPE_ID_ACCELEROMETER_UNCALIBRATED,callback: Callback
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_ACCELEROMETER_UNCALIBRATED | 是 | 要订阅的未校准加速度计传感器类型为SENSOR_TYPE_ID_ACCELEROMETER_UNCALIBRATED。 |
| callback | Callback&lt;[AccelerometerUncalibratedResponse](#accelerometeruncalibratedresponse)&gt; | 是 | 注册未校准加速度计传感器的回调函数,上报的数据类型为AccelerometerUncalibratedResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -3935,9 +3935,10 @@ on(type: SensorType.SENSOR_TYPE_ID_GRAVITY, callback: Callback&lt;GravityRespons
| -------- | --------------------------------------------------- | ---- | ----------------------------------------------------------- |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_GRAVITY | 是 | 要订阅的重力传感器类型为SENSOR_TYPE_ID_GRAVITY。 |
| callback | Callback&lt;[GravityResponse](#gravityresponse)&gt; | 是 | 注册重力传感器的回调函数,上报的数据类型为GravityResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
sensor.on(sensor.SensorType.SENSOR_TYPE_ID_GRAVITY,function(data){
console.info('X-coordinate component: ' + data.x);
......@@ -3966,7 +3967,7 @@ on(type: SensorType.SENSOR_TYPE_ID_GYROSCOPE, callback: Callback&lt;GyroscopeRes
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_GYROSCOPE | 是 | 要订阅的陀螺仪传感器类型为SENSOR_TYPE_ID_GYROSCOPE。 |
| callback | Callback&lt;[GyroscopeResponse](#gyroscoperesponse)&gt; | 是 | 注册陀螺仪传感器的回调函数,上报的数据类型为GyroscopeResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -3997,7 +3998,7 @@ on(type: SensorType.SENSOR_TYPE_ID_GYROSCOPE_UNCALIBRATED,callback:Callback&lt;G
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_GYROSCOPE_UNCALIBRATED | 是 | 要订阅的未校准陀螺仪传感器类型为SENSOR_TYPE_ID_GYROSCOPE_UNCALIBRATED。 |
| callback | Callback&lt;[GyroscopeUncalibratedResponse](#gyroscopeuncalibratedresponse)&gt; | 是 | 注册未校准陀螺仪传感器的回调函数,上报的数据类型为GyroscopeUncalibratedResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4029,7 +4030,7 @@ on(type: SensorType.SENSOR_TYPE_ID_SIGNIFICANT_MOTION, callback: Callback&lt;Sig
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_SIGNIFICANT_MOTION | 是 | 要订阅的大幅动作传感器类型为SENSOR_TYPE_ID_SIGNIFICANT_MOTION。 |
| callback | Callback&lt;[SignificantMotionResponse](#significantmotionresponse)&gt; | 是 | 注册有效运动传感器的回调函数,上报的数据类型为SignificantMotionResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4058,7 +4059,7 @@ on(type: SensorType.SENSOR_TYPE_ID_PEDOMETER_DETECTION, callback: Callback&lt;Pe
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_PEDOMETER_DETECTION | 是 | 要订阅的计步检测传感器类型为SENSOR_TYPE_ID_PEDOMETER_DETECTION。 |
| callback | Callback&lt;[PedometerDetectionResponse](#pedometerdetectionresponse)&gt; | 是 | 注册计步检测传感器的回调函数,上报的数据类型为PedometerDetectionResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4087,7 +4088,7 @@ on(type: SensorType.SENSOR_TYPE_ID_PEDOMETER, callback: Callback&lt;PedometerRes
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_PEDOMETER | 是 | 要订阅的计步传感器类型为SENSOR_TYPE_ID_PEDOMETER。 |
| callback | Callback&lt;[PedometerResponse](#pedometerresponse)&gt; | 是 | 注册计步传感器的回调函数,上报的数据类型为PedometerResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4114,7 +4115,7 @@ on(type: SensorType.SENSOR_TYPE_ID_AMBIENT_TEMPERATURE,callback:Callback&lt;Ambi
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_AMBIENT_TEMPERATURE | 是 | 要订阅的环境温度传感器类型为SENSOR_TYPE_ID_AMBIENT_TEMPERATURE。 |
| callback | Callback&lt;[AmbientTemperatureResponse](#ambienttemperatureresponse)&gt; | 是 | 注册环境温度传感器的回调函数,上报的数据类型为AmbientTemperatureResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -4142,7 +4143,7 @@ on(type: SensorType.SENSOR_TYPE_ID_MAGNETIC_FIELD, callback: Callback&lt;Magneti
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_MAGNETIC_FIELD | 是 | 要订阅的磁场传感器类型为SENSOR_TYPE_ID_MAGNETIC_FIELD。 |
| callback | Callback&lt;[MagneticFieldResponse](#magneticfieldresponse)&gt; | 是 | 注册磁场传感器的回调函数,上报的数据类型为MagneticFieldResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -4172,7 +4173,7 @@ on(type: SensorType.SENSOR_TYPE_ID_MAGNETIC_FIELD_UNCALIBRATED,callback: Callbac
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_MAGNETIC_FIELD_UNCALIBRATED | 是 | 要订阅的未校准磁场传感器类型为SENSOR_TYPE_ID_MAGNETIC_FIELD_UNCALIBRATED。 |
| callback | Callback&lt;[MagneticFieldUncalibratedResponse](#magneticfielduncalibratedresponse)&gt; | 是 | 注册未校准磁场传感器的回调函数,上报的数据类型为MagneticFieldUncalibratedResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4204,7 +4205,7 @@ on(type: SensorType.SENSOR_TYPE_ID_PROXIMITY, callback: Callback&lt;ProximityRes
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_PROXIMITY | 是 | 要订阅的接近光传感器类型为SENSOR_TYPE_ID_PROXIMITY。 |
| callback | Callback&lt;[ProximityResponse](#proximityresponse)&gt; | 是 | 注册接近光传感器的回调函数,上报的数据类型为ProximityResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4231,7 +4232,7 @@ on(type: SensorType.SENSOR_TYPE_ID_HUMIDITY, callback: Callback&lt;HumidityRespo
| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_HUMIDITY | 是 | 要订阅的湿度传感器类型为SENSOR_TYPE_ID_HUMIDITY。 |
| callback | Callback&lt;[HumidityResponse](#humidityresponse)&gt; | 是 | 注册湿度传感器的回调函数,上报的数据类型为HumidityResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -4259,7 +4260,7 @@ on(type: SensorType.SENSOR_TYPE_ID_BAROMETER, callback: Callback&lt;BarometerRes
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_BAROMETER | 是 | 要订阅的气压计传感器类型为SENSOR_TYPE_ID_BAROMETER。 |
| callback | Callback&lt;[BarometerResponse](#barometerresponse)&gt; | 是 | 注册气压计传感器的回调函数,上报的数据类型为BarometerResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -4287,7 +4288,7 @@ on(type: SensorType.SENSOR_TYPE_ID_HALL, callback: Callback&lt;HallResponse&gt;,
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_HALL | 是 | 要订阅的霍尔传感器类型为SENSOR_TYPE_ID_HALL。 |
| callback | Callback&lt;[HallResponse](#hallresponse)&gt; | 是 | 注册霍尔传感器的回调函数,上报的数据类型为&nbsp;HallResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4314,7 +4315,7 @@ on(type: SensorType.SENSOR_TYPE_ID_AMBIENT_LIGHT, callback: Callback&lt;LightRes
| -------- | ------------------------------------------------------ | ---- | ----------------------------------------------------------- |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_AMBIENT_LIGHT | 是 | 要订阅的环境光传感器类型为SENSOR_TYPE_ID_AMBIENT_LIGHT。 |
| callback | Callback&lt;[LightResponse](#lightresponse)&gt; | 是 | 注册环境光传感器的回调函数,上报的数据类型为LightResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
......@@ -4342,7 +4343,7 @@ on(type: SensorType.SENSOR_TYPE_ID_ORIENTATION, callback: Callback&lt;Orientatio
| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_ORIENTATION | 是 | 要订阅的方向传感器类型为SENSOR_TYPE_ID_ORIENTATION |
| callback | Callback&lt;[OrientationResponse](#orientationresponse)&gt; | 是 | 注册方向传感器的回调函数,上报的数据类型为OrientationResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4390,7 +4391,7 @@ on(type: SensorType.SENSOR_TYPE_ID_ROTATION_VECTOR,callback: Callback&lt;Rotatio
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_ROTATION_VECTOR | 是 | 要订阅的旋转矢量传感器类型为SENSOR_TYPE_ID_ROTATION_VECTOR。 |
| callback | Callback&lt;[RotationVectorResponse](#rotationvectorresponse)&gt; | 是 | 注册旋转矢量传感器的回调函数,上报的数据类型为RotationVectorResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......@@ -4420,7 +4421,7 @@ on(type: SensorType.SENSOR_TYPE_ID_WEAR_DETECTION, callback: Callback&lt;WearDet
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | [SensorType](#sensortype).SENSOR_TYPE_ID_WEAR_DETECTION | 是 | 要订阅的佩戴检测传感器类型为SENSOR_TYPE_ID_WEAR_DETECTION。 |
| callback | Callback&lt;[WearDetectionResponse](#weardetectionresponse)&gt; | 是 | 注册佩戴检测传感器的回调函数,上报的数据类型为WearDetectionResponse。 |
| options | [Options](#options) | 否 | 可选参数列表,设置上报频率,默认值为200000000ns。 |
| options | [Options](#options) | 否 | 可选参数列表列表,设置上报频率,默认值为200000000ns。 |
**示例:**
```js
......
......@@ -2050,7 +2050,9 @@ try {
setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback&lt;void&gt;): void
设置窗口的布局是否为全屏显示状态,使用callback异步回调。
设置窗口的布局是否为沉浸式布局,使用callback异步回调。
沉浸式布局是指布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。
非沉浸式布局是指布局避让状态栏与导航栏,组件不会与其重叠。
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
......@@ -2058,7 +2060,7 @@ setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback&l
| 参数名 | 类型 | 必填 | 说明 |
| ------------------ | ------------------------- | -- | --------- |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为全屏显示状态(该全屏状态下状态栏、导航栏仍然显示)。true表示全屏显示;false表示非全屏显示。 |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局(该沉浸式布局状态栏、导航栏仍然显示)。true表示沉浸式布局;false表示非沉浸式布局。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 |
**错误码:**
......@@ -2091,7 +2093,9 @@ try {
setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise&lt;void&gt;
设置窗口的布局是否为全屏显示状态,使用Promise异步回调。
设置窗口的布局是否为沉浸式布局,使用Promise异步回调。
沉浸式布局是指布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。
非沉浸式布局是指布局避让状态栏与导航栏,组件不会与其重叠。
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
......@@ -2099,7 +2103,7 @@ setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise&lt;void&gt;
| 参数名 | 类型 | 必填 | 说明 |
| ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为全屏显示状态(该全屏状态下状态栏、导航栏仍然显示)。true表示全屏显示;false表示非全屏显示。 |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局(该沉浸式布局状态栏、导航栏仍然显示)。true表示沉浸式布局;false表示非沉浸式布局。 |
**返回值:**
......@@ -5381,7 +5385,7 @@ setFullScreen(isFullScreen: boolean, callback: AsyncCallback&lt;void&gt;): void
| 参数名 | 类型 | 必填 | 说明 |
| ------------ | ------------------------- | ---- | ---------------------------------------------- |
| isFullScreen | boolean | 是 | 是否设为全屏状态(该全屏状态隐藏状态栏导航栏)。true表示全屏;false表示非全屏。 |
| isFullScreen | boolean | 是 | 是否设为全屏状态(该全屏状态隐藏状态栏导航栏。true表示全屏;false表示非全屏。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 |
**示例:**
......@@ -5437,7 +5441,9 @@ promise.then(()=> {
setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback&lt;void&gt;): void
设置窗口的布局是否为全屏显示状态,使用callback异步回调。
设置窗口的布局是否为沉浸式布局,使用callback异步回调。
沉浸式布局是指布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。
非沉浸式布局是指布局避让状态栏与导航栏,组件不会与其重叠。
> **说明:**
>
......@@ -5449,7 +5455,7 @@ setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback&lt;void
| 参数名 | 类型 | 必填 | 说明 |
| ------------------ | ------------------------- | ---- | ------------------------------------------------------------ |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为全屏显示状态(该全屏状态下状态栏、导航栏仍然显示)。true表示全屏;false表示非全屏。 |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局(该沉浸式布局状态栏、导航栏仍然显示)。true表示沉浸式布局;false表示非沉浸式布局。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 |
**示例:**
......@@ -5469,7 +5475,9 @@ windowClass.setLayoutFullScreen(isLayoutFullScreen, (err) => {
setLayoutFullScreen(isLayoutFullScreen: boolean): Promise&lt;void&gt;
设置窗口的布局是否为全屏显示状态,使用Promise异步回调。
设置窗口的布局是否为沉浸式布局,使用Promise异步回调。
沉浸式布局是指布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。
非沉浸式布局是指布局避让状态栏与导航栏,组件不会与其重叠。
> **说明:**
>
......@@ -5481,7 +5489,7 @@ setLayoutFullScreen(isLayoutFullScreen: boolean): Promise&lt;void&gt;
| 参数名 | 类型 | 必填 | 说明 |
| ------------------ | ------- | ---- | ------------------------------------------------------------ |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为全屏显示状态(该全屏状态下状态栏、导航栏仍然显示)。true表示全屏;false表示非全屏。 |
| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局(该沉浸式布局状态栏、导航栏仍然显示)。true表示沉浸式布局;false表示非沉浸式布局。 |
**返回值:**
......
......@@ -235,7 +235,7 @@ decompressFile(inFile: string, outFile: string, options: Options, callback: Asyn
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------- | ------------------- | ---- | ------------------------------------------------------------ |
| inFile | string | 是 | 指定的待解压缩文件的文件路径,路径必须为沙箱路径,沙箱路径可以通过context获取,可参考[FA模型](js-apis-inner-app-context.md)[Stage模型](js-apis-inner-application-context.md)。 |
| outFile | string | 是 | 指定的解压后的目录路径。 |
| outFile | string | 是 | 指定的解压后的文件夹路径,文件夹目录路径需要在系统中存在,不存在则会解压失败。路径必须为沙箱路径,沙箱路径可以通过context获取,具体方法可参考[application/context(Stage模型)](js-apis-inner-application-context.md)[app/context(FA模型)](js-apis-inner-app-context.md) |
| options | [Options](#options) | 是 | 解压的配置参数。 |
| AsyncCallback<**void**> | callback | 否 | 解压的回调函数。 |
......@@ -255,7 +255,7 @@ decompressFile(inFile: string, outFile: string, options: Options, callback: Asyn
// 代码中使用的路径需为应用的沙箱路径,如/data/storage/el2/base/haps,也可以通过context获取
import zlib from '@ohos.zlib';
let inFile = '/xx/xxx.zip';
let outFile = '/xxx';
let outFileDir = '/xxx';
let options = {
level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION,
memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT,
......@@ -263,7 +263,7 @@ let options = {
};
try {
zlib.decompressFile(inFile, outFile, options, (errData) => {
zlib.decompressFile(inFile, outFileDir, options, (errData) => {
if (errData !== null) {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
}
......@@ -286,7 +286,7 @@ decompressFile(inFile: string, outFile: string, options: Options): Promise\<void
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------------- | ---- | ------------------------------------------------------------ |
| inFile | string | 是 | 指定的待解压缩文件的文件路径,路径必须为沙箱路径,沙箱路径可以通过context获取,可参考[FA模型](js-apis-inner-app-context.md)[Stage模型](js-apis-inner-application-context.md)。 |
| outFile | string | 是 | 指定的解压后的目录路径。 |
| outFile | string | 是 | 指定的解压后的文件夹路径,文件夹目录路径需要在系统中存在,不存在则会解压失败。路径必须为沙箱路径,沙箱路径可以通过context获取,具体方法可参考[application/context(Stage模型)](js-apis-inner-application-context.md)[app/context(FA模型)](js-apis-inner-app-context.md) |
| options | [Options](#options) | 是 | 解压时的配置参数。 |
**相关错误码**
......@@ -303,7 +303,7 @@ decompressFile(inFile: string, outFile: string, options: Options): Promise\<void
// 代码中使用的路径需为应用的沙箱路径,如/data/storage/el2/base/haps,也可以通过context获取
import zlib from '@ohos.zlib';
let inFile = '/xx/xxx.zip';
let outFile = '/xxx';
let outFileDir = '/xxx';
let options = {
level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION,
memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT,
......@@ -311,7 +311,7 @@ let options = {
};
try {
zlib.decompressFile(inFile, outFile, options).then((data) => {
zlib.decompressFile(inFile, outFileDir, options).then((data) => {
console.info('decompressFile success');
}).catch((errData) => {
console.log(`errData is errCode:${errData.code} message:${errData.message}`);
......
......@@ -30,7 +30,7 @@ Bad file path.
**错误描述**
在调用uploadFile或downloadFile接口时,文件路径不合法。
在调用uploadFile或downloadFile接口时,文件路径不合法或文件路径下文件已存在
**可能原因**
......
......@@ -21,10 +21,10 @@
| 成员变量名称 | 描述 |
| -------- | -------- |
| [width](#width) | 图片的,用pixels表示。 |
| [height](#height) | Pixel的格式。 |
| [width](#width) | 图片的,用pixels表示。 |
| [height](#height) | 图片的高,用pixels表示。 |
| [rowSize](#rowsize) | 每行的bytes数。 |
| [pixelFormat](#pixelformat) | 图片的宽,用pixels表示。 |
| [pixelFormat](#pixelformat) | Pixel的格式。 |
## 结构体成员变量说明
......
# 布局更新动画
[属性动画](../reference/arkui-ts/ts-animatorproperty.md)(animation)和[显式动画](../reference/arkui-ts/ts-explicit-animation.md)(animateTo)是ArkUI提供的最基础和常用的动画功能。在布局属性(如[尺寸属性](../reference/arkui-ts/ts-universal-attributes-size.md)[位置属性](../reference/arkui-ts/ts-universal-attributes-location.md))发生变化时,可以通过属性动画或显式动画,按照动画参数过渡到新的布局参数状态。
[显式动画](../reference/arkui-ts/ts-explicit-animation.md)(animateTo)和[属性动画](../reference/arkui-ts/ts-animatorproperty.md)(animation)是ArkUI提供的最基础和常用的动画功能。在布局属性(如[尺寸属性](../reference/arkui-ts/ts-universal-attributes-size.md)[位置属性](../reference/arkui-ts/ts-universal-attributes-location.md))发生变化时,可以通过属性动画或显式动画,按照动画参数过渡到新的布局参数状态。
| 动画类型 | 特点 | 适用场景 |
| ---- | ---------------------------------------- | -------- |
| 属性动画 | 动画设置简单,属性变化时自动触发动画。 | 较简单的动画场景 |
| 动画类型 | 特点 |
| ---- | ---------------------------------------- |
| 显式动画 | 闭包内的变化均会触发动画,包括由数据变化引起的组件的增删、组件属性的变化等,可以做较为复杂的动画。 | 较复杂的动画场景 |
| 属性动画 | 动画设置简单,属性变化时自动触发动画。 |
## 使用显式动画产生布局更新动画
......
......@@ -633,7 +633,7 @@ Camera驱动的开发过程主要包含以下步骤:
### 开发实例<a name = "8"></a>
在/drivers/peripheral/camera/hal/init目录下有一个关于Camera的demo,开机后会在/vendor/bin下生成可执行文件ohos_camera_demo,该demo可以完成Camera的预览,拍照等基础功能。下面我们就以此demo为例讲述怎样用HDI接口去编写预览PreviewOn()和拍照CaptureON()的用例,可参考[ohos_camera_demo](https://gitee.com/openharmony/drivers_peripheral/tree/master/camera/hal/init)。
在/drivers/peripheral/camera/hal/test/demo目录下有一个关于Camera的demo,开机后会在/vendor/bin下生成可执行文件ohos_camera_demo,该demo可以完成Camera的预览,拍照等基础功能。下面我们就以此demo为例讲述怎样用HDI接口去编写预览PreviewOn()和拍照CaptureON()的用例,可参考[ohos_camera_demo](https://gitee.com/openharmony/drivers_peripheral/tree/master/camera/hal/test/demo)。
1. 在main函数中构造一个CameraDemo 对象,该对象中有对Camera初始化、启停流、释放等控制的方法。下面mainDemo->InitSensors()函数为初始化CameraHost,mainDemo->InitCameraDevice()函数为初始化CameraDevice。
......
......@@ -62,6 +62,7 @@
- [动态加载与链接](kernel-small-bundles-linking.md)
- [虚拟动态共享库](kernel-small-bundles-share.md)
- [轻量级进程间通信](kernel-small-bundles-ipc.md)
- [容器隔离](kernel-small-bundles-container.md)
- 文件系统
- [虚拟文件系统](kernel-small-bundles-fs-virtual.md)
- [支持的文件系统](kernel-small-bundles-fs-support.md)
......
# 容器隔离
## 概述
容器(Container)提供了一种资源隔离的解决方案。系统中许多资源是全局管理的。例如进程PID、主机信息、用户信息等,容器机制是对这种全局资源的隔离,使得处于不同容器的进程拥有独立的全局系统资源,改变一个容器中的系统资源只会影响当前容器里的进程,对其他容器中的进程没有影响。
LiteOS-A内核容器隔离功能包含7个容器:UTS容器、PID容器、Mount容器、Network容器、TIME容器、IPC容器、User容器。通过所在进程ProcessCB的Container和Credentials保存。
隔离的容器如下表。
| 编号 | 名称 | 宏定义/flag | 隔离资源 | 数据结构定义位置 |
| :-------- | :------------- | :------------------- | :----------------------- | :----------------------- |
| 1 | UTS | CLONE_NEWUTS | 主机名,域名,版本信息 |struct Container |
| 2 | PID | CLONE_NEWPID | 进程ID |struct Container |
| 3 | Mount | CLONE_NEWNS | 文件系统挂载点 |struct Container |
| 4 | Network | CLONE_NEWNET | 网络系统资源 |struct Container |
| 5 | TIME | CLONE_NEWTIME | 时钟资源 |struct Container |
| 6 | IPC | CLONE_NEWIPC | 进程间通信资源 |struct Container |
| 7 | User | CLONE_NEWUSER | 用户和用户组 |struct Credentials |
容器之间的资源隔离,细分为两种:
- 全局隔离:属于平行关系(无继承关系)的容器,所有容器之间的容器类资源彼此不可见。
- 非全局隔离:属于有父子继承关系的容器,同一层的各容器之间资源不可见,但上层容器仍然可以访问下层容器资源。
PID容器通过 unshare/setns 切换时,切换子进程的容器,而本进程容器不变。
通过在子进程ProcessCB中添加对应容器集合Container和用户容器,完成对容器功能的支持,并通过编译开关控制特性的开启和关闭。
- 每个进程ProcessCB包含一个Container指针,该指针指向真正分配的Container结构。通过这种方式,进程可单独拥有一个Container结构,也可共享同一个Container结构。 进一步分解,在Container结构中,包含各容器指针,分别指向UTS容器、PID容器、Network容器、Mount容器、TIME容器、IPC容器。
- 每个进程ProcessCB对应一个Credentials结构,单独管理User容器,便于模块化、单独处理User容器的特有逻辑。
![总体设计-总体结构-1](figures/container-001.png)
### 各容器简介
#### **UTS容器**
UTS 容器用于对主机名和域名进行隔离。
每一个进程对应有一个自己的UTS Container,用来隔离容器的内核名称、版本等信息,不同容器查看到的都是属于自己的信息,相互间不能查看。
#### **Mount容器**
用于隔离文件挂载点。在一个容器里挂载、卸载的动作不会影响到其他容器。
通过文件挂载容器,实现各进程间相互独立的使用文件挂载系统,子进程在独立的文件挂载容器里面进行挂载操作,可以建立自身的文件挂载结构:
- 文件挂载容器的基础实现,创建进程时根据clone传入的参数flag在各自进程创建文件挂载容器,将挂载信息从全局更改为与文件挂载容器相关联。
- 创建容器后,修改获取当前挂载信息的实现,将从全局或者更改为当前文件挂载容器中获取,使进程挂载、卸载或者访问挂载文件操作不会对其他进程挂载信息产生影响或者访问到其他进程的文件挂载信息。
#### **PID容器**
用于隔离进程号,不同容器的进程可以使用相同的虚拟进程号。
进程容器主要用于进程的隔离,特点如下:
- 容器间的进程ID相互独立。
- 父容器可以看到子容器中的进程,且同一个进程在父容器中的进程ID和子容器中的进程ID相互独立。
- 子容器无法看到父容器中的进程。
- 在根容器下可以看到系统的所有进程。
#### **Network容器**
用于隔离系统网络设备和网络栈。
Network容器对TCP/IP协议栈和网络设备资源进行隔离,以达到隔离目的。
- 传输层隔离:对端口号进行隔离,Network容器内的可用端口号范围是0~65535,进程绑定的是自己所属容器的端口号,所以不同Network容器的进程可以对同一个TCP/UDP端口号进行绑定,且互相之间没有影响。
- IP层隔离:对IP资源进行隔离,每个容器都有属于自己的IP资源,在一个Network容器内修改IP对其他Network容器没有影响。
- 网络设备隔离:对网卡进行隔离,每个容器都有属于自己的网卡,不同Network容器内的网卡设备之间相互隔离无法通信,用户可以通过配置veth-pair解决不同容器间的通信问题。
#### **User容器**
用于隔离用户和用户组。
User Container是用来隔离和分割管理权限的,管理权限实质分为两部分uid/gid和Capability。
- UID/GID
User Container是对资源的一种隔离,主要隔离uid/gid,处于不同的User Container具有不同的uid/gid,每个User container拥有独立的从0开始的uid/gid。这样容器中的进程可以拥有root权限,但是它的root权限会被限制在一小块范围之内。改变一个User Container中的值只会影响当前User Container,对其他User Container中的进程无影响。
- Capability
User Container通过设置Capability来实现能力隔离。
每个进程在进程初始化的时候调用OsInitCapability对权限进行初始化,对用户提供修改和获取(SysCapSet/SysCapGet)权限的系统调用,用于修改进程的权限。
Capabilities的类型如下表:
| 名称 | 描述 |
| --------------------- | ---------------------------------------------- |
| CAP_CHOWN | 修改文件所有者的权限 |
| CAP_DAC_EXECUTE | 忽略文件执行的 DAC 访问限制 |
| CAP_DAC_WRITE | 忽略文件写的 DAC 访问限制 |
| CAP_DAC_READ_SEARCH | 忽略文件读及目录搜索的 DAC 访问限制 |
| CAP_FOWNER | 忽略文件属主 ID 必须和进程用户 ID 相匹配的限制 |
| CAP_KILL | 允许对不属于自己的进程发送信号 |
| CAP_SETGID | 允许改变进程的GID |
| CAP_SETUID | 允许改变进程的UID |
| CAP_NET_BIND_SERVICE | 允许绑定到小于 1024 的端口 |
| CAP_NET_BROADCAST | 允许网络广播和多播访问 |
| CAP_NET_ADMIN | 允许执行网络管理任务 |
| CAP_NET_RAW | 允许使用原始套接字 |
| CAP_FS_MOUNT | 允许使用 chroot() 系统调用 |
| CAP_FS_FORMAT | 允许使用文件格式 |
| CAP_SCHED_SETPRIORITY | 允许设置优先级 |
| CAP_SET_TIMEOFDAY | 允许设置系统时间 |
| CAP_CLOCK_SETTIME | 允许改变系统时钟 |
| CAP_CAPSET | 允许设置任意的 capabilities |
| CAP_REBOOT | 允许重新启动系统 |
| CAP_SHELL_EXEC | 允许执行shell |
#### **TIME容器**
用于隔离系统的时间维护信息。
每一个进程对应有一个自己的TIME Container,用来隔离`CLOCK_MONOTONIC``CLOCK_MONOTONIC_RAW`对应的时钟,不同容器中的进程在对`CLOCK_MONOTONIC``CLOCK_MONOTONIC_RAW`时钟进行对应的时间操作调用时,彼此之间时钟的数值相对独立,实现安全容器间系统时钟的隔离。
容器(当前进程的time_for_children容器)中时钟的偏移量记录在`/proc/PID/timens_offsets`文件中,通过修改该文件,可以对应修改TIME容器的偏移信息。这些偏移是相对于初始时间容器中的时钟值表示的。
当前,创建TIME Container的唯一方法是通过使用`CLONE_NEWTIME`标志调用`unshare`。该调用将创建一个新的TIME Container,但不会将调用过程放在新的容器中。而是调用进程的随后创建的子级将放置在新的容器中。
这允许时钟偏移,用于新的容器的第一进程被放置在容器之前进行设置`/proc/PID/timens_offsets`文件。
#### **IPC容器**
用于隔离进程间通信对象(IPC对象),包括消息队列和共享内存。
每一个进程对应有一个自己的IPC Container,用来隔离如下全局资源:消息队列、共享内存。
不同容器中的进程在对消息队列、共享内存进行对应的时间操作调用时,彼此之间是独立的。
- 消息队列隔离:把用于消息队列的全局变量结构LosQueueCB修改为IPC Container中的局部变量保存,从而实现在各自进程中的容器内可见,达到相互隔离的效果。
- 共享内存隔离:把用于共享内存的全局变量shmInfo,sysvShmMux,shmSegs,shmUsedPageCount修改为IPC Container中的局部变量保存,从而实现在各自进程中的容器内可见,达到相互隔离的效果。
### 运作机制
#### 新建容器流程
在系统初始化时,需要为初始进程(0号、1号、2号进程)创建同一个根容器,根容器类型包括所有7种类型:UTS容器、PID容器、User容器、Network容器、Mount容器、TIME容器、IPC容器。
后续可通过clone等接口为子进程新建容器(指定容器FLAG),未指定容器FLAG的情况下clone的子进程复用父进程容器。
![容器节点公共定义部分ContainerBase](figures/container-002.png)
#### 切换容器流程
通过 unshare接口,将当前进程脱离当前所属容器,并转移到一个新建的容器。以IPC容器为例。
<img src="figures/container-003.png" alt="容器节点公共定义部分ContainerBase" style="zoom:80%;" />
## 开发指导
应用层可基于容器隔离功能,进行如下场景的使用,新建容器、切换容器、销毁容器。
### 新建容器
创建子进程时可以完成新建容器。接口如下:
**clone接口**
通过clone()创建新进程的同时创建容器,是新建容器的一种常见做法,函数原型:
```
int clone(int (*fn)(void *), void *stack, int flags, void *arg, ...
/* pid_t *parent_tid, void *tls, pid_t *child_tid */ );
```
- clone时可以指定新建的子进程通过容器隔离资源,使得资源(如UTS信息)获取和修改只限于容器范围内,不影响其他容器。
- 若调用clone接口不指定容器相关FLAG,则会将子进程也放到父进程所在容器中,即复用/共享父进程的容器。
### 切换容器
转移/切换容器是调整已有进程的容器。包括2种情况:
- **unshare 接口**
通过 unshare接口,将当前进程脱离当前所属容器,并转移到一个新建的容器。函数原型:
```
int unshare(int flags);
```
参考其他内核的实现,PID容器特殊处理,PID容器通过 unshare/setns 切换时, 是切换子进程的容器,而本进程容器仍然保持不变。
方法是,本进程将新建的容器记录下来,创建子进程时再根据记录信息进行容器归属。
这一点上,与其他容器(如Network容器)有区别,其他容器的setns、unshare操作是直接对已有进程生效。
可以一句话总结为: PID容器的setns和unshare操作,是针对后代进程的PID容器。
- **setns接口**
通过 setns接口,将当前进程脱离当前所属容器,并转移到一个已有的容器。便于灵活切换进程容器。
PID容器通过 setns 转移时, 是切换子进程的容器,而本进程容器仍然保持不变。同上文。函数原型:
```
int setns(int fd, int nstype);
```
### 销毁容器
进程终止时会退出所属容器,并对引用计数进行递减。引用计数减为0的对象,需要进行销毁。
通过kill接口,可向指定进程发送指定信号,通知进程执行关闭/退出动作。函数原型:
```
int kill(pid_t pid, int sig);
```
### 查询容器信息
容器隔离之后,系统用户可使用 ls 命令访问 /proc/[pid]/container/ 目录进行查看和确认。
```
ls -l /proc/[pid]/container
```
| 属性 | 所属用户 | 所属用户组 | 文件名 | 说明 |
| :--------- | :------- | :--------- | :--------------------------------------- | :--------------------- |
| lr--r--r-- | u:0 | g:0 | net -> 'net:[4026531847]' | 链接对象为容器唯一编号 |
| lr--r--r-- | u:0 | g:0 | user -> 'user:[4026531841]' | 同上 |
| lr--r--r-- | u:0 | u:0 | time_for_children -> 'time:[4026531846]' | 同上 |
| lr--r--r-- | u:0 | g:0 | time -> 'time:[4026531846]' | 同上 |
| lr--r--r-- | u:0 | g:0 | ipc -> 'ipc:[4026531845]' | 同上 |
| lr--r--r-- | u:0 | g:0 | mnt -> 'mnt:[4026531844]' | 同上 |
| lr--r--r-- | u:0 | g:0 | uts -> 'uts:[4026531843]' | 同上 |
| lr--r--r-- | u:0 | g:0 | pid_for_children -> 'pid:[4026531842]' | 同上 |
| lr--r--r-- | u:0 | g:0 | pid -> 'pid:[4026531842]' | 同上 |
### 容器配额
容器配额(plimits)的主要功能是限制进程组可以使用的资源,/proc/plimits 目录作为容器配额根目录。
- plimits文件系统为伪文件系统,需要实现文件与plimits控制变量的映射;通过文件操作,达到修改内核变量的目的。例如:memory限制器中,通过用户修改memory.limit文件内容,即可修改相应的内核变量值,进而限制内存分配。
- plimits文件系统中,文件能够被读写,目录能够被增删。
- plimits的目录,映射的是plimits的分组,所以需要在创建目录的时候,自动创建目录下的文件(这些文件映射为限制器的控制变量)。
- 创建限制器的文件是以组为单位创建的,例如:创建memory限制器,在增加一个memory限制器的时候,会全量创建所需的文件,而不是单独创建单个文件。
采用编译宏“LOSCFG_PROCESS_LIMITS”进行开关控制,y打开,n关闭,默认关闭
打开编译开关,查看 /proc/plimits目录, 主要包含下列文件:
| 权限 | 用户 | 用户组 | 文件名 | 描述 | 备注 |
| ---------- | ---- | ------ | ---------------- | --------------------------------- | ------------------------------------------------------------ |
| -r--r--r-- | u:0 | g:0 | sched.stat | 调度统计信息 | 输出格式:[PID runTime] |
| -r--r--r-- | u:0 | g:0 | sched.period | 调度周期配置 | 单位:us |
| -r--r--r-- | u:0 | g:0 | sched.quota | 调度配额配置 | 单位:us |
| -r--r--r-- | u:0 | g:0 | devices.list | 报告plimits中的进程访问的设备 | 输出格式:[type name access] |
| -r--r--r-- | u:0 | g:0 | devices.deny | 指定plimits中的进程可以访问的设备 | 写入格式:["type name access" >> device.deny] |
| -r--r--r-- | u:0 | g:0 | devices.allow | 报告plimits中的进程不能访问的设备 | 写入格式:["type name access" >> device.allow] |
| -r--r--r-- | u:0 | g:0 | ipc.stat | ipc对象申请统计信息 | 输出格式:[mq count: mq failed count: <br/> shm size: shm failed count: ] |
| -r--r--r-- | u:0 | g:0 | ipc.shm_limit | 共享内存大小上限 | 单位:byte |
| -r--r--r-- | u:0 | g:0 | ipc.mq_limit | 消息个数上限 | 0~最大64位正整数 |
| -r--r--r-- | u:0 | g:0 | memory.stat | 内存统计信息 | 单位:byte |
| -r--r--r-- | u:0 | g:0 | memory.limit | 组内进程占用内存总量配额 | 单位:byte |
| -r--r--r-- | u:0 | g:0 | pids.max | 组内包括的最大进程个数 | / |
| -r--r--r-- | u:0 | g:0 | pids.priority | 组内包括的最高进程优先级 | / |
| -r--r--r-- | u:0 | g:0 | plimits.procs | 组内包含的所有进程的pid | / |
| -r--r--r-- | u:0 | g:0 | plimits.limiters | plimits组内包含的限制器 | / |
其中devices参数说明:
| type (设备类型) | name (设备名字) | access (相应的权限) |
| -------------------------------------------- | ----------------- | ---------------------------------- |
| a - 所有设备,可以是字符设备,也可以是块设备 | / | r - 允许进程读取指定设备 |
| b- 块设备 | / | w - 允许进程写入指定设备 |
| c - 字符设备 | / | m - 允许进程生成还不存在的设备文件 |
## 参考
### 规格说明
#### 参数设定
内核支持每一种容器最大数默认为LOSCFG_KERNEL_CONTAINER_DEFAULT_LIMIT。
内核初始化proc/sys/user目录,生成文件max_net_container,max_ipc_container,max_time_container,max_uts_container,max_user_container,max_pid_container,max_mnt_container并且将伪文件与内核参数绑定。用户配置伪文件即会修改对应的内核参数。当前容器数量如果小于上限,则可创建新的容器,否则返回NULL表示失败。
#### 容器唯一编号
各容器的全局唯一编号,统一基于一个固定值进行编号。
```
#define CONTAINER_IDEX_BASE (0xF0000000)
inum = CONTAINER_IDEX_BASE + (unsigned int)i;
```
#### 规则设定
- PID容器和User容器,具有分层关系,最大支持3层;其他的UTS、Mount、Network容器无分层关系。
- 通过上述接口clone创建容器、setns切换容器、unshare切换容器时,需传入符合POSIX标准的FLAG,如下:
| FLAG | clone | setns | unshare |
| ------------- | ---------------------------- | -------------------------------- | -------------------------------- |
| CLONE_NEWNS | 为子进程新建文件系统容器 | 将当前进程转移到指定文件系统容器 | 为本进程新建文件系统容器 |
| CLONE_NEWPID | 为子进程新建PID容器 | 将当前进程转移到指定PID容器 | 为本进程新建的子进程新建PID容器 |
| CLONE_NEWIPC | 为子进程新建IPC容器 | 将当前进程转移到指定IPC容器 | 为本进程新建IPC容器 |
| CLONE_NEWTIME | 为进程所属父进程新建TIME容器 | 暂不支持 | 为本进程新建的子进程新建TIME容器 |
| CLONE_NEWUSER | 为子进程新建User容器 | 将当前进程转移到指定User容器 | 为本进程新建User容器 |
| CLONE_NEWUTS | 为子进程新建UTSNAME容器 | 将当前进程转移到指定UTSNAME容器 | 为本进程新建UTSNAME容器 |
| CLONE_NEWNET | 为子进程新建Network容器 | 将当前进程转移到指定Network容器 | 为本进程新建Network容器 |
- 容器功能采用编译宏、编译脚本中参数结合,完成特性的开关控制。
- 容器编译宏定义:
```
// 容器功能总编译宏
LOSCFG_CONTAINER
// 各容器编译宏
LOSCFG_UTS_CONTAINER
LOSCFG_MNT_CONTAINER
LOSCFG_PID_CONTAINER
LOSCFG_NET_CONTAINER
LOSCFG_USER_CONTAINER
LOSCFG_TIME_CONTAINER
LOSCFG_IPC_CONTAINER
```
- 测试用例编译宏定义: enable打开,disable关闭,默认关闭。
```
LOSCFG_USER_TEST_MNT_CONTAINER
LOSCFG_USER_TEST_PID_CONTAINER
LOSCFG_USER_TEST_NET_CONTAINER
LOSCFG_USER_TEST_USER_CONTAINER
LOSCFG_USER_TEST_TIME_CONTAINER
LOSCFG_USER_TEST_IPC_CONTAINER
```
### 开发实例
当前LiteOS-A冒烟用例中已包含对应接口的使用示例,请开发者自行编译验证,推荐用例路径如下:
[创建UTS容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_uts_container_001.cpp)
[Unshare 切换当前进程的UTS容器至一个新容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_uts_container_004.cpp)
[setns切换,将当前进程的UTS容器切换至子进程的UTS容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_uts_container_005.cpp)
[创建Network容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_net_container_001.cpp)
[创建User容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_user_container_001.cpp)
[创建PID容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_pid_container_023.cpp)
[创建Mount容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_mnt_container_001.cpp)
[创建IPC容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_ipc_container_001.cpp)
[创建TIME容器](https://gitee.com/openharmony/kernel_liteos_a/blob/master/testsuites/unittest/container/smoke/It_time_container_001.cpp)
......@@ -216,6 +216,7 @@
- [动态加载与链接](kernel/kernel-small-bundles-linking.md)
- [虚拟动态共享库](kernel/kernel-small-bundles-share.md)
- [轻量级进程间通信](kernel/kernel-small-bundles-ipc.md)
- [容器隔离](kernel/kernel-small-bundles-container.md)
- 文件系统
- [虚拟文件系统](kernel/kernel-small-bundles-fs-virtual.md)
- [支持的文件系统](kernel/kernel-small-bundles-fs-support.md)
......
......@@ -232,8 +232,14 @@ module.json配置文件中的ability的[name](../../../application-dev/quick-sta
**适配指导**<br>
删除module.json中[distroFilter](../../../application-dev/quick-start/module-configuration-file.md)标签,使用distributionFilter替代
## cl.bundlemanager.20 module.json配置文件中launchTypede标签standard模式修改为multiton
## cl.bundlemanager.20 module.json配置文件中launchType标签standard模式修改为multiton
删除module.json中[launchType](../../../application-dev/quick-start/module-configuration-file.md)标签的standard模式修改为multiton
**适配指导**<br>
删除module.json中[launchType](../../../application-dev/quick-start/module-configuration-file.md)标签的standard模式,使用multiton替代
## cl.bundlemanager.21 module.json配置文件中abilities的标签visible修改为exported
module.json中[abilities](../../../application-dev/quick-start/module-configuration-file.md)的标签visible修改为exported,表示当前ability是否支持导出,被其他的ability使用。
**适配指导**<br>
删除module.json中[abilities](../../../application-dev/quick-start/module-configuration-file.md)的visible标签,使用exported标签替代
\ No newline at end of file
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册