@@ -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:
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)
@@ -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.
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.
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.
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.
| 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.
@@ -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.|
| 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.
| 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).
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.
| 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).
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.
| type | string | Yes | Event type. The value is fixed at 'privateModeChange', indicating the event of display privacy mode changes.|
| callback | Callback<boolean> | 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.|
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.
| type | string | Yes | Event type. The value is fixed at **'privateModeChange'**, indicating the event of display private mode changes.|
| callback | Callback<boolean> | 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));
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.
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**.|
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.
| callback | AsyncCallback<boolean> | 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
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.
| [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<boolean> | 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
| 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<[Movement](./js-apis-inputmethod-InputMethodCommon.md#movement)> | 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.|
| inputMethodProperty | InputMethodProperty| Yes| Input method to which the subtypes belong.|
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Yes| Callback used to return all subtypes of the specified input method.|
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | 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
| 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
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | Yes | Callback used to return all subtypes of the current input method.|
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md)>> | 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
| 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.|
@@ -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.
| 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.|
| 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.|
| 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).|
| 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. |
| 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.|
| 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.
| 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.
| onComplete(callback: (event?: { width: number, height: number, componentWidth: number,<br> componentHeight: number, loadingStatus: number }) => 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 }) => 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: () => 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 }) => 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 }) => 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: () => 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';
| 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.|
| 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. |
@@ -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.|
| 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.|
| 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
| onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.<br>- **value**: text entered. |
| onCopy<sup>8+</sup>(callback:(value: string) => 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) => 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) => 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) => 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) => 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) => 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) => 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...',
| 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
| 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) => 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.|
| 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
| onChange(callback: (value: string) => void) | Triggered when the input changes.<br>**value**: text content.|
| onSubmit(callback: (enterKey: EnterKeyType) => 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) => void)<sup>(deprecated)</sup> | Triggered when the input status changes. Since API version 8, **onEditChange** is recommended.|
| onEditChange(callback: (isEditing: boolean) => 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) => 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) => 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) => 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) => 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) => 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) => void)<sup>(deprecated)</sup> | Triggered when the input status changes. Since API version 8, **onEditChange** is recommended.|
| onEditChange(callback: (isEditing: boolean) => 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) => 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) => 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) => 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})
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.|
| 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) => 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) => 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. |
| 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.
| 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.|
@@ -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.|
| 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.|
| bindMenu | Array<[MenuItem](#menuitem)>\|[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)>\|[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.|
| 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 | () => void | No| Callback triggered when the menu is displayed.|
| onDisappear | () => void | No| Callback triggered when the menu is hidden.|
| 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 | () => void | No | Callback triggered when the menu is displayed. |
| onDisappear | () => void | No | Callback triggered when the menu is hidden. |
| 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.
| 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><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><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.
@@ -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).
## @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.
## @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.
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.
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.
# 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:
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:
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
structIndex{
@Statemessage: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
exportfunctionfunc(){
return"[ohpm] func1";
}
```
On other JavaScript/TypeScript pages, use **import** to import the exported methods. The sample code is as follows:
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.
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)
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.
