提交 6f6ebd19 编写于 作者: E ester.zhou

Update docs (17231)

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 b7182db1
# ArkUI Subsystem ChangeLog
## cl.arkui.1 xcomponent API Change
Changed the following APIs of the **xcomponent** component of the ArkUI subsystem:
- **getXComponentSurfaceId** and **setXComponentSurfaceSize**: Removed the **@systemapi** tag.
- **getXComponentSurfaceId**, **getXComponentContext**, and **setXComponentSurfaceSize**: Specified the return value type.
You need to adapt your application based on the following information.
**Change Impact**
Released JS APIs are affected. The application needs to adapt these APIs so that it can be properly compiled in the SDK environment of the new version.
**Key API/Component Changes**
- **getXComponentSurfaceId**: is changed to a public API, with its return value type specified as string.
- **setXComponentSurfaceSize**: is changed to a public API, with its return value type specified as void.
- **getXComponentContext**: has its return value type specified as object.
**Adaptation Guide**
Startup rules for different scenarios are as follows:
Adaptions to be made:
- **getXComponentSurfaceId**
- Rule in OpenHarmony 3.2 Beta3:
- System API
- No specified return value
- OpenHarmony 3.2 Beta4 rules:
- Public API
- Return value type specified as string
- You need to process the return value as a string.
- **setXComponentSurfaceSize**
- Rule in OpenHarmony 3.2 Beta3:
- System API
- No specified return value
- OpenHarmony 3.2 Beta4 rules:
- Public API
- Return value type specified as void
- You need to process the return value as a void.
- **getXComponentContext**
- Rule in OpenHarmony 3.2 Beta3:
- No specified return value
- OpenHarmony 3.2 Beta4 rules:
- Return value type specified as object
- You need to process the return value as an object.
## cl.arkui.2 Change of Styles of Popup Component and APIs
Changed the styles of the **alertDialog**, **actionSheet**, and **customDialog** components, as well as the **prompt** and **promptAction** APIs. Specifically speaking:
- Added the popup background blur effect to **promptAction.showDialog**, **promptAction.showActionMenu**, **alertDialog**, **actionSheet**, and **customDialog**.
**Change Impact**
The popup background blur effect is set by default.
**Key API/Component Changes**
APIs: **promptAction.showDialog** and **promptAction.showActionMenu;**
Components: **alertDialog**, **actionSheet**, and **customDialog**
**Adaptation Guide**
No adaptation is required.
## cl.arkui.3 Supplementation of the Initialization Mode and Restriction Verification Scenarios of Custom Components' Member Variables
For details, see [Restrictions and Extensions](https://gitee.com/openharmony/docs/blob/master/en/application-dev/quick-start/arkts-restrictions-and-extensions.md).
**Change Impact**
If custom components' member variables are initialized or assigned with values not according to the document specifications, an error will be reported during compilation.
**Key API/Component Changes**
N/A.
**Adaptation Guide**
Make modification according to specifications in the above document.
## cl.arkui.4 Supplementation of Verification Scenarios of Value Assignment Restrictions on Member Variables of Custom Parent Components and Child Components
For details, see [Restrictions and Extensions](../../../application-dev/quick-start/arkts-restrictions-and-extensions.md).
**Change Impact**
If member variables of the parent component or child component are initialized not according to the document specifications, an error will be reported during compilation.
**Key API/Component Changes**
N/A.
**Adaptation Guide**
Make modification according to specifications in the above document, using other decorators or normal member variables for value assignment.
## cl.arkui.5 Supplementation of Verification for a Single Subcomponent
Added the check rule that allows only one child component to be enabled for the following components: **Button**, **FlowItem**, **GridItem**, **GridCol**, **ListItem**, **Navigator**, **Refresh**, **RichText**, **ScrollBar**, **StepperItem**, and **TabContent**.
**Change Impact**
If one of the preceding components contains more than one child component, an error will be reported during compilation.
**Key API/Component Changes**
```js
RichText('RichText') {
Text('Text1')
Text('Text2')
}
/* ArkTS:ERROR File: /root/newOH/developtools/ace-ets2bundle/compiler/sample/pages/home.ets:25:7
The component 'RichText' can only have a single child component. */
```
**Adaptation Guide**
Make modification based on the error message. Make sure that the specified component contains only one child component.
# Device Manager ChangeLog
## cl.device_manager.1 Error Information Return Method Change of APIs
The device manager API uses service logic return values to indicate the error information, which does not comply with the API error code specifications of OpenHarmony. The following changes are made in API version 9 and later:
Asynchronous API: An error message is returned via **AsyncCallback** or the **error** object of **Promise**.
Synchronous API: An error message is returned via an exception.
**Change Impact**
The application developed based on earlier versions needs to adapt the method for returning API error information. Otherwise, the original service logic will be affected.
**Key API/Component Changes**
Error code processing is added for the following APIs:
- createDeviceManager(bundleName: string, callback: AsyncCallback&lt;DeviceManager&gt;): void;
- release(): void;
- getTrustedDeviceListSync(): Array&lt;DeviceInfo&gt;
- getTrustedDeviceList(callback:AsyncCallback&lt;Array&lt;DeviceInfo&gt;&gt;): void;
- getTrustedDeviceList(): Promise&lt;Array&lt;DeviceInfo&gt;&gt;
- getLocalDeviceInfoSync(): DeviceInfo;
- getLocalDeviceInfo(callback:AsyncCallback&lt;DeviceInfo&gt;): void;
- getLocalDeviceInfo(): Promise&lt;DeviceInfo&gt;
- startDeviceDiscovery(subscribeInfo: SubscribeInfo): void;
- startDeviceDiscovery(subscribeInfo: SubscribeInfo, filterOptions?: string): void;
- stopDeviceDiscovery(subscribeId: number): void;
- publishDeviceDiscovery(publishInfo: PublishInfo): void;
- unPublishDeviceDiscovery(publishId: number): void;
- authenticateDevice(deviceInfo: DeviceInfo, authParam: AuthParam, callback: AsyncCallback&lt;{deviceId: string, pinToken ?: number}&gt;): void;
- unAuthenticateDevice(deviceInfo: DeviceInfo): void;
- verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback&lt;{deviceId: string, level: number}&gt;): void;
- setUserOperation(operateAction: number, params: string): void;
- on(type: 'uiStateChange', callback: Callback&lt;{ param: string}&gt;): void;
- off(type: 'uiStateChange', callback?: Callback&lt;{ param: string}&gt;): void;
- on(type: 'deviceStateChange', callback: Callback&lt;{ action: DeviceStateChangeAction, device: DeviceInfo }&gt;): void;
- off(type: 'deviceStateChange', callback?: Callback&lt;{ action: DeviceStateChangeAction, device: DeviceInfo }&gt;): void;
- on(type: 'deviceFound', callback: Callback&lt;{ subscribeId: number, device: DeviceInfo }&gt;): void;
- off(type: 'deviceFound', callback?: Callback&lt;{ subscribeId: number, device: DeviceInfo }&gt;): void;
- on(type: 'discoverFail', callback: Callback&lt;{ subscribeId: number, reason: number }&gt;): void;
- off(type: 'discoverFail', callback?: Callback&lt;{ subscribeId: number, reason: number }&gt;): void;
- on(type: 'publishSuccess', callback: Callback&lt;{ publishId: number }&gt;): void;
- off(type: 'publishSuccess', callback?: Callback&lt;{ publishId: number }&gt;): void;
- on(type: 'publishFail', callback: Callback&lt;{ publishId: number, reason: number }&gt;): void;
- off(type: 'publishFail', callback?: Callback&lt;{ publishId: number, reason: number }&gt;): void;
- on(type: 'serviceDie', callback: () =&gt; void): void;
- off(type: 'serviceDie', callback?: () =&gt; void): void;
**Adaptation Guide**
The following uses **getTrustedDeviceList** as an example for asynchronous APIs:
```ts
import account_osAccount from "@ohos.distributedHardware.deviceManager"
dmInstance.getTrustedDeviceList((err, data) => {
console.log("getTrustedDeviceList err: " + JSON.stringify(err));
console.log('get trusted device info: ' + JSON.stringify(data));
});
try {
dmInstance.getTrustedDeviceList((err, data) => {
if (err) {
console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message);
return;
}
console.log('get trusted device info: ' + JSON.stringify(data));
});
} catch (err) {
console.error("getTrustedDeviceList errCode:" + err.code + ",errMessage:" + err.message);
}
```
The following uses **startDeviceDiscovery** as an example for synchronous APIs:
```ts
// Automatically generate a unique subscription ID.
var subscribeId = Math.floor(Math.random() * 10000 + 1000);
var subscribeInfo = {
"subscribeId": subscribeId,
"mode": 0xAA, // Active discovery
"medium": 0, // Automatic. Multiple media can be used for device discovery.
"freq": 2, // High frequency
"isSameAccount": false,
"isWakeRemote": false,
"capability": 1
};
dmInstance.startDeviceDiscovery(subscribeInfo); // The deviceFound callback is called to notify the application when a device is discovered.
// Automatically generate a unique subscription ID.
var subscribeId = Math.floor(Math.random() * 10000 + 1000);
var subscribeInfo = {
"subscribeId": subscribeId,
"mode": 0xAA, // Active discovery
"medium": 0, // Automatic. Multiple media can be used for device discovery.
"freq": 2, // High frequency
"isSameAccount": false,
"isWakeRemote": false,
"capability": 1
};
try {
dmInstance.startDeviceDiscovery(subscribeInfo); // The deviceFound callback is called to notify the application when a device is discovered.
} catch (err) {
console.error("startDeviceDiscovery errCode:" + err.code + ",errMessage:" + err.message);
}
```
# Customization Subsystem ChangeLog
## cl.Customization.1 Change of the Enterprise Device Management Module Name
Changed **@ohos.enterpriseDeviceManager.d.ts** to **@ohos.enterprise.adminManager.d.ts**.
**Change Impact**
The application developed based on OpenHarmony earlier than 3.2.8.3 must be adapted so that it can be properly compiled in the SDK environment of the new version.
**Key API/Component Changes**
| Original API | New API |
| --------------------------------- | ---------------------------------- |
| @ohos.enterpriseDeviceManager.d.ts | @ohos.enterprise.adminManager.d.ts |
**Adaptation Guide**
The original APIs are only moved to the new namespace. Therefore, you can modify **import** to solve the adaptation problem.
If the original API uses **@ohos.enterpriseDeviceManager**:
```js
import enterpriseDeviceManager from '@ohos.enterpriseDeviceManager';
```
You can modify **import** to switch to the new namespace:
```js
import enterpriseDeviceManager from '@ohos.enterprise.adminManager';
```
## cl.Customization.2 enterpriseDeviceManager/DeviceSettingsManager.d.ts Module Change
Changed **enterpriseDeviceManager/DeviceSettingsManager.d.ts** to **ohos.enterprise.dateTimeManager.d.ts**.
**Change Impact**
The application developed based on OpenHarmony earlier than 3.2.8.3 must be adapted so that it can be properly compiled in the SDK environment of the new version.
**Key API/Component Changes**
| Original API | Original API Type | New API | New API Type |
| --------------------------------- | --------- | ---------------------------------- | ----- |
| enterpriseDeviceManager/DeviceSettingsManager.d.ts | interface | @ohos.enterprise.dateTimeManager.d.ts | namespace |
**Adaptation Guide**
If the **setDateTime** API of **enterpriseDeviceManager/DeviceSettingsManager.d.ts** is used:
```js
import enterpriseDeviceManager from '@ohos.enterpriseDeviceManager'
let wantTemp = {
bundleName: "bundleName",
abilityName: "abilityName",
};
enterpriseDeviceManager.getDeviceSettingsManager((error, mgr) => {
if (error) {
console.log("error code:" + error.code + " error message:" + error.message);
return;
}
mgr.setDateTime(wantTemp, 1526003846000, (error) => {
if (error) {
console.log("error code:" + error.code + " error message:" + error.message);
}
});
});
```
You need to import the new namespace for adaptation:
```js
import dateTimeManager from '@ohos.enterprise.dateTimeManager'
let wantTemp = {
bundleName: "bundleName",
abilityName: "abilityName",
};
dateTimeManager.setDateTime(wantTemp, 1526003846000, (error) => {
if (error) {
console.log("error code:" + error.code + " error message:" + error.message);
}
})
```
## cl.Customization.3 System API Change
Changed all enterprise device management APIs to system APIs.
**Change Impact**
All APIs can be called only by system applications.
**Key API/Component Changes**
| Module | Class | Method/Attribute/Enum/Constant | Change Type|
| ------------------------- | ------------------- | ------------------------------------------------------------ | -------- |
| @ohos.enterprise.adminManager | adminManager | **function** enableAdmin(admin: Want, enterpriseInfo: EnterpriseInfo, type: AdminType, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** enableAdmin(admin: Want, enterpriseInfo: EnterpriseInfo, type: AdminType, userId: number, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** enableAdmin(admin: Want, enterpriseInfo: EnterpriseInfo, type: AdminType, userId?: number): Promise<**void**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** disableAdmin(admin: Want, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** disableAdmin(admin: Want, userId: number, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** disableAdmin(admin: Want, userId?: number): Promise<**void**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** disableSuperAdmin(bundleName: String, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** disableSuperAdmin(bundleName: String): Promise<**void**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** isAdminEnabled(admin: Want, callback: AsyncCallback<**boolean**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** isAdminEnabled(admin: Want, userId: number, callback: AsyncCallback<**boolean**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** isAdminEnabled(admin: Want, userId?: number): Promise<**boolean**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** getEnterpriseInfo(admin: Want, callback: AsyncCallback<**EnterpriseInfo**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** getEnterpriseInfo(admin: Want): Promise<**EnterpriseInfo**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** setEnterpriseInfo(admin: Want, enterpriseInfo: EnterpriseInfo, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** setEnterpriseInfo(admin: Want, enterpriseInfo: EnterpriseInfo): Promise<**void**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** isSuperAdmin(bundleName: String, callback: AsyncCallback<**boolean**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** isSuperAdmin(bundleName: String): Promise<**boolean**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** subscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** subscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>): Promise<**void**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** unsubscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **function** unsubscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>): Promise<**void**>; | systemapi |
| @ohos.enterprise.adminManager | adminManager | **interface** EnterpriseInfo | systemapi |
| @ohos.enterprise.adminManager | adminManager | **enum** AdminType | systemapi |
| @ohos.enterprise.adminManager | adminManager | **enum** ManagedEvent | systemapi |
| @ohos.enterprise.dataTimeManager | dateTimeManager | **function** setDateTime(admin: Want, time: number, callback: AsyncCallback<**void**>): void; | systemapi |
| @ohos.enterprise.dataTimeManager | dateTimeManager | **function** setDateTime(admin: Want, time: number): Promise<**void**>; | systemapi |
## cl.Customization.4 API Permission Change
Added permission verification for some APIs.
**Change Impact**
The application developed based on OpenHarmony earlier than 3.2.8.3 must have the corresponding permission so that it can properly call these APIs.
**Key API/Component Changes**
| Module | Class | Method/Attribute/Enum/Constant | New Permission|
| ------------------------- | ------------------- | ------------------------------------------------------------ | -------- |
| @ohos.enterprise.adminManager | adminManager | **function** enableAdmin(admin: Want, enterpriseInfo: EnterpriseInfo, type: AdminType, callback: AsyncCallback<**void**>): void; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** enableAdmin(admin: Want, enterpriseInfo: EnterpriseInfo, type: AdminType, userId: number, callback: AsyncCallback<**void**>): void; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** enableAdmin(admin: Want, enterpriseInfo: EnterpriseInfo, type: AdminType, userId?: number): Promise<**void**>; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** disableAdmin(admin: Want, callback: AsyncCallback<**void**>): void; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** disableAdmin(admin: Want, userId: number, callback: AsyncCallback<**void**>): void; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** disableAdmin(admin: Want, userId?: number): Promise<**void**>; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** disableSuperAdmin(bundleName: String, callback: AsyncCallback<**void**>): void; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** disableSuperAdmin(bundleName: String): Promise<**void**>; | ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN |
| @ohos.enterprise.adminManager | adminManager | **function** setEnterpriseInfo(admin: Want, enterpriseInfo: EnterpriseInfo, callback: AsyncCallback<**void**>): void; | ohos.permission.SET_ENTERPRISE_INFO |
| @ohos.enterprise.adminManager | adminManager | **function** setEnterpriseInfo(admin: Want, enterpriseInfo: EnterpriseInfo): Promise<**void**>; | ohos.permission.SET_ENTERPRISE_INFO |
| @ohos.enterprise.adminManager | adminManager | **function** subscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>, callback: AsyncCallback<**void**>): void; | ohos.permission.ENTERPRISE_SUBSCRIBE_MANAGED_EVENT |
| @ohos.enterprise.adminManager | adminManager | **function** subscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>): Promise<**void**>; | ohos.permission.ENTERPRISE_SUBSCRIBE_MANAGED_EVENT |
| @ohos.enterprise.adminManager | adminManager | **function** unsubscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>, callback: AsyncCallback<**void**>): void; | ohos.permission.ENTERPRISE_SUBSCRIBE_MANAGED_EVENT |
| @ohos.enterprise.adminManager | adminManager | **function** unsubscribeManagedEvent(admin: Want, managedEvents: Array<**ManagedEvent**>): Promise<**void**>; | ohos.permission.ENTERPRISE_SUBSCRIBE_MANAGED_EVENT |
| @ohos.enterprise.dataTimeManager | dateTimeManager | **function** setDateTime(admin: Want, time: number, callback: AsyncCallback<**void**>): void; | ohos.permission.ENTERPRISE_SET_DATETIME |
| @ohos.enterprise.dataTimeManager | dateTimeManager | **function** setDateTime(admin: Want, time: number): Promise<**void**>; | ohos.permission.ENTERPRISE_SET_DATETIME |
**Adaptation Guide**
Apply for the corresponding permission to call these APIs properly.
# Input Method Framework ChangeLog
## cl.inputmethod_frameworks.1 API Error Information Return Method Change
The internal APIs of the following modules used service logic return values to indicate error information, which did not comply with the error code specifications of OpenHarmony. Therefore, they are modified in API version 9 and later.
- Input method framework module: system API, @ohos.inputmethod.d.ts
- Input method service module: system API, @ohos.inputmethodengine.d.ts
- Input method ExtentionAbility module: system API, @ohos.inputmethodextensionability.d.ts
- Input method ExtentionContext module: system API, @ohos.inputmethodextensioncontext.d.ts
- Input method subtype module: system API, @ohos.inputMethodSubtype.d.ts
Asynchronous API: An error message is returned via **AsyncCallback** or the **error** object of **Promise**.
Synchronous API: An error message is returned via an exception.
**Change Impact**
The application developed based on earlier versions needs to adapt the method for returning API error information. Otherwise, the original service logic will be affected.
**Key API/Component Changes**
Error code processing is added for the following APIs:
- getSetting(): InputMethodSetting;
- getController(): InputMethodController;
- switchInputMethod(target: InputMethodProperty, callback: AsyncCallback\<boolean>): void;
- switchInputMethod(target: InputMethodProperty): Promise\<boolean>;
- switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallback\<boolean>): void;
- switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise\<boolean>;
- switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype, callback: AsyncCallback\<boolean>): void;
- switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise\<boolean>;
- listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array\<InputMethodSubtype>>): void;
- listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array\<InputMethodSubtype>>;
- listCurrentInputMethodSubtype(callback: AsyncCallback<Array\<InputMethodSubtype>>): void;
- listCurrentInputMethodSubtype(): Promise<Array\<InputMethodSubtype>>;
- getInputMethods(enable: boolean, callback: AsyncCallback<Array\<InputMethodProperty>>): void;
- getInputMethods(enable: boolean): Promise<Array\<InputMethodProperty>>;
- showOptionalInputMethods(callback: AsyncCallback\<boolean>): void;
- showOptionalInputMethods(): Promise\<boolean>;
- stopInputSession(callback: AsyncCallback\<boolean>): void;
- stopInputSession(): Promise\<boolean>;
- showSoftKeyboard(callback: AsyncCallback\<void>): void;
- showSoftKeyboard():Promise\<void>;
- hideSoftKeyboard(callback: AsyncCallback\<void>): void;
- hideSoftKeyboard():Promise\<void>;
- hide(callback: AsyncCallback\<void>): void;
- hide(): Promise\<void>;
- onCreate(want: Want): void;
- onDestroy(): void;
- In **InputClient**:
- sendKeyFunction(action: number, callback: AsyncCallback\<boolean>): void;
- sendKeyFunction(action: number): Promise\<boolean>;
- deleteForward(length: number, callback: AsyncCallback\<boolean>): void;
- deleteForward(length: number): Promise\<boolean>;
- deleteBackward(length: number, callback: AsyncCallback\<boolean>): void;
- deleteBackward(length: number): Promise\<boolean>;
- insertText(text: string, callback: AsyncCallback\<boolean>): void;
- insertText(text: string): Promise\<boolean>;
- getForward(length: number, callback: AsyncCallback\<string>): void;
- getForward(length: number): Promise\<string>;
- getBackward(length: number, callback: AsyncCallback\<string>): void;
- getBackward(length: number): Promise\<string>;
- getEditorAttribute(callback: AsyncCallback\<EditorAttribute>): void;
- getEditorAttribute(): Promise\EditorAttribute>;
- moveCursor(direction: number, callback: AsyncCallback\<void>): void;
- moveCursor(direction: number): Promise\<void>;
- In **InputMethodExtensionAbility**:
- onCreate(want: Want): void;
- onDestroy(): void;
**Adaptation Guide**
The following uses **showOptionalInputMethods** as an example for asynchronous APIs:
Callback mode:
```js
import inputMethod from '@ohos.inputmethod';
let inputMethodSetting = inputMethod.getSetting();
try {
inputMethodSetting.showOptionalInputMethods((err, data) => {
if (err !== undefined) {
console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in showing optionalInputMethods.');
});
} catch (err) {
console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
}
```
Promise mode:
```js
import inputMethod from '@ohos.inputmethod';
let inputMethodSetting = inputMethod.getSetting();
inputMethodSetting.showOptionalInputMethods().then((data) => {
console.info('Succeeded in showing optionalInputMethods.');
}).catch((err) => {
console.error('Failed to showOptionalInputMethods: ' + JSON.stringify(err));
})
```
## cl.inputmethod_frameworks.2 Deprecation of Some APIs
Deprecated APIs:
- getInputMethodSetting(): InputMethodSetting;
- getInputMethodController(): InputMethodController;
- listInputMethod(callback: AsyncCallback<Array<InputMethodProperty>>): void;
- listInputMethod(): Promise<Array<InputMethodProperty>>;
- displayOptionalInputMethod(callback: AsyncCallback<void>): void;
- displayOptionalInputMethod(): Promise<void>;
- stopInput(callback: AsyncCallback<boolean>): void;
- stopInput(): Promise<boolean>;
interface InputMethodProperty:
- readonly packageName: string;
- readonly methodId: string;
- getInputMethodEngine(): InputMethodEngine;
- createKeyboardDelegate(): KeyboardDelegate;
- hideKeyboard(callback: AsyncCallback<void>): void;
- hideKeyboard(): Promise<void>;
Substitute APIs:
- getSetting(): InputMethodSetting;
- getController(): InputMethodController;
- getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
- getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>;
- showOptionalInputMethods(callback: AsyncCallback<boolean>): void;
- showOptionalInputMethods(): Promise<boolean>;
- stopInputSession(callback: AsyncCallback<boolean>): void;
- stopInputSession(): Promise<boolean>;
interface InputMethodProperty:
- readonly name: string;
- readonly id: string;
- getInputMethodAbility(): InputMethodAbility;
- getKeyboardDelegate(): KeyboardDelegate;
- hide(callback: AsyncCallback<void>): void;
- hide(): Promise<void>;
**NOTE**
Use the **getInputMethodAbility()** API to obtain an **InputMethodAbility** object, and do not use **getInputMethodEngine()** to obtain an **InputMethodEngine** object.
Use methods in **InputMethodAbility**, and do not use methods in **InputMethodEngine**.
Use the **on('inputStart')** method in **InputMethodAbility** to obtain a **KeyboardController** instance and an **InputClient** instance, and do not use the **on('inputStart')** method in **InputMethodEngine** to obtain a **TextInputClient** instance.
Before:
```js
inputMethodEngine.getInputMethodEngine().on('inputStart', (kbController, textClient) => {
let keyboardController = kbController;
let textInputClient = textClient; // Obtain a TextInputClient instance.
});
```
After:
```js
inputMethodEngine.getInputMethodAbility().on('inputStart', (kbController, client) => {
let keyboardController = kbController;
let inputClient = client; // // Obtain an InputClient instance.
});
```
## cl.inputmethod_frameworks.3 Change of Some APIs
Before change:
- listInputMethod(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
- listInputMethod(enable: boolean): Promise<Array<InputMethodProperty>>;
- terminateSelf(callback: AsyncCallback<void>): void;
- terminateSelf(): Promise<void>;
After change:
- getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void;
- getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>;
- destroy(callback: AsyncCallback<void>): void;
- destroy(): Promise<void>;
Deleted APIs in API version 9:
- startAbility(want: Want, callback: AsyncCallback<void>): void;
- startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void;
- startAbility(want: Want, options?: StartOptions): Promise<void>;
Added APIs:
- on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void;
- off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void;
- interface InputMethodProperty:
- readonly label?: string;
- readonly icon?: string;
- readonly iconId?: number;
- extra: object;
- interface InputMethodAbility:
- on(type: 'setSubtype', callback: (inputMethodSubtype: InputMethodSubtype) => void): void;
- off(type: 'setSubtype', callback?: (inputMethodSubtype: InputMethodSubtype) => void): void;
# Common Event and Notification Subsystem ChangeLog
## cl.notification.1 API Exception Handling Method Changes
Certain event notification APIs use service logic return values to indicate error information, which does not comply with the API error code specifications of OpenHarmony.
**Change Impacts**
The application developed based on earlier versions needs to adapt the new APIs and their method for returning API error information. Otherwise, the original service logic will be affected.
**Key API/Component Changes**
For adaptation to the unified API exception handling mode, certain event notification APIs are deprecated (original APIs in the following table) and corresponding new APIs in the following table are added. The newly added APIs support unified error code handling specifications and function the same as the original APIs.
| Original API | New API |
| ----------------------- | -------------------------------- |
| @ohos.commonEvent.d.ts | @ohos.commonEventManager.d.ts |
| @ohos.notification.d.ts | @ohos.notificationManager.d.ts |
| @ohos.notification.d.ts | @ohos.notificationSubscribe.d.ts |
**Adaptation Guide**
The original APIs are only migrated to the new namespace. Therefore, you can modify **import** to solve the adaptation problem.
If the original API uses **@ohos.commonEvent**:
```js
import commonEvent from '@ohos.commonEvent';
```
You can directly modify **import** to switch to the new namespace:
```js
import commonEvent from '@ohos.commonEventManager';
```
**@ohos.notification** is split into two namespaces. You need to select a new namespace for adaptation.
In addition, exception handling is needed. For details, see the API reference for the new APIs.
## cl.notification.2 API Changes
The names of some event notification APIs are changed.
**Key API/Component Changes**
| Module | Class | Method/Attribute/Enumeration/Constant | Change Type|
| ------------------------- | ------------------- | ------------------------------------------------------------ | -------- |
| @ohos.notification | notification | **function** enableNotification(bundle: BundleOption, enable: boolean, callback: AsyncCallback<**void**>): **void**; | Deprecated |
| @ohos.notification | notification | **function** enableNotification(bundle: BundleOption, enable: boolean): Promise<**void**>; | Deprecated |
| @ohos.notificationManager | notificationManager | **function** setNotificationEnable(bundle: BundleOption, enable: boolean, callback: AsyncCallback<**void**>): **void**; | Added |
| @ohos.notificationManager | notificationManager | **function** setNotificationEnable(bundle: BundleOption, enable: boolean): Promise<**void**>; | Added |
| @ohos.notification | notification | **function** enableNotificationSlot(bundle: BundleOption, **type**: SlotType, enable: boolean, callback: AsyncCallback<**void**>): **void**; | Deprecated |
| @ohos.notification | notification | **function** enableNotificationSlot(bundle: BundleOption, **type**: SlotType, enable: boolean): Promise<**void**>; | Deprecated |
| @ohos.notificationManager | notificationManager | **function** setNotificationEnableSlot(bundle: BundleOption, **type**: SlotType, enable: boolean, callback: AsyncCallback<**void**>): **void**; | Added |
| @ohos.notificationManager | notificationManager | **function** setNotificationEnableSlot(bundle: BundleOption, **type**: SlotType, enable: boolean): Promise<**void**>; | Added |
| @ohos.notification | notification | **function** enableDistributed(enable: boolean, callback: AsyncCallback<**void**>): **void**; | Deprecated |
| @ohos.notification | notification | **function** enableDistributed(enable: boolean, callback: AsyncCallback<**void**>): **void**; | Deprecated |
| @ohos.notificationManager | notificationManager | **function** setDistributedEnable(enable: boolean, callback: AsyncCallback<**void**>): **void**; | Added |
| @ohos.notificationManager | notificationManager | **function** setDistributedEnable(enable: boolean): Promise<**void**>; | Added |
| @ohos.notification | notification | **function** enableDistributedByBundle(bundle: BundleOption, enable: boolean, callback: AsyncCallback<**void**>): **void**; | Deprecated |
| @ohos.notification | notification | **function** enableDistributedByBundle(bundle: BundleOption, enable: boolean): Promise<**void**>; | Deprecated |
| @ohos.notificationManager | notificationManager | **function** setDistributedEnableByBundle(bundle: BundleOption, enable: boolean, callback: AsyncCallback<**void**>): **void**; | Added |
| @ohos.notificationManager | notificationManager | **function** setDistributedEnableByBundle(bundle: BundleOption, enable: boolean): Promise<**void**>; | Added |
# Theme Framework ChangeLog
## cl.theme.1 Support of Exception Handling for APIs in API Version 9
The internal APIs of the following modules used service logic return values to indicate error information, which did not comply with the error code specifications of OpenHarmony. Therefore, they are modified in API version 9 and later.
- Wallpaper management service: **@ohos.wallpaper.d.ts**
- Lock screen management service: **@ohos.screenLock.d.ts**
APIs in the preceding modules are changed as follows:
Synchronous API: An error message is returned via an exception.
Asynchronous API: A parameter check error is returned synchronously. A service logic error is returned via **AsyncCallback** or the **error** object of **Promise**.
**Change Impacts**
The application developed based on earlier versions needs to adapt the method for returning API error information. Otherwise, the original service logic will be affected.
**Key API/Component Changes**
Deprecated APIs of the wallpaper management service:
- getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): void;
- getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>>;
- getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void;
- getId(wallpaperType: WallpaperType): Promise<number>;
- getMinHeight(callback: AsyncCallback<number>): void;
- getMinHeight(): Promise<number>;
- getMinWidth(callback: AsyncCallback<number>): void;
- getMinWidth(): Promise<number>;
- isChangePermitted(callback: AsyncCallback<boolean>): void;
- isChangePermitted(): Promise<boolean>;
- isOperationAllowed(callback: AsyncCallback<boolean>): void;
- isOperationAllowed(): Promise<boolean>;
- reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
- reset(wallpaperType: WallpaperType): Promise<void>;
- setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
- setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>;
- getFile(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void;
- getFile(wallpaperType: WallpaperType): Promise<number>;
- getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void;
- getPixelMap(wallpaperType: WallpaperType): Promise<image.PixelMap>;
Substitute APIs of the wallpaper management service:
- getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>;
- getIdSync(wallpaperType: WallpaperType): number;
- getMinHeightSync(): number;
- getMinWidthSync(): number;
- isChangeAllowed(): boolean;
- isUserChangeAllowed(): boolean;
- restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
- restore(wallpaperType: WallpaperType): Promise<void>;
- setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void;
- setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>;
- getFileSync(wallpaperType: WallpaperType): number;
- getImage(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void;
- getImage(wallpaperType: WallpaperType): Promise<image.PixelMap>;
Changed APIs of the wallpaper management service:
- on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void
- off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void
Deprecated APIs of the lock screen management service:
- isScreenLocked(callback: AsyncCallback<boolean>): void;
- isScreenLocked(): Promise<boolean>;
- isSecureMode(callback: AsyncCallback<boolean>): void;
- isSecureMode(): Promise<boolean>;
- unlockScreen(callback: AsyncCallback<void>): void;
- unlockScreen(): Promise<void>;
Substitute APIs of the lock screen management service:
- isLocked(): boolean;
- isSecure(): boolean;
- unlock(callback: AsyncCallback<boolean>): void;
- unlock():Promise<boolean>;
Deleted APIs of the lock screen management service:
- lockScreen(callback: AsyncCallback<void>): void;
- lockScreen(): Promise<void>;
The following APIs are added for the lock screen management service:
- lock(callback: AsyncCallback<boolean>): void;
- lock():Promise<boolean>;
Changed APIs of the lock screen management service:
- onSystemEvent(callback: Callback<SystemEvent>): boolean;
- sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void;
- sendScreenLockEvent(event: String, parameter: number): Promise<boolean>;
**Adaption Guide for the Wallpaper Management Service**
The following uses **getImage** as an example for asynchronous APIs:
```ts
import pointer from '@ohos.wallpaper';
try {
wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getImage: ${JSON.stringify(data)}`);
}).catch((error) => {
console.error(`failed to getImage because: ${JSON.stringify(error)}`);
});
} catch (err) {
console.error(`failed to getImage because: ${JSON.stringify(err)}`);
}
```
The following uses **getFileSync** as an example for synchronous APIs:
```ts
import pointer from '@ohos.wallpaper';
try {
let file = wallpaper.getFileSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
} catch (err) {
console.error(`failed to getFileSync because: ${err.message}`);
}
```
**Adaption Guide for the Lock Screen Management Service**
The following uses **lock** as an example for asynchronous APIs:
```ts
import screenLock from '@ohos.screenlock';
try {
screenLock.lock((err, data) => {
if (err) {
console.error(`Failed to lock the screen, because: ${err.message}`);
return;
}
console.info(`lock the screen successfully. result: ${data}`);
});
} catch (err) {
console.error(`Failed to lock the screen, because: ${err.message}`);
}
```
The following uses **onSystemEvent** as an example for synchronous APIs:
```ts
import screenLock from '@ohos.screenlock';
try {
let isSuccess = screenLock.onSystemEvent((event) => {
console.log(`Register the system event which related to screenlock successfully. eventType: ${event.eventType}`)
});
} catch (err) {
console.error(`Failed to register the system event which related to screenlock, because: ${err.message}`)
}
```
# Web Subsystem ChangeLog
## cl.web.1 Deletion of Unnecessary Error Codes
APIs in the webviewController component of the web subsystem are changed:
- Deleted **@throws { BusinessError } 17100007 - Invalid back or forward operation** from the **forward**, **backward**, and **backOrForward** APIs.
- Deleted **@throws { BusinessError } 17100009 - Cannot zoom in or zoom out** from the **zoom**, **zoomIn**, and **zoomOut** APIs.
You need to adapt your application based on the following information.
**Change Impacts**
Released JS APIs are affected. The application can be properly compiled in the SDK environment of the new version, without any adaptation.
**Key API/Component Changes**
Involved APIs: **forward**, **backward**, **backOrForward**, **zoom**, **zoomIn**, and **zoomOut**
Involved component: web
**Adaptation Guide**
No adaptation is required.
## cl.web.2 setWebController Input Parameter Changes
Some released web controllers are migrated to the webviewController, and the original webController is deprecated. The following changes are made in API version 9 and later:
The input parameter of **setWebController** is replaced by the new **webviewController**.
**Change Impacts**
Input parameters of JS APIs need to be adapted for applications developed based on earlier versions. Otherwise, relevant functions will be affected.
**Key API/Component Changes**
- Involved API:
setWebController(controller: WebviewController): void;
- Before change:
```js
setWebController(controller: WebController): void;
```
- After change:
```js
setWebController(controller: WebviewController): void;
```
**Adaptation Guide**
The sample code is as follows:
Before change:
```js
// xxx.ets
@Entry
@Component
struct WebComponent {
controller:WebController = new WebController()
build() {
Column() {
Web({ src:'www.example.com', controller: this.controller })
.multiWindowAccess(true)
.onWindowNew((event) => {
console.log("onWindowNew...")
var popController: WebController = new WebController()
event.handler.setWebController(popController)
})
}
}
}
```
After change:
```js
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: web_webview.WebviewController = new web_webview.WebviewController()
build() {
Column() {
Web({ src:'www.example.com', controller: this.controller })
.multiWindowAccess(true)
.onWindowNew((event) => {
console.log("onWindowNew...")
var popController: web_webview.WebviewController = new web_webview.WebviewController()
event.handler.setWebController(popController)
})
}
}
}
```
## cl.web.3 getUnfilterendLinkUrl API Name Change
The **getUnfilterendLinkUrl** API is misspelled and should be changed to **getUnfilteredLinkUrl**.
**Change Impacts**
The JS API name needs to be adapted for applications developed based on earlier versions. Otherwise, relevant functions will be affected.
**Key API/Component Changes**
- Involved API:
getUnfilteredLinkUrl(): string;
- Before change:
```js
getUnfilterendLinkUrl(): string;
```
- After change:
```js
getUnfilteredLinkUrl(): string;
```
**Adaptation Guide**
The JS API name needs to be adapted for applications developed based on earlier versions. The new API name is used to replace the original one. Otherwise, relevant functions will be affected.
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册