diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/figures/accessibilityUseSamePage.png b/en/application-dev/reference/apis-arkui/arkui-ts/figures/accessibilityUseSamePage.png new file mode 100644 index 0000000000000000000000000000000000000000..6517c5252b96def9ece47eed83dd207806942004 Binary files /dev/null and b/en/application-dev/reference/apis-arkui/arkui-ts/figures/accessibilityUseSamePage.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/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/ts-component-general-attributes.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-component-general-attributes.md index bfce463dec1991479522f9efdfa4518a68e6e927..11b93d3b69a6289b46986b488fce5c9d0fd11bb6 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-component-general-attributes.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-component-general-attributes.md @@ -29,7 +29,7 @@ - [Foreground Effect](ts-universal-attributes-foreground-effect.md) - [Foreground Blur](ts-universal-attributes-foreground-blur-style.md) - [Motion Blur](ts-universal-attributes-motionBlur.md) -- [Click Effect](ts-universal-attributes-click-effect.md) +- [Click Feedback Effect](ts-universal-attributes-click-effect.md) - [Accessibility](ts-universal-attributes-accessibility.md) - [Attribute Modifier](ts-universal-attributes-attribute-modifier.md) - [Gesture Modifier](ts-universal-attributes-gesture-modifier.md) @@ -48,6 +48,7 @@ - [Obscuring](ts-universal-attributes-obscured.md) - [Universal Text Attributes](ts-universal-attributes-text-style.md) - [Drag and Drop Control](ts-universal-attributes-drag-drop.md) +- [Drag-and-Drop Sorting](ts-universal-attributes-drag-sorting.md) - [Safe Area](ts-universal-attributes-expand-safe-area.md) - [Render Fit](ts-universal-attributes-renderfit.md) - [Event Monopolization](ts-universal-attributes-monopolize-events.md) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-lazyvgridlayout.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-lazyvgridlayout.md new file mode 100644 index 0000000000000000000000000000000000000000..77a696c9f0322fab7ec40af0345d56a48eb43862 --- /dev/null +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-container-lazyvgridlayout.md @@ -0,0 +1,237 @@ +# LazyVGridLayout + +The **LazyVGridLayout** component implements a lazy-loading grid layout, with its parent component restricted to [WaterFlow](ts-container-waterflow.md) or [FlowItem](ts-container-flowitem.md). It can also be used within the **WaterFlow** or **FlowItem** component after being wrapped by custom components or [NodeContainer](ts-basic-components-nodecontainer.md). + +Lazy loading is supported only when the **WaterFlow** component uses single-column mode or single-column segments in segmented layout and the layout direction is **FlexDirection.Column**. Lazy loading is not supported if the **WaterFlow** component is in multi-column mode or the layout direction is **FlexDirection.Row** or **FlexDirection.RowReverse**. Using this component with **FlexDirection.ColumnReverse** in the **WaterFlow** component causes display anomalies. When lazy loading is enabled, the component only loads child components within the **WaterFlow** visible area, with pre-loading of half-screen content above and below the viewport during frame idle periods. + +> **NOTE** +> +> - This component is supported since API version 19. Updates will be marked with a superscript to indicate their earliest API version. +> - This component's height adapts to content by default. Setting the height, height constraints, or aspect ratio causes display anomalies. + +## APIs + +LazyVGridLayout() + +Creates a vertical lazy-loading grid layout container. + +**Atomic service API**: This API can be used in atomic services since API version 19. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +## Attributes + +In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. + +### columnsTemplate + +columnsTemplate(value: string) + +Sets the number of columns, fixed column width, or minimum column width of the grid. If this attribute is not set, one column will be used. + +For example, **'1fr 1fr 2fr'** indicates three columns, with the first column taking up 1/4 of the parent component's full width, the second column 1/4, and the third column 2/4. + +**columnsTemplate('repeat(auto-fit, track-size)')**: The layout automatically calculates the number of columns and the actual column width, while adhering to the minimum column width specified with **track-size**. + +**columnsTemplate('repeat(auto-fill, track-size)')**: The layout automatically calculates the number of columns based on the fixed column width specified with **track-size**. + +**columnsTemplate('repeat(auto-stretch, track-size)')**: The layout uses **columnsGap** to define the minimum gap between columns and automatically calculates the number of columns and the actual gap size based on the fixed column width specified with **track-size**. + +**repeat**, **auto-fit**, **auto-fill**, and **auto-stretch** are keywords. **track-size** indicates the column width, in the unit of px, vp (default), %, or any valid digit. The value must be greater than or equal to one valid column width.
+In **auto-stretch** mode, **track-size** must be a valid column width value, in the unit of px, vp, or any valid digit; percentage values (%) are not supported. + +If this attribute is set to **'0fr'**, the column width is 0, and child components are not displayed. If this attribute is set to an invalid value, the child components are displayed in a fixed column. + +**Atomic service API**: This API can be used in atomic services since API version 19. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------------------- | +| value | string | Yes | Number of columns or minimum column width of the grid.| + +### columnsGap + +columnsGap(value: LengthMetrics): T + +Sets the gap between columns. A value less than 0 evaluates to the default value. + +**Atomic service API**: This API can be used in atomic services since API version 19. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------- | ---- | ---------------------------- | +| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Gap between columns.
Default value: **0vp**| + +**Return value** + +| Type| Description | +| --- | -------------- | +| T | Current component.| + +### rowsGap + +rowsGap(value: LengthMetrics): T + +Sets the gap between rows. A value less than 0 evaluates to the default value. + +**Atomic service API**: This API can be used in atomic services since API version 19. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------- | ---- | ---------------------------- | +| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Gap between rows.
Default value: **0vp**| + +**Return value** + +| Type| Description | +| --- | -------------- | +| T | Current component.| + +## Events + +Only the [universal events](ts-component-general-events.md) are supported. + +## Example + +This example demonstrates how to implement a lazy-loading grid layout using the **WaterFlow** and **LazyVGridLayout** components. + + +```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-universal-attributes-accessibility.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md index 6e2edb5fffe58947cfed8c269616e1b50b07c8b6..75009f00af2ae1f90ff2062255e1f17aa1ceb13a 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 @@ -170,7 +170,7 @@ Sets an accessibility virtual child node. For custom drawing components, a **Cus accessibilityChecked(isCheck: boolean) -Sets the checked state of the accessibility component. This property is used in multi-select scenarios. +Sets the checked state of the accessibility component. This property is used in multiselect scenarios. **Widget capability**: This API can be used in ArkTS widgets since API version 13. @@ -182,7 +182,7 @@ Sets the checked state of the accessibility component. This property is used in | Name | Type | Mandatory| Description | | ------- | ------- | ---- | ------------------------------------------------------------ | -| isCheck | boolean | Yes | Whether the current component is selected.
The options are as follows:
**true**: The component is selected.
**false**: The component is not selected.
**undefined**: The component determines its own selected state.
Default value: **undefined**
**NOTE**
1. Setting this parameter to **true** or **false** will automatically set the component's **checkable** attribute to **true**.
2. When this parameter is set to **true** or **false**, to use it with **accessibilitySelected**, set the **accessibilitySelected** parameter to **undefined**.| +| isCheck | boolean | Yes | Whether the current component is selected.
The options are as follows:
**true**: The component is selected.
**false**: The component is not selected.
**undefined**: The component determines its own selected state.
Default value: **undefined**.
**NOTE**
1. Setting this parameter to **true** or **false** will automatically set the component's **checkable** attribute to **true**.
2. When this parameter is set to **true** or **false**, to use it with **accessibilitySelected**, set the **accessibilitySelected** parameter to **undefined**.| ## accessibilitySelected13+ @@ -200,7 +200,7 @@ Sets the selected state of the accessibility component. This property is used in | Name | Type | Mandatory| Description | | -------- | ------- | ---- | ------------------------------------------------------------ | -| isSelect | boolean | Yes | Whether the current component is selected.
The options are as follows:
**true**: The component is selected.
**false**: The component is not selected.
**undefined**: The component determines its own selected state.
Default value: **undefined**
**NOTE**
1. When this parameter is set to **true** or **false**, to use it with **accessibilityChecked**, set the **accessibilityChecked** parameter to **undefined**.| +| isSelect | boolean | Yes | Whether the current component is selected.
The options are as follows:
**true**: The component is selected.
**false**: The component is not selected.
**undefined**: The component determines its own selected state.
Default value: **undefined**.
**NOTE**
1. When this parameter is set to **true** or **false**, to use it with **accessibilityChecked**, set the **accessibilityChecked** parameter to **undefined**.| ## accessibilityRole18+ @@ -430,7 +430,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 +442,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 +454,8 @@ Enumerates the same-page modes for the current UIExtensionComponent and the host | Name | Value | Description | | ----------- | ---- | ------------------------------------------------------------ | -| SEMI_SILENT | 0 | Ignores page events sent by the root node of the UIExtensionComponent page or during the initial page load.| -| 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+ @@ -473,7 +473,7 @@ Sets whether to enable automatic scrolling for screen readers when the current p | Name | Type | Mandatory| Description | | -------------- | ------- | ---- | ------------------------------------------------------------ | -| isTriggerable | boolean | Yes | Whether the component supports automatic scrolling for screen readers when the current page has no focusable components.
The options are as follows:
**true**: The component triggers automatic scrolling for screen readers when the current page has no focusable components.
**false**: The component does not trigger automatic scrolling for screen readers when the current page has no focusable components.
**undefined**: The default settings are restored.
Default value: **true**
**NOTE**
1. This parameter does not affect the original **scrollable** attribute of the component.
2. The final scrolling behavior is determined by the screen reader based on this parameter and whether the component supports scrolling.
3. This API applies to all basic components. It is recommended for scrollable components, including **List**, **Grid**, **Scroll**, **Waterflow**, and **Swiper**.| +| isTriggerable | boolean | Yes | Whether the component supports automatic scrolling for screen readers when the current page has no focusable components.
The options are as follows:
**true**: The component triggers automatic scrolling for screen readers when the current page has no focusable components.
**false**: The component does not trigger automatic scrolling for screen readers when the current page has no focusable components.
**undefined**: The default settings are restored.
Default value: **true**
**NOTE**
1. This parameter does not affect the original **scrollable** attribute of the component.
2. The final scrolling behavior is determined by the screen reader based on this parameter and whether the component supports scrolling.
3. This API applies to all basic components. It is recommended for scrollable components, including **List**, **Grid**, **Scroll**, and **WaterFlow**.| ## accessibilityTextHint12+ @@ -527,7 +527,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) @@ -567,3 +567,181 @@ 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 and Cross-Process Focus + +This example demonstrates the use of **accessibilityScrollTriggerable** to set whether an accessibility node supports screen reading scroll 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) + } + .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') + } +} +``` + +![accessibilityUseSamePage](figures/accessibilityUseSamePage.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 c6f432f7b2eee1606b4b300dcea69f664feb2e51..50c21e937e82eddb98c077c988157b0859b35c46 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 @@ -12,7 +12,7 @@ With the attribute modifier, you can dynamically set component attributes, compl ## 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,131 @@ 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) + + ## Supported Scope of Attributes Attributes not listed in the table below are supported by default. 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-custom-property.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-custom-property.md index 795df1346efcddc9f5a1a949ee98c762537bce43..0fd9c588f9764e059a2c94b3dc1e6a11e9dba2e9 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-custom-property.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-custom-property.md @@ -8,7 +8,7 @@ You can set custom properties on components. These custom properties can be obta ## customProperty -customProperty(name: string, value: Optional\) +customProperty(name: string, value: Optional\): T Sets a custom property for this component. This API does not work for [custom components](../../../ui/state-management/arkts-create-custom-components.md#creating-a-custom-component). @@ -18,12 +18,18 @@ Sets a custom property for this component. This API does not work for [custom co **System capability**: SystemCapability.ArkUI.ArkUI.Full -**Parameters** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type | Mandatory| Description | | ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | -| name | string | Yes | Name of the custom property. | -| value | Optional\ | Yes | Value of the custom property. | +| name | string | Yes | Name of the custom property.| +| value | Optional\ | Yes | Value of the custom property.| + +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| ## Optional12+ diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-drag-sorting.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-drag-sorting.md new file mode 100644 index 0000000000000000000000000000000000000000..329425ba86446213e405e9eeb20d096a3bcdb784 --- /dev/null +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-drag-sorting.md @@ -0,0 +1,81 @@ +# Drag-and-Drop Sorting + +By using **ForEach**, **LazyForEach**, or **Repeat** within a **List** component and setting up the **onMove** event, you can implement drag-and-drop sorting. When the drag-and-drop gesture is released, if any item's position changes, the **onMove** event is triggered, which reports the original index and target index of the relocated item. In the **onMove** event, the data source must be updated based on the reported start index and target index. Ensure that only the order of the data changes so that the drop animation can be executed properly. + +> **NOTE** +> +> 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. + +## onMove + +onMove(handler: Optional\) + +Invoked when data is moved during drag-and-drop sorting. This callback is effective only when the parent container component is [List](./ts-container-list.md) and each iteration of **ForEach**, **LazyForEach**, or **Repeat** generates a **ListItem** component. It allows you to define custom drag actions and handle various drag events. + +**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 | +| ------ | --------- | ---- | ---------- | +| handler | Optional\<[OnMoveHandler](#onmovehandler)\> | Yes | Drag operation.| + +## OnMoveHandler + +type OnMoveHandler = (from: number, to: number) => void; + +Defines the callback triggered when data is moved during drag-and-drop sorting. + +**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 | +| ------ | --------- | ---- | ---------- | +| from | number | Yes | Start index of the drag operation. The value range is [0, data source length - 1].| +| to | number | Yes | End index of the drag operation. The value range is [0, data source length - 1].| + +## Example + +This example demonstrates how to use **onMove** for drag and drop with **ForEach** in a **List** component. + +```ts +@Entry +@Component +struct ForEachSort { + @State arr: Array = []; + + build() { + Row() { + List() { + ForEach(this.arr, (item: string) => { + ListItem() { + Text(item.toString()) + .fontSize(16) + .textAlign(TextAlign.Center) + .size({height: 100, width: '100%'}) + }.margin(10) + .borderRadius(10) + .backgroundColor('#FFFFFFFF') + }, (item: string) => item) + .onMove((from:number, to:number) => { + let tmp = this.arr.splice(from, 1); + this.arr.splice(to, 0, tmp[0]); + }) + } + .width('100%') + .height('100%') + .backgroundColor('#FFDCDCDC') + } + } + aboutToAppear(): void { + for (let i = 0; i < 100; i++) { + this.arr.push(i.toString()); + } + } +} +``` diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-draw-modifier.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-draw-modifier.md index 250110aadd4bb3dcd29971b7e8ab64681dc53f8f..480510eb7745cc584b88e4d8644accb297f3466f 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-draw-modifier.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-draw-modifier.md @@ -4,11 +4,11 @@ If the drawn content of some components does not meet the requirements, you can > **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. ## drawModifier -drawModifier(modifier: DrawModifier | undefined) +drawModifier(modifier: DrawModifier | undefined): T Creates a drawing modifier. @@ -26,6 +26,12 @@ AlphabetIndexer, Badge, Blank, Button, CalendarPicker, Checkbox, CheckboxGroup, | ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | | modifier | [DrawModifier](#drawmodifier-1) \| undefined | Yes | Custom drawing modifier, which defines the logic of custom drawing.
Default value: **undefined**
**NOTE**
A custom modifier applies only to the FrameNode of the currently bound component, not to its subnodes.| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + ## DrawModifier Implements a **DrawModifier** instance for using the **drawFront**, **drawContent**, and **drawBehind** methods for custom drawing as well as the **invalidate** method for redrawing. Each **DrawModifier** instance can be set for only one component. Repeated setting is not allowed. @@ -38,7 +44,7 @@ Implements a **DrawModifier** instance for using the **drawFront**, **drawConten drawFront?(drawContext: DrawContext): void -Draws the foreground. This method can be overloaded for custom foreground drawing. +Draws the content foreground. Override this method to implement custom content foreground drawing. **Atomic service API**: This API can be used in atomic services since API version 12. @@ -54,7 +60,7 @@ Draws the foreground. This method can be overloaded for custom foreground drawin drawContent?(drawContext: DrawContext): void -Draws the content. This method can be overloaded for custom content drawing. The overloaded method will replace the original content drawing function of the component. +Draws the content. Override this method to implement custom content drawing, which will replace the component's default content drawing function. **Atomic service API**: This API can be used in atomic services since API version 12. @@ -70,7 +76,7 @@ Draws the content. This method can be overloaded for custom content drawing. The drawBehind?(drawContext: DrawContext): void -Draws the background. This method can be overloaded for custom background drawing. +Draws the background. Override this method to implement custom background drawing. **Atomic service API**: This API can be used in atomic services since API version 12. @@ -95,7 +101,7 @@ Triggers redrawing of the bound component. No overloading is allowed or needed. ## Example -This example shows how to customize the drawing of a **Text** component using **DrawModifier**. +This example shows how to implement custom drawing for a **Text** component using **DrawModifier**. ```ts // xxx.ets @@ -105,6 +111,12 @@ import { AnimatorResult } from '@kit.ArkUI'; class MyFullDrawModifier extends DrawModifier { public scaleX: number = 1; public scaleY: number = 1; + uiContext: UIContext; + + constructor(uiContext: UIContext) { + super(); + this.uiContext = uiContext; + } drawBehind(context: DrawContext): void { const brush = new drawing.Brush(); @@ -118,10 +130,10 @@ class MyFullDrawModifier extends DrawModifier { const halfWidth = context.size.width / 2; const halfHeight = context.size.width / 2; context.canvas.drawRect({ - left: vp2px(halfWidth - 50 * this.scaleX), - top: vp2px(halfHeight - 50 * this.scaleY), - right: vp2px(halfWidth + 50 * this.scaleX), - bottom: vp2px(halfHeight + 50 * this.scaleY) + left: this.uiContext.vp2px(halfWidth - 50 * this.scaleX), + top: this.uiContext.vp2px(halfHeight - 50 * this.scaleY), + right: this.uiContext.vp2px(halfWidth + 50 * this.scaleX), + bottom: this.uiContext.vp2px(halfHeight + 50 * this.scaleY) }); } @@ -137,10 +149,10 @@ class MyFullDrawModifier extends DrawModifier { const halfWidth = context.size.width / 2; const halfHeight = context.size.width / 2; context.canvas.drawRect({ - left: vp2px(halfWidth - 30 * this.scaleX), - top: vp2px(halfHeight - 30 * this.scaleY), - right: vp2px(halfWidth + 30 * this.scaleX), - bottom: vp2px(halfHeight + 30 * this.scaleY) + left: this.uiContext.vp2px(halfWidth - 30 * this.scaleX), + top: this.uiContext.vp2px(halfHeight - 30 * this.scaleY), + right: this.uiContext.vp2px(halfWidth + 30 * this.scaleX), + bottom: this.uiContext.vp2px(halfHeight + 30 * this.scaleY) }); } @@ -156,13 +168,19 @@ class MyFullDrawModifier extends DrawModifier { const halfWidth = context.size.width / 2; const halfHeight = context.size.width / 2; const radiusScale = (this.scaleX + this.scaleY) / 2; - context.canvas.drawCircle(vp2px(halfWidth), vp2px(halfHeight), vp2px(20 * radiusScale)); + context.canvas.drawCircle(this.uiContext.vp2px(halfWidth), this.uiContext.vp2px(halfHeight), this.uiContext.vp2px(20 * radiusScale)); } } class MyFrontDrawModifier extends DrawModifier { public scaleX: number = 1; public scaleY: number = 1; + uiContext: UIContext; + + constructor(uiContext: UIContext) { + super(); + this.uiContext = uiContext; + } drawFront(context: DrawContext): void { const brush = new drawing.Brush(); @@ -176,17 +194,17 @@ class MyFrontDrawModifier extends DrawModifier { const halfWidth = context.size.width / 2; const halfHeight = context.size.width / 2; const radiusScale = (this.scaleX + this.scaleY) / 2; - context.canvas.drawCircle(vp2px(halfWidth), vp2px(halfHeight), vp2px(20 * radiusScale)); + context.canvas.drawCircle(this.uiContext.vp2px(halfWidth), this.uiContext.vp2px(halfHeight), this.uiContext.vp2px(20 * radiusScale)); } } @Entry @Component struct DrawModifierExample { - private fullModifier: MyFullDrawModifier = new MyFullDrawModifier(); - private frontModifier: MyFrontDrawModifier = new MyFrontDrawModifier(); + private fullModifier: MyFullDrawModifier = new MyFullDrawModifier(this.getUIContext()); + private frontModifier: MyFrontDrawModifier = new MyFrontDrawModifier(this.getUIContext()); private drawAnimator: AnimatorResult | undefined = undefined; - @State modifier: DrawModifier = new MyFrontDrawModifier(); + @State modifier: DrawModifier = new MyFrontDrawModifier(this.getUIContext()); private count = 0; create() { diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-enable.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-enable.md index 0420f03943ec00dad6120aca1b38c50c1c850e44..73a43e6fad4047c65560e3bdf8dbb2e0b20b79eb 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-enable.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-enable.md @@ -23,7 +23,7 @@ You can enable or disable a component to control whether it responds to user int ## enabled -enabled(value: boolean) +enabled(value: boolean): T Sets whether the component responds to user interactions. diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-filter-effect.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-filter-effect.md index 7aad1873121068c3fd1d73527cf192aa828aa565..0238981db9491161dfad16bc1c38f3ca53e1251e 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-filter-effect.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-filter-effect.md @@ -22,6 +22,12 @@ Sets a visual effect that is not a filter effect. | ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | | effect | [VisualEffect](../../apis-arkgraphics2d/js-apis-uiEffect.md#visualeffect) | Yes | Visual effect.| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## backgroundFilter backgroundFilter(filter: Filter): T @@ -38,6 +44,12 @@ Sets the visual effect of the background filter. | ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | | filter | [Filter](../../apis-arkgraphics2d/js-apis-uiEffect.md#filter) | Yes | Visual effect of the background filter.| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## foregroundFilter foregroundFilter(filter: Filter): T @@ -54,6 +66,12 @@ Sets the visual effect of the foreground (content) filter. | ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | | filter | [Filter](../../apis-arkgraphics2d/js-apis-uiEffect.md#filter) | Yes | Visual effect of the foreground (content) filter.| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## compositingFilter compositingFilter(filter: Filter): T @@ -70,6 +88,11 @@ Sets the visual effect of the compositing filter. | ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | | filter | [Filter](../../apis-arkgraphics2d/js-apis-uiEffect.md#filter) | Yes | Visual effect of the compositing filter.| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| ## Example @@ -82,9 +105,9 @@ import { uiEffect } from '@kit.ArkGraphics2D'; @Entry @Component struct FilterEffectExample { - @State filterTest1: uiEffect.Filter = uiEffect.createFilter().blur(10) - @State filterTest2: uiEffect.Filter = uiEffect.createFilter().blur(10) - @State filterTest3: uiEffect.Filter = uiEffect.createFilter().blur(10) + @State filterTest1: uiEffect.Filter = uiEffect.createFilter().blur(10); + @State filterTest2: uiEffect.Filter = uiEffect.createFilter().blur(10); + @State filterTest3: uiEffect.Filter = uiEffect.createFilter().blur(10); build() { Column({ space: 15 }) { diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-effect.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-effect.md index 9556d2f6549b8c1f0bdb7151785161bc433bbb92..43568b9ad653d095f8811769449fdcd4951440c4 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-effect.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-foreground-effect.md @@ -4,11 +4,11 @@ You can apply different visual effects to foreground subjects. > **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. ## foregroundEffect -foregroundEffect(options: ForegroundEffectOptions) +foregroundEffect(options: ForegroundEffectOptions): T Sets the foreground effect of the component. @@ -22,6 +22,12 @@ Sets the foreground effect of the component. | ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | | options | [ForegroundEffectOptions](#foregroundeffectoptions12) | Yes | Foreground effect settings, including the blur radius.| +**Return value** + +| Type | Description | +| ------ | ------------------------ | +| T | Current component.| + ## ForegroundEffectOptions12+ Describes the foreground effect. @@ -57,6 +63,6 @@ struct Index { ``` Below is how the component looks with the foreground effect applied. -A larger radius results in a more pronounced blur. +**radius** indicates the blur radius. A larger value creates a more blurred effect. ![foregroundColor_circle](figures/foregroundEffect.jpg) diff --git a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-gesture-modifier.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-gesture-modifier.md index b21df2e1f2fbd350ad94141890f1448bbdcf8e31..7922883c8c407c29ff649f5099f9e615096bd2bf 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-gesture-modifier.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-gesture-modifier.md @@ -8,10 +8,14 @@ With the gesture modifier, you can dynamically set gestures bound to components, ## gestureModifier -gestureModifier(modifier: GestureModifier) +gestureModifier(modifier: GestureModifier): T Creates a gesture modifier. +> **NOTE** +> +> **gestureModifier** does not support custom components. + **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.ArkUI.ArkUI.Full @@ -22,6 +26,12 @@ Creates a gesture modifier. | -------- | --------------------- | ---- | ------------------------------------------------------------ | | modifier | [GestureModifier](#gesturemodifier-1) | Yes | Modifier for dynamically setting gestures bound to the current component. The **if/else** syntax is supported.
**modifier**: gesture modifier. You need a custom class to implement the **GestureModifier** API.| +**Return value** + +| Type| Description| +| -------- | -------- | +| T | Current component.| + ## GestureModifier You need a custom class to implement the **GestureModifier** API. @@ -31,7 +41,7 @@ applyGesture(event: UIGestureEvent): void Binds a gesture to this component. -You can customize this API as required. The **if/else** syntax is supported. +You can customize this API as required. Dynamic configuration using the **if/else** syntax is supported. If gesture switching is triggered during an active gesture operation, the new configuration will take effect in the subsequent gesture interaction after all fingers are lifted from the current gesture. **Atomic service API**: This API can be used in atomic services since API version 12. @@ -48,7 +58,7 @@ This example demonstrates how to dynamically set the gestures bound to a compone ```ts // xxx.ets class MyButtonModifier implements GestureModifier { - supportDoubleTap: boolean = true + supportDoubleTap: boolean = true; applyGesture(event: UIGestureEvent): void { if (this.supportDoubleTap) { @@ -83,6 +93,11 @@ struct Index { .width(500) .height(500) .backgroundColor(Color.Blue) + Button('changeGesture') + .onClick(() => { + this.modifier.supportDoubleTap = !this.modifier.supportDoubleTap; + }) + .margin({top: 10}) } .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-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-popup.md b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-popup.md index 0fc995b7c7c54f568c886467a1aaf2eb27251035..6f44205846c24db05cf5b69198729d1d02e9335a 100644 --- a/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-popup.md +++ b/en/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-popup.md @@ -10,7 +10,7 @@ You can bind a popup to a component, specifying its content, interaction logic, ## bindPopup -bindPopup(show: boolean, popup: PopupOptions | CustomPopupOptions) +bindPopup(show: boolean, popup: PopupOptions | CustomPopupOptions): T Binds a popup to the component. @@ -22,11 +22,13 @@ Binds a popup to the component. | Name| Type | Mandatory| Description | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| show | boolean | Yes | Whether to show the popup. The default value is **false**, indicating that the popup is hidden. The popup can be displayed only after the entire page is fully constructed. Therefore, to avoid incorrect display positions and shapes, do not set this parameter to **true** while the page is still being constructed. Since API version 13, this parameter supports two-way binding through [!!](../../../ui/state-management/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).| +| show | boolean | Yes | Whether to show the popup. The default value is **false**, indicating that the popup is hidden. The popup can be displayed only after the entire page is fully constructed. Therefore, to avoid incorrect display positions and shapes, do not set this parameter to **true** while the page is still being constructed. Since API version 13, this parameter supports two-way binding through the [!! syntax](../../../ui/state-management/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).| | popup | [PopupOptions](#popupoptions) \| [CustomPopupOptions](#custompopupoptions8)8+ | Yes | Parameters of the popup. | ## PopupOptions +**System capability**: SystemCapability.ArkUI.ArkUI.Full + | Name | Type | Mandatory| Description | | ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | message | string | Yes | Content of the popup message.
**Atomic service API**: This API can be used in atomic services since API version 11. | @@ -151,6 +153,7 @@ Parameters of the popup. Use the [getPromptAction()](../js-apis-arkui-UIContext. | transition | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the popup.
**NOTE**
1. If this parameter is not set, the default effect is used.
2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.
3. Touching the Back button during the exit animation does not affect the animation playback. The Back button does not respond.
4. The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| | onWillDismiss | boolean\|Callback<[DismissPopupAction](#dismisspopupaction12)> | No | Whether to perform dismissal event interception and interception callback. The default value is **true**.
1. If this parameter is set to **false**, the system does not respond to the dismissal event initiated by touching the Back button, swiping left or right on the screen, or pressing the Esc key; and the system dismisses the popup only when **show** is set to **false**. If this parameter is set to **true**, the system responds to the dismissal event as expected.
2. If this parameter is set to a function, the dismissal event is intercepted and the callback function is executed.
**NOTE**
1. Nesting **onWillDismiss** callbacks is not allowed.
2. The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| | followTransformOfTarget | boolean | No | Whether the popup adjusts its position to follow transformations (like rotation or scaling) applied to its host component or the host component's parent container.
Default value: **false**| +|enableHoverMode | boolean | No | Whether to enable the hover mode. If the click position of the popup component is in the crease area in the hover state, the popup component does not respond to the hover state. Default value: **false**, indicating that the popup does not respond in hover mode
**NOTE**
The popup responds in hover mode when **enableHoverMode** is set to **true** and does not when **enableHoverMode** is set to **false** or an invalid value or is not set at all.| ## PopupStateChangeParam18+ @@ -180,12 +183,6 @@ type PopupStateChangeCallback = (event: PopupStateChangeParam) => void; | --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | | event | [PopupStateChangeParam](#popupstatechangeparam18) | Yes | Display state of the popup. | -**Return value** - -| Type | Description | -| ---------------------------------------- | ------- | -| void | Callback invoked when the popup state changes.| - ## PopupMaskType18+ Describes the color of the mask. @@ -236,22 +233,22 @@ struct PopupExample { primaryButton: { value: 'confirm', action: () => { - this.handlePopup = !this.handlePopup - console.info('confirm Button click') + this.handlePopup = !this.handlePopup; + console.info('confirm Button click'); } }, // Secondary button secondaryButton: { value: 'cancel', action: () => { - this.handlePopup = !this.handlePopup - console.info('cancel Button click') + this.handlePopup = !this.handlePopup; + console.info('cancel Button click'); } }, onStateChange: (e) => { console.info(JSON.stringify(e.isVisible)) if (!e.isVisible) { - this.handlePopup = false + this.handlePopup = false; } } }) @@ -261,7 +258,7 @@ struct PopupExample { // CustomPopupOptions for setting the popup Button('CustomPopupOptions') .onClick(() => { - this.customPopup = !this.customPopup + this.customPopup = !this.customPopup; }) .bindPopup(this.customPopup, { builder: this.popupBuilder, @@ -274,7 +271,7 @@ struct PopupExample { showInSubWindow: false, onStateChange: (e) => { if (!e.isVisible) { - this.customPopup = false + this.customPopup = false; } } }) @@ -320,9 +317,9 @@ struct PopupExample { enableArrow: false, // Set the arrow not to display. targetSpace: '15vp', onStateChange: (e) => { - console.info(JSON.stringify(e.isVisible)) + console.info(JSON.stringify(e.isVisible)); if (!e.isVisible) { - this.handlePopup = false + this.handlePopup = false; } } }) @@ -343,8 +340,8 @@ This example demonstrates how to use the **bindPopup** API with properties like @Entry @Component struct PopupExample { - @State customPopup: boolean = false - @State handlePopup: boolean = false + @State customPopup: boolean = false; + @State handlePopup: boolean = false; build() { Column({ space: 100 }) { @@ -363,7 +360,7 @@ struct PopupExample { Button('PopupOptions') .onClick(() => { - this.handlePopup = !this.handlePopup + this.handlePopup = !this.handlePopup; }) .bindPopup(this.handlePopup, { width: 300, @@ -390,8 +387,8 @@ In this example, the **bindPopup** API is used with the **transition** property @Entry @Component struct PopupExample { - @State handlePopup: boolean = false - @State customPopup: boolean = false + @State handlePopup: boolean = false; + @State customPopup: boolean = false; // Popup builder @Builder popupBuilder() { @@ -405,7 +402,7 @@ struct PopupExample { // PopupOptions for setting the popup Button('PopupOptions') .onClick(() => { - this.handlePopup = !this.handlePopup + this.handlePopup = !this.handlePopup; }) .bindPopup(this.handlePopup, { message: 'This is a popup with transitionEffect', @@ -414,7 +411,7 @@ struct PopupExample { onStateChange: (e) => { console.info(JSON.stringify(e.isVisible)) if (!e.isVisible) { - this.handlePopup = false + this.handlePopup = false; } }, // Set the popup animation to a combination of opacity and translation effects, with no exit animation. @@ -428,7 +425,7 @@ struct PopupExample { // CustomPopupOptions for setting the popup Button('CustomPopupOptions') .onClick(() => { - this.customPopup = !this.customPopup + this.customPopup = !this.customPopup; }) .bindPopup(this.customPopup, { builder: this.popupBuilder, @@ -436,7 +433,7 @@ struct PopupExample { showInSubWindow: false, onStateChange: (e) => { if (!e.isVisible) { - this.customPopup = false + this.customPopup = false; } }, // Set the popup entrance and exit animations to be a scaling effect. @@ -460,12 +457,12 @@ This example uses the **bindPopup** API with the **onWillDismiss** property to i @Entry @Component struct PopupExample { - @State handlePopup: boolean = false + @State handlePopup: boolean = false; build() { Column() { Button('PopupOptions') .onClick(() => { - this.handlePopup = true + this.handlePopup = true; }) .bindPopup(this.handlePopup, { message: 'This is a popup with PopupOptions', @@ -482,14 +479,14 @@ struct PopupExample { targetSpace: '15vp', onStateChange: (e) => { if (!e.isVisible) { - this.handlePopup = false + this.handlePopup = false; } }, onWillDismiss: ( (dismissPopupAction: DismissPopupAction) => { - console.info("dismissReason:" + JSON.stringify(dismissPopupAction.reason)) - if (dismissPopupAction.reason == DismissReason.PRESS_BACK) { - dismissPopupAction.dismiss() + console.info("dismissReason:" + JSON.stringify(dismissPopupAction.reason)); + if (dismissPopupAction.reason === DismissReason.PRESS_BACK) { + dismissPopupAction.dismiss(); } } ) @@ -511,12 +508,13 @@ In this example, the **onWillDismiss** property is set to **false** to intercept @Entry @Component struct PopupExample { - @State handlePopup: boolean = false + @State handlePopup: boolean = false; + build() { Column() { Button('PopupOptions') .onClick(() => { - this.handlePopup = true + this.handlePopup = true; }) .bindPopup(this.handlePopup, { message: 'This is a popup with PopupOptions', @@ -533,10 +531,12 @@ struct PopupExample { targetSpace: '15vp', followTransformOfTarget: true, onStateChange: (e) => { - let timer = setTimeout(()=>{this.handlePopup = false},6000) + let timer = setTimeout(() => { + this.handlePopup = false; + }, 6000); if (!e.isVisible) { - this.handlePopup = false - clearTimeout(timer) + this.handlePopup = false; + clearTimeout(timer); } }, onWillDismiss: false 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..572b0ebcaac3c1f046f1ceda51677b4b68bac1e0 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), the **shape** parameter supports the **undefined** type. -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..db92f31397ce1d2b51c467b998ca9d896ecf896b 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. @@ -74,9 +88,15 @@ Sets the width of the component or its horizontal layout policy. By default, the | ----- | ---------------------------- | ---- | ------------------- | | widthValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Width of the component to set.
Unit: vp| +**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. @@ -92,15 +112,21 @@ Sets the height of the component or its vertical layout policy. By default, the | ----- | ---------------------------- | ---- | ------------------- | | heightValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Height of the component to set.
Unit: vp| +**Return value** + +| Type| Description| +| --- | --- | +| T | Current component.| + > **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. +> The **width** and **height** attributes of the [Row](./ts-container-row.md) and [Column](./ts-container-column.md) components support parameters of the [LayoutPolicy](ts-types.md#layoutpolicy15) type. ## 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 +142,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 +168,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 +194,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. **Widget capability**: This API can be used in ArkTS widgets since API version 14. @@ -174,11 +218,17 @@ 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.| + ## 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 +240,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 +268,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 +290,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 +303,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 +324,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 +337,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 +348,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 +373,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 +389,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 +400,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 +411,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 +437,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 }) } } ``` 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 13b08a4a54476a1d0c2be5f11265ee60f29e2f9e..c636790b88b92db6894f97c635b9f672b2caafd4 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 @@ -26,7 +26,7 @@ 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: 16,arrowHeight: 8vp,
showAtAnchor: TipsAnchorType.TARGET
} | +| 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
} | **Return value** 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 8f99e6303e1573a574e0d97e8eee02e2bc0eb413..2e39cddc8422033219088ac4bcf8ba81213182cc 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 @@ -9,7 +9,7 @@ The **useEffect** attribute is used to combine the drawing of special effects, s ## useEffect -useEffect(value: boolean) +useEffect(value: boolean): T Specifies whether to combine the drawing of special effects, such as background blur. @@ -21,11 +21,17 @@ Specifies whether to combine the drawing of special effects, such as background | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| value | boolean | Yes| Whether the component inherits the special effect settings of the **EffectComponent** component.
The value **true** means that the component inherits the special effect settings of the **EffectComponent** component, and **false** means the opposite.
Default value: **false**| +| 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,11 +46,17 @@ 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. +Specifies whether to apply the effect defined by the parent [EffectComponent](ts-container-effectcomponent-sys.md) or the window. Compared to [useEffect14+](#useeffect), the **useEffect** parameter supports the **undefined** type. **Atomic service API**: This API can be used in atomic services since API version 18. @@ -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,16 +92,18 @@ 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 This example shows how to combine the drawing of special effects, including background blur. + + ```ts //Index.ets @Entry 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/native__interface__xcomponent_8h.md b/en/application-dev/reference/apis-arkui/native__interface__xcomponent_8h.md index 1ffd780f23b4de2cb3467dc9d957ad3030f86617..8b4c9afc12ce0378c5956dab47d919228df52510 100644 --- a/en/application-dev/reference/apis-arkui/native__interface__xcomponent_8h.md +++ b/en/application-dev/reference/apis-arkui/native__interface__xcomponent_8h.md @@ -7,7 +7,7 @@ Declares the APIs for accessing **NativeXComponent**. **Library**: libace_ndk.z.so -**Header file**: +**File to include**: **Since**: 8 @@ -22,7 +22,8 @@ Declares the APIs for accessing **NativeXComponent**. | Name| Description| | -------- | -------- | | struct [OH_NativeXComponent_TouchPoint](_o_h___native_x_component___touch_point.md) | Describes the touch point of the touch event.| -| struct [OH_NativeXComponent_TouchEvent](_o_h___native_x_component___touch_event.md) | Describes the touch event. | +| struct [OH_NativeXComponent_TouchEvent](_o_h___native_x_component___touch_event.md) | Defines the touch event. | +| struct [OH_NativeXComponent_HistoricalPoint](_o_h___native_x_component___historical_point.md) | Defines the historical touch point.| | struct [OH_NativeXComponent_MouseEvent](_o_h___native_x_component___mouse_event.md) | Describes the mouse event. | | struct [OH_NativeXComponent_Callback](_o_h___native_x_component___callback.md) | Registers callbacks for the surface lifecycle and touch event. | | struct [OH_NativeXComponent_MouseEvent_Callback](_o_h___native_x_component___mouse_event___callback.md) | Registers callbacks for the mouse event. | @@ -33,40 +34,51 @@ Declares the APIs for accessing **NativeXComponent**. | Name| Description| | -------- | -------- | -| typedef struct [OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent)[OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) | Provides an encapsulated **OH_NativeXComponent** instance. | -| typedef struct [OH_NativeXComponent_Callback](_o_h___native_x_component___callback.md)[OH_NativeXComponent_Callback](_o_h___native_x_component.md#oh_nativexcomponent_callback) | Registers callbacks for the surface lifecycle and touch event. | -| typedef struct [OH_NativeXComponent_MouseEvent_Callback](_o_h___native_x_component___mouse_event___callback.md)[OH_NativeXComponent_MouseEvent_Callback](_o_h___native_x_component.md#oh_nativexcomponent_mouseevent_callback) | Registers callbacks for the mouse event. | -| typedef struct [OH_NativeXComponent_KeyEvent](_o_h___native_x_component.md#oh_nativexcomponent_keyevent)[OH_NativeXComponent_KeyEvent](_o_h___native_x_component.md#oh_nativexcomponent_keyevent) | Provides an encapsulated **OH_NativeXComponent_KeyEvent** instance. | +| typedef struct [OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) [OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) | Provides an encapsulated **OH_NativeXComponent** instance. | +| typedef struct [OH_NativeXComponent_Callback](_o_h___native_x_component___callback.md) [OH_NativeXComponent_Callback](_o_h___native_x_component.md#oh_nativexcomponent_callback) | Registers callbacks for the surface lifecycle and touch event. | +| typedef struct [OH_NativeXComponent_MouseEvent_Callback](_o_h___native_x_component___mouse_event___callback.md) [OH_NativeXComponent_MouseEvent_Callback](_o_h___native_x_component.md#oh_nativexcomponent_mouseevent_callback) | Registers callbacks for the mouse event. | +| typedef struct [OH_NativeXComponent_KeyEvent](_o_h___native_x_component.md#oh_nativexcomponent_keyevent) [OH_NativeXComponent_KeyEvent](_o_h___native_x_component.md#oh_nativexcomponent_keyevent) | Provides an encapsulated **OH_NativeXComponent_KeyEvent** instance.| +| typedef struct [OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback) [OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback) | Defines Surface lifecycle callback functions.| +| typedef struct [OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder) [OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder) | Provides an encapsulated **OH_ArkUI_SurfaceHolder** instance.| +| typedef struct NativeWindow [OHNativeWindow](_o_h___native_x_component.md#ohnativewindow) | Provides an encapsulated **NativeWindow** instance.| ### Enums | Name| Description| | -------- | -------- | -| { [OH_NATIVEXCOMPONENT_RESULT_SUCCESS](_o_h___native_x_component.md) = 0, [OH_NATIVEXCOMPONENT_RESULT_FAILED](_o_h___native_x_component.md) = -1, [OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER](_o_h___native_x_component.md) = -2 } | Enumerates the API access states. | -| [OH_NativeXComponent_TouchEventType](_o_h___native_x_component.md#oh_nativexcomponent_toucheventtype) {
[OH_NATIVEXCOMPONENT_DOWN](_o_h___native_x_component.md) = 0, [OH_NATIVEXCOMPONENT_UP](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_MOVE](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_CANCEL](_o_h___native_x_component.md),
[OH_NATIVEXCOMPONENT_UNKNOWN](_o_h___native_x_component.md)
} | Enumerates the touch event types. | -| [OH_NativeXComponent_TouchPointToolType](_o_h___native_x_component.md#oh_nativexcomponent_touchpointtooltype) {
[OH_NATIVEXCOMPONENT_TOOL_TYPE_UNKNOWN](_o_h___native_x_component.md) = 0, [OH_NATIVEXCOMPONENT_TOOL_TYPE_FINGER](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_TOOL_TYPE_PEN](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_TOOL_TYPE_RUBBER](_o_h___native_x_component.md),
[OH_NATIVEXCOMPONENT_TOOL_TYPE_BRUSH](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_TOOL_TYPE_PENCIL](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_TOOL_TYPE_AIRBRUSH](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_TOOL_TYPE_MOUSE](_o_h___native_x_component.md),
[OH_NATIVEXCOMPONENT_TOOL_TYPE_LENS](_o_h___native_x_component.md)
} | Enumerates the touch point tool types. | -| [OH_NativeXComponent_EventSourceType](_o_h___native_x_component.md#oh_nativexcomponent_eventsourcetype) {
[OH_NATIVEXCOMPONENT_SOURCE_TYPE_UNKNOWN](_o_h___native_x_component.md) = 0, [OH_NATIVEXCOMPONENT_SOURCE_TYPE_MOUSE](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHSCREEN](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHPAD](_o_h___native_x_component.md),
[OH_NATIVEXCOMPONENT_SOURCE_TYPE_JOYSTICK](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_SOURCE_TYPE_KEYBOARD](_o_h___native_x_component.md)
} | Enumerates the touch event source types. | -| [OH_NativeXComponent_MouseEventAction](_o_h___native_x_component.md#oh_nativexcomponent_mouseeventaction) { [OH_NATIVEXCOMPONENT_MOUSE_NONE](_o_h___native_x_component.md) = 0, [OH_NATIVEXCOMPONENT_MOUSE_PRESS](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_MOUSE_RELEASE](_o_h___native_x_component.md), [OH_NATIVEXCOMPONENT_MOUSE_MOVE](_o_h___native_x_component.md) } | Enumerates the mouse event actions. | -| [OH_NativeXComponent_MouseEventButton](_o_h___native_x_component.md#oh_nativexcomponent_mouseeventbutton) {
[OH_NATIVEXCOMPONENT_NONE_BUTTON](_o_h___native_x_component.md) = 0, [OH_NATIVEXCOMPONENT_LEFT_BUTTON](_o_h___native_x_component.md) = 0x01, [OH_NATIVEXCOMPONENT_RIGHT_BUTTON](_o_h___native_x_component.md) = 0x02, [OH_NATIVEXCOMPONENT_MIDDLE_BUTTON](_o_h___native_x_component.md) = 0x04,
[OH_NATIVEXCOMPONENT_BACK_BUTTON](_o_h___native_x_component.md) = 0x08, [OH_NATIVEXCOMPONENT_FORWARD_BUTTON](_o_h___native_x_component.md) = 0x10
} | Enumerates the mouse event buttons. | +| { OH_NATIVEXCOMPONENT_RESULT_SUCCESS = 0, OH_NATIVEXCOMPONENT_RESULT_FAILED = -1, OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER = -2 } | Enumerates the API access states. | +| [OH_NativeXComponent_TouchEventType](_o_h___native_x_component.md#oh_nativexcomponent_toucheventtype) {
OH_NATIVEXCOMPONENT_DOWN = 0, OH_NATIVEXCOMPONENT_UP, OH_NATIVEXCOMPONENT_MOVE, OH_NATIVEXCOMPONENT_CANCEL,
OH_NATIVEXCOMPONENT_UNKNOWN
} | Enumerates the touch event types. | +| [OH_NativeXComponent_TouchPointToolType](_o_h___native_x_component.md#oh_nativexcomponent_touchpointtooltype) {
OH_NATIVEXCOMPONENT_TOOL_TYPE_UNKNOWN = 0, OH_NATIVEXCOMPONENT_TOOL_TYPE_FINGER, OH_NATIVEXCOMPONENT_TOOL_TYPE_PEN, OH_NATIVEXCOMPONENT_TOOL_TYPE_RUBBER,
OH_NATIVEXCOMPONENT_TOOL_TYPE_BRUSH, OH_NATIVEXCOMPONENT_TOOL_TYPE_PENCIL, OH_NATIVEXCOMPONENT_TOOL_TYPE_AIRBRUSH, OH_NATIVEXCOMPONENT_TOOL_TYPE_MOUSE,
OH_NATIVEXCOMPONENT_TOOL_TYPE_LENS
} | Enumerates the touch point tool types. | +| [OH_NativeXComponent_EventSourceType](_o_h___native_x_component.md#oh_nativexcomponent_eventsourcetype) {
OH_NATIVEXCOMPONENT_SOURCE_TYPE_UNKNOWN = 0, OH_NATIVEXCOMPONENT_SOURCE_TYPE_MOUSE, OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHSCREEN, OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHPAD,
OH_NATIVEXCOMPONENT_SOURCE_TYPE_JOYSTICK, OH_NATIVEXCOMPONENT_SOURCE_TYPE_KEYBOARD
} | Enumerates the touch event source types. | +| [OH_NativeXComponent_TouchEvent_SourceTool](_o_h___native_x_component.md#oh_nativexcomponent_touchevent_sourcetool) {
OH_NATIVEXCOMPONENT_SOURCETOOL_UNKNOWN = 0, OH_NATIVEXCOMPONENT_SOURCETOOL_FINGER, OH_NATIVEXCOMPONENT_SOURCETOOL_PEN, OH_NATIVEXCOMPONENT_SOURCETOOL_RUBBER,
OH_NATIVEXCOMPONENT_SOURCETOOL_BRUSH, OH_NATIVEXCOMPONENT_SOURCETOOL_PENCIL, OH_NATIVEXCOMPONENT_SOURCETOOL_AIRBRUSH, OH_NATIVEXCOMPONENT_SOURCETOOL_MOUSE,
OH_NATIVEXCOMPONENT_SOURCETOOL_LENS, OH_NATIVEXCOMPONENT_SOURCETOOL_TOUCHPAD
} | Enumerates the source tool types of touch events.| +| [OH_NativeXComponent_MouseEventAction](_o_h___native_x_component.md#oh_nativexcomponent_mouseeventaction) {
OH_NATIVEXCOMPONENT_MOUSE_NONE = 0, OH_NATIVEXCOMPONENT_MOUSE_PRESS, OH_NATIVEXCOMPONENT_MOUSE_RELEASE, OH_NATIVEXCOMPONENT_MOUSE_MOVE,
OH_NATIVEXCOMPONENT_MOUSE_CANCEL
} | Enumerates mouse event actions.| +| [OH_NativeXComponent_MouseEventButton](_o_h___native_x_component.md#oh_nativexcomponent_mouseeventbutton) {
OH_NATIVEXCOMPONENT_NONE_BUTTON = 0, OH_NATIVEXCOMPONENT_LEFT_BUTTON = 0x01, OH_NATIVEXCOMPONENT_RIGHT_BUTTON = 0x02, OH_NATIVEXCOMPONENT_MIDDLE_BUTTON = 0x04,
OH_NATIVEXCOMPONENT_BACK_BUTTON = 0x08, OH_NATIVEXCOMPONENT_FORWARD_BUTTON = 0x10
} | Enumerates the mouse event buttons. | +|[ArkUI_XComponent_ImageAnalyzerState](_o_h___native_x_component.md#arkui_xcomponent_imageanalyzerstate) { ARKUI_XCOMPONENT_AI_ANALYSIS_FINISHED = 0, ARKUI_XCOMPONENT_AI_ANALYSIS_DISABLED = 110000, ARKUI_XCOMPONENT_AI_ANALYSIS_UNSUPPORTED = 110001, ARKUI_XCOMPONENT_AI_ANALYSIS_ONGOING = 110002, ARKUI_XCOMPONENT_AI_ANALYSIS_STOPPED = 110003}|Enumerates the AI image analyzer error codes of the XComponent.| ### Functions | Name| Description| | -------- | -------- | -| int32_t [OH_NativeXComponent_GetXComponentId](_o_h___native_x_component.md#oh_nativexcomponent_getxcomponentid) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, char \*id, uint64_t \*size) | Obtains the ID of ArkUI XComponent. | +| int32_t [OH_NativeXComponent_GetXComponentId](_o_h___native_x_component.md#oh_nativexcomponent_getxcomponentid) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, char \*id, uint64_t \*size) | Obtain the ID of ArkUI XComponent. | | int32_t [OH_NativeXComponent_GetXComponentSize](_o_h___native_x_component.md#oh_nativexcomponent_getxcomponentsize) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, const void \*window, uint64_t \*width, uint64_t \*height) | Obtains the size of the surface held by the ArkUI XComponent. | | int32_t [OH_NativeXComponent_GetXComponentOffset](_o_h___native_x_component.md#oh_nativexcomponent_getxcomponentoffset) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, const void \*window, double \*x, double \*y) | Obtains the offset of the ArkUI XComponent relative to the upper left vertex of the screen. | | int32_t [OH_NativeXComponent_GetTouchEvent](_o_h___native_x_component.md#oh_nativexcomponent_gettouchevent) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, const void \*window, [OH_NativeXComponent_TouchEvent](_o_h___native_x_component___touch_event.md) \*touchEvent) | Obtains the touch event scheduled by the ArkUI XComponent. | | int32_t [OH_NativeXComponent_GetTouchPointToolType](_o_h___native_x_component.md#oh_nativexcomponent_gettouchpointtooltype) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, uint32_t pointIndex, [OH_NativeXComponent_TouchPointToolType](_o_h___native_x_component.md#oh_nativexcomponent_touchpointtooltype) \*toolType) | Obtains the ArkUI XComponent touch point tool type. | | int32_t [OH_NativeXComponent_GetTouchPointTiltX](_o_h___native_x_component.md#oh_nativexcomponent_gettouchpointtiltx) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, uint32_t pointIndex, float \*tiltX) | Obtains the angle between the Y-Z plane of the ArkUI XComponent touch point and the x-axis. | | int32_t [OH_NativeXComponent_GetTouchPointTiltY](_o_h___native_x_component.md#oh_nativexcomponent_gettouchpointtilty) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, uint32_t pointIndex, float \*tiltY) | Obtains the angle between the X-Z plane of the ArkUI XComponent touch point and the y-axis. | +| int32_t [OH_NativeXComponent_GetTouchPointWindowX](_o_h___native_x_component.md#oh_nativexcomponent_gettouchpointwindowx) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, uint32_t pointIndex, float \*windowX) | Obtains the X coordinate of the touch point relative to the upper left corner of the application window where the ArkUI XComponent is located. | +| int32_t [OH_NativeXComponent_GetTouchPointWindowY](_o_h___native_x_component.md#oh_nativexcomponent_gettouchpointwindowy) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, uint32_t pointIndex, float \*windowY) | Obtains the Y coordinate of the touch point relative to the upper left corner of the application window where the ArkUI XComponent is located. | +| int32_t [OH_NativeXComponent_GetTouchPointDisplayX](_o_h___native_x_component.md#oh_nativexcomponent_gettouchpointdisplayx) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, uint32_t pointIndex, float \*displayX) | Obtains the X coordinate of the touch point relative to the upper left corner of the screen where the ArkUI XComponent is located. | +| int32_t [OH_NativeXComponent_GetTouchPointDisplayY](_o_h___native_x_component.md#oh_nativexcomponent_gettouchpointdisplayy) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, uint32_t pointIndex, float \*displayY) | Obtains the Y coordinate of the touch point relative to the upper left corner of the screen where the ArkUI XComponent is located. | +| int32_t [OH_NativeXComponent_GetHistoricalPoints](_o_h___native_x_component.md#oh_nativexcomponent_gethistoricalpoints) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, const void \*window, int32_t \*size, [OH_NativeXComponent_HistoricalPoint](_o_h___native_x_component___historical_point.md) \*\*historicalPoints) | Obtains the historical touch points of the XComponent. | | int32_t [OH_NativeXComponent_GetMouseEvent](_o_h___native_x_component.md#oh_nativexcomponent_getmouseevent) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, const void \*window, [OH_NativeXComponent_MouseEvent](_o_h___native_x_component___mouse_event.md) \*mouseEvent) | Obtains the mouse event scheduled by ArkUI XComponent. | | int32_t [OH_NativeXComponent_RegisterCallback](_o_h___native_x_component.md#oh_nativexcomponent_registercallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [OH_NativeXComponent_Callback](_o_h___native_x_component___callback.md) \*callback) | Registers a callback for this **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_RegisterMouseEventCallback](_o_h___native_x_component.md#oh_nativexcomponent_registermouseeventcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [OH_NativeXComponent_MouseEvent_Callback](_o_h___native_x_component___mouse_event___callback.md) \*callback) | Registers the mouse event callback for this **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_RegisterFocusEventCallback](_o_h___native_x_component.md#oh_nativexcomponent_registerfocuseventcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void \*window)) | Registers the focus obtaining event callback for this **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_RegisterKeyEventCallback](_o_h___native_x_component.md#oh_nativexcomponent_registerkeyeventcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void \*window)) | Registers the key event callback for this **OH_NativeXComponent** instance. | +| int32_t [OH_NativeXComponent_RegisterKeyEventCallbackWithResult](_o_h___native_x_component.md#oh_nativexcomponent_registerkeyeventcallbackwithresult) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, bool(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void \*window)) | Registers a key event callback with a return value for this **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_RegisterBlurEventCallback](_o_h___native_x_component.md#oh_nativexcomponent_registerblureventcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void \*window)) | Registers the focus loss event callback for this **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_GetKeyEvent](_o_h___native_x_component.md#oh_nativexcomponent_getkeyevent) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [OH_NativeXComponent_KeyEvent](_o_h___native_x_component.md#oh_nativexcomponent_keyevent) \*\*keyEvent) | Obtains the key event scheduled by ArkUI XComponent. | | int32_t [OH_NativeXComponent_GetKeyEventAction](_o_h___native_x_component.md#oh_nativexcomponent_getkeyeventaction) ([OH_NativeXComponent_KeyEvent](_o_h___native_x_component.md#oh_nativexcomponent_keyevent) \*keyEvent, [OH_NativeXComponent_KeyAction](_o_h___native_x_component.md#oh_nativexcomponent_keyaction) \*action) | Obtains the action of the specified key event. | @@ -80,12 +92,33 @@ Declares the APIs for accessing **NativeXComponent**. | int32_t [OH_NativeXComponent_AttachNativeRootNode](_o_h___native_x_component.md#oh_nativexcomponent_attachnativerootnode) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) root) | Attaches the UI component created through the native API of ArkUI to this **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_DetachNativeRootNode](_o_h___native_x_component.md#oh_nativexcomponent_detachnativerootnode) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) root) | Detaches the native component of ArkUI from this **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_RegisterUIInputEventCallback](_o_h___native_x_component.md#oh_nativexcomponent_registeruiinputeventcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [ArkUI_UIInputEvent](_ark_u_i___event_module.md#arkui_uiinputevent) \*event, [ArkUI_UIInputEvent_Type](_ark_u_i___event_module.md#arkui_uiinputevent_type) type), [ArkUI_UIInputEvent_Type](_ark_u_i___event_module.md#arkui_uiinputevent_type) type) | Registers a UI input event callback for an **OH_NativeXComponent** instance and enables the callback to be invoked when a UI input event is received. | -| int32_t [OH_NativeXComponent_RegisterOnTouchInterceptCallback](_o_h___native_x_component.md#oh_nativexcomponent_registerontouchinterceptcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [HitTestMode](_ark_u_i___native_module.md#arkui_hittestmode)(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [ArkUI_UIInputEvent](_ark_u_i___event_module.md#arkui_uiinputevent) \*event)) | Registers a custom event intercept callback for an **OH_NativeXComponent** and enables the callback during the hit test. | +| int32_t [OH_NativeXComponent_RegisterOnTouchInterceptCallback](_o_h___native_x_component.md#oh_nativexcomponent_registerontouchinterceptcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [HitTestMode](_ark_u_i___event_module.md#hittestmode)(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [ArkUI_UIInputEvent](_ark_u_i___event_module.md#arkui_uiinputevent) \*event)) | Registers a custom event intercept callback for an **OH_NativeXComponent** and enables the callback during the hit test. | | int32_t [OH_NativeXComponent_SetNeedSoftKeyboard](_o_h___native_x_component.md#oh_nativexcomponent_setneedsoftkeyboard) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, bool needSoftKeyboard) | Sets whether the soft keyboard is required for an **OH_NativeXComponent** instance. | | int32_t [OH_NativeXComponent_RegisterSurfaceShowCallback](_o_h___native_x_component.md#oh_nativexcomponent_registersurfaceshowcallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void \*window)) | Registers a surface display callback for an **OH_NativeXComponent** instance. The callback is invoked whenever the application is switched to the foreground. | | int32_t [OH_NativeXComponent_RegisterSurfaceHideCallback](_o_h___native_x_component.md#oh_nativexcomponent_registersurfacehidecallback) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void \*window)) | Registers a surface hiding callback for an **OH_NativeXComponent** instance. The callback is invoked whenever the application is switched to the background. | | int32_t [OH_NativeXComponent_GetTouchEventSourceType](_o_h___native_x_component.md#oh_nativexcomponent_gettoucheventsourcetype) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, int32_t pointId, [OH_NativeXComponent_EventSourceType](_o_h___native_x_component.md#oh_nativexcomponent_eventsourcetype) \*sourceType) | Obtains the touch event source type of an **OH_NativeXComponent** instance. | | [OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \* [OH_NativeXComponent_GetNativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent_getnativexcomponent) ([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node) | Obtains the pointer to an **OH_NativeXComponent** instance based on the specified component instance created by the native API. | +| int32_t [OH_NativeXComponent_GetNativeAccessibilityProvider](_o_h___native_x_component.md#oh_nativexcomponent_getnativeaccessibilityprovider) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, [ArkUI_AccessibilityProvider](./arkui_native_interface_accessibility.md#arkui_accessibilityprovider) \*\*handle) | Obtains the accessibility provider handle for an ArkUI XComponent. | +| int32_t [OH_NativeXComponent_RegisterKeyEventCallbackWithResult](_o_h___native_x_component.md#oh_nativexcomponent_registerkeyeventcallbackwithresult) ([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, bool(\*callback)([OH_NativeXComponent](_o_h___native_x_component.md#oh_nativexcomponent) \*component, void \*window)) | Registers a key event callback with a return value for this **OH_NativeXComponent** instance. | +|int32_t [OH_ArkUI_XComponent_StartImageAnalyzer](_o_h___native_x_component.md#oh_arkui_xcomponent_startimageanalyzer) ([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node, void \*userData,void (\*callback)([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node, [ArkUI_XComponent_ImageAnalyzerState](_o_h___native_x_component.md#arkui_xcomponent_imageanalyzerstate) statusCode, void \*userData))|Starts AI image analysis for this XComponent instance.| +|int32_t [OH_ArkUI_XComponent_StopImageAnalyzer](_o_h___native_x_component.md#oh_arkui_xcomponent_stopimageanalyzer)([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node)|Stops AI image analysis for this XComponent instance.| +|[OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback)* [OH_ArkUI_SurfaceCallback_Create](_o_h___native_x_component.md#oh_arkui_surfacecallback_create)()|Creates an **OH_ArkUI_SurfaceCallback** object.| +|void [OH_ArkUI_SurfaceCallback_Dispose](_o_h___native_x_component.md#oh_arkui_surfacecallback_dispose)([OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback)* callback)|Disposes of an **OH_ArkUI_SurfaceCallback** object.| +|[OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)* [OH_ArkUI_SurfaceHolder_Create](_o_h___native_x_component.md#oh_arkui_surfaceholder_create)([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node)|Creates an **OH_ArkUI_SurfaceHolder** object for an XComponent.| +|void [OH_ArkUI_SurfaceHolder_Dispose](_o_h___native_x_component.md#oh_arkui_surfaceholder_dispose)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)* surfaceHolder)|Disposes of an **OH_ArkUI_SurfaceHolder** object.| +|int32_t [OH_ArkUI_SurfaceHolder_SetUserData](_o_h___native_x_component.md#oh_arkui_surfaceholder_setuserdata)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)* surfaceHolder,void* userData)|Stores custom data in an **OH_ArkUI_SurfaceHolder** instance.| +|void* [OH_ArkUI_SurfaceHolder_GetUserData](_o_h___native_x_component.md#oh_arkui_surfaceholder_getuserdata)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)* surfaceHolder)|Obtains the custom data stored in an **OH_ArkUI_SurfaceHolder** instance.| +|void [OH_ArkUI_SurfaceCallback_SetSurfaceCreatedEvent](_o_h___native_x_component.md#oh_arkui_surfacecallback_setsurfacecreatedevent)([OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback)* callback,void (\*onSurfaceCreated)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)\* surfaceHolder))|Sets the creation callback event in the Surface lifecycle callback.| +|void [OH_ArkUI_SurfaceCallback_SetSurfaceChangedEvent](_o_h___native_x_component.md#oh_arkui_surfacecallback_setsurfacechangedevent)([OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback)* callback,void (\*onSurfaceChanged)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)\* surfaceHolder,uint64_t width,uint64_t height))|Sets the size change callback event in the Surface lifecycle callback. | +|void [OH_ArkUI_SurfaceCallback_SetSurfaceDestroyedEvent](_o_h___native_x_component.md#oh_arkui_surfacecallback_setsurfacedestroyedevent)([OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback)* callback,void (\*onSurfaceDestroyed)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)\* surfaceHolder))|Sets the destruction callback event in the Surface lifecycle callback.| +|int32_t [OH_ArkUI_SurfaceHolder_AddSurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfaceholder_addsurfacecallback)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)* surfaceHolder,[OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback)* callback)|Adds a Surface lifecycle callback to an **OH_ArkUI_SurfaceHolder** instance.| +|int32_t [OH_ArkUI_SurfaceHolder_RemoveSurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfaceholder_removesurfacecallback)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)* surfaceHolder,[OH_ArkUI_SurfaceCallback](_o_h___native_x_component.md#oh_arkui_surfacecallback)* callback)|Removes a previously added Surface lifecycle callback from an **OH_ArkUI_SurfaceHolder** instance.| +|[OHNativeWindow](_o_h___native_x_component.md#ohnativewindow)* [OH_ArkUI_XComponent_GetNativeWindow](_o_h___native_x_component.md#oh_arkui_xcomponent_getnativewindow)([OH_ArkUI_SurfaceHolder](_o_h___native_x_component.md#oh_arkui_surfaceholder)* surfaceHolder)|Obtains the **NativeWindow** instance associated with an **OH_ArkUI_SurfaceHolder** instance.| +|int32_t [OH_ArkUI_XComponent_SetAutoInitialize](_o_h___native_x_component.md#oh_arkui_xcomponent_setautoinitialize)([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node,bool autoInitialize)|Sets whether the XComponent needs to automatically initialize the Surface.| +|int32_t [OH_ArkUI_XComponent_Initialize](_o_h___native_x_component.md#oh_arkui_xcomponent_initialize)([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node)|Initializes the Surface held by the XComponent.| +|int32_t [OH_ArkUI_XComponent_Finalize](_o_h___native_x_component.md#oh_arkui_xcomponent_finalize)([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node)|Destroys the Surface held by the XComponent.| +|int32_t [OH_ArkUI_XComponent_IsInitialized](_o_h___native_x_component.md#oh_arkui_xcomponent_isinitialized)([ArkUI_NodeHandle](_ark_u_i___native_module.md#arkui_nodehandle) node, bool* isInitialized)|Checks whether the Surface held by the XComponent is initialized.| + ### Variables