diff --git a/en/application-dev/reference/apis-arkui/_ark_u_i___native_dialog_a_p_i__2.md b/en/application-dev/reference/apis-arkui/_ark_u_i___native_dialog_a_p_i__2.md index 910bc1dac31b10f701f15459de6f91f0413ced83..fec3bb994e78eef18f886c9103734d7a20372b16 100644 --- a/en/application-dev/reference/apis-arkui/_ark_u_i___native_dialog_a_p_i__2.md +++ b/en/application-dev/reference/apis-arkui/_ark_u_i___native_dialog_a_p_i__2.md @@ -20,9 +20,9 @@ Provides the custom dialog box APIs (version 2) for the native side. | -------- | -------- | | [ArkUI_NativeDialogAPI_1](_ark_u_i___native_dialog_a_p_i__1.md#arkui_nativedialogapi_1) nativeDialogAPI1 | A set of the custom dialog box APIs on the native side. | | int32_t(\* [setKeyboardAvoidDistance](#setkeyboardavoiddistance) )([ArkUI_NativeDialogHandle](_ark_u_i___native_module.md#arkui_nativedialoghandle) handle, float distance, [ArkUI_LengthMetricUnit](_ark_u_i___native_module.md#arkui_lengthmetricunit) unit) | Distance between the dialog box and the keyboard after keyboard avoidance is applied. | -| int32_t(\* [setLevelMode](#setlevelmode) )([ArkUI_NativeDialogHandle](_ark_u_i___native_module.md#arkui_nativedialoghandle) handle, [ArkUI_LevelMode](_ark_u_i___native_module.md#arkui_levelmode) levelMode) | Sets the display level of the dialog box. | -| int32_t(\* [setLevelUniqueId](#setleveluniqueid) )([ArkUI_NativeDialogHandle](_ark_u_i___native_module.md#arkui_nativedialoghandle) handle, int32_t uniqueId) | Sets the ID of the node under the dialog box's display level. | -| int32_t(\* [setImmersiveMode](#setimmersivemode) )([ArkUI_NativeDialogHandle](_ark_u_i___native_module.md#arkui_nativedialoghandle) handle, [ArkUI_ImmersiveMode](_ark_u_i___native_module.md#arkui_immersivemode) immersiveMode) | Sets the display area of the embedded dialog box overlay. | +| int32_t(\* [setLevelMode](#setlevelmode) )([ArkUI_NativeDialogHandle](_ark_u_i___native_module.md#arkui_nativedialoghandle) handle, [ArkUI_LevelMode](_ark_u_i___native_module.md#arkui_levelmode) levelMode) | Display level of the dialog box. | +| int32_t(\* [setLevelUniqueId](#setleveluniqueid) )([ArkUI_NativeDialogHandle](_ark_u_i___native_module.md#arkui_nativedialoghandle) handle, int32_t uniqueId) | ID of the node under the dialog box's display level. | +| int32_t(\* [setImmersiveMode](#setimmersivemode) )([ArkUI_NativeDialogHandle](_ark_u_i___native_module.md#arkui_nativedialoghandle) handle, [ArkUI_ImmersiveMode](_ark_u_i___native_module.md#arkui_immersivemode) immersiveMode) | Display area of the embedded dialog box overlay. | diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/accessibilityFocusDrawLevel.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/accessibilityFocusDrawLevel.png new file mode 100644 index 0000000000000000000000000000000000000000..6517c5252b96def9ece47eed83dd207806942004 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/accessibilityFocusDrawLevel.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/applyDisabledAttribute.gif b/en/application-dev/reference/apis-arkui/arkui-ts/figures/applyDisabledAttribute.gif new file mode 100644 index 0000000000000000000000000000000000000000..ff047828eeaa2e38ac829e6f5e1d4a3ca58a20fc Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/applyDisabledAttribute.gif differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/applyFocusedAttribute.gif b/en/application-dev/reference/apis-arkui/arkui-ts/figures/applyFocusedAttribute.gif new file mode 100644 index 0000000000000000000000000000000000000000..f1502f158c16f7c9e1281ef6ba1cd47a97ec237a Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/applyFocusedAttribute.gif differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/applySelectedAttribute.gif b/en/application-dev/reference/apis-arkui/arkui-ts/figures/applySelectedAttribute.gif new file mode 100644 index 0000000000000000000000000000000000000000..01379c0bb6d0554464700854360b9821be096d3c Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/applySelectedAttribute.gif differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/canvasImageAnalyzer.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/canvasImageAnalyzer.png new file mode 100644 index 0000000000000000000000000000000000000000..c9fcb2c6b66ab185b6777db4e51d7a9e0645618a Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/canvasImageAnalyzer.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/drawForeground.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/drawForeground.png new file mode 100644 index 0000000000000000000000000000000000000000..7b80ea0c65cd618a10333d561f87ec534c1b4be5 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/drawForeground.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/drawModifier.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/drawModifier.png new file mode 100644 index 0000000000000000000000000000000000000000..6ce15999035382a0b16b0a0480ffab4e36dff00c Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/drawModifier.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/en-us_image_lazyvgridlayout1.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/en-us_image_lazyvgridlayout1.png new file mode 100644 index 0000000000000000000000000000000000000000..a1d173eff21f1f63a237452f929fd28b6fea3ea4 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/en-us_image_lazyvgridlayout1.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority1.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority1.png new file mode 100644 index 0000000000000000000000000000000000000000..e29425a969fdc76f8f28a290ed4f570fef2e43fc Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority1.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority2.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority2.png new file mode 100644 index 0000000000000000000000000000000000000000..bc6a636b0a2fb85fbbb5df829af60f10f9bea0a9 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority2.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority3.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority3.png new file mode 100644 index 0000000000000000000000000000000000000000..07383fdaa44a69596e1a784f7e1cd0c7f89a3683 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority3.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority4.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority4.png new file mode 100644 index 0000000000000000000000000000000000000000..797828c8c322cd24946d16dfc33397b6962dd7a8 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority4.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority5.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority5.png new file mode 100644 index 0000000000000000000000000000000000000000..50544aa1be394d9af32bea72a348e092b4c2d189 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/focusScopePriority5.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/imageAnimator_resource.gif b/en/application-dev/reference/apis-arkui/arkui-ts/figures/imageAnimator_resource.gif new file mode 100644 index 0000000000000000000000000000000000000000..d932723cde6b3559ccd49d801267e70fd4cf216a Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/imageAnimator_resource.gif differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/layoutPolicy_demo.jpg b/en/application-dev/reference/apis-arkui/arkui-ts/figures/layoutPolicy_demo.jpg new file mode 100644 index 0000000000000000000000000000000000000000..80d7cfcf3c7c6fb0fa9bb16ad7928158b94237fa Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/layoutPolicy_demo.jpg differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/safeAreaPaddingModifierExample.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/safeAreaPaddingModifierExample.png new file mode 100644 index 0000000000000000000000000000000000000000..ed76f679378f7ace48bb4a16d447ef03c83fdaea Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/safeAreaPaddingModifierExample.png differ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-formmenu.md b/en/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-formmenu.md index 1961c836bbc07dc464e1f05ae8b1d0591576c86b..5829083c33d24bb0118340c356525086fa350b47 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-formmenu.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ohos-arkui-advanced-formmenu.md @@ -14,6 +14,8 @@ This component facilitates the quick addition of service widgets to the home scr > **NOTE** > > This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. +> +> This component is not supported on wearables. ## Modules to Import @@ -110,9 +112,9 @@ struct Index { bundleName: 'com.example.myapplication', // Bundle name abilityName: 'EntryFormAbility', // Module ability name. parameters: { - 'ohos.extra.param.key.form_dimension': 2, - 'ohos.extra.param.key.form_name': 'widget', - 'ohos.extra.param.key.module_name': 'entry' + 'ohos.extra.param.key.form_dimension': 2, // Widget size: 1 for 1 x 2, 2 for 2 x 2, 3 for 2 x 4, 4 for 4 x 4, 7 for 6 x 4, 6 for 1 x 1. + 'ohos.extra.param.key.form_name': 'widget', // Widget name. + 'ohos.extra.param.key.module_name': 'entry' // Module name of the widget. }, }, this.compId, diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-appendix-enums.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-appendix-enums.md index 80f723ce184efcf44e2c617a0c559b6889bdd661..d25b8a9cdd529e413aa6521b16823da884e4e323 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-appendix-enums.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-appendix-enums.md @@ -80,8 +80,6 @@ ## TouchType -**Atomic service API**: This API can be used in atomic services since API version 11. - **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Description | @@ -89,7 +87,7 @@ | Down | A finger is pressed. | | Up | A finger is lifted. | | Move | A finger moves on the screen in pressed state.| -| Cancel | A touch event is canceled. | +| Cancel | A touch event is canceled. Examples: 1. touching the home button to return to the home screen while keeping a finger on the screen; 2. folding a foldable phone to switch to the external screen while keeping a finger on the screen.| ## MouseButton8+ @@ -417,10 +415,10 @@ Enumerates the interpolation curves. For details about the animation, see +```ts +import { LengthMetrics } from '@kit.ArkUI' +import { MyDataSource } from './MyDataSource' + +@Entry +@Component +struct LazyVGridLayoutSample1 { + private arr:MyDataSource = new MyDataSource(); + build() { + Column() { + WaterFlow() { + LazyVGridLayout() { + LazyForEach(this.arr, (item:number)=>{ + Text("item" + item.toString()) + .height(64) + .width("100%") + .borderRadius(5) + .backgroundColor(Color.White) + .textAlign(TextAlign.Center) + }) + } + .columnsTemplate("1fr 1fr") + .rowsGap(LengthMetrics.vp(10)) + .columnsGap(LengthMetrics.vp(10)) + }.padding(10) + } + .width('100%').height('100%') + .backgroundColor("#DCDCDC") + } + + aboutToAppear(): void { + for (let i = 0; i < 100; i++) { + this.arr.pushData(i); + } + } +} +``` + + +```ts +// MyDataSource.ets +export class BasicDataSource implements IDataSource { + private listeners: DataChangeListener[] = []; + protected dataArray: T[] = []; + + public totalCount(): number { + return this.dataArray.length; + } + + public getData(index: number): T { + return this.dataArray[index]; + } + + registerDataChangeListener(listener: DataChangeListener): void { + if (this.listeners.indexOf(listener) < 0) { + console.info('add listener'); + this.listeners.push(listener); + } + } + + unregisterDataChangeListener(listener: DataChangeListener): void { + const pos = this.listeners.indexOf(listener); + if (pos >= 0) { + console.info('remove listener'); + this.listeners.splice(pos, 1); + } + } + + notifyDataReload(): void { + this.listeners.forEach(listener => { + listener.onDataReloaded(); + }) + } + + notifyDataAdd(index: number): void { + this.listeners.forEach(listener => { + listener.onDataAdd(index); + }) + } + + notifyDataChange(index: number): void { + this.listeners.forEach(listener => { + listener.onDataChange(index); + }) + } + + notifyDataDelete(index: number): void { + this.listeners.forEach(listener => { + listener.onDataDelete(index); + }) + } + + notifyDataMove(from: number, to: number): void { + this.listeners.forEach(listener => { + listener.onDataMove(from, to); + }) + } + + notifyDatasetChange(operations: DataOperation[]): void { + this.listeners.forEach(listener => { + listener.onDatasetChange(operations); + }) + } +} + +export class MyDataSource extends BasicDataSource { + public shiftData(): void { + this.dataArray.shift(); + this.notifyDataDelete(0); + } + public unshiftData(data: T): void { + this.dataArray.unshift(data); + this.notifyDataAdd(0); + } + public pushData(data: T): void { + this.dataArray.push(data); + this.notifyDataAdd(this.dataArray.length - 1); + } + public popData(): void { + this.dataArray.pop(); + this.notifyDataDelete(this.dataArray.length); + } + public clearData(): void { + this.dataArray = []; + this.notifyDataReload(); + } +} +``` + +![](figures/en-us_image_lazyvgridlayout1.png) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-swiper.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-swiper.md index d37d798a4f6982a20fe7c2344948fe38725d9526..4a26edd7324334acbeb5913b20c968dcc2d14ef3 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-swiper.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-swiper.md @@ -7,20 +7,24 @@ > - This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. > > - The **Swiper** component incorporates a [PanGesture](ts-basic-gestures-pangesture.md) event that facilitates the swiping action to cycle through its child components. Setting [disableSwipe](#disableswipe8) to **true** will cancel the internal listening for the **PanGesture** event, disabling the swiping interaction. +> +> - When [NodeContainer](./ts-basic-components-nodecontainer.md) is reused in the **Swiper** component, recursive updates of parent component state variables by child nodes are prohibited. ## Child Components -This component can contain child components. +Supported > **NOTE** > -> - Child components can consist of both built-in components and custom components, and their rendering can be controlled with [if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md), and [Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md). To maximize the benefits of lazy loading, avoid mixing lazy loading components (including **LazyForEach** and **Repeat**) and non-lazy loading components, and exercise caution when using multiple lazy loading components. Avoid modifying the data source while an animation is in progress, as doing so can lead to layout issues. +> - Allowed child component types: built-in and custom components, including rendering control types ([if/else](../../../ui/state-management/arkts-rendering-control-ifelse.md), [ForEach](../../../ui/state-management/arkts-rendering-control-foreach.md), [LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md), and [Repeat](../../../ui/state-management/arkts-new-rendering-control-repeat.md)). To maximize the benefits of lazy loading, avoid mixing lazy loading components (including **LazyForEach** and **Repeat**) and non-lazy loading components, and exercise caution when using multiple lazy loading components. Avoid modifying the data source while an animation is in progress, as doing so can lead to layout issues. > > - If a child component has its [visibility](ts-universal-attributes-visibility.md#visibility) attribute set to **Visibility.None** and the **Swiper** component has its **displayCount** attribute set to **'auto'**, the child component does not take up space in the viewport, but does not affect the number of navigation points. If a child component has its **visibility** attribute set to **Visibility.None** or **Visibility.Hidden**, it takes up space in the viewport, but is not displayed. > > - Child components of the **Swiper** component are drawn based on their level if they have the [offset](ts-universal-attributes-location.md#offset) attribute set. A child component with a higher level overwrites one with a lower level. For example, if the **Swiper** contains three child components and **offset({ x: 100 })** is set for the third child component, the third child component overwrites the first child component during horizontal loop playback. To prevent the first child component from being overwritten, set its [zIndex](ts-universal-attributes-z-order.md) attribute to a value greater than that of the third child component. > -> - When focus is moved to a custom child node, navigation points and arrows may be obscured by changes to the z-index due to [focus styles](../../../ui/arkts-common-events-focus-event.md#focus-style). +> - When focus is moved to a custom child node, navigation indicators and arrows may be obscured by [focus styles](../../../ui/arkts-common-events-focus-event.md#focus-style) modifications that change **zIndex**. +> +> - For a **Swiper** components with many child components, you can optimize the performance and reduce memory consumption by using lazy loading, data caching, preloading, and component reuse techniques. For best practices, see [Optimizing Frame Loss During Swiper Component Loading](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-swiper_high_performance_development_guide). ## APIs @@ -38,7 +42,7 @@ Creates a **Swiper** component. | Name | Type | Mandatory | Description | | ---------- | ------------------------------------- | ---- | -------------------- | -| controller | [SwiperController](#swipercontroller) | No | Controller bound to the component to control the swiping.| +| controller | [SwiperController](#swipercontroller) | No | Controller to bind to the component to manage page switching and preload specific child components.| ## Attributes @@ -55,7 +59,7 @@ index(value: number) Sets the index of the child component currently displayed in the container. If the value is less than 0 or greater than or equal to the number of child components, the default value **0** is used. -Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). +Since API version 10, this attribute supports two-way binding through [$$](../../../ui/state-management/arkts-two-way-sync.md). **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -73,9 +77,9 @@ Since API version 10, this attribute supports two-way binding through [$$](../.. autoPlay(value: boolean) -Sets whether to enable automatic playback for child component switching. +Sets whether to enable automatic playback for child components, with the direction from the smallest to largest index. -If **loop** is set to **false**, the playback stops when the last page is reached. The playback continues when the page is not the last page after a swipe gesture. If the **Swiper** component becomes invisible, the playback stops. +If [loop](#loop) is set to **false**, the automatic playback stops at the last page and resumes after navigated away from the last page using gestures. If the **Swiper** component becomes invisible, the playback stops. **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -87,15 +91,15 @@ If **loop** is set to **false**, the playback stops when the last page is reache | Name| Type | Mandatory| Description | | ------ | ------- | ---- | -------------------------------------- | -| value | boolean | Yes | Whether to enable automatic playback for child component switching.
Default value: **false** (automatic playback is disabled for child component switching.)| +| value | boolean | Yes | Whether to enable automatic playback for child components.
Default value: **false** (automatic playback is disabled for child components).| ### autoPlay18+ autoPlay(autoPlay: boolean, options: AutoPlayOptions) -Sets whether child components automatically play when the screen is pressed by fingers, a mouse device, or other input devices. +Sets whether to enable automatic playback for child components, with **options** controlling whether child components stop automatic playback when the screen is pressed by fingers, a mouse device, or other input devices. -If [loop](#loop) is set to **false**, autoplay stops when the last page is reached. If a gesture is used to switch pages and the last page is not reached, playback will continue. Autoplay also stops when the **Swiper** component is not visible. +If [loop](#loop) is set to **false**, automatic playback stops at the last page and resumes after navigated away from the last page using gestures. Automatic playback also stops when the **Swiper** component is not visible. **Widget capability**: This API can be used in ArkTS widgets since API version 18. @@ -107,8 +111,8 @@ If [loop](#loop) is set to **false**, autoplay stops when the last page is reach | Name| Type | Mandatory| Description | | ------ | ------- | ---- | -------------------------------------- | -| autoPlay | boolean | Yes | Whether to enable automatic playback for child component switching.
Default value: **false** (automatic playback is disabled for child component switching)| -| options | [AutoPlayOptions](#autoplayoptions18) | Yes | Whether child components stop autoplay when the screen is pressed by fingers, a mouse device, or other input devices. If **stopWhenTouched** is set to **true**, autoplay stops when the screen is pressed.
Default value: **{ stopWhenTouched: true }** (stop autoplay)| +| autoPlay | boolean | Yes | Whether to enable automatic playback for child components.
Default value: **false** (automatic playback is disabled for child components).| +| options | [AutoPlayOptions](#autoplayoptions18) | Yes | Whether child components stop automatic playback when the screen is pressed by fingers, a mouse device, or other input devices. If **stopWhenTouched** is set to **true**, automatic playback resumes after any finger lifts in multi-touch scenarios.
Default value: **{ stopWhenTouched: true }**.| ### interval @@ -126,7 +130,7 @@ Sets the interval for automatic playback. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ---------------------------------------------------------- | -| value | number | Yes | Interval for automatic playback.
Default value: **3000**
Unit: ms
Value range: [0, +∞). If a value less than 0 is set, the default value is used.| +| value | number | Yes | Interval for automatic playback. If the value is smaller than the value of [duration](#duration), the next carousel starts immediately after page switching completes.
Default value: **3000**.
Unit: ms
Value range: [0, +∞). If a value less than 0 is set, the default value is used.| ### indicator @@ -162,7 +166,7 @@ Sets the navigation indicator for the component. | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| indicator | [IndicatorComponentController](ts-swiper-components-indicator.md#indicatorcomponentcontroller)15+ \| [DotIndicator](#dotindicator10) \| [DigitIndicator](#digitindicator10) \| boolean| Yes | Style of the navigation indicator.
\- **IndicatorComponentController**: separate navigation indicator controller. This controller can be bound to an external navigation indicator, but the external and internal indicators cannot coexist.
\- **DotIndicator**: dot-style indicator.
\- **DigitIndicator**: digit-style indicator.
\- **boolean**: whether to enable the navigation indicator. The value **true** means to enable the feature, and **false** means the opposite.
Default value: **true**
Default style: **DotIndicator**| +| indicator | [IndicatorComponentController](ts-swiper-components-indicator.md#indicatorcomponentcontroller)15+ \| [DotIndicator](#dotindicator10) \| [DigitIndicator](#digitindicator10) \| boolean| Yes | Style of the navigation indicator.
\- **IndicatorComponentController**: separate navigation indicator controller. This controller can be bound to an external navigation indicator, but the external and internal indicators cannot coexist.
\- **DotIndicator**: dot style.
\- **DigitIndicator**: digit style.
\- **boolean**: whether to enable the navigation indicator. The value **true** means to enable the feature, and **false** means the opposite.
Default value: **true**
Default style: **DotIndicator**| ### loop @@ -181,7 +185,7 @@ Sets whether to enable loop playback. The value **true** means to enable loop pl | Name| Type | Mandatory| Description | | ------ | ------- | ---- | ------------------------------- | -| value | boolean | Yes | Whether to enable loop playback.
Default value: **true**| +| value | boolean | Yes | Whether to enable loop playback. The value **true** means to enable loop playback, and **false** means the opposite.
Default value: **true**.| ### duration @@ -191,7 +195,7 @@ Sets the duration of the animation for child component switching. **duration** must be used in conjunction with [curve](#curve8). -The default curve for the animation is [interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10).When this curve is applied, the duration of the animation is determined solely by the parameters of the curve itself and is no longer governed by the **duration** setting. For curves that are not governed by the **duration** setting, see [Interpolation Calculation](../js-apis-curve.md). Among others, [springMotion](../js-apis-curve.md#curvesspringmotion9) and [responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9) do not respect the **duration** setting. To have the animation duration managed by **duration**, you should select a different curve for the **curve** attribute. +The default curve for the animation is [interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10). When this curve is applied, the duration of the animation is determined solely by the parameters of the curve itself and is no longer governed by the **duration** setting. For curves that are not governed by the **duration** setting, see [Interpolation Calculation](../js-apis-curve.md). Among others, [springMotion](../js-apis-curve.md#curvesspringmotion9) and [responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9) do not respect the **duration** setting. To have the animation duration managed by **duration**, you should select a different curve for the **curve** attribute. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -219,13 +223,13 @@ Sets whether vertical swiping is used. | Name| Type | Mandatory| Description | | ------ | ------- | ---- | ---------------------------------- | -| value | boolean | Yes | Whether vertical swiping is used. The value **true** means vertical swiping, and **false** means horizontal swiping.
Default value: **false**| +| value | boolean | Yes | Whether vertical swiping is used. The value **true** means vertical swiping, and **false** means horizontal swiping.
Default value: **false**.| ### itemSpace itemSpace(value: number | string) -Sets the space between child components. This attribute cannot be set in percentage. +Sets the space between child components. Percentage values are not supported. If the type is number, the default unit is vp. If the type is string, the pixel unit must be explicitly specified, for example, **'10px'**; if the unit is not specified, for example, **'10'**, the default unit vp is used. @@ -239,7 +243,7 @@ If the type is number, the default unit is vp. If the type is string, the pixel | Name| Type | Mandatory| Description | | ------ | -------------------------- | ---- | -------------------------------------- | -| value | number \| string | Yes | Space between child components.
Default value: **0**
Value range: [0, +∞). If a value less than 0 is set, the default value is used.| +| value | number \| string | Yes | Space between child components.
Default value: **0**
Value range: [0, +∞). Values less than 0 or exceeding the **Swiper** component width are treated as the default value.| ### displayMode @@ -263,7 +267,11 @@ Sets the mode in which elements are displayed along the main axis. This API take cachedCount(value: number) -Sets the number of child components to be preloaded (cached), which are needed for the specific number of pages immediately before and after the current page. For example, if **cachedCount** is set to **1**, the child components on the previous page and the next page are cached. If **swipeByGroup** in **displayCount** is set to **true**, child components are cached by group. For example, if **cachedCount** is set to **1** and **swipeByGroup** is set to **true**, the child components in the previous and next groups are cached. +Sets the number of child components to be preloaded (cached), which are needed for the specific number of pages immediately before and after the current page. If a preceding item is deleted, the succeeding items will shift forward. For example, if **cachedCount** is set to **1**, the child components on the previous page and the next page are cached. If **swipeByGroup** in **displayCount** is set to **true**, child components are cached by group. For example, if **cachedCount** is set to **1** and **swipeByGroup** is set to **true**, the child components in the previous and next groups are cached. + +> **NOTE** +> +> - In continuous scrolling scenarios where one **Swiper** child component is displayed per screen, setting **cachedCount** to **1** or **2** is typically sufficient. For best practices, see [Optimizing Frame Loss During Swiper Component Loading – Caching Data Items](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-swiper_high_performance_development_guide#section143504547145). **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -294,7 +302,7 @@ Sets the number of child components to be cached. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------------------- | | count | number | Yes | Number of child components to be preloaded (cached).
Default value: **1**
Value range: [0, +∞). If a value less than 0 is set, the default value is used.| -| isShown | boolean | Yes | Whether the cached nodes within the range rendered without being added to the render tree.
Default value: **false**, indicating that cached nodes within the range are rendered| +| isShown | boolean | Yes | Whether the cached nodes within the range rendered without being added to the render tree.
Default value: **false**, indicating that cached nodes within the range are rendered.| ### disableSwipe8+ @@ -312,7 +320,7 @@ Sets whether to disable the swipe feature. | Name| Type | Mandatory| Description | | ------ | ------- | ---- | ---------------------------------------- | -| value | boolean | Yes | Whether to disable the swipe feature. The value **true** means to disable the feature, and **false** means the opposite.
Default value: **false**| +| value | boolean | Yes | Whether to disable the swipe feature. The value **true** means to disable the feature, and **false** means the opposite.
Default value: **false**.| ### curve8+ @@ -330,7 +338,7 @@ Sets the animation curve. The interpolating spring curve is used by default. For | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------- | -| value | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../js-apis-curve.md#icurve9)10+ | Yes | Animation curve.
Default value: **interpolatingSpring(-1, 1, 328, 34)**| +| value | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../js-apis-curve.md#icurve9)10+ | Yes | Animation curve.
The **string** type is deprecated since API version 9 (see [curves.init](../js-apis-curve.md#curvesinitdeprecated), [curves.steps](../js-apis-curve.md#curvesstepsdeprecated), [curves.cubicBezier](../js-apis-curve.md#curvescubicbezierdeprecated), and [curves.spring](../js-apis-curve.md#curvesspringdeprecated)). Use **Curve** or **ICurve** instead.
Default value: **[interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10)(-1, 1, 328, 34)**.| ### indicatorStyle(deprecated) @@ -350,13 +358,32 @@ This API is supported since API version 8 and is deprecated since API version 10 ### displayCount8+ -displayCount(value: number | string | SwiperAutoFill, swipeByGroup?: boolean) +displayCount(value: number | string | [SwiperAutoFill](#swiperautofill10), swipeByGroup?: boolean) Sets the number of elements to display per page. -If the value is of the string type, it can only be **'auto'**. In this case, setting [customContentTransition](#customcontenttransition12) or [onContentDidScroll](#oncontentdidscroll12) has no effect. If the value is of the number type, child components stretch (shrink) on the main axis after the swiper width [deducting the result of itemSpace x (**displayCount** - 1)] is evenly distributed among them on the main axis; a value less than or equal to 0 is handled as the default value **1**. If the value is of the SwiperAutoFill type, the system automatically works out the value based on the width and **minSize** settings of the **Swiper** component. If **minSize** is left empty or set to a value less than or equal to 0, the **Swiper** component displays one column. +**number** type: Child elements' main-axis width adapts to the **Swiper** component's main-axis width. The child elements are stretched or shrunk to equally divide the **Swiper** component's width (minus **displayCount-1** times **itemSpace**). Values less than or equal to 0 are treated as the default value **1**.
+**string** type: Only **'auto'** is supported. Child elements are laid out linearly based on their main-axis width without adapting to the **Swiper** component's width. [customContentTransition](#customcontenttransition12) and [onContentDidScroll](#oncontentdidscroll12) events are disabled.
+**SwiperAutoFill** type: Child elements' main-axis width adapts to the **Swiper** component's main-axis width. The system automatically works out the number of elements per page based on the width and **minSize** settings of the **Swiper** component. If **minSize** is left empty or set to a value less than or equal to 0, the **Swiper** component displays one column. + +> **NOTE** +> +>1. When turning pages by group is used, the drag distance threshold for turning pages is half of the width of the **Swiper** component (50% of the child elements width if turning pages by child element is used). If the number of child elements in the last group is less than the value of **displayCount**, placeholders are used, but they show the **Swiper** background style directly and do not display any content. +> +>2. When **displayCount** is set to **'auto'** and looping is disabled, the position of the selected navigation indicator aligns with the first page in the viewport. If the first page is only partially displayed in the viewport after switching, the selected navigation indicator remains aligned with the page's position, between two unselected indicators. In this case, you are advised to hide the navigation indicators. +> +>3. If the navigation indicator is in dot style, the number of displayed navigation dots equals the number of child elements when the number of child elements displayed in the viewport is 1 (single-page scenario) or **displayCount** is set to **'auto'**. + +When the navigation dot is set to dot style and the number of child elements displayed in the viewport is greater than 1 (multi-page scenario), the number of displayed navigation dots follows the rules below. -When turning pages by group is used, the drag distance threshold for turning pages is half of the width of the **Swiper** component (50% of the child elements width if turning pages by child element is used). If the number of child elements in the last group is less than the value of **displayCount**, placeholders are used, but they show the **Swiper** background style directly and do not display any content. Since API version 16, when turning pages by group is used and the navigation points are set to circular, the number of circular navigation points matches the number of groups. The number of groups is calculated by dividing the total number of child elements by the number of elements displayed in the viewport. If the division does not result in an integer, the number is rounded up. +| Total Children Count > Visible Children Count| Swiping by Group Enabled| Loop Status | Number of Navigation Dots Displayed | Description | +| ------------------------------------------ | ------------ | --------------- | ------------------------------------------------------------ | ---------------------------------------- | +| Yes | Yes | **loop** set to **true** | Equals the number of groups (calculated by dividing the total number of child elements by the number of visible child elements, with rounding up if there is a remainder).| Not effective when **displayCount** is set to **'auto'**.| +| Yes | Yes | **loop** set to **false**| Equals the number of groups (calculated by dividing the total number of child elements by the number of visible child elements, with rounding up if there is a remainder).| Not effective when **displayCount** is set to **'auto'**.| +| Yes | No | **loop** set to **true** | Equals the actual number of page turns available (that is, the total number of child elements).| —— | +| Yes | No | **loop** set to **false**| Equals the actual number of page turns available (calculated as total number of child elements minus the number of visible child elements, plus 1).| Not effective when **displayCount** is set to **'auto'**.| +| No (while the total number of child elements is greater than 0) | —— | —— | 1 | Not effective when **displayCount** is set to **'auto'**.| +| No (while the total number of child elements is 0)| —— | —— | 0| —— | **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -369,7 +396,7 @@ When turning pages by group is used, the drag distance threshold for turning pag | Name | Type | Mandatory| Description | | -------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | value | number \| string \| [SwiperAutoFill](#swiperautofill10)10+ | Yes | Number of elements to display per page.
Default value: **1**
Value range: (0, +∞). If this parameter is set to a value less than or equal to 0, the default value is used.| -| swipeByGroup11+ | boolean | No | Whether to turn pages by group. The value **true** means to turn pages by group, and **false** means to turn pages by child element. When turning pages by group is used, the number of child elements per group is the value of **displayCount**.
Default value: **false**| +| swipeByGroup11+ | boolean | No | Whether to turn pages by group. The value **true** means to turn pages by group, and **false** means to turn pages by child element. When turning pages by group is used, the number of child elements per group is the value of **displayCount**.
Default value: **false**.| > **NOTE** > @@ -384,7 +411,7 @@ When turning pages by group is used, the drag distance threshold for turning pag effectMode(value: EdgeEffect) -Sets the effect used when the component is at one of the edges. This attribute takes effect when **loop** is set to **false**. For details about the supported effects, see the **EdgeEffect** enums. The spring effect does not take effect when the controller API is called. +Sets the effect used when the component is at one of the edges, which is effective only when [loop](#loop) is set to **false**. This effect does not apply when **SwiperController.changeIndex()**, **SwiperController.showNext()**, or **SwiperController.showPrevious()** is used to navigate to the first or last page. **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -412,8 +439,8 @@ Sets the arrow style of the navigation indicator. | Name | Type | Mandatory| Description | | -------------------------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | -| value | [ArrowStyle](#arrowstyle10) \| boolean | Yes | Arrow and background to set. In cases of exceptions, the default values in the **ArrowStyle** object are used. The value **true** means to show the arrow and background in the default styles, and **false** means to hide the arrow and background.
Default value: **false**| -| isHoverShow | boolean | No | Whether to show the arrow only when the mouse pointer hovers over the navigation indicator.
Default value: **false**
**NOTE**
When **isHoverShow** is set to **false**, the arrow is always displayed and can be clicked to turn pages.
When **isHoverShow** is set to **true**, the arrow is displayed only when the mouse pointer hovers over the navigation indicator, and it can be clicked to turn pages.| +| value | [ArrowStyle](#arrowstyle10) \| boolean | Yes | Arrow and background to set. In cases of exceptions, the default values in the **ArrowStyle** object are used. The value **true** means to show the arrow and background in the default styles, and **false** means to hide the arrow and background.
Default value: **false**.| +| isHoverShow | boolean | No | Whether to show the arrow on mouse hover.
Default value: **false**.
**NOTE**
1. **false**: The arrow is always displayed.
2. **true**: The arrow is displayed only mouse over.
With navigation dots, the arrow is displayed when mouse pointer hovers over the dots or arrows area.
Without navigation dots, the arrow is displayed when mouse pointer hovers over the **Swiper** display area.
3. When the arrow is displayed, clicking the arrow turns pages.| > **NOTE** > @@ -423,11 +450,11 @@ Sets the arrow style of the navigation indicator. nextMargin(value: Length, ignoreBlank?:boolean) -Sets the next margin, used to reveal a small part of the next item. This attribute is effective only when the layout mode of the child components in **Swiper** is set to stretch, which mainly includes two scenarios: 1. **displayMode** is set to **SwiperDisplayMode.STRETCH**; 2. **displayCount** is assigned a numeric value. +Sets the trailing margin to reveal a portion of the next item. For the implementation example, see [Example 1: Setting the Navigation Indicator Interaction and Page Turning Effect](#example-1-setting-the-navigation-indicator-interaction-and-page-turning-effect). This attribute is effective only when the layout mode of the child components in **Swiper** is set to stretch, which mainly includes two scenarios: 1. **displayMode** is set to **SwiperDisplayMode.STRETCH**; 2. **displayCount** is assigned a numeric value. -When the main axis runs horizontally and either the next margin or previous margin is greater than the measured width of the child component, neither the next margin nor previous margin is displayed. +When the main axis runs horizontally and either **nextMargin** or **prevMargin** is greater than the measured width of the child component, both margins are hidden. -When the main axis runs vertically and either the next margin or previous margin is greater than the measured height of the child component, neither the next margin nor previous margin is displayed. +When the main axis runs vertically and either **nextMargin** or **prevMargin** is greater than the measured height of the child component, both margins are hidden. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -437,18 +464,18 @@ When the main axis runs vertically and either the next margin or previous margin | Name| Type | Mandatory| Description | | ------ | ---------------------------- | ---- | ---------------------- | -| value | [Length](ts-types.md#length) | Yes | Next margin. This attribute cannot be set in percentage.
Default value: **0**| -| ignoreBlank12+ | boolean | No | Whether to hide (ignore) the next margin on the last page in non-loop scenarios.
**true**: The last page does not show the next margin, and the right edge of the last page is aligned with that of the **Swiper**'s viewable area.
**false**: The last page displays the next margin, and the distance between the right edge of the last page and that of the **Swiper**'s viewable area is equal to the next margin.
Default value: **false**
**NOTE**
On the last page, the values of **prevMargin** and **nextMargin** are added to create a left margin that allows the previous page to be displayed partially.| +| value | [Length](ts-types.md#length) | Yes | Trailing margin. Percentage values are not supported.
Default value: **0**.| +| ignoreBlank12+ | boolean | No | Whether to hide the trailing margin for the last page in non-loop scenarios.
**true**: Hide the trailing margin, in which case, the right edge of the last page is aligned with that of the **Swiper** component's viewable area.
**false**: Show the trailing margin, in which case, the last page has a **nextMargin**-specified gap from the **Swiper** component's right edge.
Default value: **false**.
**NOTE**
On the last page, the values of **prevMargin** and **nextMargin** are added to create a left margin that allows the previous page to be displayed partially.| ### prevMargin10+ prevMargin(value: Length, ignoreBlank?:boolean) -Sets the previous margin, used to reveal a small part of the previous item. This attribute is effective only when the layout mode of the child components in **Swiper** is set to stretch, which mainly includes two scenarios: 1. **displayMode** is set to **SwiperDisplayMode.STRETCH**; 2. **displayCount** is assigned a numeric value. +Sets the leading margin to reveal a portion of the previous item. For the implementation example, see [Example 1: Setting the Navigation Indicator Interaction and Page Turning Effect](#example-1-setting-the-navigation-indicator-interaction-and-page-turning-effect). This attribute is effective only when the layout mode of the child components in **Swiper** is set to stretch, which mainly includes two scenarios: 1. **displayMode** is set to **SwiperDisplayMode.STRETCH**; 2. **displayCount** is assigned a numeric value. -When the main axis runs horizontally and either the next margin or previous margin is greater than the measured width of the child component, neither the next margin nor previous margin is displayed. +When the main axis runs horizontally and either **nextMargin** or **prevMargin** is greater than the measured width of the child component, both margins are hidden. -When the main axis runs vertically and either the next margin or previous margin is greater than the measured height of the child component, neither the next margin nor previous margin is displayed. +When the main axis runs vertically and either **nextMargin** or **prevMargin** is greater than the measured height of the child component, both margins are hidden. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -458,8 +485,8 @@ When the main axis runs vertically and either the next margin or previous margin | Name| Type | Mandatory| Description | | ------ | ---------------------------- | ---- | ---------------------- | -| value | [Length](ts-types.md#length) | Yes | Previous margin. This attribute cannot be set in percentage.
Default value: **0**| -| ignoreBlank12+ | boolean | No | Whether to hide (ignore) the previous margin on the first page in non-loop scenarios.
**true**: The first page does not show the previous margin, and the left edge of the first page is align with that of the **Swiper**'s viewable area.
**false**: The first page displays the previous margin, and the distance between the left edge of the first page and that of the **Swiper**'s viewable area is equal to the previous margin.
Default value: **false**
**NOTE**
On the first page, the values of **prevMargin** and **nextMargin** are added to create a right margin that allows the next page to be displayed partially.| +| value | [Length](ts-types.md#length) | Yes | Leading margin. Percentage values are not supported.
Default value: **0**.| +| ignoreBlank12+ | boolean | No | Whether to hide the leading margin for the first page in non-loop scenarios.
**true**: Hide the leading margin, in which case, the left edge of the first page is aligned with that of the **Swiper** component's viewable area.
**false**: Show the leading margin, in which case, the first page has a **prevMargin**-specified gap from the **Swiper** component's left edge.
Default value: **false**.
**NOTE**
On the first page, the values of **prevMargin** and **nextMargin** are added to create a right margin that allows the next page to be displayed partially.| ### nestedScroll11+ @@ -495,7 +522,7 @@ Sets whether the navigation indicator is interactive. The value **true** means t | Name| Type | Mandatory| Description | | ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| value | boolean | Yes | Whether the navigation indicator is interactive.
Default value: **true**| +| value | boolean | Yes | Whether the navigation indicator is interactive. The value **true** means that the navigation indicator is interactive, and **false** means the opposite.
Default value: **true**.| ### pageFlipMode15+ @@ -515,6 +542,26 @@ Sets the mode for flipping pages using the mouse wheel. | ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | | mode | Optional\<[PageFlipMode](ts-appendix-enums.md#pageflipmode15)> | Yes | Mode for flipping pages using the mouse wheel.
Default value: **PageFlipMode.CONTINUOUS**| +### maintainVisibleContentPosition20+ + +maintainVisibleContentPosition(enabled: boolean) + +Sets whether to maintain the visible content position when data is inserted or deleted above or ahead of the viewport. This applies to **Swiper** components using a single [LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md) as the child node, where the data source is modified using **LazyForEach** API such as [onDateAdd](ts-rendering-control-lazyforeach.md#ondataadd8) or [onDataDelete](ts-rendering-control-lazyforeach.md#ondatadelete8). + +When **swipeByGroup** in [displayCount](#displaycount8) is set to **true**, the visible content position remains unchanged only if the inserted or deleted data quantity is a multiple of the group size. Otherwise, the visible content position may change during group recalculation. + +**Widget capability**: This API can be used in ArkTS widgets since API version 20. + +**Atomic service API**: This API can be used in atomic services since API version 20. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| enabled | boolean | Yes | Whether to maintain the visible content position when data is inserted or deleted above or ahead of the viewport.
Default value: **false**.
**false**: The visible content position will change when data is inserted or deleted. **true**: The visible content position remains unchanged when data is inserted or deleted. Animations stop if the data source is modified during an animation due to target index changes.| + ## IndicatorStyle(deprecated) This API is supported since API version 8 and is deprecated since API version 10. You are advised to use [indicator](#indicator10) instead. @@ -525,10 +572,10 @@ This API is supported since API version 8 and is deprecated since API version 10 | ------------- | ------------------------------------------ | ---- | ---------------------------------------------------- | | left | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the left edge of the **Swiper** component.
If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: higher than the **right** property
Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary. | | top | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the top edge of the **Swiper** component.
If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: higher than the **bottom** property
Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary. | -| right | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the right edge of the **Swiper** component.
If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: lower than the **left** property
Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary. | +| right | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the right edge of the **Swiper** component.
If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: lower than the **left** property.
Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary. | | bottom | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the bottom edge of the **Swiper** component.
If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: lower than the **top** property
Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary. | -| size | [Length](ts-types.md#length) | No | Diameter of the navigation indicator. It cannot be set in percentage.
Default value: **6vp**| -| mask | boolean | No | Whether to enable the mask for the navigation indicator. | +| size | [Length](ts-types.md#length) | No | Diameter of the navigation indicator. Percentage values are not supported.
Default value: **6vp**| +| mask | boolean | No | Whether to enable the mask for the navigation indicator.
The value **true** means to enable the mask for the navigation indicator, and **false** means the opposite. | | color | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the navigation indicator. | | selectedColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the selected navigation indicator. | @@ -540,10 +587,10 @@ Enumerates the modes in which elements are displayed along the main axis. | Name | Description | | ---------------------------------- | ------------------------------------------------------------ | -| Stretch(deprecated) | The slide width of the **Swiper** component is equal to the width of the component.
This API is deprecated since API version 10. You are advised to use **STRETCH** instead.
**Widget capability**: This API can be used in ArkTS widgets since API version 7.| -| AutoLinear(deprecated) | The slide width of the **Swiper** component is equal to that of the child component with the maximum width.
This API is deprecated since API version 10. You are advised to use [Scroller.scrollTo](ts-container-scroll.md#scrollto) instead.
**Widget capability**: This API can be used in ArkTS widgets since API version 7.| -| STRETCH10+ | The slide width of the **Swiper** component is equal to the width of the component.
**Widget capability**: This API can be used in ArkTS widgets since API version 10.
**Atomic service API**: This API can be used in atomic services since API version 11.| -| AUTO_LINEAR(deprecated) | The slide width of the **Swiper** component is equal to the width of the leftmost child component in the viewport.
This API is supported since API version 10 and is deprecated since API version 12. You are advised to use [Scroller.scrollTo](ts-container-scroll.md#scrollto) instead.
**Widget capability**: This API can be used in ArkTS widgets since API version 10.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| Stretch(deprecated) | The width of each page in the **Swiper** component equals the component's own width.
This API is deprecated since API version 10. You are advised to use **STRETCH** instead.
**Widget capability**: This API can be used in ArkTS widgets since API version 7.| +| AutoLinear(deprecated) | The width of each page in the **Swiper** component equals the maximum width of child components. This enumerated value behaves the same as setting [displayCount](#displaycount8) to **'auto'** (string type). For details, see [displayCount](#displaycount8).
This API is deprecated since API version 10. You are advised to use [Scroller.scrollTo](ts-container-scroll.md#scrollto) instead.
**Widget capability**: This API can be used in ArkTS widgets since API version 7.| +| STRETCH10+ | The width of each page in the **Swiper** component equals the component's own width.
**Widget capability**: This API can be used in ArkTS widgets since API version 10.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| AUTO_LINEAR(deprecated) | The width of each page in the **Swiper** component equals the width of the leftmost child component in the viewport. This enumerated value behaves the same as setting [displayCount](#displaycount8) to **'auto'** (string type). For details, see [displayCount](#displaycount8).
This API is supported since API version 10 and is deprecated since API version 12. You are advised to use [Scroller.scrollTo](ts-container-scroll.md#scrollto) instead.
**Widget capability**: This API can be used in ArkTS widgets since API version 10.
**Atomic service API**: This API can be used in atomic services since API version 11.| ## SwiperNestedScrollMode11+ @@ -560,7 +607,7 @@ Enumerates the nested scrolling modes of the **Swiper** component and its parent ## SwiperController -Controller of the **Swiper** component. You can bind this object to the **Swiper** component and use it to control page switching. +Implements the controller for the **Swiper** component. Bind this object to a **Swiper** component to control page turning and other functionalities. **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -568,12 +615,6 @@ Controller of the **Swiper** component. You can bind this object to the **Swiper **System capability**: SystemCapability.ArkUI.ArkUI.Full -### Objects to Import - -```ts -let controller: SwiperController = new SwiperController() -``` - ### constructor constructor() @@ -590,7 +631,7 @@ A constructor used to create a **SwiperController** object. showNext() -Turns to the next page. Page turning occurs with the animation, whose duration is specified by **duration**. +Turns to the next page. The page turning includes a transition animation, with the duration set by the [duration](#duration) attribute of the **Swiper** component. **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -602,7 +643,7 @@ Turns to the next page. Page turning occurs with the animation, whose duration i showPrevious() -Turns to the previous page. Page turning occurs with the animation, whose duration is specified by **duration**. +Turns to the previous page. The page turning includes a transition animation, with the duration set by the [duration](#duration) attribute of the **Swiper** component. **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -634,6 +675,9 @@ Goes to a specified page. changeIndex(index: number, animationMode?: SwiperAnimationMode | boolean) Moves to a specific page. +>**NOTE** +> +>This API itself supports jumping without animation (set **animationMode** to **false** or **SwiperAnimationMode.NO_ANIMATION**). Avoid starting an animation with **changeIndex** and then interrupt it with **finishAnimation** to achieve animation-free jumping. **Widget capability**: This API can be used in ArkTS widgets since API version 15. @@ -674,7 +718,7 @@ Preloads child nodes. After this API is called, all specified child nodes will b If the **SwiperController** object is not bound to any **Swiper** component, any attempt to call APIs on it will result in a JavaScript exception, together with the error code 100004. Therefore, you are advised to use **try-catch** to handle potential exceptions when calling APIs on **SwiperController**. -When combining **SwiperController** with [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md) and custom components, be aware that **LazyForEach** only retains custom components within the cache range. Components outside this range are removed. Therefore, make sure the nodes to preload are within the cache range of **LazyForEach** to avoid issues. +When combining **SwiperController** with [LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md) and custom components, be aware that **LazyForEach** only retains custom components within the cache range. Components outside this range are removed. Therefore, make sure the nodes to preload are within the cache range of **LazyForEach** to avoid issues. **Widget capability**: This API can be used in ArkTS widgets since API version 18. @@ -747,6 +791,12 @@ Sets the position of the navigation indicator relative to the left edge of the * | ------ | ---------------------------- | ---- | ------------------------------------------------------------ | | value | [Length](ts-types.md#length) | Yes | Position of the navigation indicator relative to the left edge of the **Swiper** component.
If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: higher than the **right** property
Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary.| +**Return value** + +| Type| Description | +| --- | ------------------ | +| T | Current navigation indicator.| + ### top top(value: Length): T @@ -765,6 +815,12 @@ Sets the position of the navigation indicator relative to the top edge of the ** | ------ | ---------------------------- | ---- | ------------------------------------------------------------ | | value | [Length](ts-types.md#length) | Yes | Position of the navigation indicator relative to the top edge of the **Swiper** component.
If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: higher than the **bottom** property
Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary.| +**Return value** + +| Type| Description | +| --- | ------------------ | +| T | Current navigation indicator.| + ### right right(value: Length): T @@ -781,7 +837,13 @@ Sets the position of the navigation indicator relative to the right edge of the | Name| Type | Mandatory| Description | | ------ | ---------------------------- | ---- | ------------------------------------------------------------ | -| value | [Length](ts-types.md#length) | Yes | Sets the position of the navigation indicator relative to the right edge of the **Swiper** component.
If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: lower than the **left** property
Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary.| +| value | [Length](ts-types.md#length) | Yes | Sets the position of the navigation indicator relative to the right edge of the **Swiper** component.
If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: lower than the **left** property.
Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary.| + +**Return value** + +| Type| Description | +| --- | ------------------ | +| T | Current navigation indicator.| ### bottom @@ -801,16 +863,21 @@ Sets the position of the navigation indicator relative to the bottom edge of the | ------ | ---------------------------- | ---- | ------------------------------------------------------------ | | value | [Length](ts-types.md#length) | Yes | Position of the navigation indicator relative to the bottom edge of the **Swiper** component.
If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: lower than the **top** property
Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary.| +**Return value** + +| Type| Description | +| --- | ------------------ | +| T | Current navigation indicator.| -### bottom18+ +### bottom19+ bottom(bottom: LengthMetrics | Length, ignoreSize: boolean): T Sets the position of the navigation indicator relative to the bottom edge of the **Swiper** component. You can also choose to ignore the size of the navigation indicator using the **ignoreSize** property. -**Widget capability**: This API can be used in ArkTS widgets since API version 18. +**Widget capability**: This API can be used in ArkTS widgets since API version 19. -**Atomic service API**: This API can be used in atomic services since API version 18. +**Atomic service API**: This API can be used in atomic services since API version 19. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -820,7 +887,13 @@ Sets the position of the navigation indicator relative to the bottom edge of the | Name| Type | Mandatory| Description | | ------ | ---------------------------- | ---- | ------------------------------------------------------------ | | bottom | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) \| [Length](ts-types.md#length)| Yes | Position of the navigation indicator relative to the bottom edge of the **Swiper** component.
If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.
If the value specified is **0**, the navigation indicator is placed at the position 0.
Priority: lower than the **top** property
Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary.| -| ignoreSize | boolean | Yes | Whether to ignore the size of the navigation indicator.
Ddefault value: **false**
The value **true** allows the navigation indicator to be positioned closer to the bottom edge of the **Swiper** component.
**NOTE**
The **ignoreSize** property for the number-style navigation indicator is ineffective in the following scenarios:
• [vertical](#vertical) is set to **false** and the value of **bottom** is greater than 0.
• When [vertical](#vertical) is set to **true**:
1. The value of **bottom** is greater than 0.
2. The value of **bottom** is **undefined**.
3. **isSidebarMiddle** is set to **false**.| +| ignoreSize | boolean | Yes | Whether to ignore the size of the navigation indicator.
Default value: **false**.
Setting **true** positions the indicator closer to the **Swiper** component's bottom. For the usage, see [Example 9: Using the space and bottom APIs on the Navigation Indicator](#example-9-using-the-space-and-bottom-apis-on-the-navigation-indicator).
**NOTE**
The **ignoreSize** property does not apply to the digit-style navigation indicator in the following scenarios:
• [vertical](#vertical) is set to **false** and the value of **bottom** is greater than 0.
• When [vertical](#vertical) is set to **true**:
1. The value of **bottom** is greater than 0.
2. The value of **bottom** is **undefined**.
3. **isSidebarMiddle** is set to **false**.| + +**Return value** + +| Type| Description | +| --- | ------------------ | +| T | Current navigation indicator.| ### start12+ @@ -840,6 +913,12 @@ Sets the distance between the navigation indicator and the right edge (in right- | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Distance between the navigation indicator and the right edge (in right-to-left scripts) or the left edge (in left-to-right scripts) of the **Swiper** component.
Default value: **0**
Unit: vp| +**Return value** + +| Type| Description | +| --- | ------------------ | +| T | Current navigation indicator.| + ### end12+ end(value: LengthMetrics): T @@ -858,6 +937,12 @@ Sets the distance between the navigation indicator and the left edge (in right-t | ------ | ---------------------------- | ---- | ---------------------------------------- | | value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Distance between the navigation indicator and the left edge (in right-to-left scripts) or the right edge (in left-to-right scripts) of the **Swiper** component.
Default value: **0**
Unit: vp | +**Return value** + +| Type| Description | +| --- | ------------------ | +| T | Current navigation indicator.| + ### dot static dot(): DotIndicator @@ -870,6 +955,12 @@ Returns a **DotIndicator** object. **System capability**: SystemCapability.ArkUI.ArkUI.Full +**Return value** + +| Type | Description | +| ------------------------------- | ------------ | +| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| + ### digit static digit(): DigitIndicator @@ -882,9 +973,15 @@ Returns **DigitIndicator** object. **System capability**: SystemCapability.ArkUI.ArkUI.Full +**Return value** + +| Type | Description | +| ----------------------------------- | ------------ | +| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| + ## DotIndicator10+ -Constructs a dot indicator style. It extends from [Indicator] (#indicator10). +A constructor used to create a **DotIndicator** object. It inherits from [Indicator](#indicator10). **Atomic service API**: This API can be used in atomic services since API version 11. @@ -912,7 +1009,7 @@ Sets the width of the dot-style navigation indicator. This parameter cannot be s | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### itemHeight @@ -936,7 +1033,7 @@ Sets the height of the dot-style navigation indicator. This parameter cannot be | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### selectedItemWidth @@ -954,13 +1051,13 @@ Sets the width of the selected dot in the dot-style navigation indicator. This p | Name| Type | Mandatory| Description | | ------ | ---------------------------- | ---- | ------------------------------------------------------------ | -| value | [Length](ts-types.md#length) | Yes | Width of the selected dot in the dot-style navigation indicator. This parameter cannot be set in percentage.
Default value: **12**
Unit: vp| +| value | [Length](ts-types.md#length) | Yes | Width of the selected dot in the dot-style navigation indicator. This parameter cannot be set in percentage.
Default value: **6**
Unit: vp| **Return value** | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### selectedItemHeight @@ -984,7 +1081,7 @@ Sets the height of the selected dot in the dot-style navigation indicator. This | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### mask @@ -1002,13 +1099,13 @@ Sets whether to enable the mask for the dot-style navigation indicator. | Name| Type | Mandatory| Description | | ------ | ------- | ---- | ------------------------------------------------------------ | -| value | boolean | Yes | Whether to enable the mask for the dot-style navigation indicator.
Default value: **false**| +| value | boolean | Yes | Whether to enable the mask for the dot-style navigation indicator. The value **true** means to enable the mask for the dot-style navigation indicator, and **false** means the opposite.
Default value: **false**.| **Return value** | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### color @@ -1032,7 +1129,7 @@ Sets the color of the dot-style navigation indicator. | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### selectedColor @@ -1056,7 +1153,7 @@ Sets the color of the selected dot in the dot-style navigation indicator. | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### maxDisplayCount12+ @@ -1064,8 +1161,6 @@ maxDisplayCount(maxDisplayCount: number): DotIndicator Sets the maximum number of navigation dots in the dot-style navigation indicator. -In a separate navigation indicator controller, this attribute has effect only when the controller is bound to a **Swiper** component. - **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -1074,23 +1169,23 @@ In a separate navigation indicator controller, this attribute has effect only wh | Name | Type | Mandatory| Description | | --------------- | ------ | ---- | ------------------------------------------------------------ | -| maxDisplayCount | number | Yes | Maximum number of navigation dots in the dot-style navigation indicator. If the actual number of navigation dots exceeds this limit, the overflow effect is activated, as shown in Example 5.
This parameter has no default value. If an invalid value is set, no overflow effect is applied.
Value range: 6–9
**NOTE**
In scenarios involving overflow display:
1. Interactive features, such as gestures and mouse operations, are not supported.
2. The position of the selected navigation dot corresponding to the middle page is not strictly fixed; it depends on the sequence of previous page-turning operations.
3. Currently, only scenarios with **displayCount** set to **1** are supported.| +| maxDisplayCount | number | Yes | Maximum number of navigation dots in the dot-style navigation indicator. If the actual number of navigation dots exceeds this limit, the overflow effect is activated, as shown in Example 5.
This parameter has no default value. If an invalid value is set, no overflow effect is applied.
Value range: [6, 9].
**NOTE**
In scenarios involving overflow display:
1. Interactive features, such as gestures and mouse operations, are not supported.
2. The position of the selected navigation dot corresponding to the middle page is not strictly fixed; it depends on the sequence of previous page-turning operations.
3. Currently, only scenarios with **displayCount** set to **1** are supported.| **Return value** | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| -### space18+ +### space19+ space(space: LengthMetrics): DotIndicator Sets the spacing between the dots in a dot-style navigation indicator for the **Swiper** component. Note that percentage values are not supported. -**Widget capability**: This API can be used in ArkTS widgets since API version 18. +**Widget capability**: This API can be used in ArkTS widgets since API version 19. -**Atomic service API**: This API can be used in atomic services since API version 18. +**Atomic service API**: This API can be used in atomic services since API version 19. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -1104,7 +1199,7 @@ Sets the spacing between the dots in a dot-style navigation indicator for the ** | Type | Description | | ------------------------------- | ------------ | -| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| +| [DotIndicator](#dotindicator10) | Current dot-style navigation indicator.| ### constructor @@ -1159,7 +1254,7 @@ Sets the font color of the digit-style navigation indicator. | Type | Description | | ----------------------------------- | ------------ | -| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| +| [DigitIndicator](#digitindicator10) | Current digit-style navigation indicator.| ### selectedFontColor @@ -1183,7 +1278,7 @@ Sets the font color of the selected digit in the digit-style navigation indicato | Type | Description | | ----------------------------------- | ------------ | -| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| +| [DigitIndicator](#digitindicator10) | Current digit-style navigation indicator.| ### digitFont @@ -1207,7 +1302,7 @@ Sets the font style of the digit-style navigation indicator. | Type | Description | | ----------------------------------- | ------------ | -| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| +| [DigitIndicator](#digitindicator10) | Current digit-style navigation indicator.| ### selectedDigitFont @@ -1235,7 +1330,7 @@ Sets the font style of the selected digit in the digit-style navigation indicato | Type | Description | | ----------------------------------- | ------------ | -| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| +| [DigitIndicator](#digitindicator10) | Current digit-style navigation indicator.| ### constructor @@ -1258,11 +1353,11 @@ Describes the left and right arrow attributes. | Name | Type | Mandatory | Description | | ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | -| showBackground | boolean | No | Whether to show the background for the arrow.
Default value: **false** | -| isSidebarMiddle | boolean | No | Whether the arrow is shown on either side of the navigation indicator.
Default value: **false**
(the arrow is shown on either side of the navigation indicator)| -| backgroundSize | [Length](ts-types.md#length) | No | Size of the background.
On both sides of the navigation indicator:
Default value: **24vp**
On both sides of the component:
Default value: **32vp**
This parameter cannot be set in percentage.| -| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the background.
On both sides of the navigation indicator:
Default value: **'\#00000000'**
On both sides of the component:
Default value: **'\#19182431'**| -| arrowSize | [Length](ts-types.md#length) | No | Size of the arrow.
On both sides of the navigation indicator:
Default value: **18vp**
On both sides of the component:
Default value: **24vp**
**NOTE**
If **showBackground** is set to **true**, the value of **arrowSize** is 3/4 of the value of **backgroundSize**.
This parameter cannot be set in percentage.| +| showBackground | boolean | No | Whether to show the background for the arrow. The value **true** means to show the background for the arrow, and **false** means the opposite.
Default value: **false**. | +| isSidebarMiddle | boolean | No | Whether the arrow is centered on both sides of the **Swiper** component. The value **true** means that the arrow is centered on both sides of the **Swiper** component, and **false** means that the arrow is show on either side of the navigation indicator.
Default value: **false**.
| +| backgroundSize | [Length](ts-types.md#length) | No | Size of the background.
On both sides of the navigation indicator:
Default value: **24vp**.
On both sides of the component:
Default value: **32vp**.
Percentage values are not supported.| +| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the background.
On both sides of the navigation indicator:
Default value: **'\#00000000'**.
On both sides of the component:
Default value: **'\#19182431'**.| +| arrowSize | [Length](ts-types.md#length) | No | Size of the arrow.
On both sides of the navigation indicator:
Default value: **18vp**.
On both sides of the component:
Default value: **24vp**.
**NOTE**
If **showBackground** is set to **true**, the value of **arrowSize** is 3/4 of the value of **backgroundSize**.
Percentage values are not supported.| | arrowColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the arrow.
Default value: **'\#182431'** | ## SwiperAutoFill10+ @@ -1277,11 +1372,11 @@ Describes the auto-fill attribute. | Name | Type | Mandatory| Description | | ------- | -------------------- | ------ | ------------------------------------ | -| minSize | [VP](ts-types.md#vp10) | Yes | Minimum width of the element.
Default value: **0**| +| minSize | [VP](ts-types.md#vp10) | Yes | Minimum width of the element.
Default value: **0**.| ## AutoPlayOptions18+ -Defines the properties for controlling the autoplay behavior. +Defines the properties for controlling the automatic playback behavior. **Widget capability**: This API can be used in ArkTS widgets since API version 18. @@ -1291,7 +1386,7 @@ Defines the properties for controlling the autoplay behavior. | Name | Type | Mandatory | Description | | ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | -| stopWhenTouched | boolean | Yes | Whether the autoplay stops immediately when the component is touched.
Default value: **true**| +| stopWhenTouched | boolean | Yes | Whether the automatic playback stops immediately when the component is touched.
The value **true** means that the automatic playback stops immediately when the component is touched, and **false** means the opposite.
Default value: **true**.| ## Events @@ -1321,7 +1416,11 @@ When the **Swiper** component is used together with **LazyForEach**, the subpage onAnimationStart(event: OnSwiperAnimationStartCallback) -Triggered when the switching animation starts. +Triggered when the page transition animation starts. + +> **NOTE** +> +> - When this callback is invoked, the page transition animation logic is executed in the rendering thread, allowing the idle main thread to load resources required by child components. This reduces preloading time for nodes within the **cachedCount** range. For best practices, see [Optimizing Frame Loss During Swiper Component Loading – Preloading Data](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-swiper_high_performance_development_guide#section8783121513246). **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -1333,19 +1432,19 @@ Triggered when the switching animation starts. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------- | -| event | [OnSwiperAnimationStartCallback](#onswiperanimationstartcallback18) | Yes | Callback triggered when the switching animation starts.| +| event | [OnSwiperAnimationStartCallback](#onswiperanimationstartcallback18) | Yes | Callback triggered when the page transition animation starts.| >**NOTE** > ->- When the duration of the switching animation is set to 0, this callback is triggered only in the following scenarios: swiping to turn pages, automatic playback, calling **SwiperController.showNext()** or **SwiperController.showPrevious()**, and touching navigation points to navigate. +>- When the duration of the page transition animation is set to 0, this callback is triggered only in the following scenarios: swiping to turn pages, automatic playback, calling **SwiperController.showNext()** or **SwiperController.showPrevious()**, and touching navigation points to navigate. ### onAnimationEnd9+ onAnimationEnd(event: OnSwiperAnimationEndCallback) -Triggered when the switching animation ends. +Triggered when the page transition animation ends. -This event is triggered when the switching animation of the **Swiper** component ends, whether it is caused by gesture interruption or by calling **finishAnimation** through SwiperController. +This event is triggered when the switching animation of the **Swiper** component ends, whether it is caused by gesture interruption or by calling **finishAnimation** through **SwiperController**. **Widget capability**: This API can be used in ArkTS widgets since API version 10. @@ -1357,11 +1456,11 @@ This event is triggered when the switching animation of the **Swiper** component | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------- | -| event | [OnSwiperAnimationEndCallback](#onswiperanimationendcallback18) | Yes | Callback triggered when the switching animation ends.| +| event | [OnSwiperAnimationEndCallback](#onswiperanimationendcallback18) | Yes | Callback triggered when the page transition animation ends.| >**NOTE** > ->- When the duration of the switching animation is set to 0, this callback is triggered only in the following scenarios: swiping to turn pages, automatic playback, calling **SwiperController.showNext()** or **SwiperController.showPrevious()**, and touching navigation points to navigate. +>- When the duration of the page transition animation is set to 0, this callback is triggered only in the following scenarios: swiping to turn pages, automatic playback, calling **SwiperController.showNext()** or **SwiperController.showPrevious()**, and touching navigation points to navigate. ### onGestureSwipe10+ @@ -1377,17 +1476,17 @@ Triggered on a frame-by-frame basis when the page is turned by a swipe. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------- | -| event | [OnSwiperGestureSwipeCallback](#onswipergestureswipecallback18) | Yes | Callback triggered on a frame-by-frame basis when the page is turned by a swipe.| +| event | [OnSwiperGestureSwipeCallback](#onswipergestureswipecallback18) | Yes | Callback triggered on a frame-by-frame basis when the page is turned by a swipe. **onGestureSwipe** is called after **onTouch**. For post-release operations, consider using [onAnimationStart](#onanimationstart9).| ### customContentTransition12+ customContentTransition(transition: SwiperContentAnimatedTransition) -Defines a custom switching animation. You can define custom animation attributes, such as **opacity**, **scale**, and **translate**, in the callback invoked on a frame-by-frame basis during the swiping-initiated page switching animation. +Defines a custom page transition animation. During finger-following swipes and post-release transition animations, this triggers a frame-by-frame callback for all pages in the viewport, allowing you to customize animations by modifying properties like opacity, scale, and translation. Instructions: -1. This API does not work when **prevMargin** and **nextMargin** are set in such a way that the **Swiper** frontend and backend display the same page during loop playback.
2. During the swiping-initiated page switching animation, the [SwiperContentTransitionProxy][SwiperContentTransitionProxy](#swipercontenttransitionproxy12) callback is invoked for all pages in the viewport on a frame-by-frame basis. For example, when there are two pages whose subscripts are 0 and 1 in the viewport, two callbacks whose indexes are 0 and 1 are invoked in each frame.
3. When the **swipeByGroup** parameter of the **displayCount** attribute is set to **true**, the callback is invoked for all pages in a group if any page in the group is within the viewport; and all pages in a group are removed from the render tree if none of them are within the viewport.
4. During the swiping-initiated page switching animation, the default animation (page scrolling) is still effective. If you do not want the page to scroll, you can set the **translate** attribute on the main axis to offset the page scrolling. For example, if the value of **displayCount** is **2** and there are two pages whose subscripts are 0 and 1 within the viewport, you can set the **translate** attribute on the main axis to the following on a frame-by-frame basis: **translate** for page 0 = **-position** x **mainAxisLength**; **translate** for page 1 = **-(position - 1)** x **mainAxisLength** +1. This API does not work when **prevMargin** and **nextMargin** are set in such a way that the **Swiper** frontend and backend display the same page during loop playback.
2. During finger-following swipes and post-release transition animations, the [SwiperContentTransitionProxy](#swipercontenttransitionproxy12) callback is invoked for all pages in the viewport on a frame-by-frame basis. For example, when there are two pages whose subscripts are 0 and 1 in the viewport, two callbacks whose indexes are 0 and 1 are invoked in each frame.
3. When the **swipeByGroup** parameter of the **displayCount** attribute is set to **true**, the callback is invoked for all pages in a group if any page in the group is within the viewport; and all pages in a group are removed from the render tree if none of them are within the viewport.
4. During finger-following swipes and post-release transition animations, the default animation (page scrolling) is still effective. If you do not want the page to scroll, you can set the **translate** property on the main axis to offset the page scrolling. For example, if the value of **displayCount** is **2** and there are two pages whose subscripts are 0 and 1 within the viewport, you can set the **translate** property on the main axis to the following on a frame-by-frame basis: **translate** for page 0 = **-position** x **mainAxisLength**; **translate** for page 1 = **-(position - 1)** x **mainAxisLength** **Atomic service API**: This API can be used in atomic services since API version 12. @@ -1397,7 +1496,7 @@ Instructions: | Name| Type| Mandatory| Description| | ------ | ---- | ---- | ---- | -| transition | [SwiperContentAnimatedTransition](#swipercontentanimatedtransition12) | Yes| Information about the custom switching animation.| +| transition | [SwiperContentAnimatedTransition](#swipercontentanimatedtransition12) | Yes| Information about the custom page transition animation.| ### onContentDidScroll12+ @@ -1491,7 +1590,7 @@ Triggered when the **Swiper** component is about to scroll. This event allows yo type OnSwiperAnimationStartCallback = (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => void -Defines the callback triggered when the switching animation starts. +Defines the callback triggered when the page transition animation starts. **Widget capability**: This API can be used in ArkTS widgets since API version 18. @@ -1511,7 +1610,7 @@ Defines the callback triggered when the switching animation starts. type OnSwiperAnimationEndCallback = (index: number, extraInfo: SwiperAnimationEvent) => void -Defines the callback triggered when the switching animation ends. +Defines the callback triggered when the page transition animation ends. **Widget capability**: This API can be used in ArkTS widgets since API version 18. @@ -1558,7 +1657,7 @@ Triggered during the swipe action of the **Swiper** component. For details about | selectedIndex | number | Yes| Index of the currently selected page.| | index | number | Yes| Index of a page in the viewport.| | position | number | Yes| Position of the page specified by **index** relative to the start position of the **Swiper** main axis (start position of the page corresponding to **selectedIndex**).| -| mainAxisLength | number | Yes| Length of the page specified by **index** along the main axis.| +| mainAxisLength | number | Yes| Length of the page specified by **index** along the main axis, in vp.| ## ContentWillScrollCallback15+ @@ -1616,7 +1715,7 @@ Describes the animation information of the **Swiper** component. ## SwiperContentAnimatedTransition12+ -Information about the custom page switching animation. +Provides the information about the custom page transition animation. **Atomic service API**: This API can be used in atomic services since API version 12. @@ -1624,25 +1723,25 @@ Information about the custom page switching animation. | Name| Type| Mandatory| Description| | ------ | ---- | ---- | ---- | -| timeout | number | No| Timeout for the switching animation. The timeout timer starts when the default animation (page scrolling) reaches the point where the first frame is moved out of the viewport. If you do not call the **finishTransition** API of [SwiperContentTransitionProxy](#swipercontenttransitionproxy12) before the timer expires, the component considers that the custom animation of the page ends and immediately removes the page node from the render tree. The unit is ms. The default value is **0**.| -| transition | Callback<[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)> | Yes| Content of the custom switching animation.| +| timeout | number | No| Timeout for the page transition animation. The timeout timer starts when the default animation (page scrolling) reaches the point where the first frame is moved out of the viewport. If you do not call the **finishTransition** API of [SwiperContentTransitionProxy](#swipercontenttransitionproxy12) before the timer expires, the component considers that the custom animation of the page ends and immediately removes the page node from the render tree. The unit is ms. The default value is **0**.| +| transition | Callback<[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)> | Yes| Content of the custom page transition animation.| ## SwiperContentTransitionProxy12+ -Implements the proxy object returned during the execution of the custom switching animation of the **Swiper** component. You can use this object to obtain the page information in the custom animation viewport. You can also call the **finishTransition** API of this object to notify the **Swiper** component that the custom animation has finished playing. +Implements the proxy object returned during the execution of the custom page transition animation of the **Swiper** component. You can use this object to obtain the page information in the custom animation viewport. You can also call the **finishTransition** API of this object to notify the **Swiper** component that the custom animation has finished playing. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full -### Properties +### Attributes | Name| Type| Read Only| Optional| Description| | ---- | ---- | --- | ---- | --- | | selectedIndex | number | No| No| Index of the currently selected page.| | index | number | No| No| Index of a page in the viewport.| | position | number | No| No| Position of the page specified by **index** relative to the start position of the **Swiper** main axis (start position of the page corresponding to **selectedIndex**).| -| mainAxisLength | number | No| No| Length of the page specified by **index** along the main axis.| +| mainAxisLength | number | No| No| Length of the page specified by **index** along the main axis, in vp.| >**NOTE** > @@ -1670,18 +1769,18 @@ This example demonstrates how to use the **changeIndex** API with **SwiperAnimat ```ts // xxx.ets class MyDataSource implements IDataSource { - private list: number[] = [] + private list: number[] = []; constructor(list: number[]) { - this.list = list + this.list = list; } totalCount(): number { - return this.list.length + return this.list.length; } getData(index: number): number { - return this.list[index] + return this.list[index]; } registerDataChangeListener(listener: DataChangeListener): void { @@ -1694,15 +1793,15 @@ class MyDataSource implements IDataSource { @Entry @Component struct SwiperExample { - private swiperController: SwiperController = new SwiperController() - private data: MyDataSource = new MyDataSource([]) + private swiperController: SwiperController = new SwiperController(); + private data: MyDataSource = new MyDataSource([]); aboutToAppear(): void { - let list: number[] = [] + let list: number[] = []; for (let i = 1; i <= 10; i++) { list.push(i); } - this.data = new MyDataSource(list) + this.data = new MyDataSource(list); } build() { @@ -1724,7 +1823,9 @@ struct SwiperExample { .loop(true) .indicatorInteractive(true) .duration(1000) - .itemSpace(0) + .itemSpace(5) + .prevMargin(35) + .nextMargin(35) .indicator( // Set the style of the navigation indicator. new DotIndicator() .itemWidth(15) @@ -1743,46 +1844,46 @@ struct SwiperExample { }, false) .curve(Curve.Linear) .onChange((index: number) => { - console.info(index.toString()) + console.info(index.toString()); }) .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => { - console.info("index: " + index) - console.info("current offset: " + extraInfo.currentOffset) + console.info("index: " + index); + console.info("current offset: " + extraInfo.currentOffset); }) .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => { - console.info("index: " + index) - console.info("targetIndex: " + targetIndex) - console.info("current offset: " + extraInfo.currentOffset) - console.info("target offset: " + extraInfo.targetOffset) - console.info("velocity: " + extraInfo.velocity) + console.info("index: " + index); + console.info("targetIndex: " + targetIndex); + console.info("current offset: " + extraInfo.currentOffset); + console.info("target offset: " + extraInfo.targetOffset); + console.info("velocity: " + extraInfo.velocity); }) .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => { - console.info("index: " + index) - console.info("current offset: " + extraInfo.currentOffset) + console.info("index: " + index); + console.info("current offset: " + extraInfo.currentOffset); }) Row({ space: 12 }) { - Button('showNext') + Button('showPrevious') .onClick(() => { - this.swiperController.showNext() + this.swiperController.showPrevious(); }) - Button('showPrevious') + Button('showNext') .onClick(() => { - this.swiperController.showPrevious() + this.swiperController.showNext(); }) }.margin(5) Row({ space: 5 }) { Button('FAST 0') .onClick(() => { - this.swiperController.changeIndex(0, SwiperAnimationMode.FAST_ANIMATION) + this.swiperController.changeIndex(0, SwiperAnimationMode.FAST_ANIMATION); }) Button('FAST 3') .onClick(() => { - this.swiperController.changeIndex(3, SwiperAnimationMode.FAST_ANIMATION) + this.swiperController.changeIndex(3, SwiperAnimationMode.FAST_ANIMATION); }) Button('FAST ' + 9) .onClick(() => { - this.swiperController.changeIndex(9, SwiperAnimationMode.FAST_ANIMATION) + this.swiperController.changeIndex(9, SwiperAnimationMode.FAST_ANIMATION); }) }.margin(5) }.width('100%') @@ -1800,18 +1901,18 @@ This example showcases how to implement a digit indicator using the **DigitIndic ```ts // xxx.ets class MyDataSource implements IDataSource { - private list: number[] = [] + private list: number[] = []; constructor(list: number[]) { - this.list = list + this.list = list; } totalCount(): number { - return this.list.length + return this.list.length; } getData(index: number): number { - return this.list[index] + return this.list[index]; } registerDataChangeListener(listener: DataChangeListener): void { @@ -1824,15 +1925,15 @@ class MyDataSource implements IDataSource { @Entry @Component struct SwiperExample { - private swiperController: SwiperController = new SwiperController() - private data: MyDataSource = new MyDataSource([]) + private swiperController: SwiperController = new SwiperController(); + private data: MyDataSource = new MyDataSource([]); aboutToAppear(): void { - let list: number[] = [] + let list: number[] = []; for (let i = 1; i <= 10; i++) { list.push(i); } - this.data = new MyDataSource(list) + this.data = new MyDataSource(list); } build() { @@ -1865,11 +1966,11 @@ struct SwiperExample { Row({ space: 12 }) { Button('showNext') .onClick(() => { - this.swiperController.showNext() + this.swiperController.showNext(); }) Button('showPrevious') .onClick(() => { - this.swiperController.showPrevious() + this.swiperController.showPrevious(); }) }.margin(5) }.width('100%') @@ -1886,18 +1987,18 @@ This example illustrates the group page-turning effect using the **displayCount* ```ts // xxx.ets class MyDataSource implements IDataSource { - private list: number[] = [] + private list: number[] = []; constructor(list: number[]) { - this.list = list + this.list = list; } totalCount(): number { - return this.list.length + return this.list.length; } getData(index: number): number { - return this.list[index] + return this.list[index]; } registerDataChangeListener(listener: DataChangeListener): void { @@ -1910,15 +2011,15 @@ class MyDataSource implements IDataSource { @Entry @Component struct SwiperExample { - private swiperController: SwiperController = new SwiperController() - private data: MyDataSource = new MyDataSource([]) + private swiperController: SwiperController = new SwiperController(); + private data: MyDataSource = new MyDataSource([]); aboutToAppear(): void { - let list: number[] = [] + let list: number[] = []; for (let i = 1; i <= 10; i++) { list.push(i); } - this.data = new MyDataSource(list) + this.data = new MyDataSource(list); } build() { @@ -1951,11 +2052,11 @@ struct SwiperExample { Row({ space: 12 }) { Button('showNext') .onClick(() => { - this.swiperController.showNext() + this.swiperController.showNext(); }) Button('showPrevious') .onClick(() => { - this.swiperController.showPrevious() + this.swiperController.showPrevious(); }) }.margin(5) }.width('100%') @@ -1965,30 +2066,71 @@ struct SwiperExample { ``` ![swiper](figures/swiper-swipe-by-group.gif) -### Example 4: Customizing the Page Switching Animation +### Example 4: Customizing the Page Page Transition Animation + +This example presents how to implement a custom page transition animation for the **Swiper** component through the **customContentTransition** API. + + + +```ts +// EntryAbility.ets +import { Configuration, UIAbility } from '@kit.AbilityKit'; +import { i18n } from '@kit.LocalizationKit'; +import { CommonUtil } from '../common/CommonUtil'; + +export default class EntryAbility extends UIAbility { + onConfigurationUpdate(newConfig: Configuration): void { + // Listen for system configuration changes. + if (newConfig.language) { + CommonUtil.setIsRTL(i18n.isRTL(newConfig.language)); + } + } +} +``` -This example presents how to implement a custom page turning animation for the **Swiper** component through the **customContentTransition** API. + + +```ts +// CommonUtil.ets +import { i18n, intl } from '@kit.LocalizationKit'; + +export class CommonUtil { + private static isRTL: boolean = i18n.isRTL((new intl.Locale()).language); + + public static setIsRTL(isRTL: boolean): void { + CommonUtil.isRTL = isRTL; + } + + public static getIsRTL(): boolean { + return CommonUtil.isRTL; + } +} +``` + + ```ts // xxx.ets +import { CommonUtil } from '../common/CommonUtil'; + @Entry @Component struct SwiperCustomAnimationExample { - private DISPLAY_COUNT: number = 2 - private MIN_SCALE: number = 0.75 + private DISPLAY_COUNT: number = 2; + private MIN_SCALE: number = 0.75; - @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange] - @State opacityList: number[] = [] - @State scaleList: number[] = [] - @State translateList: number[] = [] - @State zIndexList: number[] = [] + @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange]; + @State opacityList: number[] = []; + @State scaleList: number[] = []; + @State translateList: number[] = []; + @State zIndexList: number[] = []; aboutToAppear(): void { for (let i = 0; i < this.backgroundColors.length; i++) { - this.opacityList.push(1.0) - this.scaleList.push(1.0) - this.translateList.push(0.0) - this.zIndexList.push(0) + this.opacityList.push(1.0); + this.scaleList.push(1.0); + this.translateList.push(0.0); + this.zIndexList.push(0); } } @@ -1998,7 +2140,7 @@ struct SwiperCustomAnimationExample { ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => { Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center) .backgroundColor(backgroundColor) - // Customize how the opacity, scale, translate, and other attributes change during the custom switching animation. + // Customize how the opacity, scale, translate, and other properties change during the custom page transition animation. .opacity(this.opacityList[index]) .scale({ x: this.scaleList[index], y: this.scaleList[index] }) .translate({ x: this.translateList[index] }) @@ -2013,30 +2155,53 @@ struct SwiperCustomAnimationExample { timeout: 1000, // Called on a frame-by-frame basis for all pages in the viewport. You can change the values of attributes such as opacity, scale, translate, and zIndex in the callback to implement a custom animation. transition: (proxy: SwiperContentTransitionProxy) => { - if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) { - // Reset the attribute values when a page in the same group is swiped left or is swiped right to be completely out of the viewport. - this.opacityList[proxy.index] = 1.0 - this.scaleList[proxy.index] = 1.0 - this.translateList[proxy.index] = 0.0 - this.zIndexList[proxy.index] = 0 + if (!CommonUtil.getIsRTL()) { + if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) { + // Reset the attribute values when a page in the same group is swiped left or is swiped right to be completely out of the viewport. + this.opacityList[proxy.index] = 1.0; + this.scaleList[proxy.index] = 1.0; + this.translateList[proxy.index] = 0.0; + this.zIndexList[proxy.index] = 0; + } else { + // When a page in the same group is swiped right but is still within the viewport, the attribute values of the left and right pages in the same group are changed frame by frame based on the position. The changes implement the custom page transition animation in which the two pages move close to the middle of the and are transparently scaled in or out. + if (proxy.index % this.DISPLAY_COUNT === 0) { + this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT; + this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT); + this.translateList[proxy.index] = -proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0; + } else { + this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT; + this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT); + this.translateList[proxy.index] = -(proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0; + } + this.zIndexList[proxy.index] = -1; + } } else { - // When a page in the same group is swiped right but is still within the viewport, the attribute values of the left and right pages in the same group are changed frame by frame based on the position. The changes implement the custom switching animation in which the two pages move close to the middle of the and are transparently scaled in or out. - if (proxy.index % this.DISPLAY_COUNT === 0) { - this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT - this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT) - this.translateList[proxy.index] = - proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 + // Layout adaptation for right-to-left scripts + if (proxy.position >= -proxy.index % this.DISPLAY_COUNT || proxy.position <= -this.DISPLAY_COUNT - proxy.index % this.DISPLAY_COUNT) { + // Reset the properties when a page in the same group is swiped out of the viewport. + this.opacityList[proxy.index] = 1.0; + this.scaleList[proxy.index] = 1.0; + this.translateList[proxy.index] = 0.0; + this.zIndexList[proxy.index] = 0; } else { - this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT - this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT) - this.translateList[proxy.index] = - (proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 + // When a page in the same group is swiped left but is still within the viewport, modify property values frame by frame based on the position for the left and right pages in the group to achieve a custom transition animation where the two pages move toward the center of the Swiper with opacity and scaling effects. + if (proxy.index % this.DISPLAY_COUNT === 0) { + this.opacityList[proxy.index] = 1 + proxy.position / this.DISPLAY_COUNT; + this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 + proxy.position / this.DISPLAY_COUNT); + this.translateList[proxy.index] = -proxy.position * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0; + } else { + this.opacityList[proxy.index] = 1 + (proxy.position + 1) / this.DISPLAY_COUNT; + this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 + (proxy.position + 1) / this.DISPLAY_COUNT); + this.translateList[proxy.index] = -(proxy.position + 1) * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0; + } + this.zIndexList[proxy.index] = -1; } - this.zIndexList[proxy.index] = -1 } } }) .onContentDidScroll((selectedIndex: number, index: number, position: number, mainAxisLength: number) => { - // Called when content in the component scrolls. In this callback, you can customize the navigation indicator switching animation. - console.info("onContentDidScroll selectedIndex: " + selectedIndex + ", index: " + index + ", position: " + position + ", mainAxisLength: " + mainAxisLength) + // Listen for Swiper page scroll events. In this callback, you can customize the navigation indicator animation. + console.info("onContentDidScroll selectedIndex: " + selectedIndex + ", index: " + index + ", position: " + position + ", mainAxisLength: " + mainAxisLength); }) }.width('100%') } @@ -2050,18 +2215,18 @@ This example illustrates the activation of the overflow effect when the number o ```ts class MyDataSource implements IDataSource { - private list: number[] = [] + private list: number[] = []; constructor(list: number[]) { - this.list = list + this.list = list; } totalCount(): number { - return this.list.length + return this.list.length; } getData(index: number): number { - return this.list[index] + return this.list[index]; } registerDataChangeListener(listener: DataChangeListener): void { @@ -2074,15 +2239,15 @@ class MyDataSource implements IDataSource { @Entry @Component struct Index { - private swiperController: SwiperController = new SwiperController() - private data: MyDataSource = new MyDataSource([]) + private swiperController: SwiperController = new SwiperController(); + private data: MyDataSource = new MyDataSource([]); aboutToAppear(): void { - let list: number[] = [] + let list: number[] = []; for (let i = 1; i <= 15; i++) { list.push(i); } - this.data = new MyDataSource(list) + this.data = new MyDataSource(list); } build() { @@ -2125,11 +2290,11 @@ struct Index { Row({ space: 12 }) { Button('showNext') .onClick(() => { - this.swiperController.showNext() + this.swiperController.showNext(); }) Button('showPrevious') .onClick(() => { - this.swiperController.showPrevious() + this.swiperController.showPrevious(); }) }.margin(5) }.width('100%') @@ -2146,14 +2311,14 @@ This example shows how to use the **preloadItems** API to preload specified chil ```ts // xxx.ets -import { BusinessError } from '@kit.BasicServicesKit' +import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct SwiperPreloadItems { - @State currentIndex: number = 1 - private swiperController: SwiperController = new SwiperController() - @State arr: string[] = ["0", "1", "2", "3", "4", "5"] + @State currentIndex: number = 1; + private swiperController: SwiperController = new SwiperController(); + @State arr: string[] = ["0", "1", "2", "3", "4", "5"]; build() { Column() { @@ -2174,13 +2339,13 @@ struct SwiperPreloadItems { try { this.swiperController.preloadItems([2, 3]) .then(() => { - console.info('preloadItems [2, 3] success.') + console.info('preloadItems [2, 3] success.'); }) .catch((error: BusinessError) => { - console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message) + console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message); }) } catch (error) { - console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message) + console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message); } }) @@ -2192,14 +2357,14 @@ struct SwiperPreloadItems { @Component struct MyComponent { - private txt: string = "" + private txt: string = ""; aboutToAppear(): void { - console.info('aboutToAppear txt:' + this.txt) + console.info('aboutToAppear txt:' + this.txt); } aboutToDisappear(): void { - console.info('aboutToDisappear txt:' + this.txt) + console.info('aboutToDisappear txt:' + this.txt); } build() { @@ -2219,18 +2384,18 @@ This example shows how to implement synchronized switching between the **Tabs** ```ts // xxx.ets class MyDataSource implements IDataSource { - private list: number[] = [] + private list: number[] = []; constructor(list: number[]) { - this.list = list + this.list = list; } totalCount(): number { - return this.list.length + return this.list.length; } getData(index: number): number { - return this.list[index] + return this.list[index]; } registerDataChangeListener(listener: DataChangeListener): void { @@ -2243,19 +2408,19 @@ class MyDataSource implements IDataSource { @Entry @Component struct TabsSwiperExample { - @State fontColor: string = '#182431' - @State selectedFontColor: string = '#007DFF' - @State currentIndex: number = 0 - private list: number[] = [] - private tabsController: TabsController = new TabsController() - private swiperController: SwiperController = new SwiperController() - private swiperData: MyDataSource = new MyDataSource([]) + @State fontColor: string = '#182431'; + @State selectedFontColor: string = '#007DFF'; + @State currentIndex: number = 0; + private list: number[] = []; + private tabsController: TabsController = new TabsController(); + private swiperController: SwiperController = new SwiperController(); + private swiperData: MyDataSource = new MyDataSource([]); aboutToAppear(): void { for (let i = 0; i <= 9; i++) { this.list.push(i); } - this.swiperData = new MyDataSource(this.list) + this.swiperData = new MyDataSource(this.list); } @Builder tabBuilder(index: number, name: string) { @@ -2281,8 +2446,8 @@ struct TabsSwiperExample { }) } .onTabBarClick((index: number) => { - this.currentIndex = index - this.swiperController.changeIndex(index, true) + this.currentIndex = index; + this.swiperController.changeIndex(index, true); }) .barMode(BarMode.Scrollable) .backgroundColor('#F1F3F5') @@ -2293,10 +2458,10 @@ struct TabsSwiperExample { LazyForEach(this.swiperData, (item: string) => { Text(item.toString()) .onAppear(()=>{ - console.info('onAppear ' + item.toString()) + console.info('onAppear ' + item.toString()); }) .onDisAppear(()=>{ - console.info('onDisAppear ' + item.toString()) + console.info('onDisAppear ' + item.toString()); }) .width('100%') .height('40%') @@ -2307,9 +2472,9 @@ struct TabsSwiperExample { } .loop(false) .onSelected((index: number) => { - console.info("onSelected:" + index) + console.info("onSelected:" + index); this.currentIndex = index; - this.tabsController.changeIndex(index) + this.tabsController.changeIndex(index); }) } } @@ -2324,18 +2489,18 @@ This example demonstrates how to use the **onContentWillScroll** event to allow ```ts // xxx.ets class MyDataSource implements IDataSource { - private list: number[] = [] + private list: number[] = []; constructor(list: number[]) { - this.list = list + this.list = list; } totalCount(): number { - return this.list.length + return this.list.length; } getData(index: number): number { - return this.list[index] + return this.list[index]; } registerDataChangeListener(listener: DataChangeListener): void { @@ -2348,16 +2513,16 @@ class MyDataSource implements IDataSource { @Entry @Component struct SwiperExample { - private swiperController: SwiperController = new SwiperController() - private data: MyDataSource = new MyDataSource([]) - private currentIndex: number = 4 + private swiperController: SwiperController = new SwiperController(); + private data: MyDataSource = new MyDataSource([]); + private currentIndex: number = 4; aboutToAppear(): void { - let list: number[] = [] + let list: number[] = []; for (let i = 1; i <= 10; i++) { list.push(i); } - this.data = new MyDataSource(list) + this.data = new MyDataSource(list); } build() { @@ -2375,7 +2540,7 @@ struct SwiperExample { .index(this.currentIndex) .loop(false) .onChange((index: number) => { - this.currentIndex = index + this.currentIndex = index; }) .onContentWillScroll((result: SwiperContentWillScrollResult) => { if (result.comingIndex > this.currentIndex) { @@ -2387,11 +2552,11 @@ struct SwiperExample { Row({ space: 12 }) { Button('showNext') .onClick(() => { - this.swiperController.showNext() + this.swiperController.showNext(); }) Button('showPrevious') .onClick(() => { - this.swiperController.showPrevious() + this.swiperController.showPrevious(); }) }.margin(5) }.width('100%') @@ -2405,22 +2570,22 @@ struct SwiperExample { This example demonstrates how to use the **bottom** and **space** APIs to set the spacing between the dots in a dot-style navigation indicator and the bottom margin of the **Swiper** component. ```ts -import { LengthMetrics } from '@kit.ArkUI' +import { LengthMetrics } from '@kit.ArkUI'; // MyDataSource.ets class MyDataSource implements IDataSource { - private list: number[] = [] + private list: number[] = []; constructor(list: number[]) { - this.list = list + this.list = list; } totalCount(): number { - return this.list.length + return this.list.length; } getData(index: number): number { - return this.list[index] + return this.list[index]; } registerDataChangeListener(listener: DataChangeListener): void { @@ -2435,23 +2600,23 @@ class MyDataSource implements IDataSource { @Component struct SwiperExample { - @State space: LengthMetrics = LengthMetrics.vp(0) - @State spacePool: LengthMetrics[] = [LengthMetrics.vp(0), LengthMetrics.px(3), LengthMetrics.vp(10)] - @State spaceIndex: number = 0 + @State space: LengthMetrics = LengthMetrics.vp(0); + @State spacePool: LengthMetrics[] = [LengthMetrics.vp(0), LengthMetrics.px(3), LengthMetrics.vp(10)]; + @State spaceIndex: number = 0; - @State ignoreSize: boolean = false - @State ignoreSizePool: boolean[] = [false, true] - @State ignoreSizeIndex: number = 0 + @State ignoreSize: boolean = false; + @State ignoreSizePool: boolean[] = [false, true]; + @State ignoreSizeIndex: number = 0; - private swiperController1: SwiperController = new SwiperController() - private data1: MyDataSource = new MyDataSource([]) + private swiperController1: SwiperController = new SwiperController(); + private data1: MyDataSource = new MyDataSource([]); aboutToAppear(): void { - let list1: number[] = [] + let list1: number[] = []; for (let i = 1; i <= 10; i++) { list1.push(i); } - this.data1 = new MyDataSource(list1) + this.data1 = new MyDataSource(list1); } build() { diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-tabs.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-tabs.md index 9d9271bc1ffca48ada6ac39740efe7b0bd3ffb33..653e125a6670aa99ad60943c146195ddab01f33f 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-tabs.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-tabs.md @@ -369,7 +369,7 @@ Defines the blur style to apply between the background and content of a tab bar. barGridAlign(value: BarGridColumnOptions) -Sets the visible area of the tab bar in grid mode. For details, see **BarGridColumnOptions**. This attribute is effective only in horizontal mode. It is not applicable to [XS, XL, and XXL devices](../../../ui/arkts-layout-development-grid-layout.md#breakpoints). +Sets the visible area of the tab bar in grid mode. For details, see **BarGridColumnOptions**. This attribute is effective only in horizontal mode. It is not applicable to [XS, XL, and XXL devices](../../../ui/arkts-layout-development-grid-layout.md#grid-breakpoints). **Atomic service API**: This API can be used in atomic services since API version 11. @@ -580,7 +580,7 @@ This event is triggered when any of the following occurs: > **NOTE** > -> When a custom tab is used, relying solely on the **onChange** event for synchronization between tabs and swipe gestures may result in delayed visual updates, since it is triggered after the swipe-triggered tab switching animation is completed. For smooth animations, listen for the active tab index in [onAnimationStart](#onanimationstart11) and update the tab index accordingly. For details about the implementation, see [Example 3](#example-3-setting-up-custom-tab-switching-synchronization). +> When a custom tab is used, relying solely on the **onChange** event for synchronization between tabs and swipe gestures may result in delayed visual updates, since it is triggered after the swipe-triggered tab switching animation is completed. For smooth animations, listen for the active tab index in [onAnimationStart](#onanimationstart11) and update the tab index accordingly. For details about the implementation, see [Example 3](#example-3-implementing-custom-tab-switching-synchronization). **Atomic service API**: This API can be used in atomic services since API version 11. @@ -1025,7 +1025,7 @@ Sets the opacity of the tab bar. | Name | Type | Mandatory | Description | | ----- | ------ | ---- | ---------------------------------------- | -| opacity | number | Yes| Opacity of the tab bar. The value range is [0.0, 1.0].| +| opacity | number | Yes| Opacity of the tab bar. The value range is [0.0, 1.0]. A value less than 0.0 is handed as **0.0**. A value greater than **1.0** is handed as **1.0**.
Default value: **1.0**.| ## Example diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animatetoimmediately.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animatetoimmediately.md index ba856a10a5a74f56a7eb30fb68e3b2f5f4b0c98a..c9fb8ea94765fd0119e858cd208488d02feba124 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animatetoimmediately.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-explicit-animatetoimmediately.md @@ -10,7 +10,7 @@ In general cases, using **animateToImmediately** is not advised. Opt for [animat > **NOTE** > -> This feature is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. > ## APIs @@ -41,10 +41,10 @@ This example demonstrates how to use the **animateToImmediately** API to deliver @Entry @Component struct AnimateToImmediatelyExample { - @State widthSize: number = 250 - @State heightSize: number = 100 - @State opacitySize: number = 0 - private flag: boolean = true + @State widthSize: number = 250; + @State heightSize: number = 100; + @State opacitySize: number = 0; + private flag: boolean = true; build() { Column() { @@ -61,31 +61,31 @@ struct AnimateToImmediatelyExample { delay: 0, duration: 1000 }, () => { - this.opacitySize = 1 + this.opacitySize = 1; }) - animateTo({ + this.getUIContext()?.animateTo({ delay: 1000, duration: 1000 }, () => { - this.widthSize = 150 - this.heightSize = 60 + this.widthSize = 150; + this.heightSize = 60; }) } else { animateToImmediately({ delay: 0, duration: 1000 }, () => { - this.widthSize = 250 - this.heightSize = 100 + this.widthSize = 250; + this.heightSize = 100; }) - animateTo({ + this.getUIContext()?.animateTo({ delay: 1000, duration: 1000 }, () => { - this.opacitySize = 0 + this.opacitySize = 0; }) } - this.flag = !this.flag + this.flag = !this.flag; }) }.width('100%').margin({ top: 5 }) } diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-settings.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-settings.md index dcdf3561ef6954f4a68f13214c8c488369e38174..9beee36593bd02012c70fc26f2bdccf399025444 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-settings.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-gesture-settings.md @@ -25,6 +25,8 @@ A region in which a gesture can be recognized may be specified by the [touch tar **Atomic service API**: This API can be used in atomic services since API version 11. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name| Description| | -------- | -------- | | [TapGesture](ts-basic-gestures-tapgesture.md) | Tap gesture, which can be a single-tap or multi-tap gesture.| @@ -40,6 +42,8 @@ A region in which a gesture can be recognized may be specified by the [touch tar **Atomic service API**: This API can be used in atomic services since API version 11. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name| Description| | -------- | -------- | | Normal | The gestures of child components are enabled and recognized based on the default gesture recognition sequence.| @@ -56,30 +60,33 @@ The component binds gesture objects of different **GestureType** instances throu | onAction((event:GestureEvent) => void) | Callback invoked when a tap gesture is recognized.| ## GestureEvent - Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). -**Atomic service API**: This API can be used in atomic services since API version 11. - -| Name| Type| Description| -| -------- | -------- | -------- | -| repeat | boolean | Whether the event is triggered repeatedly. This attribute is used for the **LongPressGesture** event.| -| offsetX | number | Offset in the X coordinate of the gesture event, in vp. This attribute is used for the **PanGesture** event. A positive value means to pan from left to right, and a negative value means the opposite.| -| offsetY | number | Offset in the Y coordinate of the gesture event, in vp. This attribute is used for the **PanGesture** event. A positive value means to pan from top to bottom, and a negative value means the opposite.| -| angle | number | Rotation angle for the **RotationGesture** event;
angle of the swipe gesture for the **SwipeGesture** event, that is, the change in the included angle between the line segment created by the two fingers and the horizontal direction.
**NOTE**
Angle calculation method: After a swipe gesture is recognized, a line connecting the two fingers is identified as the initial line. As the fingers swipe, the line between the fingers rotates. Based on the coordinates of the initial line's and current line's end points, an arc tangent function is used to calculate the respective included angle of the points relative to the horizontal direction by using the following formula: Rotation angle = arctan2(cy2-cy1,cx2-cx1) - arctan2(y2-y1,x2-x1) The initial line is used as the coordinate system. The clockwise rotation is 0 to 180 degrees, and the counter-clockwise rotation is –180 to 0 degrees.| -| scale | number | Scale ratio. This attribute is used for the **PinchGesture** event.| -| pinchCenterX | number | X coordinate of the pinch center, in vp. This attribute is used for the **PinchGesture** event.| -| pinchCenterY | number | Y coordinate of the pinch center, in vp. This attribute is used for the **PinchGesture** event.| -| speed8+ | number | Swipe gesture speed, that is, the average swipe speed of all fingers relative to the original area of the current component. The unit is vp/s. This attribute is used for the **SwipeGesture** event.| -| fingerList8+ | [FingerInfo](#fingerinfo8)[] | List of contact points of the gesture event. If the event input device is touchscreen, the list includes all contact points. If the event input device is mouse or touchpad, the list contains only one contact point.
**NOTE**
The index of a finger corresponds to its position, that is, the ID of a finger in **fingerList[index]** refers to its index. If a finger is pressed first and does not participate in triggering of the current gesture, its position in **fingerList** is left empty.| -| velocityX10+ | number | Velocity along the x-axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The origin of the coordinate axis is the upper left corner of the screen. The velocity is positive if the movement is from left to right, and it is negative if the movement is from right to left. The unit is vp/s.| -| velocityY10+ | number | Velocity along the y-axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The origin of the coordinate axis is the upper left corner of the screen. The velocity is positive if the movement is from top to bottom, and it is negative if the movement is from bottom to top. The unit is vp/s.| -| velocity10+ | number | Velocity along the main axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The value is the arithmetic square root of the sum of squares of the velocity along the x- and y-axis. The unit is vp/s.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +| Name| Type| Mandatory | Description| +| -------- | -------- | ---- | -------- | +| repeat | boolean | Yes| Whether the event is triggered repeatedly. This attribute is used for the **LongPressGesture** event.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| offsetX | number | Yes|Offset in the X coordinate of the gesture event, in vp. This attribute is used for the **PanGesture** event. A positive value means to pan from left to right, and a negative value means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| offsetY | number | Yes| Offset in the Y coordinate of the gesture event, in vp. This attribute is used for the **PanGesture** event. A positive value means to pan from top to bottom, and a negative value means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| angle | number | Yes| Rotation angle for the **RotationGesture** event;
angle of the swipe gesture for the **SwipeGesture** event, that is, the change in the included angle between the line segment created by the two fingers and the horizontal direction.
**NOTE**
Angle calculation method: After a swipe gesture is recognized, a line connecting the two fingers is identified as the initial line. As the fingers swipe, the line between the fingers rotates. Based on the coordinates of the initial line's and current line's end points, an arc tangent function is used to calculate the respective included angle of the points relative to the horizontal direction by using the following formula: Rotation angle = arctan2(cy2-cy1,cx2-cx1) - arctan2(y2-y1,x2-x1) The initial line is used as the coordinate system. The clockwise rotation is 0 to 180 degrees, and the counter-clockwise rotation is –180 to 0 degrees.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| scale | number | Yes| Scale ratio. This attribute is used for the **PinchGesture** event.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| pinchCenterX | number | Yes| X coordinate of the pinch center, in vp. This attribute is used for the **PinchGesture** event.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| pinchCenterY | number | Yes| Y coordinate of the pinch center, in vp. This attribute is used for the **PinchGesture** event.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| speed8+ | number | Yes| Swipe gesture speed, that is, the average swipe speed of all fingers relative to the original area of the current component. The unit is vp/s. This attribute is used for the **SwipeGesture** event.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| fingerList8+ | [FingerInfo](#fingerinfo8)[] | Yes| List of touch points of the gesture event. If the event input device is touchscreen, the list includes all touch points. If the event input device is mouse or touchpad, the list contains only one touch point.
**NOTE**
The index of a finger corresponds to its position, that is, the ID of a finger in **fingerList[index]** refers to its index. If a finger is pressed first and does not participate in triggering of the current gesture, its position in **fingerList** is left empty.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| fingerInfos20+ | [FingerInfo](#fingerinfo8)[] | No| Information about touch points of the gesture event. For gesture events initiated by a touchscreen, **fingerInfos** includes information about all touch points. For gesture events initiated by a mouse or touchpad, **fingerInfos** contains only one touch point.
**NOTE**
**fingerInfos** only records information about effective fingers that participate in the touch. Fingers that are pressed first but do not participate in triggering of the current gesture will not be shown in **fingerInfos**. The default value is an empty array **[]**, and an empty array indicates no effective touch point information.
**Atomic service API**: This API can be used in atomic services since API version 20.| +| velocityX10+ | number | Yes| Velocity along the x-axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The origin of the coordinate axis is the upper left corner of the screen. The velocity is positive if the movement is from left to right, and it is negative if the movement is from right to left. The unit is vp/s.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| velocityY10+ | number | Yes| Velocity along the y-axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The origin of the coordinate axis is the upper left corner of the screen. The velocity is positive if the movement is from top to bottom, and it is negative if the movement is from bottom to top. The unit is vp/s.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| velocity10+ | number | Yes| Velocity along the main axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The value is the arithmetic square root of the sum of squares of the velocity along the x- and y-axis. The unit is vp/s.
**Atomic service API**: This API can be used in atomic services since API version 11.| +| tapLocation20+ | [EventLocationInfo](ts-basic-gestures-tapgesture.md#eventlocationinfo20) | Yes| Coordinate information of the current tap gesture.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 20.| ## SourceType8+ **Atomic service API**: This API can be used in atomic services since API version 11. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name| Description| | -------- | -------- | | Unknown | Unknown device type.| @@ -88,41 +95,51 @@ Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). ## FingerInfo8+ +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name| Type| Description| | -------- | -------- | -------- | -| id | number | Index of a finger.
**Atomic service API**: This API can be used in atomic services since API version 11.| -| globalX | number | X-coordinate relative to the upper left corner of the application window, in vp.
**Atomic service API**: This API can be used in atomic services since API version 11.| -| globalY | number | Y-coordinate relative to the upper left corner of the application window, in vp.
**Atomic service API**: This API can be used in atomic services since API version 11.| -| localX | number | X-coordinate relative to the upper left corner of the current component's original area, in vp.
**Atomic service API**: This API can be used in atomic services since API version 11.| -| localY | number | Y-coordinate relative to the upper left corner of the current component's original area, in vp.
**Atomic service API**: This API can be used in atomic services since API version 11.| -| displayX12+ | number | X-coordinate relative to the upper left corner of the screen, in vp.
**Atomic service API**: This API can be used in atomic services since API version 12.| -| displayY12+ | number | Y-coordinate relative to the upper left corner of the screen, in vp.
**Atomic service API**: This API can be used in atomic services since API version 12.| +| id | number | Index of a finger.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| globalX | number | X-coordinate relative to the upper left corner of the application window, in vp.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| globalY | number | Y-coordinate relative to the upper left corner of the application window, in vp.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| localX | number | X-coordinate relative to the upper left corner of the current component's original area, in vp.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| localY | number | Y-coordinate relative to the upper left corner of the current component's original area, in vp.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 11.| +| displayX12+ | number | X-coordinate relative to the upper left corner of the screen, in vp.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 12.| +| displayY12+ | number | Y-coordinate relative to the upper left corner of the screen, in vp.
Value range: [0, +∞).
**Atomic service API**: This API can be used in atomic services since API version 12.| | hand15+ | [InteractionHand](#interactionhand15) | Whether the event is triggered by a left-hand or right-hand tap.
**Atomic service API**: This API can be used in atomic services since API version 15.| ## SourceTool9+ +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name| Description| | -------- | -------- | | Unknown | Unknown input source.
**Atomic service API**: This API can be used in atomic services since API version 11.| | Finger | Finger.
**Atomic service API**: This API can be used in atomic services since API version 11.| | Pen | Stylus.
**Atomic service API**: This API can be used in atomic services since API version 11.| -| Mouse12+ | Mouse device.
**Atomic service API**: This API can be used in atomic services since API version 12.| -| Touchpad12+ | Touchpad. Single-finger input on the touchpad is treated as a mouse input operation.
**Atomic service API**: This API can be used in atomic services since API version 12.| -| Joystick12+ | Joystick.
**Atomic service API**: This API can be used in atomic services since API version 12.| +| MOUSE12+ | Mouse device.
**Atomic service API**: This API can be used in atomic services since API version 12.| +| TOUCHPAD12+ | Touchpad. Single-finger input on the touchpad is treated as a mouse input operation.
**Atomic service API**: This API can be used in atomic services since API version 12.| +| JOYSTICK12+ | Joystick.
**Atomic service API**: This API can be used in atomic services since API version 12.| ## InteractionHand15+ Defines whether an event is triggered by a left-hand or right-hand tap. +**Atomic service API**: This API can be used in atomic services since API version 15. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name| Description| | -------- | -------- | -| NONE | Unknown.
**Atomic service API**: This API can be used in atomic services since API version 16.| -| LEFT | Left hand.
**Atomic service API**: This API can be used in atomic services since API version 16.| -| RIGHT | Right hand.
**Atomic service API**: This API can be used in atomic services since API version 16.| +| NONE | Unknown.| +| LEFT | Left hand.| +| RIGHT | Right hand.| ## Example +### Example 1: Implementing Parent Component Prioritization and Simultaneous Gesture Triggering + This example demonstrates how to configure **priorityGesture** and **parallelGesture** to set up gesture recognition where the parent component has priority in recognizing gestures, and both parent and child components can trigger gestures simultaneously. ```ts @@ -179,4 +196,75 @@ struct GestureSettingsExample { } ``` -![en-us_image_0000001257058419](figures/en-us_image_0000001257058419.gif) +![en-us_image_0000001210195016](figures/en-us_image_0000001210195016.gif) + +### Example 2: Implementing Real-time Monitoring of Effective Touch Points Involved in a Swipe Gesture + +This example demonstrates how to configure **fingerInfos** to monitor the number of effective touch points involved in a swipe gesture in real time. + +```ts +// xxx.ets +@Entry +@Component + +struct PanGestureWithFingerCount { + @State offsetX: number = 0 + @State offsetY: number = 0 + @State positionX: number = 0 + @State positionY: number = 0 + @State fingerCount: number = 0 // Used to record the number of touch points involved in the gesture. + + private panOption: PanGestureOptions = new PanGestureOptions({ + direction: PanDirection.All, + fingers: 1 + }) + + build() { + Column() { + // Display the number of effective touch points. + Text(`Touch Points: ${this.fingerCount}`) + .fontSize(20) + .margin(10) + + Column() { + Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) + } + .height(200) + .width(300) + .padding(20) + .border({ width: 3 }) + .margin(50) + .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) + .gesture( + PanGesture(this.panOption) + .onActionStart((event: GestureEvent) => { + console.info('Pan start') + this.fingerCount = event.fingerInfos?.length || 0 // Record the number of touch points. + }) + .onActionUpdate((event: GestureEvent) => { + if (event) { + console.log('fingerInfos',JSON.stringify(event.fingerInfos)) + this.offsetX = this.positionX + event.offsetX + this.offsetY = this.positionY + event.offsetY + this.fingerCount = event.fingerInfos?.length || 0 // Update the number of touch points, recording the effective touch points involved in the current gesture. + } + }) + .onActionEnd((event: GestureEvent) => { + this.positionX = this.offsetX + this.positionY = this.offsetY + this.fingerCount = 0 // Reset the value to zero when the touch points leave the touch target. + console.info('Pan end') + }) + .onActionCancel(() => { + this.fingerCount = 0 // Reset the value to zero when the gesture is canceled. + }) + ) + + Button('Switch to Two-Finger Swipe') + .onClick(() => { + this.panOption.setFingers(2) + }) + } + } +} +``` diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-motion-path-animation.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-motion-path-animation.md index 2c60886910970114dfb1afd390f438f1e32e3ffc..2ec2aa76206af155f68d62d813a360c153eea2c8 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-motion-path-animation.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-motion-path-animation.md @@ -4,13 +4,17 @@ The motion path animation is used to animate a component along a custom path. > **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 initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. ## motionPath motionPath(value: MotionPathOptions) +Sets a path animation for the component. + **Atomic service API**: This API can be used in atomic services since API version 11. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + **Parameters** | Name | Type | Mandatory| Description | @@ -21,12 +25,14 @@ motionPath(value: MotionPathOptions) **Atomic service API**: This API can be used in atomic services since API version 11. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name| Type| Mandatory| Description| | -------- | -------- | ---- | -------- | | path | string | Yes | Motion path of the translation animation. The **svg** path string is used. In the value, **start** and **end** can be used in place of the start point and end point, for example, **'Mstart.x start.y L50 50 Lend.x end.y Z'**. For details, see [Path Drawing](../../../ui/ui-js-components-svg-path.md).
If this parameter is set to an empty string, the path animation is not set. | | from | number | No | Start point of the motion path.
Default value: **0.0**
Value range: [0, 1]
A value less than 0 or greater than 1 evaluates to the default value **0**. | | to | number | No | End point of the motion path.
Default value: **1.0**
Value range: [0, 1]
A value less than 0 or greater than 1 evaluates to the default value **1**, provided that the value of **to** is greater than or equal to the value of **from**. | -| rotatable | boolean | No | Whether to rotate along the path.
Default value: **false** | +| rotatable | boolean | No | Whether to rotate along the path. The value **true** means to rotate along the path, and **false** means the opposite.
Default value: **false** | ## Example @@ -38,7 +44,7 @@ This example demonstrates how to animate a component along a custom path. @Entry @Component struct MotionPathExample { - @State toggle: boolean = true + @State toggle: boolean = true; build() { Column() { @@ -50,9 +56,9 @@ struct MotionPathExample { rotatable: true }) // Execute the animation: Move from the start point to (300,200), then to (300,500), and finally to the end point. .onClick(() => { - animateTo({ duration: 4000, curve: Curve.Linear }, () => { - this.toggle =! this.toggle // Use this.toggle to change the position of the component. - }) + this.getUIContext()?.animateTo({ duration: 4000, curve: Curve.Linear }, () => { + this.toggle = !this.toggle; // Change the component's position using this.toggle. + }); }) }.width('100%').height('100%').alignItems(this.toggle ? HorizontalAlign.Start : HorizontalAlign.Center) } diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-page-transition-animation.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-page-transition-animation.md index 009013ce5a740d987485c085fa0f4d28610199ed..dd96140378e51bc9838f13fefb44910b0e71ff1f 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-page-transition-animation.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-page-transition-animation.md @@ -1,10 +1,10 @@ # Page Transition (pageTransition) -You can customize the page entrance and exit animations in the **pageTransition** API for transition between pages. For details, see [Page Transition Animation](../../../ui/arkts-page-transition-animation.md). +When performing route switching using the [router](../js-apis-router.md), you can customize entrance and exit transition animations between pages by implementing the **pageTransition** API. For details, see [Page Transition Animation](../../../ui/arkts-page-transition-animation.md). > **NOTE** > -> This event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. +> This feature is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. > > To achieve a better transition effect, you are advised to use the [Navigation](../../../ui/arkts-navigation-navigation.md) component and [modal transition](../../../ui/arkts-modal-transition.md). @@ -48,7 +48,7 @@ Invoked on a per-frame basis until the entrance animation is complete, with the | Name| Type | Mandatory| Description | | ------ | ----------------------------------------------------------------- | ---- | ------------------------------------------------ | -| event | [PageTransitionCallback](#pagetransitioncallback14) | Yes | Callback invoked on a per-frame basis until the entrance animation is complete, with the **progress** parameter changing from 0 to 1.| +| event | [PageTransitionCallback](#pagetransitioncallback18) | Yes | Callback invoked on a per-frame basis until the entrance animation is complete, with the **progress** parameter changing from 0 to 1.| **Example** @@ -92,7 +92,7 @@ Invoked on a per-frame basis until the exit animation is complete, with the **pr | Name| Type | Mandatory| Description | | ------ | ----------------------------------------------------------------- | ---- | ------------------------------------------------ | -| event | [PageTransitionCallback](#pagetransitioncallback14) | Yes | Callback invoked on a per-frame basis until the exit animation is complete, with the **progress** parameter changing from 0 to 1.| +| event | [PageTransitionCallback](#pagetransitioncallback18) | Yes | Callback invoked on a per-frame basis until the exit animation is complete, with the **progress** parameter changing from 0 to 1.| **Example** @@ -201,13 +201,13 @@ Sets the starting opacity value for entrance or the ending opacity value for exi | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | value | number | Yes | Starting opacity value for entrance or the ending opacity value for exit.
Value range: [0, 1]| -## PageTransitionCallback14+ +## PageTransitionCallback18+ type PageTransitionCallback = (type: RouteType, progress: number) => void Represents the callback for page transition events. -**Atomic service API**: This API can be used in atomic services since API version 14. +**Atomic service API**: This API can be used in atomic services since API version 18. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -251,14 +251,12 @@ Represents the callback for page transition events. Method 1: Configure different entrance and exit animations based on different transition types. ```ts -// index.ets -import { router } from '@kit.ArkUI'; - +// Index.ets @Entry @Component struct Index { - @State scale1: number = 1 - @State opacity1: number = 1 + @State scale1: number = 1; + @State opacity1: number = 1; build() { Column() { @@ -269,7 +267,7 @@ struct Index { .scale({ x: this.scale1 }) .opacity(this.opacity1) .onClick(() => { - router.pushUrl({ url: 'pages/Page1' }) + this.getUIContext().getRouter().pushUrl({ url: 'pages/Page1' }); }) } @@ -277,15 +275,15 @@ struct Index { PageTransitionEnter({ duration: 1200, curve: Curve.Linear }) .onEnter((type: RouteType, progress: number) => { if (type == RouteType.Push || type == RouteType.Pop) { - this.scale1 = progress - this.opacity1 = progress + this.scale1 = progress; + this.opacity1 = progress; } }) PageTransitionExit({ duration: 1200, curve: Curve.Ease }) .onExit((type: RouteType, progress: number) => { if (type == RouteType.Push) { - this.scale1 = 1 - progress - this.opacity1 = 1 - progress + this.scale1 = 1 - progress; + this.opacity1 = 1 - progress; } }) } @@ -293,14 +291,12 @@ struct Index { ``` ```ts -// page1.ets -import { router } from '@kit.ArkUI'; - +// Page1.ets @Entry @Component struct Page1 { - @State scale2: number = 1 - @State opacity2: number = 1 + @State scale2: number = 1; + @State opacity2: number = 1; build() { Column() { @@ -311,7 +307,7 @@ struct Page1 { .scale({ x: this.scale2 }) .opacity(this.opacity2) .onClick(() => { - router.pushUrl({ url: 'pages/Index' }) + this.getUIContext().getRouter().pushUrl({ url: 'pages/Index' }); }) } @@ -319,15 +315,15 @@ struct Page1 { PageTransitionEnter({ duration: 1200, curve: Curve.Linear }) .onEnter((type: RouteType, progress: number) => { if (type == RouteType.Push || type == RouteType.Pop) { - this.scale2 = progress + this.scale2 = progress; } - this.opacity2 = progress + this.opacity2 = progress; }) PageTransitionExit({ duration: 1200, curve: Curve.Ease }) .onExit((type: RouteType, progress: number) => { if (type == RouteType.Pop) { - this.scale2 = 1 - progress - this.opacity2 = 1 - progress + this.scale2 = 1 - progress; + this.opacity2 = 1 - progress; } }) } @@ -339,16 +335,17 @@ struct Page1 { Method 2: Configure the entrance animation of sliding in from the left and the exit animation of translating with opacity change. ```ts -// index.ets +// Index.ets @Entry @Component -struct PageTransitionExample { +struct Index { build() { Column() { - Navigator({ target: 'pages/page1', type: NavigationType.Push }) { - Image($r("app.media.transition_image2")).width('100%').height('100%') // The image is stored in the media folder. - } + Image($r('app.media.bg1')).width('100%').height('100%') // The image is stored in the media folder. } + .onClick(() => { + this.getUIContext().getRouter().pushUrl({ url: 'pages/Page1' }); + }) } // Use the default effects provided by the system, such as translation, scaling, and opacity. @@ -365,16 +362,17 @@ struct PageTransitionExample { ``` ```ts -// page1.ets +// Page1.ets @Entry @Component -struct PageTransitionExample1 { +struct Page1 { build() { Column() { - Navigator({ target: 'pages/index', type: NavigationType.Push }) { - Image($r('app.media.bg2')).width('100%').height('100%') // The image is stored in the media folder. - } + Image($r('app.media.bg2')).width('100%').height('100%') // The image is stored in the media folder. } + .onClick(() => { + this.getUIContext().getRouter().pushUrl({ url: 'pages/Index' }); + }) } // Use the default effects provided by the system, such as translation, scaling, and opacity. @@ -397,20 +395,18 @@ struct PageTransitionExample1 { Method 1: Configure the various translation effects provided, with the system language layout mode set to right-to-left (RTL). ```ts -// index.ets -import { router } from '@kit.ArkUI' - +// Index.ets @Entry @Component -struct PageTransitionExample { - @State scale1: number = 1 - @State opacity1: number = 1 +struct Index { + @State scale1: number = 1; + @State opacity1: number = 1; build() { Column() { Button("Page 1").onClick(() => { - router.pushUrl({ - url: "pages/page1" + this.getUIContext().getRouter().pushUrl({ + url: "pages/Page1" }) }) .width(200) @@ -440,21 +436,19 @@ struct PageTransitionExample { ``` ```ts -// page1.ets -import { router } from '@kit.ArkUI' - +// Page1.ets @Entry @Component -struct PageTransitionExample { - @State scale1: number = 1 - @State opacity1: number = 1 +struct Page1 { + @State scale1: number = 1; + @State opacity1: number = 1; build() { Column() { Button("Page 2").onClick(() => { - router.pushUrl({ + this.getUIContext().getRouter().pushUrl({ url: "pages/Index" - }) + }); }) .width(200) .height(60) @@ -486,21 +480,19 @@ struct PageTransitionExample { Method 2: Use the system's default entrance and exit effects, with the system language layout mode set to right-to-left (RTL). ```ts -// index.ets -import { router } from '@kit.ArkUI' - +// Index.ets @Entry @Component -struct PageTransitionExample { - @State scale1: number = 1 - @State opacity1: number = 1 +struct Index { + @State scale1: number = 1; + @State opacity1: number = 1; build() { Column() { Button("Page 1").onClick(() => { - router.pushUrl({ - url: "pages/page1" - }) + this.getUIContext().getRouter().pushUrl({ + url: "pages/Page1" + }); }) .width(200) .height(60) @@ -516,21 +508,19 @@ struct PageTransitionExample { ``` ```ts -// page1.ets -import { router } from '@kit.ArkUI' - +// Page1.ets @Entry @Component -struct PageTransitionExample { - @State scale1: number = 1 - @State opacity1: number = 1 +struct Page1 { + @State scale1: number = 1; + @State opacity1: number = 1; build() { Column() { Button("Page 2").onClick(() => { - router.pushUrl({ + this.getUIContext().getRouter().pushUrl({ url: "pages/Index" - }) + }); }) .width(200) .height(60) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md index d6c0a5fb2dfd06eb99cebf916bb31748bf6e8bb5..3f6c8eb8779182028e7539884682d23b935f5b40 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md @@ -1,10 +1,10 @@ # Accessibility -You can set accessibility attributes and events for components. +You can set accessibility attributes and events for components to fully leverage accessibility features. > **NOTE** > -> The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. ## accessibilityGroup @@ -12,7 +12,7 @@ accessibilityGroup(value: boolean) Sets whether to enable accessibility grouping. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components. -If accessibility grouping is enabled and the component does not contain a universal text attribute or an [accessibility text](#accessibilitytext) attribute, the system will concatenate the universal text attributes of its child components to form a merged text for the component. If a child component lacks a universal text attribute, it will be ignored in the concatenation process. The merged text will not use the accessibility text of the child components. +If accessibility grouping is enabled for a component that does not contain a universal text attribute or an [accessibility text](#accessibilitytext) attribute, the system will concatenate the universal text attributes of its child components to generate merged text for the component. Child components without universal text attributes will be ignored during concatenation, and their accessibility text (if any) won't be used in the merged text. **Widget capability**: This API can be used in ArkTS widgets since API version 12. @@ -24,17 +24,17 @@ If accessibility grouping is enabled and the component does not contain a univer | Name| Type | Mandatory| Description | | ------ | ------- | ---- | ------------------------------------------------------------ | -| value | boolean | Yes | Whether to enable accessibility grouping. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components.
Default value: **false**| +| value | boolean | Yes | Whether to enable accessibility grouping. The value **true** means to enable accessibility grouping, and **false** means the opposite. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components.
Default value: **false**| ## accessibilityGroup14+ accessibilityGroup(isGroup: boolean, accessibilityOptions: AccessibilityOptions) -Sets whether to enable accessibility grouping, with support for prioritizing the concatenation of accessibility text for accessibility announcement. When accessibility grouping is enabled, the component and all its children are treated as a single selectable entity, and the accessibility service will no longer focus on the individual child components. +Sets whether to enable accessibility grouping. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components. -If accessibility grouping is enabled and the component does not contain a universal text attribute or an [accessibility text](#accessibilitytext) attribute, the system will concatenate the universal text attributes of its child components to form a merged text for the component. If a child component lacks a universal text attribute, it will be ignored in the concatenation process. +If accessibility grouping is enabled for a component that does not contain a universal text attribute or an [accessibility text](#accessibilitytext) attribute, the system will concatenate the universal text attributes of its child components to generate merged text for the component. Child components without universal text attributes will be ignored during concatenation. -When **accessibilityPreferred** is set to **true**, the system will prioritize concatenating the accessibility text attributes of the child components to form the merged text. If a child component lacks an accessibility text attribute, the system will continue to concatenate its universal text attribute. If a child component lacks both, it will be ignored. +When **accessibilityPreferred** is set to **true**, the system will prioritize concatenating the accessibility text attributes of the child components. If a child component has no accessibility text set, its universal text attribute will be used instead. Components without either attribute will be excluded from concatenation. **Widget capability**: This API can be used in ArkTS widgets since API version 14. @@ -46,8 +46,8 @@ When **accessibilityPreferred** is set to **true**, the system will prioritize c | Name | Type | Mandatory| Description | | -------------------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| isGroup | boolean | Yes | Whether to enable accessibility grouping. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components.
Default value: **false**| -| accessibilityOptions | [AccessibilityOptions](#accessibilityoptions14) | Yes | Options for accessibility grouping. When **accessibilityPreferred** is set to **true**, the system will prioritize concatenating the accessibility text attributes of the child components to form the merged text.
Default value: **false** | +| isGroup | boolean | Yes | Whether to enable accessibility grouping. The value **true** means to enable accessibility grouping, and **false** means the opposite. When accessibility grouping is enabled, the component and all its children are treated as a single selectable unit, and the accessibility service will no longer focus on the individual child components.
Default value: **false**| +| accessibilityOptions | [AccessibilityOptions](#accessibilityoptions14) | Yes | Options for accessibility grouping. When **accessibilityPreferred** is set to **true**, the system will prioritize concatenating accessibility text for screen readers. When **accessibilityPreferred** is set to **false**, accessibility text will not be prioritized.
Default value: **false** | ## AccessibilityOptions14+ @@ -55,7 +55,7 @@ When **accessibilityPreferred** is set to **true**, the system will prioritize c | Name | Type | Mandatory| Description | | ---------------------- | ------- | ---- | ------------------------------------------------------------ | -| accessibilityPreferred | boolean | No | Whether to prioritize the accessibility text of child components during a deep traversal. The value **true** means to prioritize the accessibility text of child components.
If a child component's accessibility text is empty, the accessibility service uses the component's own text content. The concatenated text is then assigned to the parent node if both its accessibility text and text content are empty.
Default value: **false**| +| accessibilityPreferred | boolean | No | Whether to prioritize the accessibility text of child components during a deep traversal. The value **true** means to prioritize the accessibility text of child components.
If a child component's accessibility text is empty, the accessibility service uses the component's own text content. The concatenated text is then assigned to the parent node if both its accessibility text and text content are empty.
The value **false** means not to prioritize the accessibility text of child components.
Default value: **false**| ## accessibilityText @@ -218,41 +218,7 @@ Sets the role type of the accessibility component, which affects how the compone | Name | Type | Mandatory| Description | | -------- | ------- | ---- | ------------------------------------------------------------ | -| role | [AccessibilityRoleType](ts-universal-attributes-accessibility.md#AccessibilityRoleType18) | Yes | Role of the component as announced by screen readers (for example, button or chart). You can define custom roles.| - -## onAccessibilityFocus18+ - -onAccessibilityFocus(callback: AccessibilityFocusCallback) - -Triggered when the accessibility component gains or loses focus. Callback triggered when the component gains or loses focus. - -**Widget capability**: This API can be used in ArkTS widgets since API version 18. - -**Atomic service API**: This API can be used in atomic services since API version 18. - -**System capability**: SystemCapability.ArkUI.ArkUI.Full - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | ------- | ---- | ------------------------------------------------------------ | -| callback | [AccessibilityFocusCallback](ts-universal-attributes-accessibility.md#AccessibilityFocusCallback18) | Yes | Callback that notifies the registered component of focus and blur events.| - -## AccessibilityFocusCallback18+ - -type AccessibilityFocusCallback = (isFocus: boolean) => void - -Defines the callback type used in **onAccessibilityFocus**. - -**Atomic service API**: This API can be used in atomic services since API version 18. - -**System capability**: SystemCapability.ArkUI.ArkUI.Full - -**Parameters** - -| Name | Type | Mandatory| Description | -| ------ | ------ | ---- | ---------------- | -| isFocus | boolean | Yes| Whether the component has gained or lost focus.| +| role | [AccessibilityRoleType](ts-universal-attributes-accessibility.md#accessibilityroletype18) | Yes | Role of the component as announced by screen readers (for example, button or chart). You can define custom roles.| ## AccessibilityRoleType18+ @@ -430,7 +396,7 @@ Sets whether the component is the default initial focus for screen readers on th accessibilityUseSamePage(pageMode: AccessibilitySamePageMode) -Solves focus jumping issues in sub-tree scenarios like UIExtensionComponent. Sets the same-page mode for this UIExtensionComponent and the host application. This property is intended to solve focus jumping issues in sub-tree scenarios. Due to the timing of page events sent by the UIExtensionComponent and the host application, focus may jump from one component to another, causing "focus jumping." +Solves focus jumping issues in sub-tree scenarios for cross-process embedded components, such as **UIExtensionComponent**. Focus jumping occurs when the timing of page events from the embedded component's process conflicts with those of the host application, causing focus to unexpectedly shift between components. **Widget capability**: This API can be used in ArkTS widgets since API version 18. @@ -442,11 +408,11 @@ Solves focus jumping issues in sub-tree scenarios like UIExtensionComponent. Set | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------ | -| pageMode | [AccessibilitySamePageMode](#accessibilitysamepagemode18) | Yes | Same-page mode for the current UIExtensionComponent and the host application.| +| pageMode | [AccessibilitySamePageMode](#accessibilitysamepagemode18) | Yes | Same-page mode for the cross-process embedded component and the host application.| ## AccessibilitySamePageMode18+ -Enumerates the same-page modes for the current UIExtensionComponent and the host application. +Enumerates the same-page modes for cross-process embedded components and their host applications. **Atomic service API**: This API can be used in atomic services since API version 18. @@ -454,8 +420,8 @@ Enumerates the same-page modes for the current UIExtensionComponent and the host | Name | Value | Description | | ----------- | ---- | ------------------------------------------------------------ | -| SEMI_SILENT | 0 | Ignores page events if it is the first page load or if the root node of the page sends the page event.| -| FULL_SILENT | 1 | Ignores all page events in the UIExtensionComponent. | +| SEMI_SILENT | 0 | Ignores initial page loading events and root node page events from the cross-process embedded component.| +| FULL_SILENT | 1 | Ignores all page events from the cross-process embedded component. | ## accessibilityScrollTriggerable18+ @@ -493,21 +459,22 @@ Sets the text hint for the component, which can be queried by accessibility serv | -------------- | ------- | ---- | ------------------------------------------------------------ | | value | string | Yes | Text hint for the component, which can be queried by accessibility services.| -## accessibilityFocusDrawLevel18+ +## accessibilityFocusDrawLevel19+ accessibilityFocusDrawLevel(drawLevel: FocusDrawLevel) -Sets the drawing level for the accessibility focus highlight (green box) to ensure it is visible and not obscured by other components. +Sets the drawing level for the accessibility focus highlight frame. + > **NOTE** > -> 1. By default, the accessibility focus highlight (green box) is drawn at the same level as the focused component. This can sometimes result in the highlight being obscured or clipped by parent components or siblings with higher z-order. +> 1. By default, the accessibility focus highlight frame is drawn at the same level as the focused component. This can sometimes result in the frame being obscured or clipped by parent components or siblings with higher z-order. > -> 2. Setting the drawing level to the topmost layer ensures that the accessibility focus highlight is not obscured by other components. This is useful when you want the highlight to be clearly visible at all times. However, this setting may not be suitable if you need to interact with components that should overlay the currently focused component and you do not want the accessibility highlight to be visible. +> 2. Setting the drawing level to the topmost layer ensures that the accessibility focus highlight frame is not obscured by other components. This is useful when you want the highlight frame to be clearly visible at all times. However, this setting may not be suitable if you need to interact with components that should overlay the currently focused component and you do not want the accessibility highlight to be visible. -**Widget capability**: This API can be used in ArkTS widgets since API version 18. +**Widget capability**: This API can be used in ArkTS widgets since API version 19. -**Atomic service API**: This API can be used in atomic services since API version 18. +**Atomic service API**: This API can be used in atomic services since API version 19. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -515,13 +482,15 @@ Sets the drawing level for the accessibility focus highlight (green box) to ensu | Name | Type | Mandatory| Description | | -------- | ------- | ---- | ------------------------------------------------------------ | -| drawLevel | [FocusDrawLevel](ts-appendix-enums.md#focusdrawlevel18) | Yes | Drawing level for the accessibility focus highlight.| +| drawLevel | [FocusDrawLevel](ts-appendix-enums.md#focusdrawlevel19) | Yes | Drawing level for the accessibility focus highlight frame.| -## Example 1: Setting Accessibility Text and Description +## Example + +### Example 1: Setting Accessibility Text and Description This example demonstrates how to use **accessibilityText** and **accessibilityDescription** to customize the content announced by screen readers. -``` +```ts // xxx.ets @Entry @Component @@ -549,7 +518,7 @@ struct Index { .accessibilityGroup(true) .accessibilityLevel("yes") .accessibilityText("Group") // If a component has both text content and accessibility text, only the accessibility text is announced. - .accessibilityDescription("The Column component is selectable , and the text to be read out is "Group".) + .accessibilityDescription("The Column component can be selected, and the announced content is 'Group'") .accessibilityVirtualNode(this.customAccessibilityNode) .accessibilityChecked(true) .accessibilitySelected(undefined) @@ -559,11 +528,11 @@ struct Index { } ``` -## Example 2: Setting the Accessibility Group +### Example 2: Setting the Accessibility Group This example shows how to use **accessibilityGroup** to prioritize reading the accessibility text of child components. -``` +```ts // xxx.ets @Entry @Component @@ -578,11 +547,10 @@ struct Focus { Button().accessibilityLevel("yes").accessibilityText("Accessibility text is announced if no text is present") Button("Text content is announced if no accessibility text is present").accessibilityLevel("yes") Button() - Button('btnl23').accessibilityText("Button with both accessibility text and text").accessibilityLevel("yes") + Button('btn123').accessibilityText("Button with both accessibility text and text").accessibilityLevel("yes") Button('btn123').accessibilityLevel("yes") } .accessibilityGroup(true, { accessibilityPreferred: true }) - //.accessibilityGroup(true) .borderWidth(5) .width('100%') .height('100%') @@ -590,3 +558,182 @@ struct Focus { } ``` +### Example 3: Setting the Initial Focus and the Next Focus of a Component + +This example demonstrates the use of **accessibilityDefaultFocus** to set the default initial focus for the screen reader on the current page and **accessibilityNextFocusId** to set the next focus for components during focus traversal. + +```ts +// xxx.ets +@Entry +@Component +struct Index { + build() { + Column({ space: 20 }) { + Text('Text Demo 1') + .fontSize(50) + .accessibilityLevel('yes') + .accessibilityNextFocusId('text3') + Text('Text Demo 2') + .id('text2') + .fontSize(50) + .accessibilityLevel('yes') + .accessibilityDefaultFocus(true) // Set the component as initial focus for the screen reader. + .accessibilityNextFocusId('text4') + Text('Text Demo 3') + .id('text3') + .fontSize(50) + .accessibilityLevel('yes') + .accessibilityNextFocusId('text2') + Text('Text Demo 4') + .id('text4') + .fontSize(50) + .accessibilityLevel('yes') + } + .height('100%') + .width('100%') + } +} +``` + +### Example 4: Setting the Accessibility Component Type and Text Hint + +This example demonstrates the use of **accessibilityRole** to set the accessibility component type and **accessibilityTextHint** to provide text hints for components that can be queried by assistive technologies. + +```ts +// xxx.ets +@Entry +@Component +struct Index { + @State isDownloading: boolean = false; + @State hintStr: string = 'Click to start download'; + + build() { + Column({ space: 20 }) { + Button(this.isDownloading ? 'Downloading' : 'Click to download') + .accessibilityLevel('yes') + .accessibilityTextHint(this.hintStr) + .onClick(() => { + this.isDownloading = !this.isDownloading; + this.hintStr = this.isDownloading ? 'Status changed to downloading' : 'Status changed to paused'; + }) + TextInput({ placeholder: 'Enter phone number' }) + .accessibilityLevel('yes') + .accessibilityTextHint('Enter an 11-digit phone number') + .width('80%') + Text('Announced as button type') + .accessibilityLevel('yes') + .accessibilityRole(AccessibilityRoleType.BUTTON) + .accessibilityTextHint('The screen reader will announce this component as a button') + .fontSize(30) + } + .height('100%') + .width('100%') + } +} +``` + +### Example 5: Configuring Screen Reader Scrolling, Focus Highlight Frame, and Cross-Process Focus + +This example demonstrates the use of **accessibilityScrollTriggerable** to set whether an accessibility node supports screen reading scroll, **accessibilityFocusDrawLevel** to set the drawing level of the accessibility focus highlight frame, and **accessibilityUseSamePage** for cross-process embedded components like **EmbeddedComponent**. + +```ts +// xxx.ets +import { Want } from '@kit.AbilityKit'; + +@Entry +@Component +struct Index { + @State message: string = 'Message: '; + private want: Want = { + bundleName: 'com.example.embeddeddemo', + abilityName: 'ExampleEmbeddedAbility', + } + + build() { + Row() { + List() { + ListItem() { + Column() { + Text(this.message) + .fontSize(18) + .fontColor('#2D2D2D') + .fontWeight(FontWeight.Medium) + Column() { + EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION) + .width('100%') + .height('90%') + .onTerminated((info) => { + this.message = 'Termination: code = ' + info.code + ', want = ' + JSON.stringify(info.want); + }) + .onError((error) => { + this.message = 'Error: code = ' + error.code; + }) + .accessibilityUseSamePage(AccessibilitySamePageMode.FULL_SILENT) + .width('90%') + .height('50%') + .backgroundColor('#F0F0F0') + .borderRadius(8) + .borderWidth(1) + .borderColor('#D9D9D9') + + Stack() { + Column() { + Text('Text 1') + .fontSize(18) + .fontColor('#2D2D2D') + .fontWeight(FontWeight.Medium) + Text('Text 1') + .fontSize(18) + .fontColor('#2D2D2D') + .fontWeight(FontWeight.Medium) + .accessibilityFocusDrawLevel(FocusDrawLevel.TOP) + } + .padding({ top: 8, bottom: 8 }) + + Column() { + Text('Text 2') + .fontSize(18) + .fontColor('#FFFFFF') + .fontWeight(FontWeight.Medium) + Text('Text 2') + .fontSize(18) + .fontColor('#FFFFFF') + .fontWeight(FontWeight.Medium) + } + .backgroundColor('#4A90E2') + .padding({ + left: 12, + right: 12, + top: 10, + bottom: 10 + }) + .borderRadius(6) + } + .width('100%') + .margin({ top: 10, bottom: 10 }) + } + .width('100%') + .height('100%') + .margin({ top: 15 }) + .accessibilityText($r('app.string.app_name')) + .accessibilityDescription($r('app.string.module_desc')) + Column() { + Text('Text 4') + .fontSize(18) + .fontWeight(FontWeight.Medium) + } + .margin({ top: 15 }) + } + .width('100%') + } + } + .accessibilityScrollTriggerable(false) + .width('100%') + } + .height('100%') + .backgroundColor('#F7F9FC') + } +} +``` + +![accessibilityFocusDrawLevel](figures/accessibilityFocusDrawLevel.png) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-modifier.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-modifier.md index a5165bb48f52b774b1cf0e1494f071eb7ab24f4f..74712ff4fac17a7c7f16e4ff68c465fce4c64aeb 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-modifier.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-modifier.md @@ -2,17 +2,17 @@ With the attribute modifier, you can dynamically set component attributes, complete with the **if/else** syntax and polymorphic style. -> **NOTE** +> **NOTE** > -> This feature is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. +> This feature is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. > > Ensure that the attributes set in **attributeModifier** are different from those set in other methods. Otherwise, **attributeModifier** does not take effect when the page is refreshed. > -> **attributeModifier** does not support custom components. +> **attributeModifier** supports custom components since API version 20. ## attributeModifier -attributeModifier(modifier: AttributeModifier\) +attributeModifier(modifier: AttributeModifier\): T Creates an attribute modifier. @@ -24,7 +24,13 @@ Creates an attribute modifier. | Name | Type | Mandatory| Description | | -------- | -------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------- | -| modifier | [AttributeModifier\](#attributemodifiert) | Yes | Modifier for dynamically setting attributes on the current component. The **if/else** syntax is supported.
**modifier**: attribute modifier. You need a custom class to implement the **AttributeModifier** API.| +| modifier | [AttributeModifier\](#attributemodifiert) | Yes | Modifier for dynamically setting attributes on the current component. The **if/else** syntax is supported.
**modifier**: attribute modifier. You need to customize classes to implement the **AttributeModifier** API.| + +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| ## AttributeModifier\ @@ -121,7 +127,7 @@ CommonModifier, ColumnModifier, ColumnSplitModifier, RowModifier, RowSplitModifi 2. Updating the attribute value of a custom modifier changes the corresponding attribute of the component to which the modifier is applied. The custom modifier is a base class, and the constructed object is a child class object. When using the object, use **as** to assert the type as a child class. 3. With a custom modifier applied to two components, updating the attribute value of the custom modifier changes the corresponding attributes of both components. 4. If attributes A and B are set through a custom modifier, and then attributes C and D are set through other means, all the four attributes take effect on the component. -5. The custom modifier does not support change observation for @State decorated variables. For details, see Example 2. +5. Custom modifiers do not support change detection of state data decorated with @State. For details, see [Example 3: Understanding Custom Modifiers Do Not Support State Data Changes)](#example-3-understanding-custom-modifiers-do-not-support-state-data-changes). 6. If you use **attributeModifier** to set attributes multiple times, all the set attributes take effect, and those attributes that are set multiple times take effect based on the configuration sequence. ## Example @@ -132,13 +138,13 @@ This example demonstrates how to switch the background color of a **Button** com ```ts // xxx.ets class MyButtonModifier implements AttributeModifier { - isDark: boolean = false + public isDark: boolean = false; applyNormalAttribute(instance: ButtonAttribute): void { if (this.isDark) { - instance.backgroundColor(Color.Black) + instance.backgroundColor(Color.Black); } else { - instance.backgroundColor(Color.Red) + instance.backgroundColor(Color.Red); } } } @@ -146,7 +152,7 @@ class MyButtonModifier implements AttributeModifier { @Entry @Component struct attributeDemo { - @State modifier: MyButtonModifier = new MyButtonModifier() + @State modifier: MyButtonModifier = new MyButtonModifier(); build() { Row() { @@ -154,7 +160,7 @@ struct attributeDemo { Button("Button") .attributeModifier(this.modifier) .onClick(() => { - this.modifier.isDark = !this.modifier.isDark + this.modifier.isDark = !this.modifier.isDark; }) } .width('100%') @@ -173,18 +179,18 @@ This example demonstrates how to implement a pressed state effect for a **Button // xxx.ets class MyButtonModifier implements AttributeModifier { applyNormalAttribute(instance: ButtonAttribute): void { - instance.backgroundColor(Color.Black) + instance.backgroundColor(Color.Black); } applyPressedAttribute(instance: ButtonAttribute): void { - instance.backgroundColor(Color.Red) + instance.backgroundColor(Color.Red); } } @Entry @Component struct attributePressedDemo { - @State modifier: MyButtonModifier = new MyButtonModifier() + @State modifier: MyButtonModifier = new MyButtonModifier(); build() { Row() { @@ -205,7 +211,7 @@ struct attributePressedDemo { This example shows how to set the width of a custom modifier using state data. Custom modifiers do not support observing changes in data decorated with the @State decorator. Therefore, the width does not change when the button is clicked. ```ts -import { CommonModifier } from "@kit.ArkUI" +import { CommonModifier } from "@kit.ArkUI"; const TEST_TAG : string = "AttributeModifier"; class MyModifier extends CommonModifier { @@ -216,7 +222,7 @@ class MyModifier extends CommonModifier { @Component struct MyImage1 { - @Link modifier: CommonModifier + @Link modifier: CommonModifier; build() { Image($r("app.media.startIcon")).attributeModifier(this.modifier as MyModifier) @@ -229,21 +235,21 @@ struct Index { index: number = 0; @State width1: number = 100; @State height1: number = 100; - @State myModifier: CommonModifier = new MyModifier().width(this.width1).height(this.height1).margin(10) + @State myModifier: CommonModifier = new MyModifier().width(this.width1).height(this.height1).margin(10); build() { Column() { Button($r("app.string.EntryAbility_label")) .margin(10) .onClick(() => { - console.log(TEST_TAG, "onClick") + console.log(TEST_TAG, "onClick"); this.index++; if (this.index % 2 === 1) { this.width1 = 10; - console.log(TEST_TAG, "setGroup1") + console.log(TEST_TAG, "setGroup1"); } else { this.width1 = 10; - console.log(TEST_TAG, "setGroup2") + console.log(TEST_TAG, "setGroup2"); } }) MyImage1({ modifier: this.myModifier }) @@ -259,7 +265,7 @@ struct Index { In this example, the custom modifier sets the **width** and **height** attributes, and the **borderStyle** and **borderWidth** attributes are set through a button click. In this case, all the four attributes take effect when the button is clicked. ```ts -import { CommonModifier } from "@kit.ArkUI" +import { CommonModifier } from "@kit.ArkUI"; const TEST_TAG: string = "AttributeModifier"; @@ -269,19 +275,19 @@ class MyModifier extends CommonModifier { } public setGroup1(): void { - this.borderStyle(BorderStyle.Dotted) - this.borderWidth(8) + this.borderStyle(BorderStyle.Dotted); + this.borderWidth(8); } public setGroup2(): void { - this.borderStyle(BorderStyle.Dashed) - this.borderWidth(8) + this.borderStyle(BorderStyle.Dashed); + this.borderWidth(8); } } @Component struct MyImage1 { - @Link modifier: CommonModifier + @Link modifier: CommonModifier; build() { Image($r("app.media.startIcon")).attributeModifier(this.modifier as MyModifier) @@ -291,7 +297,7 @@ struct MyImage1 { @Entry @Component struct Index { - @State myModifier: CommonModifier = new MyModifier().width(100).height(100).margin(10) + @State myModifier: CommonModifier = new MyModifier().width(100).height(100).margin(10); index: number = 0; build() { @@ -299,14 +305,14 @@ struct Index { Button($r("app.string.EntryAbility_label")) .margin(10) .onClick(() => { - console.log(TEST_TAG, "onClick") + console.log(TEST_TAG, "onClick"); this.index++; if (this.index % 2 === 1) { - (this.myModifier as MyModifier).setGroup1() - console.log(TEST_TAG, "setGroup1") + (this.myModifier as MyModifier).setGroup1(); + console.log(TEST_TAG, "setGroup1"); } else { - (this.myModifier as MyModifier).setGroup2() - console.log(TEST_TAG, "setGroup2") + (this.myModifier as MyModifier).setGroup2(); + console.log(TEST_TAG, "setGroup2"); } }) MyImage1({ modifier: this.myModifier }) @@ -317,6 +323,174 @@ struct Index { ``` ![attributeModifier](figures/attributeModifier.gif) +### Example 5: Setting the Focused State Style with a Modifier + +This example demonstrates how to implement a focused state style for a **Button** component by binding it to a modifier. After **Button2** is clicked, the **Button** component displays the focused style when it has focus. + +```ts +class MyButtonModifier implements AttributeModifier { + + applyNormalAttribute(instance: ButtonAttribute): void { + instance.backgroundColor(Color.Blue); + } + applyFocusedAttribute(instance: ButtonAttribute): void { + instance.backgroundColor(Color.Green); + } +} + +@Entry +@Component +struct attributeDemo { + @State modifier: MyButtonModifier = new MyButtonModifier(); + @State isDisable: boolean = true; + + build() { + Row() { + Column() { + Button("Button") + .attributeModifier(this.modifier) + .enabled(this.isDisable) + .id("app") + Divider().vertical(false).strokeWidth(15).color(Color.Transparent) + Button("Button2") + .onClick(() => { + this.getUIContext().getFocusController().activate(true); + this.getUIContext().getFocusController().requestFocus("app"); + }) + } + .width('100%') + } + .height('100%') + } +} +``` +![applyFocusedAttribute](figures/applyFocusedAttribute.gif) + +### Example 6: Setting the Disabled State Style with a Modifier + +This example demonstrates how to implement a disabled state style for a **Button** component by binding it to a modifier. After **Button2** is clicked, the **Button** component displays the disabled style when it is disabled. + +```ts +class MyButtonModifier implements AttributeModifier { + applyDisabledAttribute(instance: ButtonAttribute): void { + instance.width(200); + } +} + +@Entry +@Component +struct attributeDemo { + @State modifier: MyButtonModifier = new MyButtonModifier(); + @State isDisable: boolean = true; + + build() { + Row() { + Column() { + Button("Button") + .attributeModifier(this.modifier) + .enabled(this.isDisable) + Divider().vertical(false).strokeWidth(15).color(Color.Transparent) + Button("Button2") + .onClick(() => { + this.isDisable = !this.isDisable; + }) + } + .width('100%') + } + .height('100%') + } +} +``` +![applyDisabledAttribute](figures/applyDisabledAttribute.gif) + +### Example 7: Setting the Selected State Style with a Modifier + +This example demonstrates how to implement a selected state style for a **Radio** component by binding it to a modifier. + +```ts +class MyRadioModifier implements AttributeModifier { + applyNormalAttribute(instance: RadioAttribute): void { + instance.backgroundColor(Color.Blue); + } + applySelectedAttribute(instance: RadioAttribute): void { + instance.backgroundColor(Color.Red); + instance.borderWidth(2); + } +} + +@Entry +@Component +struct attributeDemo { + @State modifier: MyRadioModifier = new MyRadioModifier(); + @State value: boolean = false; + @State value2: boolean = false; + + build() { + Row() { + Column() { + Radio({ value: 'Radio1', group: 'radioGroup1' }) + .checked(this.value) + .height(50) + .width(50) + .borderWidth(0) + .borderRadius(30) + .onClick(() => { + this.value = !this.value; + }) + .attributeModifier(this.modifier) + } + .width('100%') + } + .height('100%') + } +} +``` +![applySelectedAttribute](figures/applySelectedAttribute.gif) + +### Example 8: Implementing the Pressed State Effect for a Custom Component with a Modifier + +This example demonstrates how to implement a pressed state effect for a custom component (**Common**) by binding it to a modifier. + +```ts +// xxx.ets +class CustomModifier implements AttributeModifier { + applyNormalAttribute(instance: CommonAttribute): void { + instance.backgroundColor(Color.Blue) + } + + applyPressedAttribute(instance: CommonAttribute): void { + instance.backgroundColor(Color.Red) + } +} + +@Entry +@Component +struct attributePressedDemo { + @State modifier: CustomModifier = new CustomModifier() + + build() { + Row() { + Column() { + ChildCompoent() + .attributeModifier(this.modifier) + } + .width('100%') + } + .height('100%') + } +} + +@Component +struct ChildCompoent { + build() { + Text("common").fontColor(Color.Green).fontSize(28).textAlign(TextAlign.Center) + .width('35%') + .height('10%') + } +} +``` +![attributeModifier_common](figures/attributeModifier_common.gif) + ## Supported Scope of Attributes Attributes not listed in the table below are supported by default. @@ -345,11 +519,7 @@ Attributes not listed in the table below are supported by default. | gesture | Not supported | Method not implemented. | Gesture-related attributes are not supported. | | gestureModifier | Not supported | is not callable | Modifier-related attributes are not supported. | | onAccessibilityHover | Not supported | is not callable | - | -| onChildTouchTest | Not supported | is not callable | - | | onDragStart | Not supported | Method not implemented. | Attributes that return a CustomBuilder are not supported. | -| onPreDrag | Not supported | Method not implemented. | - | -| onTouchIntercept | Not supported | is not callable | - | -| onVisibleAreaChange | Not supported | Method not implemented. | - | | parallelGesture | Not supported | Method not implemented. | Gesture-related attributes are not supported. | | priorityGesture | Not supported | Method not implemented. | Gesture-related attributes are not supported. | | reuseId | Not supported | Method not implemented. | - | diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click-effect.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click-effect.md index d832c215537948c0185b7e7d4e7a963239b92dd4..7fa9f083411103c4352ee00f592a09f4e270102c 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click-effect.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click-effect.md @@ -1,6 +1,6 @@ -# Click Effect +# Click Feedback Effect -You can set the click effect for a component to define how it behaves when clicked. +You can set the click feedback effect for a component to define its visual response when it is clicked. > **NOTE** > @@ -8,9 +8,9 @@ You can set the click effect for a component to define how it behaves when click ## clickEffect -clickEffect(value: ClickEffect | null) +clickEffect(value: ClickEffect | null): T -Click effect of the component. +Sets the click feedback effect of the component. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -20,13 +20,19 @@ Click effect of the component. | Name| Type | Mandatory| Description | | ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | -| value | [ClickEffect](#clickeffect) \| null | Yes | Click effect of the component.
**NOTE**
The click effect is revoked when this attribute is set to **null**.
Avoid using this attribute in scenarios where the component size dynamically changes.
This attribute is not supported when the component cannot trigger a universal event.| +| value | [ClickEffect](#clickeffect) \| null | Yes | Click feedback effect of the component.
**NOTE**
Use **null** to disable the click feedback effect.
Avoid using this feature in scenarios where the component size dynamically changes.
This attribute is not supported when the component cannot trigger universal events.
After the click feedback effect triggers scaling, the touch point may fall outside the control, making the component unresponsive to gesture events.| + +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| ## clickEffect18+ -clickEffect(effect: Optional\) +clickEffect(effect: Optional\): T -Click effect of the component. Compared to [clickEffect](#clickeffect), this API supports the **undefined** type for the **effect** parameter. +Sets the click feedback effect of the component. Compared to [clickEffect](#clickeffect), this API supports the **undefined** type for the **effect** parameter. **Atomic service API**: This API can be used in atomic services since API version 18. @@ -36,7 +42,13 @@ Click effect of the component. Compared to [clickEffect](#clickeffect), this API | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| effect | Optional\<[ClickEffect](#clickeffect) \| null> | Yes | Click effect of the component.
**NOTE**
You can remove the click effect by setting this attribute to **undefined** or **null**.
Avoid using this attribute in scenarios where the component size dynamically changes.
This attribute is not supported when the component cannot trigger a universal event.| +| effect | Optional\<[ClickEffect](#clickeffect) \| null> | Yes | Click feedback effect of the component.
**NOTE**
Use **undefined** or **null** to disable the click feedback effect.
Avoid using this feature in scenarios where the component size dynamically changes.
This attribute is not supported when the component cannot trigger universal events.
After the click feedback effect triggers scaling, the touch point may fall outside the control, making the component unresponsive to gesture events.| + +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| ## ClickEffect @@ -44,12 +56,12 @@ Click effect of the component. Compared to [clickEffect](#clickeffect), this API | Name | Type | Mandatory| Description | | ----- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| level | [ClickEffectLevel](ts-appendix-enums.md#clickeffectlevel10) | Yes | Click effect of the component.
**NOTE**
If **level** is set to **undefined** or **null**, the click effect corresponding to **ClickEffectLevel.LIGHT** will be used. For details about the zoom ratio, see the description of **scale**.| -| scale | number | No | Zoom ratio. This parameter works based on the setting of **ClickEffectLevel**.
**NOTE**
The default value of this parameter varies by the value of **level**.
If **level** is set to **ClickEffectLevel.LIGHT**, the default value is **0.90**.
If **level** is set to **ClickEffectLevel.MIDDLE** or **ClickEffectLevel.HEAVY**, the default value is **0.95**.
If **level** is set to **undefined** or **null** (both of which evaluate to **ClickEffectLevel.LIGHT**), the default value is **0.90**.
If **scale** is set to **undefined** or **null**, the default zoom ratio for the set level will be used.
| +| level | [ClickEffectLevel](ts-appendix-enums.md#clickeffectlevel10) | Yes | Click feedback effect of the component.
**NOTE**
When **level** is **undefined** or **null**, **ClickEffect** uses the effect corresponding to **ClickEffectLevel.LIGHT** with a scaling ratio as described below.| +| scale | number | No | Custom scaling ratio for fine-tuning the click feedback effect.
**NOTE**
The default value varies depending on the value of **level**:
**ClickEffectLevel.LIGHT**: **0.90**.
**ClickEffectLevel.MIDDLE** or **ClickEffectLevel.HEAVY**: **0.95**.
**undefined** or **null** (treated as **ClickEffectLevel.LIGHT**): **0.90**.
When **scale** is set to **undefined** or **null**, the default scaling ratio for the current **level** is used.| ## Example -This example demonstrates the click effects on different types of components. +This example demonstrates the click feedback effects on different types of components. ```ts // xxx.ets @@ -65,7 +77,7 @@ struct ToggleExample { .selectedColor('#007DFF') .switchPointColor('#FFFFFF') .onChange((isOn: boolean) => { - console.info('Component status:' + isOn) + console.info('Component status:' + isOn); }) Toggle({ type: ToggleType.Switch, isOn: true }) @@ -73,7 +85,7 @@ struct ToggleExample { .selectedColor('#007DFF') .switchPointColor('#FFFFFF') .onChange((isOn: boolean) => { - console.info('Component status:' + isOn) + console.info('Component status:' + isOn); }) } @@ -84,7 +96,7 @@ struct ToggleExample { .size({ width: 20, height: 20 }) .selectedColor('#007DFF') .onChange((isOn: boolean) => { - console.info('Component status:' + isOn) + console.info('Component status:' + isOn); }) Toggle({ type: ToggleType.Checkbox, isOn: true }) @@ -92,7 +104,7 @@ struct ToggleExample { .size({ width: 20, height: 20 }) .selectedColor('#007DFF') .onChange((isOn: boolean) => { - console.info('Component status:' + isOn) + console.info('Component status:' + isOn); }) } @@ -104,7 +116,7 @@ struct ToggleExample { .clickEffect({level:ClickEffectLevel.HEAVY}) .selectedColor('rgba(0,125,255,0.20)') .onChange((isOn: boolean) => { - console.info('Component status:' + isOn) + console.info('Component status:' + isOn); }) Toggle({ type: ToggleType.Button, isOn: true }) { @@ -113,7 +125,7 @@ struct ToggleExample { .clickEffect({level:ClickEffectLevel.HEAVY, scale: 0.5}) .selectedColor('rgba(0,125,255,0.20)') .onChange((isOn: boolean) => { - console.info('Component status:' + isOn) + console.info('Component status:' + isOn); }) } }.width('100%').padding(24) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click.md index 5b83363ed4374806ef0f4daca3db716ce1d22e91..b6fb8146ebf1b7d11ac2a316627cc8e11705fc21 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-click.md @@ -1,19 +1,22 @@ # Click Control + Click control attributes are used to set whether a component can respond to finger interactions such as click and touch events. > **NOTE** > +> This module is deprecated since API version 9. You are advised to use [hitTestBehavior](ts-universal-attributes-hit-test-behavior.md) instead. +> > The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. ## Attributes +**System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type| Description | | ----------- | -------- | ------------------------ | -| touchable(deprecated) | boolean | Whether the component can respond to finger interactions such as click and touch events.
Default value: **true**
**NOTE**
This API is deprecated since API version 9. You are advised to use [hitTestBehavior](ts-universal-attributes-hit-test-behavior.md) instead.| - +| touchable(deprecated) | boolean | Whether the component can respond to finger interactions such as click and touch events.
**true** (default): The component can respond to finger interactions. **false**: The component cannot respond to finger interactions.| ## Example diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-content-modifier.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-content-modifier.md index 9d758d2a57bf1d7fe808c01d51c5e45b8e1e0517..c36a9992460341c2489de2a4c58ff749820ae1d8 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-content-modifier.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-content-modifier.md @@ -2,13 +2,13 @@ You can apply a content modifier to a component to customize its content area using a style builder. -> **NOTE** +> **NOTE** > -> This feature is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. ## contentModifier -contentModifier(modifier:ContentModifier\) +contentModifier(modifier: ContentModifier\): T Creates a content modifier. @@ -16,9 +16,15 @@ Creates a content modifier. **Parameters** -| Name | Type | Mandatory | Description | +| Name | Type | Mandatory| Description | | -------- | ------------------ | ---- | ------------------------------------------------------------ | -| modifier | ContentModifier\ | Yes | Content modifier to apply to the current component.
**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API. | +| modifier | ContentModifier\ | Yes | Content modifier to apply to the current component.
**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API.| + +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| ## ContentModifier\ @@ -26,7 +32,7 @@ You need a custom class to implement the **ContentModifier** API. ### applyContent -applyContent() : WrappedBuilder<[T]> +applyContent(): WrappedBuilder<[T]> Builder of the custom content area. @@ -36,9 +42,9 @@ Builder of the custom content area. **Parameters** -| Name | Description | +| Name| Description | | ---- | ------------------------------------------------------------ | -| T | Component attribute class, which is used to distinguish different information required by different components after content areas are customized, for example, **ButtonConfiguration** for the **Button** component and **CheckBoxConfiguration** of the **Checkbox** component. | +| T | Component attribute class, which is used to distinguish different information required by different components after content areas are customized, for example, **ButtonConfiguration** for the **Button** component and **CheckBoxConfiguration** of the **Checkbox** component.| **Value range of the T parameter:** @@ -68,21 +74,21 @@ This example demonstrates how to create a custom check box using **ContentModifi ```ts // xxx.ets class MyCheckboxStyle implements ContentModifier { - selectedColor: Color = Color.White + selectedColor: Color = Color.White; constructor(selectedColor: Color) { this.selectedColor = selectedColor; } applyContent(): WrappedBuilder<[CheckBoxConfiguration]> { - return wrapBuilder(buildCheckbox) + return wrapBuilder(buildCheckbox); } } @Builder function buildCheckbox(config: CheckBoxConfiguration) { Column({ space: 10 }) { - Text(config.name + (config.selected ? "(Selected)" : "(Not selected)")) + Text(config.name + (config.selected ? "(Selected)" : ""(Not selected)")) Shape() { // Pentagon check box style Path() @@ -114,9 +120,9 @@ function buildCheckbox(config: CheckBoxConfiguration) { .onClick(() => { // Trigger the check box state change upon click. if (config.selected) { - config.triggerChange(false) + config.triggerChange(false); } else { - config.triggerChange(true) + config.triggerChange(true); } }) .margin({ left: 150 }) @@ -133,7 +139,7 @@ struct Index { .select(true) .contentModifier(new MyCheckboxStyle(Color.Red)) .onChange((value: boolean) => { - console.info('Checkbox change is' + value) + console.info('Checkbox change is' + value); }) } .width('100%') diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-monopolize-events.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-monopolize-events.md index 02719fb3077ced2d95c9f6af4510310d44c836a1..544419b6a410389451b33878066c4b1a5a8546bd 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-monopolize-events.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-monopolize-events.md @@ -5,11 +5,11 @@ When a component with event monopolization is the first to respond to an interac > **NOTE** > -> This feature is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. ## monopolizeEvents -monopolizeEvents(monopolize: boolean) +monopolizeEvents(monopolize: boolean): T Sets whether the component exclusively handles events. @@ -19,11 +19,16 @@ Sets whether the component exclusively handles events. **Parameters** - | Name | Type| Mandatory| Description | | ----------- | -------- | ------------------------ | ------------------------ | | monopolize | boolean | Yes| Whether the component exclusively handles events.
**true**: The component exclusively handles events.
**false**: The component does not exclusively handle events.
Default value: **false**.
**NOTE**
1. If a component is exclusively handling events after a finger is pressed on it, and another finger is pressed before the first finger is lifted, the component continues to exclusively handle events while interacting with the second finger. The same case applies to a third and more fingers.
2. If a component is bound through [parallelGesture](ts-gesture-settings.md) to a gesture, for example, [pan gesture](ts-basic-gestures-pangesture.md), that can also be triggered by its child component, and the child component has event monopolization and is the first to respond, then the parent will not respond to the gesture.| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## Example This example demonstrates how to set **monopolizeEvents** to determine whether a component exclusively handles events. @@ -33,10 +38,10 @@ This example demonstrates how to set **monopolizeEvents** to determine whether a @Entry @Component struct Index { - @State message: string = 'set monopolizeEvents false' - @State messageOut: string = ' ' - @State messageInner: string = ' ' - @State monopolize: boolean = false + @State message: string = 'set monopolizeEvents false'; + @State messageOut: string = ' '; + @State messageInner: string = ' '; + @State monopolize: boolean = false; build() { Column() { diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-motionBlur.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-motionBlur.md index 9abe66b88503116971da5bc90008a21a60588971..765b7245d320267bbb7a8e416c556a1551b1e097 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-motionBlur.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-motionBlur.md @@ -8,9 +8,9 @@ You can apply a motion blur effect to a component being scaled or moved. This ef ## motionBlur -motionBlur(value: MotionBlurOptions) +motionBlur(value: MotionBlurOptions): T -Apply a motion blur effect to the component being scaled or moved. +Applies a motion blur effect to the component being scaled or moved. 1. Do not use this API in intra-component transitions, shared element transitions, implicit element transitions, or particle animations. Doing so may cause unexpected results. @@ -26,17 +26,25 @@ Apply a motion blur effect to the component being scaled or moved. **Atomic service API**: This API can be used in atomic services since API version 12. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + **Parameters** | Name| Type | Mandatory| Description | | ------ | ----------------------------------------------- | ---- | ------------------ | | value | [MotionBlurOptions](#motionbluroptions) | Yes | Motion blur options.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## motionBlur18+ -motionBlur(motionBlur: Optional\) +motionBlur(motionBlur: Optional\): T -Apply a motion blur effect to the component being scaled or moved. Compared to [motionBlur](#motionblur), this API supports the **undefined** type for the **motionBlur** parameter. +Applies a motion blur effect to the component being scaled or moved. Compared to [motionBlur](#motionblur), this API supports the **undefined** type for the **motionBlur** parameter. 1. Do not use this API in intra-component transitions, shared element transitions, implicit element transitions, or particle animations. Doing so may cause unexpected results. @@ -52,16 +60,26 @@ Apply a motion blur effect to the component being scaled or moved. Compared to [ **Atomic service API**: This API can be used in atomic services since API version 18. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + **Parameters** | Name | Type | Mandatory | Description | | ---------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | | motionBlur | Optional\<[MotionBlurOptions](#motionbluroptions)> | Yes | Motion blur options.
If **motionBlur** is set to **undefined**, the previous value is retained.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## MotionBlurOptions **Atomic service API**: This API can be used in atomic services since API version 12. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name | Type | Mandatory | Description | | ------------- | ----------------------------------------------------------- | ----- | ------------------------------------------------------------ | | radius | number | Yes | Blur radius. The value range is [0.0, ∞). You are advised to set it to a value less than 1.0.| @@ -71,6 +89,8 @@ Apply a motion blur effect to the component being scaled or moved. Compared to [ **Atomic service API**: This API can be used in atomic services since API version 12. +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name | Type | Mandatory | Description | | ------------- | ----------------------------------------------------------- | ----- | ------------------------------------------------------------ | | x | number | Yes | X-coordinate of the anchor point. The value range is [0.0, 1.0].| @@ -86,12 +106,12 @@ import { curves } from '@kit.ArkUI'; @Entry @Component struct motionBlurTest { - @State widthSize: number = 400 - @State heightSize: number = 320 - @State flag: boolean = true - @State radius: number = 0 - @State x: number = 0 - @State y: number = 0 + @State widthSize: number = 400; + @State heightSize: number = 320; + @State flag: boolean = true; + @State radius: number = 0; + @State x: number = 0; + @State y: number = 0; build() { Column() { diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-on-child-touch-test.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-on-child-touch-test.md index 2a5649781da946cf14d0d96258876628f383ddbc..95343545a5ce6b0e7f1528134ad23631a62e820b 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-on-child-touch-test.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-on-child-touch-test.md @@ -1,10 +1,10 @@ # Custom Event Dispatch -When handling a touch event, ArkUI performs a touch test on the touch point and the component area before the event is triggered – to determine the components targeted by the event – and dispatches the event based on the test result. You can use **onChildTouchTest** on a parent node to specify how to perform the touch test on child nodes and thereby exert an impact on touch event dispatch. For details about the impact, see [TouchTestStrategy](#touchteststrategy). +When handling a touch event, ArkUI performs a hit test on the touch point and the component area before the event is triggered – to determine the components targeted by the event – and dispatches the event based on the test result. You can use **onChildTouchTest** on a parent node to specify how to perform the hit test on child nodes and thereby exert an impact on touch event dispatch. For details about the impact, see [TouchTestStrategy](#touchteststrategy). > **NOTE** > -> - This feature is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. +> - The initial APIs of this module are supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. > > - With use of **onChildTouchTest**, the **onClick**, rotation, and pinch gesture events may receive no response due to the touch target not being hit. @@ -12,7 +12,7 @@ When handling a touch event, ArkUI performs a touch test on the touch point and onChildTouchTest(event: (value: Array<TouchTestInfo>) => TouchResult): T -Called to specify how to perform the touch test on the children of this component. +Allows the current component to customize the hit test and control child component behavior during the test by setting a callback. **Atomic service API**: This API can be used in atomic services since API version 12. @@ -22,7 +22,7 @@ Called to specify how to perform the touch test on the children of this componen | Name| Type | Mandatory| Description | | ------ | ------------------------------------------ | ---- | ---------------------- | -| value | Array<[TouchTestInfo>](#touchtestinfo) | Yes | Array of child components.| +| value | Array<[TouchTestInfo>](#touchtestinfo) | Yes | Array of child node information.| **Return value** @@ -32,7 +32,7 @@ Called to specify how to perform the touch test on the children of this componen >**NOTE** > ->The array of child components contains only components for which **id** is set. +>The array of child node information only includes information about named nodes, that is, nodes for which the **id** attribute is explicitly set. ## TouchTestInfo @@ -76,24 +76,25 @@ Enumerates the event dispatch strategies. | Name | Description | | ------------| ----------------------------------------- | -| DEFAULT | Custom dispatch has no effect; the system distributes events based on the hit status of the current node.| -| FORWARD_COMPETITION | The specified event is forwarded to a particular child node, and the system determines whether to distribute the event to other sibling nodes.| -| FORWARD | The specified event is forwarded to a particular child node, and the system no longer distributes the event to other sibling nodes.| +| DEFAULT | Custom dispatch has no effect; the system dispatches events based on the hit status of the current node.| +| FORWARD_COMPETITION | The event is dispatched to a specified child node, and the system determines whether to dispatch events to other sibling nodes.| +| FORWARD | The event is dispatched to a specified child node, and the system will not dispatch events to other sibling nodes.| ## Example ### Example 1: Setting the Event Dispatch Strategy to FORWARD_COMPETITION -In this example, dragging the blank area below the list allows the list to scroll, and clicking the button will trigger its **onClick** event. +In this example, clicking and dragging in the blank area below the **List** component causes the **List** component to scroll. The **Button** component still responds to clicks. ```ts // xxx.ets -import { promptAction } from '@kit.ArkUI'; +import { PromptAction } from '@kit.ArkUI'; @Entry @Component struct ListExample { private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] + promptAction: PromptAction = this.getUIContext().getPromptAction(); @State text: string = 'Button' build() { @@ -134,7 +135,7 @@ struct ListExample { .margin({ top: 80 }) .onClick(() => { this.text = 'click the button' - promptAction.showToast({ message: 'you click the button.', duration: 3000 }) + this.promptAction.showToast({ message: 'you click the button.', duration: 3000 }) }) } .width('100%') @@ -158,16 +159,17 @@ struct ListExample { ### Example 2: Setting the Event Dispatch Strategy to FORWARD -In this example, dragging the blank area below the list allows the list to scroll, but clicking the button will not trigger its **onClick** event. +In this example, clicking and dragging in the blank area below the **List** component causes the **List** component to scroll. The **Button** component does not respond to clicks. ```ts // xxx.ets -import { promptAction } from '@kit.ArkUI'; +import { PromptAction } from '@kit.ArkUI'; @Entry @Component struct ListExample { private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] + promptAction: PromptAction = this.getUIContext().getPromptAction(); @State text: string = 'Button' build() { @@ -208,7 +210,7 @@ struct ListExample { .margin({ top: 80 }) .onClick(() => { this.text = 'click the button' - promptAction.showToast({ message: 'you click the button.', duration: 3000 }) + this.promptAction.showToast({ message: 'you click the button.', duration: 3000 }) }) } .width('100%') @@ -232,16 +234,17 @@ struct ListExample { ### Example 3: Setting the Event Dispatch Strategy to DEFAULT -In this example, dragging the blank area below the list will not scroll the list, and clicking the button will trigger its **onClick** event. +In this example, clicking and dragging in the blank area below the **List** component does not cause the **List** component to scroll. The **Button** component responds to clicks. ```ts // xxx.ets -import { promptAction } from '@kit.ArkUI'; +import { PromptAction } from '@kit.ArkUI'; @Entry @Component struct ListExample { private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] + promptAction: PromptAction = this.getUIContext().getPromptAction(); @State text: string = 'Button' build() { @@ -282,7 +285,7 @@ struct ListExample { .margin({ top: 80 }) .onClick(() => { this.text = 'click the button' - promptAction.showToast({ message: 'you click the button.', duration: 3000 }) + this.promptAction.showToast({ message: 'you click the button.', duration: 3000 }) }) } .width('100%') diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-outline.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-outline.md index 5eb0fa489a337cd2911d39e0b9f599b66b628b24..df9e23f8695dbdb045b750745e7c82e0ce80157e 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-outline.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-outline.md @@ -6,11 +6,11 @@ You can set outline attributes for components. Drawn outside the component, the > **NOTE** > -> This feature is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. ## outline -outline(value: OutlineOptions) +outline(value: OutlineOptions): T Sets the outline attributes in one declaration. @@ -26,9 +26,15 @@ Sets the outline attributes in one declaration. | ------ | ----------------------------------------- | ---- | ------------ | | value | [OutlineOptions](#outlineoptions) | Yes | Outline attributes.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## outline18+ -outline(options: Optional\) +outline(options: Optional\): T Sets the outline attributes in one declaration. Compared to [outline](#outline), this API supports the **undefined** type for the **options** parameter. @@ -44,6 +50,12 @@ Sets the outline attributes in one declaration. Compared to [outline](#outline), | ------ | ----------------------------------------- | ---- | ---- | | options | Optional\<[OutlineOptions](#outlineoptions)> | Yes | Outline attributes.
If **options** is **undefined**, the component reverts to its original style with no outline. | +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## OutlineStyle11+ Outline attributes. @@ -62,7 +74,7 @@ Outline attributes. ## outlineStyle -outlineStyle(value: OutlineStyle | EdgeOutlineStyles) +outlineStyle(value: OutlineStyle | EdgeOutlineStyles): T Sets the style of the outline. @@ -78,9 +90,15 @@ Sets the style of the outline. | ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | | value | [OutlineStyle](#outlinestyle11) \| [EdgeOutlineStyles](#edgeoutlinestyles) | Yes | Outline style.
Default value: **OutlineStyle.SOLID**| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## outlineStyle18+ -outlineStyle(style: Optional\) +outlineStyle(style: Optional\): T Sets the style of the outline. Compared to [outlineStyle](#outlinestyle), this API supports the **undefined** type for the **style** parameter. @@ -96,9 +114,15 @@ Sets the style of the outline. Compared to [outlineStyle](#outlinestyle), this A | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | style | Optional\<[OutlineStyle](#outlinestyle11) \| [EdgeOutlineStyles](#edgeoutlinestyles)> | Yes | Outline style.
Default value: **OutlineStyle.SOLID**
If **style** is **undefined**, the component reverts to its original style with no outline.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## outlineWidth -outlineWidth(value: Dimension | EdgeOutlineWidths) +outlineWidth(value: Dimension | EdgeOutlineWidths): T Sets the thickness of the outline. @@ -114,9 +138,15 @@ Sets the thickness of the outline. | ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | | value | [Dimension](ts-types.md#dimension10) \| [EdgeOutlineWidths](#edgeoutlinewidths) | Yes | Outline thickness. Percentage values are not supported.
Default value: **0**| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## outlineWidth18+ -outlineWidth(width: Optional\) +outlineWidth(width: Optional\): T Sets the thickness of the outline. Compared to [[outlineWidth](#outlinewidth), this API supports the **undefined** type for the **width** parameter. @@ -132,9 +162,15 @@ Sets the thickness of the outline. Compared to [[outlineWidth](#outlinewidth), t | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | width | Optional\<[Dimension](ts-types.md#dimension10) \| [EdgeOutlineWidths](#edgeoutlinewidths)> | Yes | Outline thickness. Percentage values are not supported.
Default value: **0**
If **width** is **undefined**, the component reverts to its original style with no outline width.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## outlineColor -outlineColor(value: ResourceColor | EdgeColors) +outlineColor(value: ResourceColor | EdgeColors): T Sets the color of the outline. @@ -148,11 +184,17 @@ Sets the color of the outline. | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------ | -| value | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors) | Yes | Outline color.
Default value: **Color.Black**| +| value | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors) | Yes | Outline color.
Default value: **Color.Black**.| + +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| ## outlineColor18+ -outlineColor(color: Optional\) +outlineColor(color: Optional\): T Sets the color of the outline. Compared to [outlineColor](#outlinecolor), this API supports the **undefined** type for the **color** parameter. @@ -166,11 +208,17 @@ Sets the color of the outline. Compared to [outlineColor](#outlinecolor), this A | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| color | Optional\<[ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors)> | Yes | Outline color.
Default value: **Color.Black**
If **color** is **undefined**, the component reverts to its original style with the outline color of **Color.Black**.| +| color | Optional\<[ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors)> | Yes | Outline color.
Default value: **Color.Black**.
If **color** is **undefined**, the component reverts to its original style with the outline color of **Color.Black**.| + +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| ## outlineRadius -outlineRadius(value: Dimension | OutlineRadiuses) +outlineRadius(value: Dimension | OutlineRadiuses): T Sets the radius of the outline corners. @@ -186,9 +234,15 @@ Sets the radius of the outline corners. | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | value | [Dimension](ts-types.md#dimension10) \| [OutlineRadiuses](#outlineradiuses) | Yes | Radius of the outline corners. Percentage values are not supported.
Default value: **0**
Maximum effective value: Component width/2 + outlineWidth or component height/2 + outlineWidth| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## outlineRadius18+ -outlineRadius(radius: Optional\) +outlineRadius(radius: Optional\): T Sets the radius of the outline corners. Compared to [outlineRadius](#outlineradius), this API supports the **undefined** type for the **radius** parameter. @@ -204,6 +258,12 @@ Sets the radius of the outline corners. Compared to [outlineRadius](#outlineradi | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | radius | Optional\<[Dimension](ts-types.md#dimension10) \| [OutlineRadiuses](#outlineradiuses)> | Yes | Radius of the outline corners. Percentage values are not supported.
Default value: **0**
Maximum effective value: Component width/2 + outlineWidth or component height/2 + outlineWidth
If **radius** is **undefined**, the component reverts to its original style with the outline corner radius of 0.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## OutlineOptions **Atomic service API**: This API can be used in atomic services since API version 12. @@ -212,8 +272,8 @@ Sets the radius of the outline corners. Compared to [outlineRadius](#outlineradi | Name | Type |Mandatory | Description | | ------ | ----------------------|-------------------------------------- | ------------------------------------------------------------ | -| width | [Dimension](ts-types.md#dimension10) \| [EdgeOutlineWidths](#edgeoutlinewidths) | No| Outline thickness. Percentage values are not supported.
Default value: **0**| -| color | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors) \| [LocalizedEdgeColors](#localizededgecolors12)12+ |No| Outline color.
Default value: **Color.Black** | +| width | [Dimension](ts-types.md#dimension10) \| [EdgeOutlineWidths](#edgeoutlinewidths) | No| Outline thickness. Percentage values are not supported.
Default value: **0**.
**width** must be set to display the outline effect.| +| color | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors) \| [LocalizedEdgeColors](#localizededgecolors12)12+ |No| Outline color.
Default value: **Color.Black**. | | radius | [Dimension](ts-types.md#dimension10) \| [OutlineRadiuses](#outlineradiuses) | No| Radius of the outline corners. Percentage values are not supported.
Default value: **0**
Maximum effective value: Component width/2 + outlineWidth or component height/2 + outlineWidth| | style | [OutlineStyle](#outlinestyle11) \| [EdgeOutlineStyles](#edgeoutlinestyles) |No| Outline style.
Default value: **OutlineStyle.SOLID** | @@ -259,8 +319,8 @@ To reference this object, at least one parameter must be passed. | Name | Type | Mandatory | Description | | ------ | ---------------------------------------- | ---- | ------- | -| start | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the left outline.
For right-to-left scripts, this indicates the color of the right outline.| -| end | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the right outline.
For right-to-left scripts, this indicates the color of the left outline.| +| start | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the left outline.
For left-to-right scripts, this indicates the color of the right outline.| +| end | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the right outline.
For left-to-right scripts, this indicates the color of the left outline.| | top | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the top outline.| | bottom | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the bottom outline.| diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-pixelRound.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-pixelRound.md index fdb6c08153cd3d43f933cc11aae5df4e2c18e4c6..d0d9e169e9978762a8ed1617b8dc62f1cf8f5b07 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-pixelRound.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-pixelRound.md @@ -8,7 +8,7 @@ Component-level pixel rounding allows you to enable or disable system pixel roun ## pixelRound -pixelRound(value: PixelRoundPolicy) +pixelRound(value: PixelRoundPolicy): T Sets the pixel rounding policy for the current component in the specified direction. If a direction is not set, the pixels are rounded to the nearest whole number in that direction. @@ -16,11 +16,11 @@ Sets the pixel rounding policy for the current component in the specified direct > > In API version 11, this API uses half-pixel alignment (that is, 0\-0.25 rounds to 0, 0.25\-0.75 rounds to 0.5, 0.75\-1.0 rounds to 1). Since API version 12, this API rounds pixels to the nearest integers and allows you to disable pixel rounding for individual components. -In normal calculations, the top and bottom directions correspond to the component height, and the left and right directions (the starting direction of mirroring is called left) and width correspond to each other. For ease of description, these two sets of directions are referred to as upper left and lower right. +In normal calculations, the vertical direction (top and bottom) correspond to the component height, and the horizontal direction (the starting direction of mirroring is considered "left") correspond to the component width. For ease of description, these two sets of directions are referred to as top-left and bottom-right. -- Calculate the upper left corner coordinates of the current component: offset of the upper left corner relative to the parent container. -- Calculate the lower right corner coordinates of the current component: offset of the upper left corner relative to the parent container plus the size of the component itself. -- Recalculate the size of the current component: lower right corner rounded value minus the upper left corner rounded value. +- Calculate the top-left coordinates of the current component: offset of the top-left corner relative to the parent container. +- Calculate the bottom-right coordinates of the current component: offset of the top-left corner relative to the parent container plus the size of the component itself. +- Recalculate the size of the current component: bottom-right corner rounded value minus the top-left corner rounded value. **Widget capability**: This API can be used in ArkTS widgets since API version 11. @@ -34,6 +34,12 @@ In normal calculations, the top and bottom directions correspond to the componen | ------ | ------ | ---- | ------------------------------------------------------------ | | value | [PixelRoundPolicy](ts-types.md#pixelroundpolicy11) | Yes| Rounding policy for the bounds of the component.
**NOTE**
This attribute is applicable in scenarios where artifacts occur due to floating-point drawing. The rounding result is related not only to the component's width and height but also to its position. Even if the component's width and height are set to be the same, due to different floating-point positions described, the final width and height of the component may also be different after rounding.| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + ## FAQs | Issue | Solution | diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-reuse-id.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-reuse-id.md index 56c16237a3b765349664995f6eb2811e520ccaf9..e3f088e9a9b9b239a9a256047d7025419d08ec59 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-reuse-id.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-reuse-id.md @@ -13,6 +13,10 @@ reuseId(id: string) Sets the ID that identifies the reuse group of the component. +> **NOTE** +> +> Set **reuseId** flexibly based on different scenarios to achieve optimal reuse effects. For best practices, see [Using reuseId to Mark Components with Layout Changes](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-component-reuse#section1239555818211). + **Atomic service API**: This API can be used in atomic services since API version 11. **System capability**: SystemCapability.ArkUI.ArkUI.Full diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md index 175ae6991ddb661dcb2b815bb715dbaca679ca39..3ae4278df5a7a19e924db225f4a03c2269159310 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-sharp-clipping.md @@ -4,11 +4,11 @@ Shape clipping changes the visible portion of a component through clipping or ma > **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 initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. ## clip12+ -clip(value: boolean) +clip(value: boolean): T Sets whether to clip the areas of child components that extend beyond this component's boundaries, that is, whether to perform clipping based on the edge contour of the parent container @@ -24,9 +24,15 @@ Sets whether to clip the areas of child components that extend beyond this compo | ------ | ------- | ---- | ------------------------------------------------------------ | | value | boolean | Yes | Whether to perform clipping based on the edge contour of the parent container.
Default value: **false**
**true**: Perform clipping.
**false**: Do not perform clipping.
**NOTE**
If this parameter is set to **true**, child components exceeding the current component's bounds will not respond to bound gesture events.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## clip18+ -clip(clip: Optional\) +clip(clip: Optional\): T Sets whether to clip the areas of child components that extend beyond this component's boundaries, that is, whether to perform clipping based on the edge contour of the parent container Compared to [clip12+](#clip12), this API supports the **undefined** type for the **clip** parameter. @@ -42,9 +48,15 @@ Sets whether to clip the areas of child components that extend beyond this compo | ------ | ------------------ | ------------------------------------------------------------ | ---- | | clip | Optional\ | Yes| Whether to perform clipping based on the edge contour of the parent container.
Default value: **false**
**NOTE**
If this parameter is set to **true**, child components exceeding the current component's bounds will not respond to bound gesture events.
If **clip** is set to **undefined**, clipping is disabled, and child components are not clipped. | +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## clip(deprecated) -clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute) +clip(value: boolean | CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute): T Sets whether to clip this component based on the given shape. @@ -62,11 +74,25 @@ Sets whether to clip this component based on the given shape. | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | value | boolean \| [CircleAttribute](ts-drawing-components-circle.md) \| [EllipseAttribute](ts-drawing-components-ellipse.md) \| [PathAttribute](ts-drawing-components-path.md) \| [RectAttribute](ts-drawing-components-rect.md) | Yes | Clip mode. If the value is a shape attribute, the component is clipped based on the specified shape. If the value is of the Boolean type, it specifies whether to clip the component based on the boundaries of the parent container.
Default value: **false**
**NOTE**
If the value is a shape attribute, the clipped area can still respond to bound gesture events. If the value is of the Boolean type, the clipped area will not respond to bound gesture events.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## clipShape12+ -clipShape(value: CircleShape | EllipseShape | PathShape | RectShape) +clipShape(value: CircleShape | EllipseShape | PathShape | RectShape): T -Clips this component based on the given shape. +Clips this component according to the specified shape (which may include position information). + +> **NOTE** +> +> Different shapes support different ranges of attributes. A path is one type of shape, along with others like ellipses and rectangles. +> +> Path shapes do not support setting width and height attributes. For details about the supported attributes, see the specific shape documentation. +> +> The [fill](../js-apis-arkui-shape.md#fill) attribute of shapes has no effect on the **clipShape** API. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -78,13 +104,27 @@ Clips this component based on the given shape. | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| value | [CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape) | Yes | Shape that the component to be clipped into.
**NOTE**
The clipped area remains responsive to bound gesture events.| +| value | [CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape) | Yes | Shape (which may include position information) to clip the current component.
**NOTE**
The clipped area remains responsive to bound gesture events.| + +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| ## clipShape18+ -clipShape(shape: Optional\) +clipShape(shape: Optional\): T + +Clips this component according to the specified shape (which may include position information). Compared to [clipShape12+](#clipshape12), this API supports the **undefined** type for the **shape** parameter. -Sets whether to clip this component based on the given shape. Compared to [clipShape12+](#clipshape12), this API supports the **undefined** type for the **shape** parameter. +> **NOTE** +> +> Different shapes support different ranges of attributes. A path is one type of shape, along with others like ellipses and rectangles. +> +> Path shapes do not support setting width and height attributes. For details about the supported attributes, see the specific shape documentation. +> +> The [fill](../js-apis-arkui-shape.md#fill) attribute of shapes has no effect on the **clipShape** API. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -96,11 +136,17 @@ Sets whether to clip this component based on the given shape. Compared to [clipS | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| shape | Optional\<[CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape)> | Yes | Shape that the component to be clipped into.
**NOTE**
The clipped area remains responsive to bound gesture events.
If **shape** is set to **undefined**, the previous value is retained.| +| shape | Optional\<[CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape)> | Yes | Shape (which may include position information) to clip the current component.
**NOTE**
The clipped area remains responsive to bound gesture events.
If **shape** is set to **undefined**, the previous value is retained.| + +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| ## mask12+ -mask(value: ProgressMask) +mask(value: ProgressMask): T Adds a mask to the component to indicate the progress. @@ -114,9 +160,15 @@ Adds a mask to the component to indicate the progress. | ------ | ------------------------------- | ---- | ---------------------------------------------------- | | value | [ProgressMask](#progressmask10) | Yes | Mask to add to the component, which allows for dynamic adjustment of progress, maximum value, and color settings.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## mask18+ -mask(mask: Optional\) +mask(mask: Optional\): T Adds a mask to the component to indicate the progress. Compared to [mask12+](#mask12), this API supports the **undefined** type for the **mask** parameter. @@ -130,9 +182,15 @@ Adds a mask to the component to indicate the progress. Compared to [mask12+ | ------ | ------------------------------------------------------------ | ---- | -------------------------------- | | mask | Optional\<[ProgressMask](#progressmask10)> | Yes| Mask to add to the component, which allows for dynamic adjustment of progress, maximum value, and color settings.
If **mask** is set to **undefined**, the component to revert to its original effect without the mask to indicate the progress. | +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## mask(deprecated) -mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask) +mask(value: CircleAttribute | EllipseAttribute | PathAttribute | RectAttribute | ProgressMask): T Adds a mask of the specified shape to the component. @@ -150,9 +208,15 @@ Adds a mask of the specified shape to the component. | ------ | ------------------------------------------------------------ | ---- | -------------------------------- | | value | [CircleAttribute](ts-drawing-components-circle.md) \| [EllipseAttribute](ts-drawing-components-ellipse.md) \| [PathAttribute](ts-drawing-components-path.md) \| [RectAttribute](ts-drawing-components-rect.md) \| [ProgressMask](#progressmask10)10+ | Yes | Mask of the specified shape to add to the component.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## maskShape12+ -maskShape(value: CircleShape | EllipseShape | PathShape | RectShape) +maskShape(value: CircleShape | EllipseShape | PathShape | RectShape): T Adds a mask of the specified shape to the component. @@ -168,9 +232,15 @@ Adds a mask of the specified shape to the component. | ------ | ------------------------------------------------------------ | ---- | -------------------------------- | | value | [CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape) | Yes | Mask of the specified shape to add to the component.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## maskShape18+ -maskShape(shape: Optional\) +maskShape(shape: Optional\): T Adds a mask of the specified shape to the component. Compared to [maskShape12+](#maskshape12), this API supports the **undefined** type for the **shape** parameter. @@ -186,6 +256,12 @@ Adds a mask of the specified shape to the component. Compared to [maskShape | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | shape | Optional\<[CircleShape](../js-apis-arkui-shape.md#circleshape) \| [EllipseShape](../js-apis-arkui-shape.md#ellipseshape) \| [PathShape](../js-apis-arkui-shape.md#pathshape) \| [RectShape](../js-apis-arkui-shape.md#rectshape)> | Yes | Mask of the specified shape to add to the component.
If **shape** is set to **undefined**, the previous value is retained.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## ProgressMask10+ Implements a **ProgressMask** object to set the progress, maximum value, and color of the mask. @@ -267,7 +343,7 @@ Sets whether to enable the breathing animation when the progress indicator is fu ```ts // xxx.ets -import { CircleShape, RectShape } from '@kit.ArkUI' +import { CircleShape, RectShape } from '@kit.ArkUI'; @Entry @Component @@ -287,12 +363,12 @@ struct ClipAndMaskExample { .width('500px').height('280px') Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC') - // Add a 500 px x 280 px square mask to the image. + // Add a 500x280 px square mask to the image. Image($r('app.media.testImg')) .maskShape(new RectShape({ width: '500px', height: '280px' }).fill(Color.Gray)) .width('500px').height('280px') - // Add a 280 px x 280 px circular mask to the image. + // Add a 280x280 px circular mask to the image. Image($r('app.media.testImg')) .maskShape(new CircleShape({ width: '280px', height: '280px' }).fill(Color.Gray)) .width('500px').height('280px') @@ -311,7 +387,7 @@ struct ClipAndMaskExample { @Entry @Component struct ProgressMaskExample { - @State progressflag1: boolean = true; + @State progressFlag1: boolean = true; @State color: Color = 0x01006CDE; @State value: number = 10.0; @State enableBreathingAnimation: boolean = false; @@ -320,13 +396,13 @@ struct ProgressMaskExample { build() { Column({ space: 15 }) { Text('progress mask').fontSize(12).width('75%').fontColor('#DCDCDC') - // Add a 280 px x 280 px progress mask to the image. + // Add a 280x280 px progress mask to the image. Image($r('app.media.testImg')) .width('500px').height('280px') .mask(this.progress) .animation({ duration: 2000, // Animation duration. - .curve(Curve.Linear) // Animation curve. + curve: Curve.Linear, // Animation curve. delay: 0, // Animation delay. iterations: 1, // Number of playback times. playMode: PlayMode.Normal // Animation playback mode. @@ -342,18 +418,18 @@ struct ProgressMaskExample { // Update the color of the progress mask. Button('updateColor') .onClick((event?: ClickEvent) => { - if (this.progressflag1) { + if (this.progressFlag1) { this.progress.updateColor(0x9fff0000); } else { this.progress.updateColor(0x9f0000ff); } - this.progressflag1 = !this.progressflag1 + this.progressFlag1 = !this.progressFlag1 }).width(200).height(50).margin(20) // Enable or disable the breathing animation. Button('enableBreathingAnimation:' + this.enableBreathingAnimation) .onClick((event?: ClickEvent) => { - this.enableBreathingAnimation = !this.enableBreathingAnimation + this.enableBreathingAnimation = !this.enableBreathingAnimation; this.progress.enableBreathingAnimation(this.enableBreathingAnimation); }).width(200).height(50).margin(20) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md index 6a26b01e5467b96b7b797e426c79e3b4f0636e3a..6d8932d268cb9115cf472cbd6f9f27f73e9392c9 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md @@ -1,14 +1,16 @@ # Size -The size attributes set the width, height, and margin of a component. +The size attributes set the width, height, and margins of a component. > **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 initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. +> +> When a component's size is set by percentage, the actual size is calculated based on the size of the nearest ancestor node with a fixed size. ## width -width(value: Length) +width(value: Length): T Sets the width of the component. By default, the width required to fully hold the component content is used. If the width of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. @@ -26,6 +28,12 @@ Since API version 10, this API supports the calc calculation feature. | ----- | ---------------------------- | ---- | ------------------- | | value | [Length](ts-types.md#length) | Yes | Width of the component to set.
Unit: vp| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + > **NOTE** > > - In the [TextInput](./ts-basic-components-textinput.md) component, setting **width** to **auto** means that the width adapts to the width of the text content. @@ -34,7 +42,7 @@ Since API version 10, this API supports the calc calculation feature. ## height -height(value: Length) +height(value: Length): T Sets the height of the component. By default, the height required to fully hold the component content is used. If the height of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. @@ -52,13 +60,19 @@ Since API version 10, this API supports the calc calculation feature. | ----- | ---------------------------- | ---- | ------------------- | | value | [Length](ts-types.md#length) | Yes | Height of the component to set.
Unit: vp| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + > **NOTE** > > In the [Row](./ts-container-row.md), [Column](./ts-container-column.md), and [RelativeContainer](./ts-container-relativecontainer.md) components, setting **width** and **height** to **auto** means that the size adapts to the size of their child components. ## width15+ -width(widthValue: Length | LayoutPolicy) +width(widthValue: Length | LayoutPolicy): T Sets the width of the component or its horizontal layout policy. By default, the component uses the width required for its content. If the width of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. @@ -72,11 +86,17 @@ Sets the width of the component or its horizontal layout policy. By default, the | Name | Type | Mandatory | Description | | ----- | ---------------------------- | ---- | ------------------- | -| widthValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Width of the component to set.
Unit: vp| +| widthValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Width of the component to set.
Unit: vp
The [Flex](./ts-container-flex.md), [Row](./ts-container-row.md), [Column](./ts-container-column.md) and [Stack](./ts-container-stack.md) components support all parameters in [LayoutPolicy](ts-types.md#layoutpolicy15).
The [RelativeContainer](./ts-container-relativecontainer.md), [FolderStack](./ts-container-folderstack.md), [Divider](./ts-basic-components-divider.md), and [Blank](./ts-basic-components-blank.md) components support the **matchParent** parameter in [LayoutPolicy](ts-types.md#layoutpolicy15).| + +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| ## height15+ -height(heightValue: Length | LayoutPolicy) +height(heightValue: Length | LayoutPolicy): T Sets the height of the component or its vertical layout policy. By default, the component uses the height required for its content. If the height of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. @@ -90,17 +110,19 @@ Sets the height of the component or its vertical layout policy. By default, the | Name | Type | Mandatory | Description | | ----- | ---------------------------- | ---- | ------------------- | -| heightValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Height of the component to set.
Unit: vp| +| heightValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Height of the component to set.
Unit: vp
The [Flex](./ts-container-flex.md), [Row](./ts-container-row.md), [Column](./ts-container-column.md) and [Stack](./ts-container-stack.md) components support all parameters in [LayoutPolicy](ts-types.md#layoutpolicy15).
The [RelativeContainer](./ts-container-relativecontainer.md), [FolderStack](./ts-container-folderstack.md), [Divider](./ts-basic-components-divider.md), and [Blank](./ts-basic-components-blank.md) components support the **matchParent** parameter in [LayoutPolicy](ts-types.md#layoutpolicy15).
The [GridRow](./ts-container-gridrow.md) and [GridCol](./ts-container-gridcol.md) components support the **fixAtIdealSize** parameter in [LayoutPolicy](ts-types.md#layoutpolicy15).| -> **NOTE** -> -> In the [Row](./ts-container-row.md) and [Column](./ts-container-column.md) components, **width** and **height** can be set to parameters of the [LayoutPolicy](ts-types.md#layoutpolicy15) type. +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| ## size -size(value: SizeOptions) +size(value: SizeOptions): T -Sets the size of the component. +Sets the width and height of the component. Since API version 10, this API supports the calc calculation feature. @@ -116,9 +138,15 @@ Since API version 10, this API supports the calc calculation feature. | ----- | ------------------------------- | ---- | ----------------- | | value | [SizeOptions](#sizeoptions) | Yes | Size of the component to set.
Unit: vp| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + ## padding -padding(value: Padding | Length | LocalizedPadding) +padding(value: Padding | Length | LocalizedPadding): T Sets the padding of the component. @@ -136,9 +164,15 @@ Since API version 10, this API supports the calc calculation feature. | ----- | ---------------------------------------- | ---- | ---------------------------------------- | | value | [Padding](ts-types.md#padding) \| [Length](ts-types.md#length) \| [LocalizedPadding](ts-types.md#localizedpadding12)12+| Yes | Padding of the component to set.
When the parameter is of the **Length** type, the four paddings take effect.
Default value: **0**
Unit: vp
When **padding** is set to a percentage, the width of the parent container is used as the basic value.| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + ## margin -margin(value: Margin | Length | LocalizedMargin) +margin(value: Margin | Length | LocalizedMargin): T Sets the margin of the component. @@ -156,11 +190,17 @@ Since API version 10, this API supports the calc calculation feature. | ------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | | value | [Margin](ts-types.md#margin) \| [Length](ts-types.md#length) \| [LocalizedMargin](ts-types.md#localizedmargin12)12+ | Yes| Margin of the component to set.
When the parameter is of the **Length** type, the four margins take effect.
Default value: **0**
Unit: vp
When **margin** is set to a percentage, the width of the parent container is used as the basic value. When child components are laid out along the cross axis of the [Row](./ts-container-row.md), [Column](./ts-container-column.md), or [Flex](./ts-container-flex.md) container, the cross axis size of the child components and the margins add up to the total size of the container.
For example, if the width of the **Column** container is 100, the width of the child component is 50, the left margin is 10, and the right margin is 20, then the actual horizontal offset of the child component is 10.| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + ## safeAreaPadding14+ -safeAreaPadding(value: Padding | LengthMetrics | LocalizedPadding) +safeAreaPadding(paddingValue: Padding | LengthMetrics | LocalizedPadding): T -Sets the safe area padding. It enables a container to add a component-level safe area for child components to expand into. +Sets the safe area padding. This allows the container to add a component-level safe area for its child components to extend into. This attribute can be dynamically set using [attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier). **Widget capability**: This API can be used in ArkTS widgets since API version 14. @@ -174,11 +214,23 @@ Sets the safe area padding. It enables a container to add a component-level safe | ----- | ---------------------------------------- | ---- | ---------------------------------------- | | paddingValue | [Padding](ts-types.md#padding) \| [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) \| [LocalizedPadding](ts-types.md#localizedpadding12)| Yes | Safe area padding.
Default value: **0**
Unit: vp| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + +> **NOTE** +> +> When parent and ancestor containers define component-level safe areas, child components can detect and utilize these areas, referred to as Accumulated Safe Area Expansion (SAE), which represents the maximum extendable length in each direction. When ancestor containers have contiguous **safeAreaPadding** (undivided by margin, border, or padding), SAE accumulates recursively outward until no adjacent outer **safeAreaPadding** exists or the recursion extends beyond the page container. System-level avoid areas (status bar, navigation bar, notch areas, and more**) are treated as the page container's inherent safeAreaPadding** and participate in SAE calculations. For details about the avoid areas, see [expandSafeArea](./ts-universal-attributes-expand-safe-area.md). +> +>These component-level safe areas can be leveraged by combining with other attributes. For example, setting the [ignoreLayoutSafeArea](./ts-universal-attributes-expand-safe-area.md#ignorelayoutsafearea20) attribute on a child component allows it to extend its layout into the SAE region. + ## layoutWeight -layoutWeight(value: number | string) +layoutWeight(value: number | string): T -Sets the weight of the component during layout. A component with this attribute is allocated space along the main axis of its parent container ([Row](./ts-container-row.md), [Column](./ts-container-column.md), or [Flex](./ts-container-flex.md)) based on its specified weight. +Sets the weight of the component during layout. A component with this attribute set is allocated space along the main axis of its parent container ([Row](./ts-container-row.md), [Column](./ts-container-column.md), or [Flex](./ts-container-flex.md)) based on its specified weight. **Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. @@ -190,11 +242,17 @@ Sets the weight of the component during layout. A component with this attribute | Name | Type | Mandatory | Description | | ----- | -------------------------- | ------- | ---------------------------------------- | -| value | number \| string | Yes| Weight of the component during layout. When the size of the parent container is determined, the container space is allocated along the main axis among the component and its sibling components based on their respective weights, ignoring their own size settings.
Default value: **0**
**NOTE**
This parameter is only effective in [Row](./ts-container-row.md), [Column](./ts-container-column.md), and [Flex](./ts-container-flex.md) container components.
The value can be a number greater than or equal to 0 or a string that can be converted to a number.
If any child component in a container has the **layoutWeight** attribute set to a value greater than 0, then child components will no longer be laid out based on **flexShrink** and **flexGrow**.| +| value | number \| string | Yes| Layout weight of the component.
When the parent container size is determined:
Elements without **layoutWeight** or with **layoutWeight** set to **0** take precedence in occupying space.
The remaining space on the main axis is then allocated proportionally among elements with a **layoutWeight** value greater than 0, ignoring their own size settings.
Default value: **0**
**NOTE**
This parameter is only effective in [Row](./ts-container-row.md), [Column](./ts-container-column.md), and [Flex](./ts-container-flex.md) container components.
The value can be a number greater than or equal to 0 or a string that can be converted to a number.
If any child component in a container has the **layoutWeight** attribute set to a value greater than 0, then child components will no longer be laid out based on **flexShrink** and **flexGrow**.| + +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| ## constraintSize -constraintSize(value: ConstraintSizeOptions) +constraintSize(value: ConstraintSizeOptions): T Sets the constraint size of the component, which is used to limit the size range during component layout. @@ -212,6 +270,12 @@ Since API version 10, this API supports the calc calculation feature. | ----- | ---------------------------------------- | ---- | ---------------------------------------- | | value | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | Yes | Constraint size of the component to set. **constraintSize** takes precedence over **width** and **height**. See **Impact of constraintSize on width/height**.
Default value:
{
minWidth: 0,
maxWidth: Infinity,
minHeight: 0,
maxHeight: Infinity
}
Unit: vp
| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + **Impact of constraintSize(minWidth/maxWidth/minHeight/maxHeight) on width/height** | Default Value | Result | @@ -228,6 +292,8 @@ Since API version 10, this API supports the calc calculation feature. ## SizeOptions +Describes the width and height of a component during layout. + **Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -239,6 +305,8 @@ Since API version 10, this API supports the calc calculation feature. ## ConstraintSizeOptions +Describes the size constraints of a component during layout. + **Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -258,7 +326,7 @@ Since API version 10, this API supports the calc calculation feature. ### Example 1: Setting the Component Width, Height, Margin, and Padding -This example demonstrates how to set the width, height, margin, and padding of a component. +This example demonstrates how to set the width, height, padding, and margin of a component. ```ts // xxx.ets @@ -271,7 +339,9 @@ struct SizeExample { Row() { // Width: 80; height: 80; margin: 20 (blue area); top, bottom, left, and right paddings: 5, 15, 10, and 20 (white area) Row() { - Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow) + Row() + .size({ width: '100%', height: '100%' }) + .backgroundColor(Color.Yellow) } .width(80) .height(80) @@ -280,12 +350,18 @@ struct SizeExample { .backgroundColor(Color.White) }.backgroundColor(Color.Blue) - Text('constraintSize').fontSize(12).fontColor(0xCCCCCC).width('90%') + Text('constraintSize') + .fontSize(12) + .fontColor(0xCCCCCC) + .width('90%') Text('this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text') .width('90%') .constraintSize({ maxWidth: 200 }) - Text('layoutWeight').fontSize(12).fontColor(0xCCCCCC).width('90%') + Text('layoutWeight') + .fontSize(12) + .fontColor(0xCCCCCC) + .width('90%') // When the container size is determined, the component occupies the space along the main axis based on the layout weight, and the component size setting is ignored. Row() { // Weight 1: The component occupies 1/3 of the remaining space along the main axis. @@ -299,9 +375,14 @@ struct SizeExample { // If layoutWeight is not set, the component is rendered based on its own size setting. Text('no layoutWeight') .size({ width: '30%', height: 110 }).backgroundColor(0xD2B48C).textAlign(TextAlign.Center) - }.size({ width: '90%', height: 140 }).backgroundColor(0xAFEEEE) + } + .size({ width: '90%', height: 140 }) + .backgroundColor(0xAFEEEE) // calc calculation feature - Text('calc:').fontSize(12).fontColor(0xCCCCCC).width('90%') + Text('calc:') + .fontSize(12) + .fontColor(0xCCCCCC) + .width('90%') Text('calc test') .fontSize(50) .fontWeight(FontWeight.Bold) @@ -310,7 +391,9 @@ struct SizeExample { .margin('calc(25vp*2)') // If width or height is set to a percentage, the width or height of the parent container are used as the basic value. .size({ width: 'calc(90%)', height: 'calc(50vp + 10%)' }) - }.width('100%').margin({ top: 5 }) + } + .width('100%') + .margin({ top: 5 }) } } ``` @@ -319,7 +402,7 @@ struct SizeExample { ### Example 2: Using LocalizedPadding and LocalizedMargin Types -This example demonstrates how to use **LocalizedPadding** and **LocalizedMargin** types to set the padding and margin. +This example demonstrates how to use **LocalizedPadding** and **LocalizedMargin** types to define the **padding** and **margin** attributes. ```ts // xxx.ets @@ -330,11 +413,16 @@ import { LengthMetrics } from '@kit.ArkUI' struct SizeExample { build() { Column({ space: 10 }) { - Text('margin and padding:').fontSize(12).fontColor(0xCCCCCC).width('90%') + Text('margin and padding:') + .fontSize(12) + .fontColor(0xCCCCCC) + .width('90%') Row() { // Set the width to 80, height to 80, top, bottom, start, and end paddings to 40, 20, 30, and 10, respectively (blue area), and top, bottom, start, and end margins to 5, 15, 10, and 20, respectively (white area). Row() { - Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow) + Row() + .size({ width: '100%', height: '100%' }) + .backgroundColor(Color.Yellow) } .width(80) .height(80) @@ -351,8 +439,11 @@ struct SizeExample { end: LengthMetrics.vp(10) }) .backgroundColor(Color.White) - }.backgroundColor(Color.Blue) - }.width('100%').margin({ top: 5 }) + } + .backgroundColor(Color.Blue) + } + .width('100%') + .margin({ top: 5 }) } } ``` @@ -398,3 +489,106 @@ struct SafeAreaPaddingExample { ``` ![safeAreaPaddingExample](figures/safeAreaPaddingExample.png) + +### Example 4: Using attributeModifier to Dynamically Set a Safe Area + +This example demonstrates how to use **attributeModifier** to dynamically set a component-level safe area for a container. + +```ts +// xxx.ets +class MyModifier implements AttributeModifier { + applyNormalAttribute(instance: CommonAttribute): void { + instance.safeAreaPadding({ + left: 10, + top: 20, + right: 30, + bottom: 40 + }) + } +} + +@Entry +@Component +struct SafeAreaPaddingExample { + @State modifier: MyModifier = new MyModifier() + + build() { + Column() { + Column() { + Column() + .width("100%") + .height("100%") + .backgroundColor(Color.Pink) + } + .width(200) + .height(200) + .backgroundColor(Color.Yellow) + .borderWidth(10) + .padding(10) + .attributeModifier(this.modifier) + } + .height('100%') + .width('100%') + } +} +``` + +![safeAreaPaddingModifierExample](figures/safeAreaPaddingModifierExample.png) + +### Example 5: Setting the Layout Policy + +This example demonstrates how to set the layout policy for a container's size. + +```ts +// xxx.ets +@Entry +@Component +struct LayoutPolicyExample { + build() { + Column() { + Column() { + // When matchParent is effective, the current component's size is equal to its parent component's content area size (180x180 vp) and not subject to its own constraintSize (150x150 vp), so the current component's size is 180x180 vp. + Text("matchParent") + Flex() + .backgroundColor('rgb(0, 74, 175)') + .width(LayoutPolicy.matchParent) + .height(LayoutPolicy.matchParent) + .constraintSize({ maxWidth: 150, maxHeight: 150 }) + + // When wrapContent is effective, the current component's size is equal to its child component size (300x300 vp), but it cannot exceed the parent component's content size (180x180 vp) and is subject to its own constraintSize (250x250 vp), so the current component's size is 180x180 vp. + Text("wrapContent") + Row() { + Flex() + .width(300) + .height(300) + } + .backgroundColor('rgb(39, 135, 217)') + .width(LayoutPolicy.wrapContent) + .height(LayoutPolicy.wrapContent) + .constraintSize({ maxWidth: 250, maxHeight: 250 }) + + // When fixAtIdealSize is effective, the current component's size is equal to its child component size (300x300 vp), it can exceed the parent component's content size (180x180 vp) but is subject to its own constraintSize (250x250 vp), so the current component's size is 250x250 vp. + Text("fixAtIdealSize") + + Row() { + Flex() + .width(300) + .height(300) + } + .backgroundColor('rgb(240, 250, 255)') + .width(LayoutPolicy.fixAtIdealSize) + .height(LayoutPolicy.fixAtIdealSize) + .constraintSize({ maxWidth: 250, maxHeight: 250 }) + } + .width(200) + .height(200) + .padding(10) + } + .width("100%") + .height("100%") + } +} +``` + +![layoutPolicyExample](figures/layoutPolicy_demo.jpg) + \ No newline at end of file diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-tips.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-tips.md index 67cb87fd3a0aed6d757277962b6937ba4c0ec6d4..93b16a6f4a83a9885078813754c9db959c1dd516 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-tips.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-tips.md @@ -1,13 +1,15 @@ # Tooltip Control -You can bind a floating tooltip to a component. The tooltip is automatically displayed when the cursor hovers over the component and hidden when the cursor moves away. +You can bind a floating tooltip to a component. The tooltip automatically appears when a pointer hovers over the component and disappears when the pointer moves away. > **NOTE** > -> This API is supported since API version 18. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module is supported since API version 19. Updates will be marked with a superscript to indicate their earliest API version. +> +> Currently, this feature supports only external mouse devices, styluses, and touchpads as pointers. ## bindTips -bindTips(message: TipsMessageType, options?: TipsOptions) +bindTips(message: TipsMessageType, options?: TipsOptions): T Binds a tooltip to the component. @@ -15,7 +17,7 @@ Binds a tooltip to the component. > > If the **enable** attribute of the bound component is set to **false**, the tooltip can still be displayed. -**Atomic service API**: This API can be used in atomic services since API version 18. +**Atomic service API**: This API can be used in atomic services since API version 19. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -24,26 +26,31 @@ Binds a tooltip to the component. | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | message| [TipsMessageType](#tipsmessagetype) | Yes | Content of the tooltip message.| -| options | [TipsOptions](#tipsoptions) | No | Parameters of the tooltip.
Default value:
{
appearingTime:700,
disappearingTime:300,
appearingTimeWithContinuousOperation: 300,
disappearingTimeWithContinuousOperation:0, enableArrow:true,
arrowPointPosition:ArrowPointPosition.CENTER,
arrowWidth:16vp,arrowHeight:8vp
} | +| options | [TipsOptions](#tipsoptions) | No | Parameters of the tooltip.
Default value:
{
appearingTime: 700,
disappearingTime: 300,
appearingTimeWithContinuousOperation: 300,
disappearingTimeWithContinuousOperation: 0, enableArrow: true,
arrowPointPosition: ArrowPointPosition.CENTER,
arrowWidth: 16,arrowHeight: 8vp,
showAtAnchor: TipsAnchorType.TARGET
} | + +**Return value** + +|Type|Description| +|---|---| +|T|Current component.| ## TipsOptions Defines the parameters of the tooltip. -**Atomic service API**: This API can be used in atomic services since API version 18. - **System capability**: SystemCapability.ArkUI.ArkUI.Full | Name | Type | Mandatory| Description | | ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| appearingTime | number | No |Delay before the tooltip appears.
Default value: **700**.
Unit: ms.| -| disappearingTime | number | No | Delay before the tooltip disappears.
Default value: **300**.
Unit: ms.| -| appearingTimeWithContinuousOperation | number | No | Delay before the tooltip disappears when multiple tooltips are displayed consecutively.
Default value: **300**.
Unit: ms.| -| disappearingTimeWithContinuousOperation | number | No | Delay before the tooltip disappears when multiple tooltips are displayed consecutively.
Default value: **0**.
Unit: ms.| -| enableArrow | boolean | No | Whether to display the tooltip arrow.
Default value: **true**.
**NOTE**
If the available space on the screen is insufficient, the tooltip will cover part of the component and the arrow will not be displayed.| -| arrowPointPosition | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No | Position of the tooltip arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. These positions are within the parent component area and do not exceed its boundaries or cover rounded corners.
Default value: **ArrowPointPosition.CENTER**.| -| arrowWidth | [Dimension](ts-types.md#dimension10) | No | Width of the tooltip arrow. If the arrow width exceeds the length of the edge minus twice the size of the tooltip rounded corner, the arrow is not drawn.
Default value: **16**.
Unit: vp.
**NOTE**
Percentage values are not supported.| -| arrowHeight | [Dimension](ts-types.md#dimension10) | No | Height of the tooltip arrow.
Default value: **8**.
Unit: vp.
**NOTE**
Percentage values are not supported.| +| appearingTime | number | No |Delay before the tooltip appears.
Default value: **700**.
Unit: ms.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| disappearingTime | number | No | Delay before the tooltip disappears.
Default value: **300**.
Unit: ms.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| appearingTimeWithContinuousOperation | number | No | Delay before the tooltip disappears when multiple tooltips are displayed consecutively.
Default value: **300**.
Unit: ms.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| disappearingTimeWithContinuousOperation | number | No | Delay before the tooltip disappears when multiple tooltips are displayed consecutively.
Default value: **0**.
Unit: ms.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| enableArrow | boolean | No | Whether to display the tooltip arrow. The value **true** means to display the tooltip arrow, and **false** means the opposite.
Default value: **true**.
**NOTE**
If the available space on the screen is insufficient, the tooltip will cover part of the component and the arrow will not be displayed.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| arrowPointPosition | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No | Position of the tooltip arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. These positions are within the parent component area and do not exceed its boundaries or cover rounded corners.
Default value: **ArrowPointPosition.CENTER**.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| arrowWidth | [Dimension](ts-types.md#dimension10) | No | Width of the tooltip arrow. If the set width exceeds the length of the edge minus twice the tooltip's corner radius, the arrow is not drawn.
Default value: **16**.
Unit: vp.
**NOTE**
Percentage values are not supported.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| arrowHeight | [Dimension](ts-types.md#dimension10) | No | Height of the tooltip arrow.
Default value: **8**.
Unit: vp.
**NOTE**
Percentage values are not supported.
**Atomic service API**: This API can be used in atomic services since API version 19.| +| showAtAnchor20+ | [TipsAnchorType](ts-appendix-enums.md) |aNo | Anchor type of the tooltip
Default value: **TipsAnchorType.TARGET**.
**Atomic service API**: This API can be used in atomic services since API version 20. | ## TipsMessageType @@ -51,7 +58,7 @@ type TipsMessageType = ResourceStr | StyledString Provides information about the tooltip. -**Atomic service API**: This API can be used in atomic services since API version 18. +**Atomic service API**: This API can be used in atomic services since API version 19. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -61,7 +68,7 @@ Provides information about the tooltip. | [StyledString](ts-universal-styled-string.md#styledstring) | Styled string. | ## Example - +You can preview how this component looks on a real device, but not in DevEco Studio Previewer. ### Example 1: Binding a Tooltip This example shows how to bind a tooltip to a button using **bindTooltip**. @@ -74,12 +81,12 @@ struct TipsExample { build() { Flex({ direction: FlexDirection.Column }) { Button('Hover Tips') - .bindTips("test Tips", { + .bindTips("Tips", { appearingTime: 700, disappearingTime: 300, appearingTimeWithContinuousOperation: 300, disappearingTimeWithContinuousOperation: 0, - enableArrow:true, + enableArrow: true, }) .position({ x: 100, y: 250 }) }.width('100%').padding({ top: 5 }) @@ -88,7 +95,6 @@ struct TipsExample { ``` ![](figures/tips01.gif) - ### Example 2: Displaying and Hiding Multiple Tooltips This example demonstrates how to configure multiple tooltips to appear and disappear in sequence using **bindTips**. @@ -102,22 +108,22 @@ struct TipsExample { build() { Flex({ direction: FlexDirection.Column }) { Button('Hover Tips') - .bindTips("test Tips", { + .bindTips("Tips", { appearingTime: 700, disappearingTime: 300, appearingTimeWithContinuousOperation: 300, disappearingTimeWithContinuousOperation: 0, - enableArrow:true, + enableArrow: true, }) .position({ x: 100, y: 250 }) Button('Hover Tips') - .bindTips("test Tips", { + .bindTips("Tips", { appearingTime: 700, disappearingTime: 300, appearingTimeWithContinuousOperation: 300, disappearingTimeWithContinuousOperation: 0, - enableArrow:true, + enableArrow: true, }) .position({ x: 100, y: 350 }) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-use-effect.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-use-effect.md index 432a214e9b656446467ff314819f8bfbbafd8974..f1b07949f0b653ede06a130eefe4b98ed5892bcc 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-use-effect.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-use-effect.md @@ -4,12 +4,12 @@ The **useEffect** attribute is used to combine the drawing of special effects, s > **NOTE** > -> This attribute is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. > ## useEffect -useEffect(value: boolean) +useEffect(value: boolean): T Specifies whether to combine the drawing of special effects, such as background blur. @@ -23,9 +23,15 @@ Specifies whether to combine the drawing of special effects, such as background | -------- | -------- | -------- | -------- | | value | boolean | Yes| Whether the component inherits the special effect settings of the **EffectComponent** component.
The value **true** means the component inherits the special effect settings of the **EffectComponent** component, and **false** means the opposite.
Default value: **false**| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## useEffect14+ -useEffect(useEffect: boolean, effectType: EffectType) +useEffect(useEffect: boolean, effectType: EffectType): T Specifies whether to apply the effect defined by the parent [EffectComponent](ts-container-effectcomponent-sys.md) or the window. @@ -40,9 +46,15 @@ Specifies whether to apply the effect defined by the parent [EffectCom | useEffect | boolean | Yes | Whether to apply the effect defined by the parent **EffectComponent** or the window.
The value **true** means to apply the effect defined by the parent **EffectComponent** or the window.
Default value: **false**| | effectType | [EffectType](ts-universal-attributes-use-effect.md#effecttype14) | Yes | Type of effect to apply to the component, which is defined by the parent **EffectComponent** or the window.
Default value: **EffectType.DEFAULT**| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## useEffect18+ -useEffect(useEffect: Optional\, effectType?: EffectType) +useEffect(useEffect: Optional\, effectType?: EffectType): T Specifies whether to apply the effect defined by the parent [EffectComponent](ts-container-effectcomponent-sys.md) or the window. Compared to [useEffect14+](#useeffect), this API supports the **undefined** type for the **useEffect** parameter. @@ -57,6 +69,12 @@ Specifies whether to apply the effect defined by the parent [EffectCom | useEffect | Optional\ | Yes| Whether to apply the effect defined by the parent **EffectComponent** or the window.
The value **true** means to apply the effect defined by the parent **EffectComponent** or the window.
Default value: **false**
If **useEffect** is set to **undefined**, the previous value is retained.| | effectType | [EffectType](ts-universal-attributes-use-effect.md#effecttype14) | No| Type of effect to apply to the component, which is defined by the parent **EffectComponent** or the window.
Default value: **EffectType.DEFAULT**| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## EffectType14+ Enumerates the types of effect templates. @@ -74,10 +92,10 @@ Effect Template | Device Type | Fuzzy Radius (Unit: px) | Saturation | Brightness | Color | | -------- | ---- | ---------------------- | -------- | -------- | -| Mobile device | 0 | 0 | 0 | '#ffffffff' | -| 2-in-1 device: dark mode | 80 | 1.5 | 1.0 | '#e52e3033' | -| 2-in-1 device: light mode | 80 | 1.9 | 1.0 | '#e5ffffff' | -| Tablet | 0 | 0 | 0 | '#ffffffff' | +| Mobile device | 0 | 0 | 0 | '#ffffffff' +| 2-in-1 device: dark mode | 80 | 1.5 | 1.0 | '#e52e3033' +| 2-in-1 device: light mode | 80 | 1.9 | 1.0 | '#e5ffffff' +| Tablet | 0 | 0 | 0 | '#ffffffff' ## Example diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-visibility.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-visibility.md index 38882580628f2579d8152a0f3dcb131fc8e02721..c10954399f3962d5e0981fe1fb668f090bda4b9e 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-visibility.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-visibility.md @@ -4,13 +4,13 @@ The visibility attribute controls whether a component is visible. > **NOTE** > -> This event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. ## visibility -visibility(value: Visibility) +visibility(value: Visibility): T -Sets the visibility of this component. +Sets the visibility of the component. **Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. @@ -24,6 +24,12 @@ Sets the visibility of this component. | ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | | value | [Visibility](ts-appendix-enums.md#visibility) | Yes | Whether the component is visible. When appropriate, consider using [conditional rendering](../../../ui/state-management/arkts-rendering-control-ifelse.md) as a substitute.
Default value: **Visibility.Visible**| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## Example diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-z-order.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-z-order.md index 990e2247b54b7757b39245204b275227a032cabb..dda387fe35cf76598c2ec05e2b5b1cf4a17dbae7 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-z-order.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-z-order.md @@ -4,11 +4,11 @@ The **zIndex** attribute sets the z-order of a component in the stacking context > **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 initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. ## zIndex -zIndex(value: number) +zIndex(value: number): T Sets the stack level of the component. @@ -24,6 +24,11 @@ Sets the stack level of the component. | ------ | ------ | ---- | ------------------------------------------------------------ | | value | number | Yes | Stacking order of the component relative to its sibling components in a container. The components with a larger z-index value cover those with a smaller one. When dynamically changing zIndex does not involve adding or removing sibling nodes, the components are sorted stably based on their previous stack level.| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| ## Example @@ -39,7 +44,7 @@ struct ZIndexExample { build() { Column() { Stack() { - // Components are stacked. By default, the component defined later is on the top. A component with a larger zIndex value is displayed before one with a smaller zIndex value. + // Components in the stack layout overlap. By default, later-defined elements are on top. Elements with higher zIndex values appear in front of those with lower zIndex values. Text('1, zIndex(2)') .size({ width: '40%', height: '30%' }).backgroundColor(0xbbb2cb) .zIndex(2) @@ -99,6 +104,6 @@ Effect after clicking the **Button** component to dynamically change **zIndex** ![zIndex_1.png](figures/zIndex_1.png) -Effect after clicking the **Button** component to dynamically change **zIndex** so that **Text1** has a higher **zIndex** value than **Text2** +Effect after the **Button** component is clicked to dynamically change **zIndex** so that **Text1** has a higher **zIndex** value than **Text2** ![zIndex_2.png](figures/zIndex_2.png) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-click.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-click.md index 864cef41103af3b0fc001dfef5d5fb5f8b50cc48..18cf8509fd5d6fc0ac5358517f1c681c15b024c4 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-click.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-events-click.md @@ -4,7 +4,9 @@ A click event is triggered when a component is clicked. > **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 event is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. +> +> For details about the event distribution process, see [Multi-level Gesture Events](../../../ui/arkts-gesture-events-multi-level-gesture.md). ## onClick12+ @@ -12,9 +14,9 @@ onClick(event: Callback\, distanceThreshold: number): T Called when a click event occurs. -When the click event is triggered by a keyboard or gamepad, the value of **SourceTool** is **Unknown**. +When the click event is triggered by a keyboard or game controller, the value of **SourceTool** is **Unknown**. -Compared to the original **onClick** API, this API has the **distanceThreshold** parameter that specifies the movement threshold for click events. If the finger's movement exceeds the set threshold, the gesture recognition will fail. +Compared to the original **onClick** API, this API has the **distanceThreshold** parameter that specifies the finger movement threshold for click events. If the finger's movement exceeds the set threshold, the gesture recognition will fail. For scenarios where there is no restriction on the finger movement distance during a click, the original API is recommended. If there is a requirement for the finger to stay within a certain area during the click, this API is recommended. **Widget capability**: This API can be used in ArkTS widgets since API version 12. @@ -22,8 +24,8 @@ For scenarios where there is no restriction on the finger movement distance duri > **NOTE** > > Since API version 12, the following constraints apply when this API is used in service widgets: -> 1. Click events cannot be triggered if the finger is pressed for more than 800 ms. -> 2. Click events cannot be triggered if the finger moves more than 20 px after pressing down. +> 1. Click events will not be triggered if the finger is pressed for more than 800 ms. +> 2. Click events will not be triggered if the finger moves more than 20 px after pressing down. **Atomic service API**: This API can be used in atomic services since API version 12. @@ -34,7 +36,13 @@ For scenarios where there is no restriction on the finger movement distance duri | Name| Type | Mandatory| Description | | ------ | --------------------------------- | ---- | -------------------- | | event | [ClickEvent](#clickevent) | Yes | [ClickEvent](#clickevent) object.| -| distanceThreshold | number | Yes | Movement threshold for click events. If the value specified is less than or equal to 0, it will be converted to the default value.
Default value: 2^31-1
**NOTE**
If the finger movement exceeds the preset movement threshold, the gesture recognition fails. If the default threshold is used during initialization and the finger moves beyond the component's touch target, the gesture recognition fails.| +| distanceThreshold | number | Yes | Finger movement threshold for click events. If the value specified is less than or equal to 0, it will be converted to the default value.
Default value: 2^31-1
Unit: vp
**NOTE**
If the finger movement exceeds the preset movement threshold, the gesture recognition fails. If the default threshold is used during initialization and the finger moves beyond the component's touch target, the gesture recognition fails.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| ## onClick @@ -49,8 +57,8 @@ When the click event is triggered by a keyboard or gamepad, the value of **Sourc > **NOTE** > > Since API version 9, the following constraints apply when this API is used in service widgets: -> 1. Click events cannot be triggered if the finger is pressed for more than 800 ms. -> 2. Click events cannot be triggered if the finger moves more than 20 px after pressing down. +> 1. Click events will not be triggered if the finger is pressed for more than 800 ms. +> 2. Click events will not be triggered if the finger moves more than 20 px after pressing down. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -83,14 +91,24 @@ Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). | windowY10+ | number | Y coordinate of the click relative to the upper left corner of the application window.
Unit: vp
**Atomic service API**: This API can be used in atomic services since API version 11.| | displayX10+ | number | X coordinate of the click relative to the upper left corner of the application screen.
Unit: vp
**Atomic service API**: This API can be used in atomic services since API version 11.| | displayY10+ | number | Y coordinate of the click relative to the upper left corner of the application screen.
Unit: vp
**Atomic service API**: This API can be used in atomic services since API version 11.| -| screenX(deprecated) | number | X coordinate of the click relative to the upper left corner of the application window.
This API is deprecated since API version 10. You are advised to use **windowX** instead.| -| screenY(deprecated) | number | Y coordinate of the click relative to the upper left corner of the application window.
This API is deprecated since API version 10. You are advised to use **windowY** instead.| -| preventDefault12+ | () => void | Blocks the default event.
**NOTE**
This API can only be used by certain components; currently supported components are **RichEditor** and **Hyperlink**. Currently, asynchronous calls and Modifier APIs are not supported.
**Atomic service API**: This API can be used in atomic services since API version 12.| +| screenX(deprecated) | number | X coordinate of the click relative to the upper left corner of the application window.
Unit: vp
This API is deprecated since API version 10. You are advised to use **windowX** instead.| +| screenY(deprecated) | number | Y coordinate of the click relative to the upper left corner of the application window.
Unit: vp
This API is deprecated since API version 10. You are advised to use **windowY** instead.| +| preventDefault12+ | () => void | Blocks the default event.
**NOTE**
This API is only supported by the following components: **RichEditor** and **Hyperlink**. An exception is thrown when this API is used with unsupported components. Currently, asynchronous calls and Modifier APIs are not supported.
**Atomic service API**: This API can be used in atomic services since API version 12.| | targetDisplayId15+ | number | ID of the screen where the event occurs.
**Atomic service API**: This API can be used in atomic services since API version 15.| | hand15+ | [InteractionHand](./ts-gesture-settings.md#interactionhand15) | Whether the event is triggered by a left-hand or right-hand tap.
**Atomic service API**: This API can be used in atomic services since API version 15.| +**Error codes** + +For details about the error codes, see [Interaction Event Error Codes](../errorcode-event.md). + +| ID | Error Message| +| --------- | ------- | +| 100017 | Component does not support prevent function. | + ## EventTarget8+ +Describes the display area of the object that triggers the event. + **Widget capability**: This API can be used in ArkTS widgets since API version 9. **Atomic service API**: This API can be used in atomic services since API version 11. @@ -100,7 +118,7 @@ Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). | Name | Type | Description | | ---- | ------------------------- | ---------- | | area | [Area](ts-types.md#area8) | Area information of the target element.| -| id15+ | [string](ts-universal-attributes-component-id.md) | Custom node ID.| +| id15+ | [string](ts-universal-attributes-component-id.md) | Custom node ID. Default value: **undefined**.| ## Example diff --git a/en/application-dev/reference/apis-arkui/errorcode-node.md b/en/application-dev/reference/apis-arkui/errorcode-node.md new file mode 100644 index 0000000000000000000000000000000000000000..d39beff0305e13cd3167b20a76d96305345b1105 --- /dev/null +++ b/en/application-dev/reference/apis-arkui/errorcode-node.md @@ -0,0 +1,95 @@ +# Custom Node Error Codes + +> **NOTE** +> +> This topic describes only module-specific error codes. For details about universal error codes, see [Universal Error Codes](../errorcode-universal.md). + +## 100021 FrameNode Not Modifiable + +**Error Message** + +The FrameNode is not modifiable. + +**Description** + +This error code is reported when the current FrameNode is unmodifiable, preventing the requested operation, for example, setting properties, adding or removing child nodes, or binding controllers. + +**Possible Causes** + +An attempt is made to modify a declarative node. + +**Solution** + +Avoid modifying unmodifiable nodes. Use try-catch to handle errors and prevent impact on other logic. + +## 100022 Cross-Language Attribute Configuration Not Supported + +**Error Message** + +The FrameNode cannot be set whether to support cross-language common attribute setting. + +**Description** + +This error code is reported when the target FrameNode does not support cross-language attribute configuration. + +**Possible Causes** + +An attempt is made to adjust the cross-language attribute permission of the target FrameNode. + +**Solution** + +NA + +## 100023 Parameter Error + +**Error Message** + +Parameter error. Possible causes: 1. The component type of the node is incorrect. 2. The node is null or undefined. 3. The controller is null or undefined. + +**Description** + +This error code is reported when the parameters passed to the API are incorrect. + +**Possible Causes** + +1. The component type of the provided node is incorrect. +2. The provided node is null or undefined. +3. The provided controller is null or undefined. + +**Solution** + +Adjust the passed parameter values or perform pre-checks. + +## 106103 Operation Not Allowed on Nodes Created by ArkTS + +**Error Message** + +The corresponding operation does not support nodes created by ArkTS. + +**Description** + +This error code is reported when the operation does not support nodes created by ArkTS. + +**Possible Causes** + +The current operation is incompatible with nodes created by ArkTS. + +**Solution** + +Pass nodes not created by ArkTS. + +## 106203 Passed Node Not Mounted to Component Tree + +**Error Message** + +**Description** + +This error code is reported when the passed node is not mounted to the component tree. + +**Possible Causes** + +The passed node is not mounted to the component tree when the API is called. + +**Solution** + +Adjust the API call timing to ensure the node is mounted to the component tree. diff --git a/en/application-dev/reference/apis-arkui/errorcode-xcomponent.md b/en/application-dev/reference/apis-arkui/errorcode-xcomponent.md new file mode 100644 index 0000000000000000000000000000000000000000..4c39d91db86798ee00bb08c41e9d12b00a3ed6a4 --- /dev/null +++ b/en/application-dev/reference/apis-arkui/errorcode-xcomponent.md @@ -0,0 +1,23 @@ +# XComponent Error Codes + +> **NOTE** +> +> This topic describes only module-specific error codes. For details about universal error codes, see [Universal Error Codes](../errorcode-universal.md). + +## 103501 XComponent in Invalid State + +**Error Message** + +XComponent is in invalid state. + +**Description** + +This error code is reported when the **XComponent** is in an invalid or unsupported state. + +**Possible Causes** + +Refer to the specific documentation of the API that triggers this error. + +**Solution** + +Ensure that the Surface held by the **XComponent** is in a normal state. diff --git a/en/application-dev/ui/arkts-layout-development-arcswiper.md b/en/application-dev/ui/arkts-layout-development-arcswiper.md index eb2293c2d4d4026f06c056df0ff3495d1816a6d7..4ab5aaa408697b2cd2c70e6436d011e7ec04b096 100644 --- a/en/application-dev/ui/arkts-layout-development-arcswiper.md +++ b/en/application-dev/ui/arkts-layout-development-arcswiper.md @@ -12,7 +12,7 @@ import { ArcDotIndicator, ArcDirection, ArcSwiperController -} from '@kit.ArkUI' +} from '@kit.ArkUI'; ``` ## Setting the Navigation Point Indicator Style @@ -90,7 +90,7 @@ The **ArcSwiper** component supports four page switching modes: swiping with fin @Entry @Component struct SwiperCustomAnimationExample { - private wearableSwiperController: ArcSwiperController = new ArcSwiperController() + private wearableSwiperController: ArcSwiperController = new ArcSwiperController(); build() { Column() { @@ -191,20 +191,27 @@ When **vertical** is set to **true**, swiping occurs in the vertical direction. Use the [customContentTransition](../reference/apis-arkui/arkui-ts/ts-container-arcswiper.md#customcontenttransition) attribute to set a custom transition animation for **ArcSwiper**. Define the animation by adjusting opacity, scale, translation, and rendering layer for all pages within the viewport frame by frame in the callback. ```ts -import { Decimal } from '@kit.ArkTS' +import { Decimal } from '@kit.ArkTS'; +import { + ArcSwiper, + ArcSwiperAttribute, + ArcDotIndicator, + ArcDirection, + ArcSwiperController +} from '@kit.ArkUI'; @Entry @Component struct SwiperCustomAnimationExample { - private MIN_SCALE: number = 0.1 - @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange] - @State opacityList: number[] = [] - @State scaleList: number[] = [] + private MIN_SCALE: number = 0.1; + @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange]; + @State opacityList: number[] = []; + @State scaleList: number[] = []; aboutToAppear(): void { for (let i = 0; i < this.backgroundColors.length; i++) { - this.opacityList.push(1.0) - this.scaleList.push(1.0) + this.opacityList.push(1.0); + this.scaleList.push(1.0); } } @@ -227,13 +234,13 @@ struct SwiperCustomAnimationExample { transition: (proxy: SwiperContentTransitionProxy) => { if (proxy.position <= -1 || proxy.position >= 1) { // When a group of pages is completely scrolled out of the viewport, reset the attribute values. - this.opacityList[proxy.index] = 1.0 - this.scaleList[proxy.index] = 1.0 + this.opacityList[proxy.index] = 1.0; + this.scaleList[proxy.index] = 1.0; } else { - let position: number = Decimal.abs(proxy.position).toNumber() - this.opacityList[proxy.index] = 1 - position + let position: number = Decimal.abs(proxy.position).toNumber(); + this.opacityList[proxy.index] = 1 - position; this.scaleList[proxy.index] = - this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - position) + this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - position); } } }) @@ -249,11 +256,19 @@ struct SwiperCustomAnimationExample { The swipe gesture of the **ArcSwiper** component may conflict with the swipe-to-return functionality. To resolve this, you can use [gesture judgment](../reference/apis-arkui/arkui-ts/ts-gesture-blocking-enhancement.md#ongesturerecognizerjudgebegin) to determine whether **ArcSwiper** has scrolled to the beginning. This allows you to intercept the swipe gesture and enable the swipe-to-return functionality. ```ts +import { + ArcSwiper, + ArcSwiperAttribute, + ArcDotIndicator, + ArcDirection, + ArcSwiperController +} from '@kit.ArkUI'; + @Entry @Component struct SwiperCustomAnimationExample { - @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange] - innerSelectedIndex: number = 0 + @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange]; + innerSelectedIndex: number = 0; build() { Column() { @@ -268,18 +283,18 @@ struct SwiperCustomAnimationExample { }) } .onAnimationStart((index: number, targetIndex: number) => { - this.innerSelectedIndex = targetIndex + this.innerSelectedIndex = targetIndex; }) .onGestureRecognizerJudgeBegin((event: BaseGestureEvent, current: GestureRecognizer, others: Array): GestureJudgeResult => { // When the implementation is about to succeed, set the recognizer enabling state based on the current component state. if (current) { let target = current.getEventTargetInfo(); if (target && current.isBuiltIn() && current.getType() == GestureControl.GestureType.PAN_GESTURE) { - let swiperTaget = target as ScrollableTargetInfo - if (swiperTaget instanceof ScrollableTargetInfo && - (swiperTaget.isBegin() || this.innerSelectedIndex === 0)) { // This condition checks whether ArcSwiper has scrolled to the beginning. + let swiperTarget = target as ScrollableTargetInfo; + if (swiperTarget instanceof ScrollableTargetInfo && + (swiperTarget.isBegin() || this.innerSelectedIndex === 0)) { // Check whether the ArcSwiper has scrolled to the beginning: swiperTarget.isBegin() or innerSelectedIndex === 0. let panEvent = event as PanGestureEvent; - if (panEvent && panEvent.offsetX > 0 && (swiperTaget.isBegin() || this.innerSelectedIndex === 0)) { + if (panEvent && panEvent.offsetX > 0 && (swiperTarget.isBegin() || this.innerSelectedIndex === 0)) { return GestureJudgeResult.REJECT; } } diff --git a/en/device-dev/device-test/smartperf-host.md b/en/device-dev/device-test/smartperf-host.md index 6f8451539b9e7bde43dbe79029138508f520d809..76292dee2288c8fcece89bd3e5a451ae938092c0 100644 --- a/en/device-dev/device-test/smartperf-host.md +++ b/en/device-dev/device-test/smartperf-host.md @@ -65,7 +65,7 @@ The PC end is accessible from the Smartperf-Host website. It consists of modules In Smartperf_Host, you can collect I/O operation records, which provide the following information: start time, total latency, process, average latency of every 4 KB data, thread, operation (write data, page swap-in, and metadata), access traffic, path, block number, priority, and backtrace call stack. For details, see [Usage of BIO Latency Recording](https://gitee.com/openharmony-sig/developtools_smartperf_host/blob/master/ide/src/doc/md/quickstart_bio.md). - Collecting Smaps Records - In Smartperf_Host, you can collect the smaps data (type, Pss, Rss, Vss, and more) on a process-by-process basis. The data source is **/proc/$pid/smaps**. For details, see [Smaps Usage](https://gitee.com/openharmony-sig/developtools_smartperf_host/blob/master/ide/src/doc/md/quickstart_smaps.md). + In Smartperf_Host, you can collect the smaps data (type, Pss, Rss, Vss, and more) on a process-by-process basis. The data source is **/proc/$pid/smaps**. For details, see [Smaps Usage](https://gitee.com/openharmony/developtools_smartperf_host/blob/master/ide/src/doc/md/quickstart_memory_template.md). - Using SQL Analysis and Metrics You can use Query (SQL) and Metrics features to quickly locate the trace data. For details, see [SQL Analysis and Metrics Usage](https://gitee.com/openharmony-sig/developtools_smartperf_host/blob/master/ide/src/doc/md/quickstart_sql_metrics.md). diff --git a/en/device-dev/device-test/xts.md b/en/device-dev/device-test/xts.md index 9fbfd198d14529490b8960a17b6d55a9d798b639..242d41ce3cc788c532a290aee719d7d6565a3850 100644 --- a/en/device-dev/device-test/xts.md +++ b/en/device-dev/device-test/xts.md @@ -146,7 +146,7 @@ The HCTest framework is used to support test cases developed with the C language ``` LITE_TEST_CASE(IntTestSuite, TestCase001, Function | MediumTest | Level1) { - //do something + //do something. }; ``` 5. Use the **RUN_TEST_SUITE** macro to register the test suite. diff --git a/en/device-dev/subsystems/subsys-graphics-layout-guide.md b/en/device-dev/subsystems/subsys-graphics-layout-guide.md index f0d19d5b29ebb68b9da78ab8b6556b20fc1c76c8..b9b82a0bd7730f7a5889e5b8fee47bdece569236 100644 --- a/en/device-dev/subsystems/subsys-graphics-layout-guide.md +++ b/en/device-dev/subsystems/subsys-graphics-layout-guide.md @@ -1,206 +1,156 @@ -# Development of Layout Container Components +# Development of Layout Container Components Layout container components consist of basic view classes. You can set the view positions to achieve nested and overlapped layouts, set the layout type and margin to standardize the child components in the layout, and call certain functions to implement layout views based on parent and sibling components. -## UISwipeView - -## When to Use - -**UISwipeView** inherits from **UIViewGroup**. In addition to the **Add**, **Remove**, and **Insert** functions, **UISwipeView** provides the functions to swipe contents by page and center the current page after swiping. This component can be horizontally or vertically centered. Child components added via the **Add** function are automatically horizontally or vertically centered, adaptive to the **UISwipeView** direction, in the sequence they were added. - -## Available APIs - -**Table 1** Available functions in SwipeView - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Function

-

Description

-

void SetCurrentPage(uint16_t index);

-

Sets the current page.

-

uint16_t GetCurrentPage()

-

Obtains the current page.

-

UIView* GetCurrentView() const

-

Obtains the current view.

-

void SetOnSwipeListener(OnSwipeListener& onSwipeListener)

-

Sets the swiping callback class.

-

void SetAnimatorTime(uint16_t time);

-

Sets the animator event.

-

void SetLoopState(bool loop)

-

Sets whether to enable the cyclic state.

-

UIView* GetViewByIndex(uint16_t index);

-

Obtains a view based on its index.

-
- -## Development Procedure \(Non-Cyclic Horizontal Swiping\) - -1. Create a horizontal swiping **UISwipeView**. - - ``` - UISwipeView* swipe = new UISwipeView(UISwipeView::HORIZONTAL); - ``` - -2. Add child components to **UISwipeView**. - - ``` - UILabelButton* button1 = new UILabelButton(); - button1->SetPosition(0, 0, g_ButtonW, g_ButtonH); - button1->SetText("button1"); - swipe->Add(button1); - UILabelButton* button2 = new UILabelButton(); - button2->SetPosition(0, 0, g_ButtonW, g_ButtonH); - button2->SetText("button2"); - swipe->Add(button2); - UILabelButton* button3 = new UILabelButton(); - button3->SetPosition(0, 0, g_ButtonW, g_ButtonH); - button3->SetText("button3"); - swipe->Add(button3); - ``` - -3. Verify that the components are swiping horizontally but not cyclically. - - **Figure 1** Horizontal swiping effect of **UISwipeView** - - ![](figures/en-us_image_0000001053247975.gif) +## UISwipeView -## Development Procedure \(Cyclic Horizontal Swiping\) +### When to Use -1. Create a horizontal swiping **UISwipeView** and add its child components. +**UISwipeView** inherits from **UIViewGroup**. In addition to the **Add**, **Remove**, and **Insert** functions, **UISwipeView** provides the functions to swipe contents by page and center the current page after swiping. This component can be horizontally or vertically centered. Child components added via the **Add** function are automatically horizontally or vertically centered, adaptive to the **UISwipeView** direction, in the sequence they were added. - ``` - UISwipeView* swipe = new UISwipeView(UISwipeView::HORIZONTAL); - UILabelButton* button1 = new UILabelButton(); - button1->SetPosition(0, 0, g_ButtonW, g_ButtonH); - button1->SetText("button1"); - swipe->Add(button1); - UILabelButton* button2 = new UILabelButton(); - button2->SetPosition(0, 0, g_ButtonW, g_ButtonH); - button2->SetText("button2"); - swipe->Add(button2); - UILabelButton* button3 = new UILabelButton(); - button3->SetPosition(0, 0, g_ButtonW, g_ButtonH); - button3->SetText("button3"); - swipe->Add(button3); - ``` -2. Enable cyclic swiping for the **UISwipeView**. +### Available APIs - ``` - swipe->SetLoopState(true); - ``` +**Table 1** Available functions in SwipeView -3. Verify that the components are swiping horizontally and cyclically. +| Function | Description | +| -------- | -------- | +| void SetCurrentPage(uint16_t index) | Sets the current page. | +| uint16_t GetCurrentPage() | Obtains the current page. | +| UIView\* GetCurrentView() const | Obtains the current view. | +| void SetOnSwipeListener(OnSwipeListener& onSwipeListener) | Sets the swiping callback class. | +| void SetAnimatorTime(uint16_t time) | Sets the animator event. | +| void SetLoopState(bool loop) | Sets whether to enable the cyclic state. | +| UIView\* GetViewByIndex(uint16_t index)| Obtains a view based on its index. | - **Figure 2** Cyclic horizontal swiping effect of **UISwipeView** - + +### Development Procedure (Non-Cyclic Horizontal Swiping) + +1. Create a horizontal swiping **UISwipeView**. + + ``` + UISwipeView* swipe = new UISwipeView(UISwipeView::HORIZONTAL); + ``` + +2. Add child components to **UISwipeView**. + + ``` + UILabelButton* button1 = new UILabelButton(); + button1->SetPosition(0, 0, g_ButtonW, g_ButtonH); + button1->SetText("button1"); + swipe->Add(button1); + UILabelButton* button2 = new UILabelButton(); + button2->SetPosition(0, 0, g_ButtonW, g_ButtonH); + button2->SetText("button2"); + swipe->Add(button2); + UILabelButton* button3 = new UILabelButton(); + button3->SetPosition(0, 0, g_ButtonW, g_ButtonH); + button3->SetText("button3"); + swipe->Add(button3); + ``` + +3. Verify that the components are swiping horizontally but not cyclically. + + **Figure 1** Horizontal swiping effect of **UISwipeView** + + ![](figures/en-us_image_0000001053247975.gif) + + +### Development Procedure (Cyclic Horizontal Swiping) + +1. Create a horizontal swiping **UISwipeView** and add its child components. + + ``` + UISwipeView* swipe = new UISwipeView(UISwipeView::HORIZONTAL); + UILabelButton* button1 = new UILabelButton(); + button1->SetPosition(0, 0, g_ButtonW, g_ButtonH); + button1->SetText("button1"); + swipe->Add(button1); + UILabelButton* button2 = new UILabelButton(); + button2->SetPosition(0, 0, g_ButtonW, g_ButtonH); + button2->SetText("button2"); + swipe->Add(button2); + UILabelButton* button3 = new UILabelButton(); + button3->SetPosition(0, 0, g_ButtonW, g_ButtonH); + button3->SetText("button3"); + swipe->Add(button3); + ``` + +2. Enable cyclic swiping for the **UISwipeView**. + + ``` + swipe->SetLoopState(true); + ``` + +3. Verify that the components are swiping horizontally and cyclically. + + **Figure 2** Cyclic horizontal swiping effect of **UISwipeView** ![](figures/en-us_image_0000001053207924.gif) -## GridLayout +## GridLayout -## When to Use + +### When to Use **GridLayout** provides the basic layout capability to set the number of grid rows and columns. Child components added via the **Add** function are automatically arranged after the **LayoutChildren\(\)** function is called. -## Available APIs - -**Table 2** Available functions in GridLayout - - - - - - - - - - - - - - - - -

Function

-

Description

-

void SetRows(const uint16_t& rows)

-

Sets the number of grid rows.

-

void SetCols(const uint16_t& cols)

-

Sets the number of grid columns.

-

void LayoutChildren(bool needInvalidate = false)

-

Lays out child components.

-
- -## How to Develop - -1. Create a **GridLayout** instance and set its position and size. - - ``` - GridLayout* layout_ = new GridLayout(); - layout_->SetPosition(0, g_y, HROIZONTAL_RESOLUTION, 200); - layout_->SetLayoutDirection(LAYOUT_HOR); - layout_->SetRows(2); - layout_->SetCols(2); - ``` - -2. Create **UILabelButton** instances. - - ``` - UILabelButton* bt1 = new UILabelButton(); - bt1->SetPosition(0,0,100,50); - bt1->SetText("bt1"); - UILabelButton* bt2 = new UILabelButton(); - bt2->SetPosition(0, 0, 100, 50); - bt2->SetText("bt2"); - UILabelButton* bt3 = new UILabelButton(); - bt3->SetPosition(0, 0, 100, 50); - bt3->SetText("bt3"); - UILabelButton* bt4 = new UILabelButton(); - bt4->SetPosition(0, 0, 100, 50); - bt4->SetText("bt4"); - ``` - -3. Add child components and call the **LayoutChildren\(\)** function. - - ``` - layout_->Add(bt1); - layout_->Add(bt2); - layout_->Add(bt3); - layout_->Add(bt4); - layout_->LayoutChildren(); - ``` - -4. Verify the layout of buttons, as shown in the following figure. - - **Figure 3** Setting a 2x2 grid and adding four buttons in a layout - ![](figures/setting-a-2x2-grid-and-adding-four-buttons-in-a-layout.png "setting-a-2x2-grid-and-adding-four-buttons-in-a-layout") +### ½Ó¿Ú˵Ã÷ + + **Table 2** Available functions in GridLayout + +| Function | Description | +| -------- | -------- | +| void SetRows(const uint16_t& rows) | Sets the number of grid rows. | +| void SetCols(const uint16_t& cols) | Sets the number of grid columns. | +| void LayoutChildren(bool needInvalidate = false) | Lays out child components. | + + +### How to Develop + +1. Create a **GridLayout** instance and set its position and size. + + ``` + GridLayout* layout_ = new GridLayout(); + layout_->SetPosition(0, g_y, HROIZONTAL_RESOLUTION, 200); + layout_->SetLayoutDirection(LAYOUT_HOR); + layout_->SetRows(2); + layout_->SetCols(2); + ``` + +2. Create **UILabelButton** instances. + + ``` + UILabelButton* bt1 = new UILabelButton(); + bt1->SetPosition(0,0,100,50); + bt1->SetText("bt1"); + UILabelButton* bt2 = new UILabelButton(); + bt2->SetPosition(0, 0, 100, 50); + bt2->SetText("bt2"); + UILabelButton* bt3 = new UILabelButton(); + bt3->SetPosition(0, 0, 100, 50); + bt3->SetText("bt3"); + UILabelButton* bt4 = new UILabelButton(); + bt4->SetPosition(0, 0, 100, 50); + bt4->SetText("bt4"); + ``` + +3. Add child components and call the **LayoutChildren()** function. + + ``` + layout_->Add(bt1); + layout_->Add(bt2); + layout_->Add(bt3); + layout_->Add(bt4); + layout_->LayoutChildren(); + ``` + +4. Verify the layout of buttons, as shown in the following figure. + + **Figure 3** Setting a 2x2 grid and adding four buttons in a layout + ![](figures/setting-a-2x2-grid-and-adding-four-buttons-in-a-layout.png "setting-a-2x2-grid-and-adding-four-buttons-in-a-layout") diff --git a/en/device-dev/subsystems/subsys-graphics-simulator-guide.md b/en/device-dev/subsystems/subsys-graphics-simulator-guide.md index fa1354e7f66dde0f662911ac52201b7e20599c5a..d2944edebe5384653b7d5899b8317896e5c811ca 100644 --- a/en/device-dev/subsystems/subsys-graphics-simulator-guide.md +++ b/en/device-dev/subsystems/subsys-graphics-simulator-guide.md @@ -59,10 +59,10 @@ git clone https://gitee.com/openharmony/third_party_libjpeg-turbo.git 1. Choose **File > Open File or Project**. 2. Select the project in the displayed dialog box. -The path of the source code is as follows: -```bash -foundation/arkui/ui_lite/tools/qt/simulator/simulator.pro -``` + The path of the source code is as follows: + ```bash + foundation/arkui/ui_lite/tools/qt/simulator/simulator.pro + ``` Note: When you open the project for the first time, select only **minGW** in the **kits** list on the **Configure Project** page.