diff --git a/en/application-dev/application-models/common-event-static-subscription.md b/en/application-dev/application-models/common-event-static-subscription.md index 7005c86ae2e29eb7c635f55b5da05f658ccd8360..465fc236129d4c78967e6122c318132933043fb6 100644 --- a/en/application-dev/application-models/common-event-static-subscription.md +++ b/en/application-dev/application-models/common-event-static-subscription.md @@ -2,9 +2,7 @@ ## When to Use -A static subscriber is started once it receives a target event published by the system or application. At the same time, the [onReceiveEvent()](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent) callback is triggered. - -You can implement the service logic in the [onReceiveEvent()](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent) callback. For example, if an application needs to execute some initialization tasks during device power-on, the application can subscribe to the power-on event in static mode. After receiving the power-on event, the application is started to execute the initialization tasks. +A static subscriber is started once it receives a target event published by the system or application. At the same time, the [onReceiveEvent()](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent) callback is triggered, in which you can implement the service logic. For example, if an application needs to execute some initialization tasks during device power-on, the application can subscribe to the power-on event in static mode. After receiving the power-on event, the application is started to execute the initialization tasks. Subscribing to a common event in static mode is achieved by configuring a declaration file and implementing a class that inherits from [StaticSubscriberExtensionAbility](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md). @@ -18,7 +16,7 @@ Subscribing to a common event in static mode is achieved by configuring a declar To declare a static subscriber, create an ExtensionAbility, which is derived from the **StaticSubscriberExtensionAbility** class, in the project. - You can implement service logic in the **onReceiveEvent()** callback. + You can implement service logic in the [**onReceiveEvent()**](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent) callback. ```ts import StaticSubscriberExtensionAbility from '@ohos.application.StaticSubscriberExtensionAbility' @@ -93,23 +91,24 @@ Subscribing to a common event in static mode is achieved by configuring a declar - **permission**: permission required for the publisher. If a publisher without the required permission attempts to publish an event, the event is regarded as invalid and will not be published. - **events**: list of target events to subscribe to. -4. Modify the [preset configuration file](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json) of the device, that is, the **/system/etc/app/install_list_permission.json** file on the device. When the device is started, this file is read. During application installation, the common event type specified by **allowCommonEvent** in the file is authorized. The **install_list_permission.json** file contains the following fields: +4. Modify the [preset configuration file](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_capability.json) of the device, that is, the **/system/etc/app/install_list_capability.json** file on the device. When the device is started, this file is read. During application installation, the common event type specified by **allowCommonEvent** in the file is authorized. The **install_list_capability.json** file contains the following fields: - **bundleName**: bundle name of the application. - - **app_signature**: fingerprint information of the application. For details, see [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md#configuration-in-install_list_capabilityjson). + - **app_signature**: fingerprint information of the application. For details, see [Configuration in install_list_capability.json](../../device-dev/subsystems/subsys-app-privilege-config-guide.md#configuration-in-install_list_capabilityjson). - **allowCommonEvent**: type of common event that can be started by static broadcast. - > **NOTE** - > - > The **install_list_permissions.json** file is available only for preinstalled applications. - ```json [ + ... { - "bundleName": "com.example.myapplication", - "app_signature": ["****"], - "allowCommonEvent": ["usual.event.A", "usual.event.B"] + "bundleName": "com.example.myapplication", // Bundle name. + "app_signature": ["****"], // Fingerprint information. + "allowCommonEvent": ["usual.event.A", "usual.event.B"] // Type of common event that can be started by static broadcast. } ] ``` + + > **NOTE** + > + > The **install_list_capability.json** file is available only for preinstalled applications. diff --git a/en/application-dev/reference/apis/js-apis-animator.md b/en/application-dev/reference/apis/js-apis-animator.md index 5eb3e73a20a45f459f1879b49cfc4c9743c22fa7..ca8c254cc2920df317a9c9b5d5cce55f3efa852d 100644 --- a/en/application-dev/reference/apis/js-apis-animator.md +++ b/en/application-dev/reference/apis/js-apis-animator.md @@ -7,7 +7,10 @@ The **Animator** module provides APIs for applying animation effects, including > The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > > This module can be used only after a component instance is created, and it cannot be used in the [UIAbility](./js-apis-app-ability-uiAbility.md). - +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](./js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [createAnimator](./js-apis-arkui-UIContext.md#createanimator) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. ## Modules to Import diff --git a/en/application-dev/reference/apis/js-apis-arkui-UIContext.md b/en/application-dev/reference/apis/js-apis-arkui-UIContext.md new file mode 100644 index 0000000000000000000000000000000000000000..8afcf3acf26dfff247c8a9f6831543ac12658b2f --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-arkui-UIContext.md @@ -0,0 +1,1691 @@ +# @ohos.arkui.UIContext (UIContext) + +In the stage model, a window stage or window can use the **loadContent** API to load pages, create a UI instance, and render page content to the associated window. Naturally, UI instances and windows are associated on a one-by-one basis. Some global UI APIs are executed in the context of certain UI instances. When calling these APIs, you must identify the UI context, and consequently UI instance, by tracing the call chain. If these APIs are called on a non-UI page or in some asynchronous callback, the current UI context may fail to be identified, resulting in failure in API execution. + +**@ohos.window** adds the [getUIContext](./js-apis-window.md#getuicontext10) API in API version 10 for obtaining the **UIContext** object of a UI instance. The API provided by the **UIContext** object can be directly applied to the corresponding UI instance. + +> **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. + +## UIContext + +In the following API examples, you must first use [getUIContext()](./js-apis-window.md#getuicontext10) in **@ohos.window** to obtain a **UIContext** instance, and then call the APIs using the obtained instance. In this document, the **UIContext** instance is represented by **uiContext**. + +### getFont + +getFont(): Font + +Obtains a **Font** object. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type | Description | +| ----- | ----------------- | +| [Font](#font) | **Font** object.| + +**Example** + +```ts +uiContext.getFont(); +``` + +### getMediaQuery + +getMediaQuery(): MediaQuery + +Obtains a **MediaQuery** object. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type | Description | +| ----- | ----------------- | +| [MediaQuery](#mediaquery) | **MediaQuery** object.| + +**Example** + +```ts +uiContext.getMediaQuery(); +``` + +### getRouter + +getRouter(): Router + +Obtains a **Router** object. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type | Description | +| ----- | ----------------- | +| [Router](#router) | **Router** object.| + +**Example** + +```ts +uiContext.getRouter(); +``` + +### getPromptAction + +getPromptAction(): PromptAction + +Obtains a **PromptAction** object. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type | Description | +| ----- | ----------------- | +| [PromptAction](#promptaction) | **PromptAction** object.| + +**Example** + +```ts +uiContext.getPromptAction(); +``` + +### animateTo + +animateTo(value: AnimateParam, event: () => void): void + +Applies a transition animation for state changes. + +Since API version 9, this API is supported in ArkTS widgets. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---------------- | ------------ | -------------------- | -------------------- | +| value | [AnimateParam](../arkui-ts/ts-explicit-animation.md#animateparam) | Yes| Animation settings.| +| event | () => void | Yes| Closure function that displays the dynamic effect. The system automatically inserts the transition animation if the status changes in the closure function.| + +**Example** + +```ts +// xxx.ets +@Entry +@Component +struct AnimateToExample { + @State widthSize: number = 250 + @State heightSize: number = 100 + @State rotateAngle: number = 0 + private flag: boolean = true + + build() { + Column() { + Button('change size') + .width(this.widthSize) + .height(this.heightSize) + .margin(30) + .onClick(() => { + if (this.flag) { + uiContext.animateTo({ + duration: 2000, + curve: Curve.EaseOut, + iterations: 3, + playMode: PlayMode.Normal, + onFinish: () => { + console.info('play end') + } + }, () => { + this.widthSize = 150 + this.heightSize = 60 + }) + } else { + uiContext.animateTo({}, () => { + this.widthSize = 250 + this.heightSize = 100 + }) + } + this.flag = !this.flag + }) + Button('change rotate angle') + .margin(50) + .rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle }) + .onClick(() => { + uiContext.animateTo({ + duration: 1200, + curve: Curve.Friction, + delay: 500, + iterations: -1, // The value -1 indicates that the animation is played for an unlimited number of times. + playMode: PlayMode.Alternate, + onFinish: () => { + console.info('play end') + } + }, () => { + this.rotateAngle = 90 + }) + }) + }.width('100%').margin({ top: 5 }) + } +} +``` + +### showAlertDialog + +showAlertDialog(options: AlertDialogParamWithConfirm | AlertDialogParamWithButtons): void + +Shows an alert dialog box. + +**Parameters** + +| Name | Type | Description| +| ---- | --------------- | -------- | +| options | [AlertDialogParamWithConfirm](../arkui-ts/ts-methods-alert-dialog-box.md#alertdialogparamwithconfirm) \| [AlertDialogParamWithButtons](../arkui-ts/ts-methods-alert-dialog-box.md#alertdialogparamwithbuttons) | Defines and displays the **\** component.| + +**Example** + +```ts +uiContext.showAlertDialog( + { + title: 'title', + message: 'text', + autoCancel: true, + alignment: DialogAlignment.Bottom, + offset: { dx: 0, dy: -20 }, + gridCount: 3, + confirm: { + value: 'button', + action: () => { + console.info('Button-clicking callback') + } + }, + cancel: () => { + console.info('Closed callbacks') + } + } +) +``` + +### showActionSheet + +showActionSheet(value: ActionSheetOptions): void + +Defines and shows the action sheet. + +**ActionSheetOptions parameters** + +| Name | Type | Mandatory | Description | +| ---------- | -------------------------- | ------- | ----------------------------- | +| title | [Resource](../arkui-ts/ts-types.md#resource) \| string | Yes | Title of the dialog box.| +| message | [Resource](../arkui-ts/ts-types.md#resource) \| string | Yes | Content of the dialog box. | +| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.
Default value: **true**| +| confirm | {
value: [ResourceStr](../arkui-ts/ts-types.md#resourcestr),
action: () => void
} | No | Text content of the confirm button and callback upon button clicking.
Default value:
**value**: button text.
**action**: callback upon button clicking.| +| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked. | +| alignment | [DialogAlignment](../arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.
Default value: **DialogAlignment.Bottom**| +| offset | {
dx: [Length](../arkui-ts/ts-types.md#length),
dy: [Length](../arkui-ts/ts-types.md#length)
} | No | Offset of the dialog box relative to the alignment position.{
dx: 0,
dy: 0
} | +| sheets | Array<SheetInfo> | Yes | Options in the dialog box. Each option supports the image, text, and callback.| + +**SheetInfo parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------------------------------------------------------ | ---- | ----------------- | +| title | [ResourceStr](../arkui-ts/ts-types.md#resourcestr) | Yes | Text of the option. | +| icon | [ResourceStr](../arkui-ts/ts-types.md#resourcestr) | No | Sheet icon. By default, no icon is displayed. | +| action | ()=>void | Yes | Callback when the sheet is selected.| + +**Example** + +```ts +uiContext.showActionSheet({ + title: 'ActionSheet title', + message: 'message', + autoCancel: true, + confirm: { + value: 'Confirm button', + action: () => { + console.log('Get Alert Dialog handled') + } + }, + cancel: () => { + console.log('actionSheet canceled') + }, + alignment: DialogAlignment.Bottom, + offset: { dx: 0, dy: -10 }, + sheets: [ + { + title: 'apples', + action: () => { + console.log('apples') + } + }, + { + title: 'bananas', + action: () => { + console.log('bananas') + } + }, + { + title: 'pears', + action: () => { + console.log('pears') + } + } + ] +}) +``` + +### showDatePickerDialog + +showDatePickerDialog(options: DatePickerDialogOptions): void + +Shows a date picker dialog box. + +**DatePickerDialogOptions parameters** + +| Name| Type| Mandatory| Default Value| Description| +| -------- | -------- | -------- | -------- | -------- | +| start | Date | No| Date('1970-1-1') | Start date of the picker.| +| 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 | boolean | No| false | Whether to display the time item.| +| useMilitaryTime | boolean | No| false | Whether to display time in 24-hour format.| +| disappearTextStyle | [PickerTextStyle](../arkui-ts/ts-basic-components-datepicker.md#pickertextstyle10) | No| - | Font color, font size, and font width for the top and bottom items.| +| textStyle | [PickerTextStyle](../arkui-ts/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 | [PickerTextStyle](../arkui-ts/ts-basic-components-datepicker.md#pickertextstyle10) | No| - | Font color, font size, and font width of the selected item.| +| onAccept | (value: [DatePickerResult](../arkui-ts/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](../arkui-ts/ts-basic-components-datepicker.md#datepickerresult)) => void | No| - | Callback invoked when the selected item in the picker changes.| + +**Example** + +```ts +let selectedDate: Date = new Date("2010-1-1") +uiContext.showDatePickerDialog({ + start: new Date("2000-1-1"), + end: new Date("2100-12-31"), + selected: selectedDate, + onAccept: (value: DatePickerResult) => { + // Use the setFullYear method to set the date when the OK button is touched. In this way, when the date picker dialog box is displayed again, the selected date is the date last confirmed. + selectedDate.setFullYear(value.year, value.month, value.day) + console.info("DatePickerDialog:onAccept()" + JSON.stringify(value)) + }, + onCancel: () => { + console.info("DatePickerDialog:onCancel()") + }, + onChange: (value: DatePickerResult) => { + console.info("DatePickerDialog:onChange()" + JSON.stringify(value)) + } +}) +``` + +### showTimePickerDialog + +showTimePickerDialog(options: TimePickerDialogOptions): void + +Shows a time picker dialog box. + +**TimePickerDialogOptions parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| selected | Date | No| Selected time.
Default value: current system time| +| useMilitaryTime | boolean | No| Whether to display time in 24-hour format. The 12-hour format is used by default.
Default value: **false**| +| disappearTextStyle | [PickerTextStyle](../arkui-ts/ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.| +| textStyle | [PickerTextStyle](../arkui-ts/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 | [PickerTextStyle](../arkui-ts/ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.| +| onAccept | (value: [TimePickerResult](../arkui-ts/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](../arkui-ts/ts-basic-components-timepicker.md#timepickerresult)) => void | No| Callback invoked when the selected time changes.| + +**Example** + +```ts +let selectTime: Date = new Date('2020-12-25T08:30:00') +uiContext.showTimePickerDialog({ + selected: this.selectTime, + onAccept: (value: TimePickerResult) => { + // Set selectTime to the time when the OK button is clicked. In this way, when the dialog box is displayed again, the selected time is the time when the operation was confirmed last time. + this.selectTime.setHours(value.hour, value.minute) + console.info("TimePickerDialog:onAccept()" + JSON.stringify(value)) + }, + onCancel: () => { + console.info("TimePickerDialog:onCancel()") + }, + onChange: (value: TimePickerResult) => { + console.info("TimePickerDialog:onChange()" + JSON.stringify(value)) + } +}) +``` + +### showTextPickerDialog + +showTextPickerDialog(options: TextPickerDialogOptions): void + +Shows a text picker in the given settings. + +**TextPickerDialogOptions parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| range | string[] \| [Resource](../arkui-ts/ts-types.md#resource)\|[TextPickerRangeContent](../arkui-ts/ts-basic-components-textpicker.md#textpickerrangecontent10)[] | 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.
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 | [PickerTextStyle](../arkui-ts/ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.| +| textStyle | [PickerTextStyle](../arkui-ts/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 | [PickerTextStyle](../arkui-ts/ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.| +| onAccept | (value: [TextPickerResult](../arkui-ts/ts-methods-textpicker-dialog.md#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](../arkui-ts/ts-methods-textpicker-dialog.md#textpickerresult)) => void | No| Callback invoked when the selected item changes.| + +**Example** + +```ts +let select: number = 2 +let fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] +uiContext.showTextPickerDialog({ + range: this.fruits, + selected: this.select, + onAccept: (value: TextPickerResult) => { + // Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed. + this.select = value.index + console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) + }, + onCancel: () => { + console.info("TextPickerDialog:onCancel()") + }, + onChange: (value: TextPickerResult) => { + console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) + } +}) +``` + +### createAnimator + +createAnimator(options: AnimatorOptions): AnimatorResult + +Creates an **Animator** object. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ----------------------------------- | ---- | ------- | +| options | [AnimatorOptions](./js-apis-animator.md#animatoroptions) | Yes | Animator options.| + +**Return value** + +| Type | Description | +| --------------------------------- | ------------- | +| [AnimatorResult](./js-apis-animator.md#animatorresult) | Animator result.| + +**Example** + +```ts +let options = { + duration: 1500, + easing: "friction", + delay: 0, + fill: "forwards", + direction: "normal", + iterations: 3, + begin: 200.0, + end: 400.0 +}; +uiContext.createAnimator(options); +``` + +### runScopedTask + +runScopedTask(callback: () => void): void + +Executes the specified callback in this UI context. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ----------------------------------- | ---- | ------- | +| callback | () => void | Yes | Callback used to return the result.| + +**Example** + +```ts +uiContext.runScopedTask( + () => { + console.log('Succeeded in runScopedTask'); + } +); +``` + +## Font + +In the following API examples, you must first use [getFont()](#getfont) in **UIContext** to obtain a **Font** instance, and then call the APIs using the obtained instance. + +### registerFont + +registerFont(options: FontOptions): void + +Registers a custom font with the font manager. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | --------------------------- | ---- | ----------- | +| options | [FontOptions](js-apis-font.md#fontoptions) | Yes | Information about the custom font to register.| + +**Example** + +```ts +let font = uiContext.getFont(); +font.registerFont({ + familyName: 'medium', + familySrc: '/font/medium.ttf' +}); +``` + +## MediaQuery + +In the following API examples, you must first use [getMediaQuery()](#getmediaquery) in **UIContext** to obtain a **MediaQuery** instance, and then call the APIs using the obtained instance. + +### matchMediaSync + +matchMediaSync(condition: string): MediaQueryListener + +Sets the media query criteria and returns the corresponding listening handle. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ------ | ---- | ---------------------------------------- | +| condition | string | Yes | Media query condition. For details, see [Syntax](../../ui/arkts-layout-development-media-query.md#syntax).| + +**Return value** + +| Type | Description | +| ------------------ | ---------------------- | +| MediaQueryListener | Listening handle to a media event, which is used to register or deregister the listening callback.| + +**Example** + +```ts +let mediaquery = uiContext.getMediaQuery(); +let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events. +``` + +## Router + +In the following API examples, you must first use [getRouter()](#getrouter) in **UIContext** to obtain a **Router** instance, and then call the APIs using the obtained instance. + +### pushUrl + +pushUrl(options: RouterOptions): Promise<void> + +Navigates to a specified page in the application. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | --------- | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100002 | if the uri is not exist. | +| 100003 | if the pages are pushed too much. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushUrl({ + url: 'pages/routerpage2', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}) + .then(() => { + // success + }) + .catch(err => { + console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### pushUrl + +pushUrl(options: RouterOptions, callback: AsyncCallback<void>): void + +Navigates to a specified page in the application. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | --------- | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100002 | if the uri is not exist. | +| 100003 | if the pages are pushed too much. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushUrl({ + url: 'pages/routerpage2', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, (err) => { + if (err) { + console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('pushUrl success'); +}) +``` + +### pushUrl + +pushUrl(options: RouterOptions, mode: RouterMode): Promise<void> + +Navigates to a specified page in the application. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100002 | if the uri is not exist. | +| 100003 | if the pages are pushed too much. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushUrl({ + url: 'pages/routerpage2', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, router.RouterMode.Standard) + .then(() => { + // success + }) + .catch(err => { + console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### pushUrl + +pushUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void + +Navigates to a specified page in the application. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100002 | if the uri is not exist. | +| 100003 | if the pages are pushed too much. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushUrl({ + url: 'pages/routerpage2', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, router.RouterMode.Standard, (err) => { + if (err) { + console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('pushUrl success'); +}) +``` + +### replaceUrl + +replaceUrl(options: RouterOptions): Promise<void> + +Replaces the current page with another one in the application and destroys the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found, only throw in standard system. | +| 200002 | if the uri is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceUrl({ + url: 'pages/detail', + params: { + data1: 'message' + } +}) + .then(() => { + // success + }) + .catch(err => { + console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### replaceUrl + +replaceUrl(options: RouterOptions, callback: AsyncCallback<void>): void + +Replaces the current page with another one in the application and destroys the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found, only throw in standard system. | +| 200002 | if the uri is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceUrl({ + url: 'pages/detail', + params: { + data1: 'message' + } +}, (err) => { + if (err) { + console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('replaceUrl success'); +}) +``` + +### replaceUrl + +replaceUrl(options: RouterOptions, mode: RouterMode): Promise<void> + +Replaces the current page with another one in the application and destroys the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if can not get the delegate, only throw in standard system. | +| 200002 | if the uri is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceUrl({ + url: 'pages/detail', + params: { + data1: 'message' + } +}, router.RouterMode.Standard) + .then(() => { + // success + }) + .catch(err => { + console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### replaceUrl + +replaceUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void + +Replaces the current page with another one in the application and destroys the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Lite + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found, only throw in standard system. | +| 200002 | if the uri is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceUrl({ + url: 'pages/detail', + params: { + data1: 'message' + } +}, router.RouterMode.Standard, (err) => { + if (err) { + console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('replaceUrl success'); +}); +``` + +### pushNamedRoute + +pushNamedRoute(options: NamedRouterOptions): Promise<void> + +Navigates to a page using the named route. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | --------- | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}) + .then(() => { + // success + }) + .catch(err => { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### pushNamedRoute + +pushNamedRoute(options: NamedRouterOptions, callback: AsyncCallback<void>): void + +Navigates to a page using the named route. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | --------- | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, (err) => { + if (err) { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('pushNamedRoute success'); +}) +``` +### pushNamedRoute + +pushNamedRoute(options: NamedRouterOptions, mode: RouterMode): Promise<void> + +Navigates to a page using the named route. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, router.RouterMode.Standard) + .then(() => { + // success + }) + .catch(err => { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### pushNamedRoute + +pushNamedRoute(options: NamedRouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void + +Navigates to a page using the named route. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, router.RouterMode.Standard, (err) => { + if (err) { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('pushNamedRoute success'); +}) +``` + +### replaceNamedRoute + +replaceNamedRoute(options: NamedRouterOptions): Promise<void> + +Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}) + .then(() => { + // success + }) + .catch(err => { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### replaceNamedRoute + +replaceNamedRoute(options: NamedRouterOptions, callback: AsyncCallback<void>): void + +Replaces the current page with another one using the named route and destroys the current page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}, (err) => { + if (err) { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('replaceNamedRoute success'); +}) +``` + +### replaceNamedRoute + +replaceNamedRoute(options: NamedRouterOptions, mode: RouterMode): Promise<void> + +Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| + + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if can not get the delegate. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}, router.RouterMode.Standard) + .then(() => { + // success + }) + .catch(err => { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +### replaceNamedRoute + +replaceNamedRoute(options: NamedRouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void + +Replaces the current page with another one using the named route and destroys the current page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page. | +| mode | [RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +let router = uiContext.getRouter(); +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}, router.RouterMode.Standard, (err) => { + if (err) { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('replaceNamedRoute success'); +}); +``` + +### back + +back(options?: RouterOptions ): void + +Returns to the previous page or a specified page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------- | ---- | ------------------------------------------------------------ | +| options | [RouterOptions](js-apis-router.md#routeroptions) | No | Description of the page. The **url** parameter indicates the URL of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If no URL is set, the application returns to the previous page, and the page is not rebuilt. The page in the page stack is not reclaimed. It will be reclaimed after being popped up.| + +**Example** + +```ts +let router = uiContext.getRouter(); +router.back({url:'pages/detail'}); +``` + +### clear + +clear(): void + +Clears all historical pages in the stack and retains only the current page at the top of the stack. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Example** + +```ts +let router = uiContext.getRouter(); +router.clear(); +``` + +### getLength + +getLength(): string + +Obtains the number of pages in the current stack. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type | Description | +| ------ | ------------------ | +| string | Number of pages in the stack. The maximum value is **32**.| + +**Example** + +```ts +let router = uiContext.getRouter(); +let size = router.getLength(); +console.log('pages stack size = ' + size); +``` + +### getState + +getState(): RouterState + +Obtains state information about the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type | Description | +| --------------------------- | ------- | +| [RouterState](js-apis-router.md#routerstate) | Page routing state.| + +**Example** + +```ts +let router = uiContext.getRouter(); +let page = router.getState(); +console.log('current index = ' + page.index); +console.log('current name = ' + page.name); +console.log('current path = ' + page.path); +``` + +### showAlertBeforeBackPage + +showAlertBeforeBackPage(options: EnableAlertOptions): void + +Enables the display of a confirm dialog box before returning to the previous page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ---------------------------------------- | ---- | --------- | +| options | [EnableAlertOptions](js-apis-router.md#enablealertoptions) | Yes | Description of the dialog box.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | + +**Example** + +```ts +let router = uiContext.getRouter(); +try { + router.showAlertBeforeBackPage({ + message: 'Message Info' + }); +} catch(error) { + console.error(`showAlertBeforeBackPage failed, code is ${error.code}, message is ${error.message}`); +} +``` + +### hideAlertBeforeBackPage + +hideAlertBeforeBackPage(): void + +Disables the display of a confirm dialog box before returning to the previous page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Example** + +```ts +let router = uiContext.getRouter(); +router.hideAlertBeforeBackPage(); +``` + +### getParams + +getParams(): Object + +Obtains the parameters passed from the page that initiates redirection to the current page. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Return value** + +| Type | Description | +| ------ | ---------------------------------- | +| object | Parameters passed from the page that initiates redirection to the current page.| + +**Example** + +```ts +let router = uiContext.getRouter(); +router.getParams(); +``` + +## PromptAction + +In the following API examples, you must first use [getPromptAction()](#getpromptaction) in **UIContext** to obtain a **PromptAction** instance, and then call the APIs using the obtained instance. + +### showToast + +showToast(options: ShowToastOptions): void + +Shows a toast. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------------- | ---- | ------- | +| options | [ShowToastOptions](js-apis-promptAction.md#showtoastoptions) | Yes | Toast options.| + +**Error codes** + +For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | + +**Example** + +```ts +let promptAction = uiContext.getPromptAction(); +try { + promptAction.showToast({ + message: 'Message Info', + duration: 2000 + }); +} catch (error) { + console.error(`showToast args error code is ${error.code}, message is ${error.message}`); +}; +``` + +### showDialog + +showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse<): void + +Shows a dialog box. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------ | +| options | [ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | Yes | Dialog box options.| +| callback | AsyncCallback<[ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | Yes | Callback used to return the dialog box response result. | + +**Error codes** + +For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | + +**Example** + +```ts +let promptAction = uiContext.getPromptAction(); +try { + promptAction.showDialog({ + title: 'showDialog Title Info', + message: 'Message Info', + buttons: [ + { + text: 'button1', + color: '#000000' + }, + { + text: 'button2', + color: '#000000' + } + ] + }, (err, data) => { + if (err) { + console.info('showDialog err: ' + err); + return; + } + console.info('showDialog success callback, click button: ' + data.index); + }); +} catch (error) { + console.error(`showDialog args error code is ${error.code}, message is ${error.message}`); +}; +``` + +### showDialog + +showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse> + +Shows a dialog box. This API uses a promise to return the result synchronously. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | --------------------------------------- | ---- | ------ | +| options | [ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | Yes | Dialog box options.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | -------- | +| Promise<[ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | Promise used to return the dialog box response result.| + +**Error codes** + +For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | + +**Example** + +```ts +let promptAction = uiContext.getPromptAction(); +try { + promptAction.showDialog({ + title: 'Title Info', + message: 'Message Info', + buttons: [ + { + text: 'button1', + color: '#000000' + }, + { + text: 'button2', + color: '#000000' + } + ], + }) + .then(data => { + console.info('showDialog success, click button: ' + data.index); + }) + .catch(err => { + console.info('showDialog error: ' + err); + }) +} catch (error) { + console.error(`showDialog args error code is ${error.code}, message is ${error.message}`); +}; +``` + +### showActionMenu + +showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void + +Shows an action menu. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | --------- | +| options | [ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | Yes | Action menu options. | +| callback | AsyncCallback<[ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | Yes | Callback used to return the action menu response result.| + +**Error codes** + +For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | + +**Example** + +```ts +let promptAction = uiContext.getPromptAction(); +try { + promptAction.showActionMenu({ + title: 'Title Info', + buttons: [ + { + text: 'item1', + color: '#666666' + }, + { + text: 'item2', + color: '#000000' + }, + ] + }, (err, data) => { + if (err) { + console.info('showActionMenu err: ' + err); + return; + } + console.info('showActionMenu success callback, click button: ' + data.index); + }) +} catch (error) { + console.error(`showActionMenu args error code is ${error.code}, message is ${error.message}`); +}; +``` + +### showActionMenu + +showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse> + +Shows an action menu. This API uses a promise to return the result synchronously. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | --------------------------------------- | ---- | ------- | +| options | [ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | Yes | Action menu options.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise<[ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | Promise used to return the action menu response result.| + +**Error codes** + +For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | + +**Example** + +```ts +let promptAction = uiContext.getPromptAction(); +try { + promptAction.showActionMenu({ + title: 'showActionMenu Title Info', + buttons: [ + { + text: 'item1', + color: '#666666' + }, + { + text: 'item2', + color: '#000000' + }, + ] + }) + .then(data => { + console.info('showActionMenu success, click button: ' + data.index); + }) + .catch(err => { + console.info('showActionMenu error: ' + err); + }) +} catch (error) { + console.error(`showActionMenu args error code is ${error.code}, message is ${error.message}`); +}; +``` diff --git a/en/application-dev/reference/apis/js-apis-curve.md b/en/application-dev/reference/apis/js-apis-curve.md index bd673773b094eda6a3aa6d14c6d6ab7336120e65..dc0fdd5742cee370e7caa76bb6600fbf4b34ee98 100644 --- a/en/application-dev/reference/apis/js-apis-curve.md +++ b/en/application-dev/reference/apis/js-apis-curve.md @@ -25,9 +25,9 @@ Implements initialization for the interpolation curve, which is used to create a **Parameters** -| Name| Type | Mandatory| Default Value | Description | -| ------ | ------------------------------------------------------------ | ---- | ------------ | ---------- | -| curve | [Curve](../arkui-ts/ts-appendix-enums.md#curve) | No | Curve.Linear | Curve type.| +| Name| Type | Mandatory| Description | +| ------ | ----------------------------------------------- | ---- | ----------------------------------- | +| curve | [Curve](../arkui-ts/ts-appendix-enums.md#curve) | No | Curve type.
Default value: **Curve.Linear**| **Return value** @@ -151,16 +151,16 @@ Creates a spring animation curve. If multiple spring animations are applied to t | Name | Type | Mandatory | Description | | --------- | ------ | ---- | ----- | -| response | number | No | Duration of one complete oscillation,
Default value: **0.55**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0.55**.| +| response | number | No | Duration of one complete oscillation.
Default value: **0.55**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0.55**.| | dampingFraction | number | No | Damping coefficient.
**0**: undamped. In this case, the spring oscillates forever.
> 0 and < 1: underdamped. In this case, the spring overshoots the equilibrium position.
**1**: critically damped.
> 1: overdamped. In this case, the spring approaches equilibrium gradually.
Default value: **0.825**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0.55**.| -| overlapDuration | number | No | Duration for animations to overlap, in seconds. When animations overlap, if the **response** values of the two animations are different, they will transit smoothly over this duration.

Default value: **0**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0**.
The spring animation curve is physics-based. Its duration depends on the **springMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md) or [animateTo](../arkui-ts/ts-explicit-animation.md). The time cannot be normalized. Therefore, the interpolation cannot be obtained by using the **[interpolate](#interpolate)** function of the curve.| +| overlapDuration | number | No | Duration for animations to overlap, in seconds. When animations overlap, if the **response** values of the two animations are different, they will transit smoothly over this duration.

Default value: **0**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0**.
The spring animation curve is physics-based. Its duration depends on the **springMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md) or [animateTo](../arkui-ts/ts-explicit-animation.md). The time cannot be normalized. Therefore, the interpolation cannot be obtained by using the **interpolate** function of the curve.| **Return value** | Type | Description | | ---------------------------------- | ---------------- | -| [ICurve](#icurve)| Curve.
**NOTE**
The spring animation curve is physics-based. Its duration depends on the **springMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md) or [animateTo](../arkui-ts/ts-explicit-animation.md). The time cannot be normalized. Therefore, the interpolation cannot be obtained by using the **[interpolate](#interpolate)** function of the curve.| +| [ICurve](#icurve)| Curve.
**NOTE**
The spring animation curve is physics-based. Its duration depends on the **springMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md) or [animateTo](../arkui-ts/ts-explicit-animation.md). The time cannot be normalized. Therefore, the interpolation cannot be obtained by using the **interpolate** function of the curve.| **Example** @@ -187,13 +187,13 @@ Creates a responsive spring animation curve. It is a special case of [springMoti | --------- | ------ | ---- | ----- | | response | number | No | See **response** in **springMotion**.
Default value: **0.15**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0.15**.| | dampingFraction | number | No | See **dampingFraction** in **springMotion**.
Default value: **0.86**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0.86**.| -| overlapDuration | number | No | See **overlapDuration** in **springMotion**.
Default value: **0.25**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0.25**.
To apply custom settings for a spring animation, you are advised to use **springMotion**. When using **responsiveSpringMotion**, you are advised to retain the default settings.
The duration of the responsive spring animation depends on the **responsiveSpringMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md) or [animateTo](../arkui-ts/ts-explicit-animation.md). In addition, the interpolation cannot be obtained by using the [interpolate](#interpolate) function of the curve.| +| overlapDuration | number | No | See **overlapDuration** in **springMotion**.
Default value: **0.25**
Unit: second
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value **0.25**.
To apply custom settings for a spring animation, you are advised to use **springMotion**. When using **responsiveSpringMotion**, you are advised to retain the default settings.
The duration of the responsive spring animation depends on the **responsiveSpringMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md) or [animateTo](../arkui-ts/ts-explicit-animation.md). In addition, the interpolation cannot be obtained by using the **interpolate** function of the curve.| **Return value** | Type | Description | | ---------------------------------- | ---------------- | -| [ICurve](#icurve)| Curve.
**NOTE**
1. To apply custom settings for a spring animation, you are advised to use **springMotion**. When using **responsiveSpringMotion**, you are advised to retain the default settings.
2. The duration of the responsive spring animation depends on the **responsiveSpringMotion** parameters and the previous velocity, rather than the **duration** parameter in **animation** or **animateTo**. In addition, the interpolation cannot be obtained by using the [interpolate](#interpolate) function of the curve.| +| [ICurve](#icurve)| Curve.
**NOTE**
1. To apply custom settings for a spring animation, you are advised to use **springMotion**. When using **responsiveSpringMotion**, you are advised to retain the default settings.
2. The duration of the responsive spring animation depends on the **responsiveSpringMotion** parameters and the previous velocity, rather than the **duration** parameter in **animation** or **animateTo**. In addition, the interpolation cannot be obtained by using the [interpolate](#interpolate9) function of the curve.| **Example** @@ -260,7 +260,7 @@ import Curves from '@ohos.curves' interpolate(fraction) { return Math.sqrt(fraction); } -Curves.customCurve(this.interpolate) // Create a custom curve. +private curve = Curves.customCurve(this.interpolate) // Create a custom curve. ``` @@ -268,7 +268,7 @@ Curves.customCurve(this.interpolate) // Create a custom curve. ## ICurve -### interpolate +### interpolate9+ interpolate(fraction: number): number @@ -310,9 +310,9 @@ Implements initialization to create a curve. This API is deprecated since API ve **Parameters** -| Name| Type | Mandatory| Default Value | Description | -| ------ | ------------------------------------------------------------ | ---- | ------------ | ---------- | -| curve |[Curve](../arkui-ts/ts-appendix-enums.md#curve) | No | Curve.Linear | Curve type.| +| Name| Type | Mandatory| Description | +| ------ | ----------------------------------------------- | ---- | ----------------------------------- | +| curve | [Curve](../arkui-ts/ts-appendix-enums.md#curve) | No | Curve type.
Default value: **Curve.Linear**| ## Curves.steps(deprecated) diff --git a/en/application-dev/reference/apis/js-apis-font.md b/en/application-dev/reference/apis/js-apis-font.md index dad280bb91d43d69f78f719cc8733fc212fec826..0a66ea708e32f95433061f082b3debd9911e753d 100644 --- a/en/application-dev/reference/apis/js-apis-font.md +++ b/en/application-dev/reference/apis/js-apis-font.md @@ -7,6 +7,10 @@ The **font** module provides APIs for registering custom fonts. > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > > The APIs provided by this module are system APIs. +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](./js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [getFont](./js-apis-arkui-UIContext.md#getfont) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [Font](./js-apis-arkui-UIContext.md#font) object associated with the current UI context. ## Modules to Import @@ -165,3 +169,4 @@ struct FontExample { } } ``` + diff --git a/en/application-dev/reference/apis/js-apis-matrix4.md b/en/application-dev/reference/apis/js-apis-matrix4.md index b707f54df167497056052a8524ec00d7bbe11188..9c8c1a77c0150f8d820ec03701c3bd58ad9c8a17 100644 --- a/en/application-dev/reference/apis/js-apis-matrix4.md +++ b/en/application-dev/reference/apis/js-apis-matrix4.md @@ -16,7 +16,7 @@ import matrix4 from '@ohos.matrix4' ## matrix4.init -init(array: Array<number>): Matrix4Transit +init(option: [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number]): Matrix4Transit Matrix constructor, which is used to create a 4 x 4 matrix by using the input parameter. Column-major order is used. @@ -25,17 +25,17 @@ Matrix constructor, which is used to create a 4 x 4 matrix by using the input pa **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------------------- | ---- | ------------------------------------------------------------ | -| array | Array<number> | Yes | A number array whose length is 16 (4 x 4). For details, see **array** parameters.
Default value:
[1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1] | +| Name| Type | Mandatory| Description | +| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| option | [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number] | Yes | A number array whose length is 16 (4 x 4). For details, see **Description of a 4 x 4 matrix**.
Default value:
[1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1] | **Return value** -| Type | Description | -| -------------- | ---------------------------- | -| Matrix4Transit | 4 x 4 matrix object created based on the input parameter.| +| Type | Description | +| --------------------------------- | ---------------------------- | +| [Matrix4Transit](#matrix4transit) | 4 x 4 matrix object created based on the input parameter.| -**array** parameters +**Description of a 4 x 4 matrix** | Name | Type | Mandatory | Description | | ---- | ------ | ---- | -------------------- | @@ -91,9 +91,9 @@ Constructs an identity matrix. **Return value** -| Type | Description | -| -------------- | -------------- | -| Matrix4Transit | Identity matrix object.| +| Type | Description | +| --------------------------------- | -------------- | +| [Matrix4Transit](#matrix4transit) | Identity matrix object.| **Example** @@ -136,9 +136,9 @@ Copies this matrix object. **Return value** -| Type | Description | -| -------------- | -------------------- | -| Matrix4Transit | Copy object of the current matrix.| +| Type | Description | +| --------------------------------- | -------------------- | +| [Matrix4Transit](#matrix4transit) | Copy object of the current matrix.| **Example** @@ -171,12 +171,12 @@ struct Test { ![en-us_image_0000001219744181](figures/en-us_image_0000001219744181.png) -## Matrix4 +## Matrix4Transit ### combine -combine(matrix: Matrix4): Matrix4Transit +combine(option: Matrix4Transit): Matrix4Transit Combines the effects of two matrices to generate a new matrix object. @@ -185,15 +185,15 @@ Combines the effects of two matrices to generate a new matrix object. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------- | ---- | ------------------ | -| matrix | Matrix4 | Yes | Matrix object to be combined.| +| Name| Type | Mandatory| Description | +| ------ | --------------------------------- | ---- | ------------------ | +| option | [Matrix4Transit](#matrix4transit) | Yes | Matrix object to be combined.| **Return value** -| Type | Description | -| -------------- | ------------------ | -| Matrix4Transit | Object after matrix combination.| +| Type | Description | +| --------------------------------- | ------------------ | +| [Matrix4Transit](#matrix4transit) | Object after matrix combination.| **Example** @@ -238,9 +238,9 @@ Inverts this matrix object. **Return value** -| Type | Description | -| -------------- | ---------------------- | -| Matrix4Transit | Inverse matrix object of the current matrix.| +| Type | Description | +| --------------------------------- | ---------------------- | +| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| **Example** @@ -273,7 +273,7 @@ struct Tests { ### translate -translate({x?: number, y?: number, z?: number}): Matrix4Transit +translate(option: TranslateOption): Matrix4Transit Translates this matrix object along the x, y, and z axes. @@ -281,17 +281,15 @@ Translates this matrix object along the x, y, and z axes. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ----------------------------------------------------------- | -| x | number | No | Translation distance along the x-axis, in px.
Default value: **0**
Value range: (-∞, +∞)| -| y | number | No | Translation distance along the y-axis, in px.
Default value: **0**
Value range: (-∞, +∞)| -| z | number | No | Translation distance along the z-axis, in px.
Default value: **0**
Value range: (-∞, +∞)| +| Name| Type | Mandatory| Description | +| ------ | ----------------------------------- | ---- | -------------- | +| option | [TranslateOption](#translateoption) | Yes | Translation configuration.| **Return value** -| Type | Description | -| -------------- | ---------------------------- | -| Matrix4Transit | Matrix object after the translation effect is added.| +| Type | Description | +| --------------------------------- | ---------------------------- | +| [Matrix4Transit](#matrix4transit) | Matrix object after the translation.| **Example** @@ -319,7 +317,7 @@ struct Test { ### scale -scale({x?: number, y?: number, z?: number, centerX?: number, centerY?: number}): Matrix4Transit +scale(option: ScaleOption): Matrix4Transit Scales this matrix object along the x, y, and z axes. @@ -328,19 +326,16 @@ Scales this matrix object along the x, y, and z axes. **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| x | number | No | Scaling multiple along the x-axis. If the value is greater than 1, the image is scaled up along the x-axis. If the value is less than 1, the image is scaled down along the x-axis.
Default value: **1**
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value.| -| y | number | No | Scaling multiple along the y-axis. If the value is greater than 1, the image is scaled up along the y-axis. If the value is less than 1, the image is scaled down along the y-axis.
Default value: **1**
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value.| -| z | number | No | Scaling multiple along the z-axis. If the value is greater than 1, the image is scaled up along the z-axis. If the value is less than 1, the image is scaled down along the z-axis.
Default value: **1**
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value.| -| centerX | number | No | X coordinate of the center point.
Default value: **0**
Value range: (-∞, +∞) | -| centerY | number | No | Y coordinate of the center point.
Default value: **0**
Value range: (-∞, +∞) | +| Name| Type | Mandatory| Description | +| ------ | --------------------------- | ---- | -------------- | +| option | [ScaleOption](#scaleoption) | Yes | Scaling configuration.| + **Return value** -| Type | Description | -| -------------- | ---------------------------- | -| Matrix4Transit | Matrix object after the scaling effect is added.| +| Type | Description | +| --------------------------------- | ---------------------------- | +| [Matrix4Transit](#matrix4transit) | Matrix object after the scaling.| **Example** @@ -367,7 +362,7 @@ struct Test { ### rotate -rotate({x?: number, y?: number, z?: number, angle?: number, centerX?: Length, centerY?: Length}): Matrix4Transit +rotate(option: RotateOption): Matrix4Transit Rotates this matrix object along the x, y, and z axes. @@ -376,20 +371,16 @@ Rotates this matrix object along the x, y, and z axes. **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ------ | ---- | ------------------------------------------------------- | -| x | number | No | X coordinate of the rotation axis vector.
Default value: **1**
Value range: (-∞, +∞)| -| y | number | No | Y coordinate of the rotation axis vector.
Default value: **1**
Value range: (-∞, +∞)| -| z | number | No | Z coordinate of the rotation axis vector.
Default value: **1**
Value range: (-∞, +∞)| -| angle | number | No | Rotation angle.
Default value: **0** | -| centerX | number | No | X coordinate of the center point.
Default value: **0** | -| centerY | number | No | Y coordinate of the center point.
Default value: **0** | +| Name| Type | Mandatory| Description | +| ------ | ----------------------------- | ---- | -------------- | +| option | [RotateOption](#rotateoption) | Yes | Rotation configuration.| + **Return value** -| Type | Description | -| -------------- | ---------------------------- | -| Matrix4Transit | Matrix object after the rotation effect is added.| +| Type | Description | +| --------------------------------- | ---------------------------- | +| [Matrix4Transit](#matrix4transit) | Matrix object after the rotation.| **Example** @@ -417,7 +408,7 @@ struct Test { ### transformPoint -transformPoint(point: Point): Point +transformPoint(option: [number, number]): [number, number] Applies the current transformation effect to a coordinate point. @@ -426,15 +417,15 @@ Applies the current transformation effect to a coordinate point. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----- | ---- | ------------------ | -| point | Point | Yes | Point to be transformed.| +| Name| Type | Mandatory| Description | +| ------ | ---------------- | ---- | ------------------ | +| option | [number, number] | Yes | Point to be transformed.| **Return value** -| Type | Description | -| ----- | ---------------- | -| Point | Point object after matrix transformation| +| Type | Description | +| ---------------- | --------------------------- | +| [number, number] | Point object after matrix transformation| **Example** @@ -472,3 +463,32 @@ struct Test { ``` ![en-us_image_0000001219864133](figures/en-us_image_0000001219864133.PNG) + +## TranslateOption + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ----------------------------------------------------------- | +| x | number | No | Translation distance along the x-axis, in px.
Default value: **0**
Value range: (-∞, +∞)| +| y | number | No | Translation distance along the y-axis, in px.
Default value: **0**
Value range: (-∞, +∞)| +| z | number | No | Translation distance along the z-axis, in px.
Default value: **0**
Value range: (-∞, +∞)| + +## ScaleOption + +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| x | number | No | Scaling multiple along the x-axis. If the value is greater than 1, the image is scaled up along the x-axis. If the value is less than 1, the image is scaled down along the x-axis.
Default value: **1**
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value.| +| y | number | No | Scaling multiple along the y-axis. If the value is greater than 1, the image is scaled up along the y-axis. If the value is less than 1, the image is scaled down along the y-axis.
Default value: **1**
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value.| +| z | number | No | Scaling multiple along the z-axis. If the value is greater than 1, the image is scaled up along the z-axis. If the value is less than 1, the image is scaled down along the z-axis.
Default value: **1**
Value range: [0, +∞)
**NOTE**
A value less than 0 evaluates to the default value.| +| centerX | number | No | X coordinate of the center point.
Default value: **0**
Value range: (-∞, +∞) | +| centerY | number | No | Y coordinate of the center point.
Default value: **0**
Value range: (-∞, +∞) | + +## RotateOption + +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | ------------------------------------------------------- | +| x | number | No | X coordinate of the rotation axis vector.
Default value: **1**
Value range: (-∞, +∞)| +| y | number | No | Y coordinate of the rotation axis vector.
Default value: **1**
Value range: (-∞, +∞)| +| z | number | No | Z coordinate of the rotation axis vector.
Default value: **1**
Value range: (-∞, +∞)| +| angle | number | No | Rotation angle.
Default value: **0** | +| centerX | number | No | X coordinate of the center point.
Default value: **0** | +| centerY | number | No | Y coordinate of the center point.
Default value: **0** | diff --git a/en/application-dev/reference/apis/js-apis-measure.md b/en/application-dev/reference/apis/js-apis-measure.md index 55d5b70a7009b42f2a9d683566c958ad027d9eb4..4b0eac439ab60844ca48f768ed768126b01d64da 100644 --- a/en/application-dev/reference/apis/js-apis-measure.md +++ b/en/application-dev/reference/apis/js-apis-measure.md @@ -112,7 +112,7 @@ Provides attributes of the measured text. | Name | Type | Mandatory| Description | | -------------- | -------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- | -| textContent10+ | string | Yes | Content of the measured text. | +| textContent | string | Yes | Content of the measured text. | | constraintWidth10+ | number \| string \| [Resource](../arkui-ts/ts-types.md#resource) | No | Layout width of the measured text.
The default unit is vp. | | fontSize | number \| string \| [Resource](../arkui-ts/ts-types.md#resource) | No | Font size of the measured text. If the value is of the number type, the unit fp is used.
Default value: **16fp**
**NOTE**
The value cannot be a percentage. | | fontStyle | number \| [FontStyle](../arkui-ts/ts-appendix-enums.md#fontstyle) | No | Font style of the measured text.
Default value: **FontStyle.Normal** | diff --git a/en/application-dev/reference/apis/js-apis-mediaquery.md b/en/application-dev/reference/apis/js-apis-mediaquery.md index b2b8dfd30eb68510227790c45366de315cbb856b..29f319addaadfc093be1d7da8e5eb6aecc40f98d 100644 --- a/en/application-dev/reference/apis/js-apis-mediaquery.md +++ b/en/application-dev/reference/apis/js-apis-mediaquery.md @@ -7,6 +7,10 @@ The **mediaquery** module provides different styles for different media types. > The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. > > This module can be used only after a component instance is created, and it cannot be used in the [UIAbility](./js-apis-app-ability-uiAbility.md). +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](./js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [getMediaQuery](./js-apis-arkui-UIContext.md#getmediaquery) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [MediaQuery](./js-apis-arkui-UIContext.md#mediaquery) object associated with the current UI context. ## Modules to Import diff --git a/en/application-dev/reference/apis/js-apis-promptAction.md b/en/application-dev/reference/apis/js-apis-promptAction.md index aed51460eb6f196f07d72ee6071da53e4b052458..1624fd511a1f1fd99fb75e4aa93b3dc2a2872bd9 100644 --- a/en/application-dev/reference/apis/js-apis-promptAction.md +++ b/en/application-dev/reference/apis/js-apis-promptAction.md @@ -7,6 +7,10 @@ The **PromptAction** module provides APIs for creating and showing toasts, dialo > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > > This module can be used only after a component instance is created, and it cannot be used in the [UIAbility](./js-apis-app-ability-uiAbility.md). +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](./js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [getPromptAction](./js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](./js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. ## Modules to Import @@ -62,7 +66,7 @@ Describes the options for showing the toast. | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | message | string\| [Resource](../arkui-ts/ts-types.md#resource)9+| Yes | Text to display. | | duration | number | No | Duration that the toast will remain on the screen. The default value is 1500 ms. The value range is 1500 ms to 10000 ms. If a value less than 1500 ms is set, the default value is used. If the value greater than 10000 ms is set, the upper limit 10000 ms is used.| -| bottom | string\| number | No | Distance between the toast border and the bottom of the screen. | +| bottom | string\| number | No | Distance between the toast border and the bottom of the screen.
Default value: **80vp** | ## promptAction.showDialog @@ -319,7 +323,7 @@ Describes the options for showing the action menu. | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | title | string\| [Resource](../arkui-ts/ts-types.md#resource)9+| No | Title of the dialog box. | -| buttons | [[Button](#button),[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?] | Yes | Array of menu item buttons. The array structure is **{text:'button', color: '\#666666'}**. Up to six buttons are supported. If there are more than six buttons, extra buttons will not be displayed.| +| buttons | [[Button](#button),[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?] | Yes | Array of menu item buttons. The array structure is **{text:'button', color: '\#666666'}**. Up to six buttons are supported. If there are more than six buttons, only the first six buttons will be displayed.| ## ActionMenuSuccessResponse diff --git a/en/application-dev/reference/apis/js-apis-router.md b/en/application-dev/reference/apis/js-apis-router.md index 2020f98279bc94e3ba292ced7d156cc963f46dd6..4319de28861f4056ca47657cf72a4af526b886f6 100644 --- a/en/application-dev/reference/apis/js-apis-router.md +++ b/en/application-dev/reference/apis/js-apis-router.md @@ -7,6 +7,10 @@ The **Router** module provides APIs to access pages through URLs. You can use th > - 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. > > - Page routing APIs can be invoked only after page rendering is complete. Do not call these APIs in **onInit** and **onReady** when the page is still in the rendering phase. +> +> - The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](./js-apis-arkui-UIContext.md#uicontext). +> +> - Since API version 10, you can use the [getRouter](./js-apis-arkui-UIContext.md#getrouter) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [Router](./js-apis-arkui-UIContext.md#router) object associated with the current UI context. ## Modules to Import @@ -46,7 +50,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.pushUrl({ url: 'pages/routerpage2', params: { @@ -91,7 +95,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.pushUrl({ url: 'pages/routerpage2', params: { @@ -141,7 +145,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.pushUrl({ url: 'pages/routerpage2', params: { @@ -187,7 +191,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.pushUrl({ url: 'pages/routerpage2', params: { @@ -236,7 +240,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.replaceUrl({ url: 'pages/detail', params: { @@ -277,7 +281,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.replaceUrl({ url: 'pages/detail', params: { @@ -325,7 +329,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.replaceUrl({ url: 'pages/detail', params: { @@ -367,7 +371,7 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** -```js +```ts router.replaceUrl({ url: 'pages/detail', params: { @@ -383,6 +387,375 @@ router.replaceUrl({ ``` +## router.pushNamedRoute10+ + +pushNamedRoute(options: NamedRouterOptions): Promise<void> + +Navigates to a page using the named route. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | --------- | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Page routing parameters.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}) + .then(() => { + // success + }) + .catch(err => { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +## router.pushNamedRoute10+ + +pushNamedRoute(options: NamedRouterOptions, callback: AsyncCallback<void>): void + +Navigates to a page using the named route. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | --------- | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Page routing parameters.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, (err) => { + if (err) { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('pushNamedRoute success'); +}) +``` +## router.pushNamedRoute10+ + +pushNamedRoute(options: NamedRouterOptions, mode: RouterMode): Promise<void> + +Navigates to a page using the named route. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Page routing parameters. | +| mode | [RouterMode](#routermode9) | Yes | Routing mode.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, router.RouterMode.Standard) + .then(() => { + // success + }) + .catch(err => { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +## router.pushNamedRoute10+ + +pushNamedRoute(options: NamedRouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void + +Navigates to a page using the named route. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Page routing parameters. | +| mode | [RouterMode](#routermode9) | Yes | Routing mode.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100003 | if the pages are pushed too much. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.pushNamedRoute({ + name: 'myPage', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + } + } +}, router.RouterMode.Standard, (err) => { + if (err) { + console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('pushNamedRoute success'); +}) +``` + +## router.replaceNamedRoute10+ + +replaceNamedRoute(options: NamedRouterOptions): Promise<void> + +Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Description of the new page.| + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}) + .then(() => { + // success + }) + .catch(err => { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +## router.replaceNamedRoute10+ + +replaceNamedRoute(options: NamedRouterOptions, callback: AsyncCallback<void>): void + +Replaces the current page with another one using the named route and destroys the current page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Description of the new page.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}, (err) => { + if (err) { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('replaceNamedRoute success'); +}) +``` + +## router.replaceNamedRoute10+ + +replaceNamedRoute(options: NamedRouterOptions, mode: RouterMode): Promise<void> + +Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Description of the new page. | +| mode | [RouterMode](#routermode9) | Yes | Routing mode.| + + +**Return value** + +| Type | Description | +| ------------------- | --------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if can not get the delegate. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}, router.RouterMode.Standard) + .then(() => { + // success + }) + .catch(err => { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + }) +``` + +## router.replaceNamedRoute10+ + +replaceNamedRoute(options: NamedRouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void + +Replaces the current page with another one using the named route and destroys the current page. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------- | +| options | [NamedRouterOptions](#namedrouteroptions10) | Yes | Description of the new page. | +| mode | [RouterMode](#routermode9) | Yes | Routing mode.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Error codes** + +For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md). + +| ID | Error Message| +| --------- | ------- | +| 100001 | if UI execution context not found. | +| 100004 | if the named route is not exist. | + +**Example** + +```ts +router.replaceNamedRoute({ + name: 'myPage', + params: { + data1: 'message' + } +}, router.RouterMode.Standard, (err) => { + if (err) { + console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); + return; + } + console.info('replaceNamedRoute success'); +}); + +``` + ## router.back back(options?: RouterOptions ): void @@ -399,7 +772,7 @@ Returns to the previous page or a specified page. **Example** -```js +```ts router.back({url:'pages/detail'}); ``` @@ -413,7 +786,7 @@ Clears all historical pages in the stack and retains only the current page at th **Example** -```js +```ts router.clear(); ``` @@ -433,7 +806,7 @@ Obtains the number of pages in the current stack. **Example** -```js +```ts let size = router.getLength(); console.log('pages stack size = ' + size); ``` @@ -454,7 +827,7 @@ Obtains state information about the current page. **Example** -```js +```ts let page = router.getState(); console.log('current index = ' + page.index); console.log('current name = ' + page.name); @@ -497,15 +870,15 @@ For details about the error codes, see [Router Error Codes](../errorcodes/errorc **Example** - ```js +```ts try { - router.showAlertBeforeBackPage({ - message: 'Message Info' + router.showAlertBeforeBackPage({ + message: 'Message Info' }); } catch(error) { console.error(`showAlertBeforeBackPage failed, code is ${error.code}, message is ${error.message}`); } - ``` +``` ## EnableAlertOptions Describes the confirm dialog box. @@ -526,7 +899,7 @@ Disables the display of a confirm dialog box before returning to the previous pa **Example** -```js +```ts router.hideAlertBeforeBackPage(); ``` @@ -563,7 +936,6 @@ Describes the page routing options. > **NOTE** - > > The page routing stack supports a maximum of 32 pages. ## RouterMode9+ @@ -577,11 +949,22 @@ Enumerates the routing modes. | Standard | Multi-instance mode. It is the default routing mode.
The target page is added to the top of the page stack, regardless of whether a page with the same URL exists in the stack.
**NOTE**
If the routing mode is not used, the page is redirected to in multi-instance mode.| | Single | Singleton mode.
If the URL of the target page already exists in the page stack, the page closest to the top of the stack is moved to the top and becomes a new page.
If the URL of the target page does not exist in the page stack, the page is redirected to in multi-instance mode.| +## NamedRouterOptions10+ + +Describes the named route options. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name | Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| name | string | Yes | Name of the target named route.| +| params | object | No | Data that needs to be passed to the target page during redirection. The target page can use **router.getParams()** to obtain the passed parameters, for example, **this.keyValue** (**keyValue** is the value of a key in **params**). In the web-like paradigm, these parameters can be directly used on the target page. If the field specified by **key** already exists on the target page, the passed value of the key will be displayed.| + ## Examples ### JavaScript-based Web-like Development Paradigm -```js +```ts // Current page export default { pushPage() { @@ -594,7 +977,7 @@ export default { } } ``` -```js +```ts // detail page export default { onInit() { @@ -704,7 +1087,7 @@ This API is deprecated since API version 9. You are advised to use [pushUrl **Example** -```js +```ts router.push({ url: 'pages/routerpage2', params: { @@ -734,7 +1117,7 @@ This API is deprecated since API version 9. You are advised to use [replaceUrl(deprecated) @@ -779,6 +1162,6 @@ This API is deprecated since API version 9. You are advised to use [hideAlertBef **Example** -```js -router.disableAlertBeforeBackPage(); +```ts +router.disableAlertBeforeBackPage(); ``` diff --git a/en/application-dev/reference/apis/js-apis-system-router.md b/en/application-dev/reference/apis/js-apis-system-router.md index e2e2ef013c53ec132fd73a54f6a171d84063b161..0813fbd568ea310b81ab0ed9868e0ad0302aba7c 100644 --- a/en/application-dev/reference/apis/js-apis-system-router.md +++ b/en/application-dev/reference/apis/js-apis-system-router.md @@ -343,8 +343,8 @@ Defines the page routing parameters. | Name | Type| Mandatory| Description | | ------ | -------- | ---- | ------------------------------------------------------------ | -| uri7+ | string | Yes | URI of the target page, in either of the following formats:
1. Absolute path, which is provided by the **pages** list in the **config.json** file. Example:
- pages/index/index
- pages/detail/detail
2. Specific path. If the URI is a slash (/), the home page is displayed.| -| params7+ | object | No | Data that needs to be passed to the target page during redirection. The target page can use **router.getParams()** to obtain the passed parameters, for example, **this.keyValue** (**keyValue** is the value of a key in **params**). In the web-like paradigm, these parameters can be directly used on the target page. If the field specified by **key** already exists on the target page, the passed value of the key will be displayed.| +| uri | string | Yes | URI of the target page, in either of the following formats:
1. Absolute path, which is provided by the **pages** list in the **config.json** file. Example:
- pages/index/index
- pages/detail/detail
2. Specific path. If the URI is a slash (/), the home page is displayed.| +| params | object | No | Data that needs to be passed to the target page during redirection. The target page can use **router.getParams()** to obtain the passed parameters, for example, **this.keyValue** (**keyValue** is the value of a key in **params**). In the web-like paradigm, these parameters can be directly used on the target page. If the field specified by **key** already exists on the target page, the passed value of the key will be displayed.| ## BackRouterOptions diff --git a/en/application-dev/reference/arkui-ts/figures/DataPickerDialog.gif b/en/application-dev/reference/arkui-ts/figures/DataPickerDialog.gif new file mode 100644 index 0000000000000000000000000000000000000000..e447f0d8916e19385da7f38e1c4b15334e4a6a70 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/DataPickerDialog.gif differ diff --git a/en/application-dev/reference/arkui-ts/figures/TextPickerDialog.gif b/en/application-dev/reference/arkui-ts/figures/TextPickerDialog.gif new file mode 100644 index 0000000000000000000000000000000000000000..de15f47d3d9e9f18794c7fe92ce060bf2aa135e8 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/TextPickerDialog.gif differ diff --git a/en/application-dev/reference/arkui-ts/figures/TimePickerDialog.gif b/en/application-dev/reference/arkui-ts/figures/TimePickerDialog.gif new file mode 100644 index 0000000000000000000000000000000000000000..44fe3a771a01e9fec2e155663c1f2f552d202b68 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/TimePickerDialog.gif differ diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md b/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md index e5aa84e29ece1a1a11f91a0a66fc6526bdc1b2ab..bb8c77dd981948116af501bcd05378fd75503200 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md @@ -30,12 +30,12 @@ Creates a date picker in the given date range. In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. -| Name | Type | Description | -| -------------------------------- | ---------------------------------------- | ---------------------------------------- | -| lunar | boolean | Whether to display the lunar calendar.
- **true**: Display the lunar calendar.
- **false**: Do not display the lunar calendar.
Default value: **false**| -| disappearTextStyle10+ | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width for the top and bottom items. | -| textStyle10+ | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items. | -| selectedTextStyle10+ | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width of the selected item. | +| Name | Type | Description | +| -------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | +| lunar | boolean | Whether to display the lunar calendar.
- **true**: Display the lunar calendar.
- **false**: Do not display the lunar calendar.
Default value: **false**| +| disappearTextStyle10+ | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | +| textStyle10+ | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | +| selectedTextStyle10+ | [PickerTextStyle](#pickertextstyle10) | Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | ## PickerTextStyle10+ diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-rating.md b/en/application-dev/reference/arkui-ts/ts-basic-components-rating.md index efc15c08f744eb3cf89c534a2bc21d8397d729b2..73221ce76c2b1d2f0767cdb440fefe4f7bef5542 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-rating.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-rating.md @@ -28,10 +28,10 @@ Since API version 9, this API is supported in ArkTS widgets. ## Attributes -| Name | Type | Description | -| --------- | ---------------------------------------- | ---------------------------------------- | -| stars | number | Total number of ratings.
Default value: **5**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
A value less than 0 evaluates to the default value.| -| stepSize | number | Step of an operation.
Default value: **0.5**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
A value less than 0 evaluates to the default value.
Value range: [0.1, stars]| +| Name | Type | Description | +| --------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| stars | number | Total number of ratings.
Default value: **5**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
A value less than or equal to 0 evaluates to the default value.| +| stepSize | number | Step of an operation.
Default value: **0.5**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
A value less than 0 evaluates to the default value.
Value range: [0.1, stars]| | starStyle | {
backgroundUri: string,
foregroundUri: string,
secondaryUri?: string
} | Star style.
**backgroundUri**: image path for the unselected star. You can use the default system image or a custom image.
**foregroundUri**: image path for the selected star. You can use the default system image or a custom image.
**secondaryUir**: image path for the partially selected star. You can use the default system image or a custom image.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
For details about the image types supported by the **startStyle** attribute, see [Image](ts-basic-components-image.md).
Local and online images are supported, but not **PixelMap** and **Resource** objects.
By default, the image is loaded in asynchronous mode. Synchronous loading is not supported.
If this parameter is set to **undefined** or an empty string, the **\** component loads the default star image source.| > **NOTE** diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md b/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md index 4958173d84c8894bd661ddfd0cdfd05f9041b251..cab18d856b6dc0e86a5d49b75b7bb56afc7b7ca7 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-slider.md @@ -22,7 +22,7 @@ Since API version 9, this API is supported in ArkTS widgets. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| value | number | No| Current progress.
Default value: min
Since API version 10, this parameter supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.| +| value | number | No| Current progress.
Default value: value of **min**
Since API version 10, this parameter supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.| | min | number | No| Minimum value.
Default value: **0**| | max | number | No| Maximum value.
Default value: **100**
**NOTE**
If the value of **min** is greater than or equal to the value of **max**, the default value **0** is used for **min** and the default value **100** is used for **max**.
If the value is not within the [min, max] range, the value of **min** or **max**, whichever is closer.| | step | number | No| Step of the slider.
Default value: **1**
Value range: [0.01, max]
**NOTE**
If this parameter is set to a value less than 0 or a percentage, the default value is used.| @@ -47,7 +47,7 @@ Except touch target attributes, the universal attributes are supported. | trackColor | [ResourceColor](ts-types.md#resourcecolor) | Background color of the slider.
Since API version 9, this API is supported in ArkTS widgets.| | selectedColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the selected part of the slider track.
Since API version 9, this API is supported in ArkTS widgets.| | showSteps | boolean | Whether to display the current step.
Default value: **false**
Since API version 9, this API is supported in ArkTS widgets.| -| showTips | boolean | Whether to display a bubble to indicate the percentage when the user drags the slider.
Default value: **false**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
When **direction** is set to **Axis.Horizontal**, the bubble is displayed right above the slider. When **direction** is set to **Axis.Vertical**, the bubble is displayed on the left of the slider.
The drawing area of the bubble is the overlay of the slider.
If no margin is set for the slider or the margin is not large enough, the bubble will be clipped.| +| showTips | value: boolean,
content10+?: [ResourceStr](ts-types.md#resourcestr) | **value**: whether to display a tooltip when the user drags the slider.
Default value: **false**
**content**: text content of the tooltip. The default value is the current percentage.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
When **direction** is set to **Axis.Horizontal**, the tooltip is displayed right above the slider. When **direction** is set to **Axis.Vertical**, the tooltip is displayed on the left of the slider.
The drawing area of the tooltip is the overlay of the slider.
If no margin is set for the slider or the margin is not large enough, the tooltip will be clipped.| | trackThickness | [Length](ts-types.md#length) | Track thickness of the slider.
Default value: **4.0vp** when **style** is set to **[SliderStyle](#sliderstyle).OutSet**; **20.0vp** when **style** is set to **[SliderStyle](#sliderstyle).InSet**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
A value less than 0 evaluates to the default value.| | blockBorderColor10+ | [ResourceColor](ts-types.md#resourcecolor) | Border color of the slider in the block direction.| | blockBorderWidth10+ | [Length](ts-types.md#length) | Border width of the slider in the block direction.| diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md b/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md index 5f88febc197d777bfdea733e3e94530d5f181cf4..ac4939dac0b575bc416c3fa85a2d1c777a43947e 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md @@ -14,7 +14,7 @@ Not supported ## APIs -TextPicker(options?: {range: string[]|Resource|TextPickerRangeContent[], selected?: number, value?: string}) +TextPicker(options?: {range: string[] | string[][] | Resource | TextPickerRangeContent[] | TextCascadePickerRangeContent[], selected?: number, value?: string}) Creates a text picker based on the selection range specified by **range**. @@ -22,9 +22,9 @@ Creates a text picker based on the selection range specified by **range**. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| range | string[] \| [Resource](ts-types.md#resource) \| [TextPickerRangeContent](#textpickerrangecontent10)[]10+ | 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.
Default value: **0**
Since API version 10, this parameter supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.| -| value | string | No| Value of the default item in the range. The priority of this parameter is lower than that of **selected**.
Default value: value of the first item
**NOTE**
This parameter works only for a text list. It does not work for an image list or a list consisting of text and images.
Since API version 10, this parameter supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables. | +| range | string[] \| string[][]10+ \| [Resource](ts-types.md#resource) \|
[TextPickerRangeContent](#textpickerrangecontent10)[]10+ \| [TextCascadePickerRangeContent](#textcascadepickerrangecontent10)[]10+ | 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.
**NOTE**
For a single-column picker, use a value of the string[], Resource, or TextPickerRangeContent[] type.
For a multi-column picker, use a value of the string[] type.
For a multi-column linked picker, use a value of the TextCascadePickerRangeContent[] type.
The Resource type supports only [strarray.json](../../quick-start/resource-categories-and-access.md#resource-group-subdirectories).| +| selected | number \| number[]10+ | No| Index of the default item in the range.
Default value: **0**
**NOTE**
For a single-column picker, use a value of the number type.
For a multi-column (linked) picker, use a value of the number[] type.
Since API version 10, this parameter supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.| +| value | string \| string[]10+ | No| Value of the default item in the range. The priority of this parameter is lower than that of **selected**.
Default value: value of the first item
**NOTE**
This parameter works only when the picker contains text only.
For a single-column picker, use a value of the string type.
For a multi-column (linked) picker, use a value of the string[] type.
Since API version 10, this parameter supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables. | ## TextPickerRangeContent10+ @@ -33,6 +33,13 @@ Creates a text picker based on the selection range specified by **range**. | icon | string \| [Resource](ts-types.md#resource) | Yes | Image resource.| | text | string \| [Resource](ts-types.md#resource) | No | Text information.| +## TextCascadePickerRangeContent10+ + +| Name| Type | Mandatory| Description | +| ------ | -------------------------------------------------------- | ---- | ---------- | +| text | string \| [Resource](ts-types.md#resource) | Yes | Text information.| +| children | [TextCascadePickerRangeContent](#textcascadepickerrangecontent10)[] | No | Linkage data.| + ## Attributes In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. @@ -40,9 +47,10 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the | Name| Type| Description| | -------- | -------- | -------- | | defaultPickerItemHeight | number \| string | Height of each item in the picker.| -| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width for the top and bottom items.| -| textStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items.| -| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of the selected item.| +| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | +| textStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | +| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | +| selectedIndex10+ | number \| number[] | Sets the index value of the default selected item in the array. The priority is higher than that of the selected value in options.
**NOTE**
For a single-column picker, use a value of the number type. For a multi-column (linked) picker, use a value of the number[] type.| ## Events @@ -50,9 +58,9 @@ In addition to the [universal events](ts-universal-events-click.md), the followi | Name| Description| | -------- | -------- | -| onAccept(callback: (value: string, index: number) => void) | Triggered when the OK button in the dialog box is clicked.

- **value**: value of the selected item.
- **index**: index of the selected item.
**NOTE**
This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md).| -| onCancel(callback: () => void) | Triggered when the Cancel button in the dialog box is clicked.
**NOTE**
This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md).| -| onChange(callback: (value: string, index: number) => void) | Triggered when an item in the picker is selected.
- **value**: value of the selected item.
**NOTE**
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.
- **index**: index of the selected item.| +| onAccept(callback: (value: string, index: number) => void)(deprecated) | Triggered when the OK button in the dialog box is clicked.
- **value**: value of the selected item.
- **index**: index of the selected item.
This API is deprecated since API version 10.
**NOTE**
This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md).| +| onCancel(callback: () => void)(deprecated) | Triggered when the Cancel button in the dialog box is clicked.
This API is deprecated since API version 10.
**NOTE**
This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md).| +| onChange(callback: (value: string \| string[]10+, index: number \| number[]10+) => void) | Triggered when an item in the picker is selected.
- **value**: value of the selected item. (For a multi-column picker, **value** is of the array type.)
- **index**: index of the selected item. (For a multi-column picker, **index** is of the array type.)
**NOTE**
When the picker contains text only or both text and imagery, **value** indicates the text value of the selected item.When the picker contains imagery only, **value** is empty.| ## Example diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md b/en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md index 633e92d812e4aca2db4c68842a0e6745732c52b1..6a48af10416c622cbf2726655a82711202093e56 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md @@ -28,12 +28,12 @@ Creates a time picker, which is in 24-hour format by default. In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. -| Name | Type | Description | -| -------------------------------- | ---------------------------------------- | ----------------------------------- | -| useMilitaryTime | boolean | Whether to display time in 24-hour format. The value cannot be modified dynamically.
Default value: **false**| -| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width for the top and bottom items. | -| textStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items. | -| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of the selected item. | +| Name | Type | Description | +| -------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| useMilitaryTime | boolean | Whether the display time is in 24-hour format.
Default value: **false** | +| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | +| textStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | +| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | ## Events diff --git a/en/application-dev/reference/arkui-ts/ts-components-offscreencanvas.md b/en/application-dev/reference/arkui-ts/ts-components-offscreencanvas.md index 71009d767f23d99fc89b24061b46579e4c9b050a..d9d6a891eb62380dce9ad2c93e15eb9017d8c5a1 100644 --- a/en/application-dev/reference/arkui-ts/ts-components-offscreencanvas.md +++ b/en/application-dev/reference/arkui-ts/ts-components-offscreencanvas.md @@ -170,14 +170,14 @@ Obtains the drawing context of the offscreen canvas. | Name | Type | Mandatory| Default Value| Description | | ----------- | ------------------------------------------------------------ | ---- | ------ | ------------------------------------------------------------ | -| contextType | string | Yes | "2d" | Type of the drawing context of the offscreen canvas. | +| contextType | string | Yes | "2d" | Type of the drawing context of the offscreen canvas. The value can only be **"2d"**. | | option | [RenderingContextSettings](ts-canvasrenderingcontext2d.md#renderingcontextsettings) | No | - | For details, see [RenderingContextSettings](ts-canvasrenderingcontext2d.md#renderingcontextsettings).| **Return value** | Type | Description | | ------------------------------------------------------------ | --------------------------------- | -| [OffscreenCanvasRenderingContext2D](ts-offscreencanvasrenderingcontext2d.md) | Drawing context of the offscreen canvas.| +| [OffscreenCanvasRenderingContext2D](ts-offscreencanvasrenderingcontext2d.md) | Drawing context of the offscreen canvas. If **contextType** in **getContext** is set to a value other than **"2d"** (including **null** and **undefined**), **null** is returned.| **Example** diff --git a/en/application-dev/reference/arkui-ts/ts-container-badge.md b/en/application-dev/reference/arkui-ts/ts-container-badge.md index 1984ff242a64a9e8360e6ef2064e84211bd6d0d5..78c8f0060a334c71b476f36fedac5d194213fb8a 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-badge.md +++ b/en/application-dev/reference/arkui-ts/ts-container-badge.md @@ -2,7 +2,7 @@ The **\** component is a container that can be attached to another component for tagging. -> **NOTE** +> **NOTE** > > This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. @@ -11,6 +11,10 @@ The **\** component is a container that can be attached to another compon This component supports only one child component. +> **NOTE** +> +> Built-in components and custom components are allowed, with support for ([if/else](../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md)) rendering control. + ## APIs @@ -22,12 +26,12 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name| Type| Mandatory| Default Value| Description| -| -------- | -------- | -------- | -------- | -------- | -| count | number | Yes| - | Number of notifications.| -| position | [BadgePosition](#badgeposition) | No| BadgePosition.RightTop | Position to display the badge relative to the parent component.| -| maxCount | number | No| 99 | Maximum number of notifications. When the maximum number is reached, only **maxCount+** is displayed.| -| style | [BadgeStyle](#badgestyle) | Yes| - | Style of the badge, including the font color, font size, badge color, and badge size.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| count | number | Yes| Number of notifications.
**NOTE**
If the value is less than or equal to 0, no badge is displayed.
Value range: [-2147483648, 2147483647]
If the value is not an integer, it is rounded off to the nearest integer. For example, 5.5 is rounded off to 5.| +| position | [BadgePosition](#badgeposition) | No| Position to display the badge relative to the parent component.
Default value: **BadgePosition.RightTop**| +| maxCount | number | No| Maximum number of notifications. When the maximum number is reached, only **maxCount+** is displayed.
Default value: **99**
Value range: [-2147483648, 2147483647]
If the value is not an integer, it is rounded off to the nearest integer. For example, 5.5 is rounded off to 5.| +| style | [BadgeStyle](#badgestyle) | Yes| Style of the badge, including the font color, font size, badge color, and badge size.| **API 2**: Badge(value: {value: string, position?: BadgePosition, style: BadgeStyle}) @@ -57,15 +61,23 @@ Since API version 9, this API is supported in ArkTS widgets. Since API version 9, this API is supported in ArkTS widgets. -| Name | Type | Mandatory| Default Value | Description | -| ------------------------- | ------------------------------------------------------------ | ---- | ----------------- | ------------------------------------------------------------ | -| color | [ResourceColor](ts-types.md#resourcecolor) | No | Color.White | Font color. | -| fontSize | number \| string | No | 10 | Font size, in vp. | -| badgeSize | number \| string | No | 16 | Badge size, in vp. This parameter cannot be set in percentage. If it is set to an invalid value, the default value is used.| -| badgeColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color.Red | Badge color. | -| fontWeight10+ | number \|[FontWeight](ts-appendix-enums.md#fontweight) \| string | No | FontWeight.Normal | Font weight of the text. | -| borderColor10+ | [ResourceColor](ts-types.md#resourcecolor) | No | Color.Red | Border color of the background. | -| borderWidth10+ | [Length](ts-types.md#length) | No | 1.0vp | Border width of the background. | +| Name | Type | Mandatory| Description | +| ------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| color | [ResourceColor](ts-types.md#resourcecolor) | No | Font color.
Default value: **Color.White** | +| fontSize | number \| string | No | Font size.
Default value: **10**
Unit: vp
**NOTE**
This parameter cannot be set in percentage.| +| badgeSize | number \| string | No | Badge size.
Default value: **16**
Unit: vp
**NOTE**
This parameter cannot be set in percentage. If it is set to an invalid value, the default value is used.| +| badgeColor | [ResourceColor](ts-types.md#resourcecolor) | No | Badge color.
Default value: **Color.Red** | +| fontWeight10+ | number \|[FontWeight](ts-appendix-enums.md#fontweight) \| string | No | Font weight of the text.
Default value: **FontWeight.Normal**
**NOTE**
This parameter cannot be set in percentage.| +| borderColor10+ | [ResourceColor](ts-types.md#resourcecolor) | No | Border color of the background. | +| borderWidth10+ | [Length](ts-types.md#length) | No | Border width of the background.
Default value: **1**
Unit: vp
**NOTE**
This parameter cannot be set in percentage.| + +## Attributes + +The [universal attributes](ts-universal-attributes-size.md) are supported. + +## Events + +The [universal events](ts-universal-events-click.md) are supported. ## Example diff --git a/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md b/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md index 7615fe3729496bd536aebc57a9efc622fa3957a5..05c6a8e612ead7cd031b37c1fe52c3ba302bd52d 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md @@ -5,8 +5,10 @@ An action sheet is a dialog box that displays actions a user can take. > **NOTE** > > The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. - - +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [showActionSheet](../apis/js-apis-arkui-UIContext.md#showactionsheet) API in [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. ## ActionSheet.show diff --git a/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md b/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md index db8ca389e215c3a8ffd750b672212f0db0453ff9..20b98309f386de5f891f49955adb97a9c879be79 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md @@ -5,7 +5,10 @@ You can set the text content and response callback for an alert dialog box. > **NOTE** > > The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. - +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the[showAlertDialog](../apis/js-apis-arkui-UIContext.md#showalertdialog) API in [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. ## Attributes diff --git a/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md b/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md index c1ad40842425ca4cdf7c66635cee70623b1c4509..95a43d0529cce215537848c33198d99c8361594d 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md @@ -4,8 +4,11 @@ A date picker dialog box is a dialog box that allows users to select a date from > **NOTE** > -> The APIs of this module are supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version. - +> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [showDatePickerDialog](../apis/js-apis-arkui-UIContext.md#showdatepickerdialog) API in [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. ## DatePickerDialog.show @@ -15,20 +18,20 @@ Shows a date picker dialog box. **DatePickerDialogOptions** -| Name| Type| Mandatory| Default Value| Description| -| -------- | -------- | -------- | -------- | -------- | -| start | Date | No| Date('1970-1-1') | Start date of the picker.| -| 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.| -| showTime10+ | boolean | No| false | Whether to display the time item.| -| useMilitaryTime10+ | boolean | No| false | Whether to display time in 24-hour format.| -| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| - | Font color, font size, and font width for the top and bottom items.| -| textStyle10+ | [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.| -| selectedTextStyle10+ | [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.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| start | Date | No| Start date of the picker.
Default value: **Date('1970-1-1')**| +| end | Date | No| End date of the picker.
Default value: **Date('2100-12-31')**| +| selected | Date | No| Selected date.
Default value: current system date| +| lunar | boolean | No| Whether to display the lunar calendar.
Default value: **false**| +| showTime10+ | boolean | No| Whether to display the time item.
Default value: **false**| +| useMilitaryTime10+ | boolean | No| Whether to display time in 24-hour format.
Default value: **false**| +| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | +| textStyle10+ | [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.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | +| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | +| 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.| ## Example @@ -86,3 +89,5 @@ struct DatePickerDialogExample { } } ``` + +![DataPickerDialog](figures/DataPickerDialog.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md b/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md index 4da30a11300a3c5e2ab2cf3f622384f207bbf415..c4eb8a23c9fa6473b7c20eb31277ccca64feb4d6 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md @@ -5,7 +5,10 @@ A text picker dialog box is a dialog box that allows users to select text from t > **NOTE** > > The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. - +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [showTextPickerDialog](../apis/js-apis-arkui-UIContext.md#showtextpickerdialog) API in [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. ## TextPickerDialog.show @@ -17,13 +20,13 @@ Shows a text picker in the given settings. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| range | string[] \| [Resource](ts-types.md#resource)\|[TextPickerRangeContent](ts-basic-components-textpicker.md#textpickerrangecontent10)[]10+ | 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.| +| range | string[] \| [Resource](ts-types.md#resource)\|[TextPickerRangeContent](ts-basic-components-textpicker.md#textpickerrangecontent10)[]10+ | 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.
**NOTE**
The Resource type supports only [strarray.json](../../quick-start/resource-categories-and-access.md#resource-group-subdirectories).| | selected | number | No| Index of the selected item.
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.| -| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.| -| textStyle10+ | [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.| -| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.| +| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | +| textStyle10+ | [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.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | +| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | | 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.| @@ -32,8 +35,8 @@ Shows a text picker in the given settings. | Name| Type| Description| | -------- | -------- | -------- | -| value | string | Text of the selected item.
**NOTE**
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.| -| index | number | Index of the selected item in the range.| +| value | string \| string []10+ | Text of the selected item.
**NOTE**
When the picker contains text only or both text and imagery, **value** indicates the text value of the selected item. (For a multi-column picker, **value** is of the array type.)
For an image list, **value** is empty.| +| index | number \| number []10+ | Index of the selected item in the range. (For a multi-column picker, **index** is of the array type.)| ## Example @@ -42,31 +45,35 @@ Shows a text picker in the given settings. @Entry @Component struct TextPickerDialogExample { - @State select: number = 2 + private select: number | number[] = 2 private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5'] build() { - Column() { - Button("TextPickerDialog") - .margin(20) - .onClick(() => { - TextPickerDialog.show({ - range: this.fruits, - selected: this.select, - onAccept: (value: TextPickerResult) => { - // Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed. - this.select = value.index - console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) - }, - onCancel: () => { - console.info("TextPickerDialog:onCancel()") - }, - onChange: (value: TextPickerResult) => { - console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) - } + Row() { + Column() { + Button("TextPickerDialog") + .margin(20) + .onClick(() => { + TextPickerDialog.show({ + range: this.fruits, + selected: this.select, + onAccept: (value: TextPickerResult) => { + // Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed. + this.select = value.index + console.info("TextPickerDialog:onAccept()" + JSON.stringify(value)) + }, + onCancel: () => { + console.info("TextPickerDialog:onCancel()") + }, + onChange: (value: TextPickerResult) => { + console.info("TextPickerDialog:onChange()" + JSON.stringify(value)) + } + }) }) - }) - }.width('100%') + }.width('100%') + }.height('100%') } } ``` + +![TextPickerDialog](figures/TextPickerDialog.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md b/en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md index 246beaf9da869b68aa059efe66b7570f042ff205..bbb16d3d03209f0b955b5c47092e280ef45950db 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md @@ -5,6 +5,10 @@ A time picker dialog box is a dialog box that allows users to select a time from > **NOTE** > > The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. +> +> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext). +> +> Since API version 10, you can use the [showTimePickerDialog](../apis/js-apis-arkui-UIContext.md#showtimepickerdialog) API in [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. ## TimePickerDialog.show @@ -19,9 +23,9 @@ Shows a time picker dialog box. | -------- | -------- | -------- | -------- | | selected | Date | No| Selected time.
Default value: current system time| | useMilitaryTime | boolean | No| Whether to display time in 24-hour format. The 12-hour format is used by default.
Default value: **false**| -| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.| -| textStyle10+ | [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.| -| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.| +| disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | +| textStyle10+ | [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.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | +| selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | | 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.| @@ -43,7 +47,7 @@ struct TimePickerDialogExample { TimePickerDialog.show({ selected: this.selectTime, onAccept: (value: TimePickerResult) => { - //Set selectTime to the time when the OK button is clicked. In this way, when the dialog box is displayed again, the selected time is the time when the operation was confirmed last time. + // Set selectTime to the time when the OK button is clicked. In this way, when the dialog box is displayed again, the selected time is the time when the operation was confirmed last time. this.selectTime.setHours(value.hour, value.minute) console.info("TimePickerDialog:onAccept()" + JSON.stringify(value)) }, @@ -77,3 +81,5 @@ struct TimePickerDialogExample { } } ``` + +![TimetPickerDialog](figures/TimePickerDialog.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-types.md b/en/application-dev/reference/arkui-ts/ts-types.md index dd3ce725c77effe392403ed8b2102e9f8608e19b..df71967ffb8f97b52183d429b82ae3d7c38b8c0e 100644 --- a/en/application-dev/reference/arkui-ts/ts-types.md +++ b/en/application-dev/reference/arkui-ts/ts-types.md @@ -156,10 +156,10 @@ The **Font** type is used to set the text style. | Name | Type | Mandatory | Description | | ------ | ---------------------------------------- | ---- | ---------------------------------------- | -| size | [Length](#length) | No | Font size. If the value is of the number type, the unit fp is used. The value cannot be a percentage.| -| weight | [FontWeight](ts-appendix-enums.md#fontweight) \| number \| string | No | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.| +| size | [Length](#length) | No | Font size. If the value is of the number type, the unit fp is used. The value cannot be a percentage.
Default value: **16.0** | +| weight | [FontWeight](ts-appendix-enums.md#fontweight) \| number \| string | No | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a thicker font.
Default value: **400** \| **FontWeight.Normal** | | family | string \| [Resource](#resource) | No | Font family of the text. Use commas (,) to separate multiple fonts. The priority of the fonts is the sequence in which they are placed. An example value is **'Arial, HarmonyOS Sans'**. Currently, only the **'HarmonyOS Sans'** font is supported.| -| style | [FontStyle](ts-appendix-enums.md#fontstyle) | No | Font style. | +| style | [FontStyle](ts-appendix-enums.md#fontstyle) | No | Font style.
Default value: **FontStyle.Normal** | ## Area8+ diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md index 5c282923bc24c0d62718d986f16a7ed09b0d7642..62ff2bf39459d2e6ff58418fc7d0ab1cea3c46ff 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-image-effect.md @@ -22,10 +22,10 @@ Image effects include blur, shadow, spherical effect, and much more. | invert | number | 0 | Inversion ratio of the component. If the value is **1**, the component is completely inverted. If the value is **0**, the component remains unchanged. The unit is percentage.
Value range: [0, 1]
**NOTE**
A value less than 0 evaluates to the value **0**.
Since API version 9, this API is supported in ArkTS widgets.| | sepia | number | 0 | Sepia conversion ratio of the component. If the value is **1**, the image is completely sepia. If the value is **0**, the component remains unchanged. The unit is percentage.
Since API version 9, this API is supported in ArkTS widgets.| | hueRotate | number \| string | '0deg' | Hue rotation angle of the component.
Value range: (-∞, +∞)
**NOTE**
A rotation of 360 degrees leaves the color unchanged. A rotation of 180 degrees and then -180 degrees also leaves the color unchanged. When the data type is number, the value 90 is equivalent to **'90deg'**.
Since API version 9, this API is supported in ArkTS widgets.| -| colorBlend 8+ | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | - | Color to blend with the component.
Since API version 9, this API is supported in ArkTS widgets.| -| sphericalEffect10+ | [number] | - | Spherical degree of the component.
The value ranges from 0 to 1.
**NOTE**
1. If the value is **0**, the component remains unchanged. If the value is **1**, the component is completely spherical. Between 0 and 1, a greater value indicates a higher spherical degree.
A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.
2. If a component image is loaded asynchronously, the spherical effect is not supported. For example, the **\** component uses asynchronous loading by default, which means that **syncLoad** must be set to **true** to apply the spherical effect. However, this setting is not recommended. Asynchronous loading is also used for **backgroundImage**. Therefore, if **backgroundImage** is set, the spherical effect is not supported.
3. If the shadow effect is set for a component, the spherical effect is not supported.| -| lightUpEffect10+ | [number] | - | Light up degree of the component.
The value ranges from 0 to 1.
If the value is **0**, the component is dark. If the value is **1**, the component is fully illuminated. Between 0 and 1, a greater value indicates higher luminance. A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.| -| pixelStretchEffect10+ | [PixelStretchEffectOptions](ts-types.md#pixelstretcheffectoptions10) | - | Pixel stretch effect options.
The **options** parameter includes the length by which a pixel is stretched toward the four edges.
**NOTE**
1. If the length is a positive value, the original image is stretched, and the image size increases. The edge pixels grow by the set length toward the top, bottom, left, and right edges.
2. 2. If the length is a negative value, the original image shrinks as follows, but the image size remains unchanged:
(1) The image shrinks from the four edges by the absolute value of length set through **options**.
(2) The image is stretched back to the original size with edge pixels.
3. Constraints on **options**:
(1) The length values for the four edges must be all positive or all negative. That is, the four edges are stretched or shrink at the same time in the same direction.
(2) The length values must all be a percentage or a specific value. Combined use of the percentage and specific value is not allowed.
(3) If the input value is invalid, the image is displayed as {0, 0, 0, 0}, that is, the image is the same as the original image. | +| colorBlend8+ | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | - | Color to blend with the component.
Since API version 9, this API is supported in ArkTS widgets.| +| sphericalEffect10+ | [number] | - | Spherical degree of the component.
The value ranges from 0 to 1.
**NOTE**
1. If the value is **0**, the component remains unchanged. If the value is **1**, the component is completely spherical. Between 0 and 1, a greater value indicates a higher spherical degree.
A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.
2. If a component image is loaded asynchronously, the spherical effect is not supported. For example, the **\** component uses asynchronous loading by default, which means that **syncLoad** must be set to **true** to apply the spherical effect. However, this setting is not recommended. Asynchronous loading is also used for **backgroundImage**. Therefore, if **backgroundImage** is set, the spherical effect is not supported.
3. If the shadow effect is set for a component, the spherical effect is not supported.
This is a system API.| +| lightUpEffect10+ | [number] | - | Light up degree of the component.
The value ranges from 0 to 1.
If the value is **0**, the component is dark. If the value is **1**, the component is fully illuminated. Between 0 and 1, a greater value indicates higher luminance. A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.
This is a system API.| +| pixelStretchEffect10+ | [PixelStretchEffectOptions](ts-types.md#pixelstretcheffectoptions10) | - | Pixel stretch effect options.
The **options** parameter includes the length by which a pixel is stretched toward the four edges.
**NOTE**
1. If the length is a positive value, the original image is stretched, and the image size increases. The edge pixels grow by the set length toward the top, bottom, left, and right edges.
2. 2. If the length is a negative value, the original image shrinks as follows, but the image size remains unchanged:
(1) The image shrinks from the four edges by the absolute value of length set through **options**.
(2) The image is stretched back to the original size with edge pixels.
3. Constraints on **options**:
(1) The length values for the four edges must be all positive or all negative. That is, the four edges are stretched or shrink at the same time in the same direction.
(2) The length values must all be a percentage or a specific value. Combined use of the percentage and specific value is not allowed.
(3) If the input value is invalid, the image is displayed as {0, 0, 0, 0}, that is, the image is the same as the original image.
This is a system API.| ## ShadowOptions @@ -320,7 +320,6 @@ Below is how the component looks: Compared with the original image, the effect drawing is implemented in two steps: -1. The image size is reduced. The resultant size is the original image size minus -the lengths by which the pixels shrink. For example, if the original image size is 100 x 100 and **pixelStretchEffect({top:-10,left:-10,** +1. The image size is reduced. The resultant size is the original image size minus the lengths by which the pixels shrink. For example, if the original image size is 100 x 100 and **pixelStretchEffect({top:-10,left:-10,** **right:-10,bottom:-10})** is set, the resultant size is (100-10-10) x (100-10-10), that is, 8080. 2. Edge pixels are stretched to restore the image to its original size. \ No newline at end of file diff --git a/en/application-dev/reference/arkui-ts/ts-universal-component-area-change-event.md b/en/application-dev/reference/arkui-ts/ts-universal-component-area-change-event.md index 2e0e8610515d57f66aa28d424140c657da95f368..61312be7ecde554a1a50681c007f70421e257cf9 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-component-area-change-event.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-component-area-change-event.md @@ -11,7 +11,7 @@ The area change event is triggered when the component's size, position, or any o | Name | Bubbling Supported| Description | | ---------------------------------------- | ---- | ---------------------------------------- | -| onAreaChange(event: (oldValue: [Area](ts-types.md#area8), newValue: [Area](ts-types.md#area8)) => void) | No | Triggered when the component area changes.| +| onAreaChange(event: (oldValue: [Area](ts-types.md#area8), newValue: [Area](ts-types.md#area8)) => void) | No | Triggered when the component area changes in size or position due to layout updates. This event is not triggered for render attribute changes caused by re-rendering, such as changes of **translate** and **offset**.| ## Example