Update docs (20778)

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>

en/application-dev/faqs/faqs-arkui-arkts.md

@@ -760,147 +760,6 @@ Text in the **\<Text>** component is centered by default. You do not need to set
 
 [Text](../reference/arkui-ts/ts-basic-components-text.md#example-1)
 
-## How do I set the controlButton attribute for the \<SideBarContainer> component?
-
-Applicable to: OpenHarmony 3.2 Beta5 (API version 9)
-
-**Solution**
-
-The sample code is as follows:
-
-```
-@Entry
-@Component
-struct SideBarContainerExample {
-  normalIcon : Resource = $r("app.media.icon")
-  selectedIcon: Resource = $r("app.media.icon")
-  @State arr: number[] = [1, 2, 3]
-  @State current: number = 1
-
-  build() {
-    SideBarContainer(SideBarContainerType.Embed)
-    {
-      Column() {
-        ForEach(this.arr, (item, index) => {
-          Column({ space: 5 }) {
-            Image(this.current === item ? this.selectedIcon : this.normalIcon).width(64).height(64)
-            Text("Index0" + item)
-              .fontSize(25)
-              .fontColor(this.current === item ? '#0A59F7' : '#999')
-              .fontFamily('source-sans-pro,cursive,sans-serif')
-          }
-          .onClick(() => {
-            this.current = item
-          })
-        }, item => item)
-      }.width('100%')
-      .justifyContent(FlexAlign.SpaceEvenly)
-      .backgroundColor('#19000000')
-
-
-      Column() {
-        Text('SideBarContainer content text1').fontSize(25)
-        Text('SideBarContainer content text2').fontSize(25)
-      }
-      .margin({ top: 50, left: 20, right: 30 })
-    }
-    .sideBarWidth(150)
-    .minSideBarWidth(50)
-    .controlButton({left:32,
-      top:32,
-      width:32,
-      height:32, 
-      icons:{shown: $r("app.media.icon"),
-        hidden: $r("app.media.icon"),
-        switching: $r("app.media.icon")}})
-    .maxSideBarWidth(300)
-    .onChange((value: boolean) => {
-      console.info('status:' + value)
-    })
-  }
-}
-```
-
-## How do I implement the dragging feature for the \<Grid> component?
-
-Applicable to: OpenHarmony 3.2 Beta5 (API version 9)
-
-**Solution**
-
-1.  Set the **editMode\(true\)** attribute of the **\<Grid>** component to specify whether the component enters the editing mode. In the editing mode, you can drag grid items.
-2.  Set the image displayed during dragging in the [onItemDragStart](../reference/arkui-ts/ts-container-grid.md#events) callback.
-3.  Obtain the drag start position and drag insertion position from the [onItemDrop](../reference/arkui-ts/ts-container-grid.md#events) callback, and complete the array position exchange logic in the [onDrag](../reference/arkui-ts/ts-universal-events-drag-drop.md#events) callback. The sample code is as follows:
-
-    ```
-    @Entry
-    @Component
-    struct GridExample {
-      @State numbers: String[] = []
-      scroller: Scroller = new Scroller()
-      @State text: string = 'drag'
-    
-      @Builder pixelMapBuilder () { // Drag style
-        Column() {
-          Text(this.text)
-            .fontSize(16)
-            .backgroundColor(0xF9CF93)
-            .width(80)
-            .height(80)
-            .textAlign(TextAlign.Center)
-        }
-      }
-    
-      aboutToAppear() {
-        for (let i = 1;i <= 15; i++) {
-          this.numbers.push(i + '')
-        }
-      }
-    
-      changeIndex(index1: number, index2: number) {// Exchange the array item position.
-        [this.numbers[index1], this.numbers[index2]] = [this.numbers[index2], this.numbers[index1]];
-      }
-    
-      build() {
-        Column({ space: 5 }) {
-          Grid(this.scroller) {
-            ForEach(this.numbers, (day: string) => {
-              GridItem() {
-                Text(day)
-                  .fontSize(16)
-                  .backgroundColor(0xF9CF93)
-                  .width(80)
-                  .height(80)
-                  .textAlign(TextAlign.Center)
-                  .onTouch((event: TouchEvent) => {
-                    if (event.type === TouchType.Up) {
-                      this.text = day
-                    }
-                  })
-              }
-            })
-          }
-          .columnsTemplate('1fr 1fr 1fr')
-          .columnsGap(10)
-          .rowsGap(10)
-          .onScrollIndex((first: number) => {
-            console.info(first.toString())
-          })
-          .width('90%')
-          .backgroundColor(0xFAEEE0)
-          .height(300)
-          .editMode(true) // Set whether the grid enters the editing mode. In the editing mode, you can drag grid items.
-          .onItemDragStart((event: ItemDragInfo, itemIndex: number) => { // Triggered when a grid item starts to be dragged.
-            return this.pixelMapBuilder() // Set the image displayed during dragging.
-          })
-          .onItemDrop((event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => { // Triggered when the dragged item is dropped on the drop target of the grid.
-            console.info('beixiang' + itemIndex + '', insertIndex + '') // itemIndex indicates the initial position of the dragged item; insertIndex indicates the index of the position to which the dragged item will be dropped.
-            this.changeIndex(itemIndex, insertIndex)
-          })
-        }.width('100%').margin({ top: 5 })
-      }
-    }
-    ```
-
 
 ## Which API is used for URL encoding?
 

en/application-dev/faqs/faqs-arkui-component.md

 # ArkUI Component Development (ArkTS)
 
-## Can custom dialog boxes be defined or used in .ts files?
+## Can custom dialog boxes be defined and used in .ts files?
 
 Applicable to: OpenHarmony 3.2 Beta 5 (API version 9)
 
-Unfortunately, no. ArkTS syntax is required for defining and initializing custom dialog boxes. Therefore, they can be defined and used only in .ets files.
+Unfortunately not. Custom dialog boxes require ArkTS syntax for definition and initialization. Therefore, they can be defined and used only in .ets files.
 
 **Reference**
 
@@ -245,8 +245,8 @@ When a custom dialog box contains a child component whose area size can be chang
 
 **Solution**
 
--   Method 1: Use the default style of the custom dialog box. In this case, the dialog box automatically adapts its width to the grid system and its height to the child components; the maximum height is 90% of the container height.
--   Method 2: Use a custom style of the custom dialog box. In this case, the dialog box automatically adapts its width and height to the child components.
+-   Method 1: Set the custom dialog box to the default style. In this style, the dialog box automatically adapts its width to the grid system and its height to the child components; the maximum height is 90% of the container height.
+-   Method 2: Set the custom dialog box to a custom style. In this style, the dialog box automatically adapts its width and height to the child components.
 
 **Reference**
 
@@ -685,3 +685,64 @@ You can use **focusControl.requestFocus** to control the focus of the text input
 **Reference**
 
 [Focus Control](../reference/arkui-ts/ts-universal-attributes-focus.md)
+
+## How do I set the controlButton attribute for the \<SideBarContainer> component?
+
+Applicable to: OpenHarmony 3.2 Beta5 (API version 9)
+
+**Solution**
+
+Refer to the following sample code:
+
+```
+@Entry
+@Component
+struct SideBarContainerExample {
+  normalIcon : Resource = $r("app.media.icon")
+  selectedIcon: Resource = $r("app.media.icon")
+  @State arr: number[] = [1, 2, 3]
+  @State current: number = 1
+
+  build() {
+    SideBarContainer(SideBarContainerType.Embed)
+    {
+      Column() {
+        ForEach(this.arr, (item, index) => {
+          Column({ space: 5 }) {
+            Image(this.current === item ? this.selectedIcon : this.normalIcon).width(64).height(64)
+            Text("Index0" + item)
+              .fontSize(25)
+              .fontColor(this.current === item ? '#0A59F7' : '#999')
+              .fontFamily('source-sans-pro,cursive,sans-serif')
+          }
+          .onClick(() => {
+            this.current = item
+          })
+        }, item => item)
+      }.width('100%')
+      .justifyContent(FlexAlign.SpaceEvenly)
+      .backgroundColor('#19000000')
+
+
+      Column() {
+        Text('SideBarContainer content text1').fontSize(25)
+        Text('SideBarContainer content text2').fontSize(25)
+      }
+      .margin({ top: 50, left: 20, right: 30 })
+    }
+    .sideBarWidth(150)
+    .minSideBarWidth(50)
+    .controlButton({left:32,
+      top:32,
+      width:32,
+      height:32, 
+      icons:{shown: $r("app.media.icon"),
+        hidden: $r("app.media.icon"),
+        switching: $r("app.media.icon")}})
+    .maxSideBarWidth(300)
+    .onChange((value: boolean) => {
+      console.info('status:' + value)
+    })
+  }
+}
+```

en/application-dev/reference/arkui-ts/ts-container-grid.md

@@ -23,10 +23,11 @@ The **\<Grid>** component accepts only **\<[GridItem](ts-container-griditem.md)>
 >
 >  If the values of [if/else](../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md) change, the indexes of subnodes are updated.
 >
->  Child components of **\<Grid>** whose **visibility** attribute is set to **Hidden** or **None** are included in the index calculation.
+>  The child component that has the **visibility** attribute set to **Hidden** or **None** is included in the index calculation.
 >
->  Child components of **\<Grid>** whose **visibility** attribute is set to **None** are not displayed, but still take up the corresponding cells.
-
+>  The child component that has the **visibility** attribute set to **None** is not displayed, but still takes up the corresponding cell.
+>
+>  The child component that has the **position** attribute set takes up the corresponding cell, and is offset by the distance specified by **position** relative to the upper left corner of the grid. This child component does not scroll with the corresponding cell and is not displayed after the corresponding cell extends beyond the display range of the grid.
 
 ## APIs
 
@@ -61,6 +62,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
 | supportAnimation<sup>8+</sup> | boolean | Whether to enable animation. Currently, the grid item drag animation is supported.<br>Default value: **false**|
 | edgeEffect<sup>10+</sup> | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Scroll effect. The spring effect and shadow effect are supported.<br>Default value: **EdgeEffect.None**<br>|
 | enableScrollInteraction<sup>10+</sup>  |  boolean  |   Whether to support scroll gestures. When this attribute is set to **false**, scrolling by finger or mouse is not supported, but the scrolling controller API is not affected.<br>Default value: **true**     |
+| nestedScroll<sup>10+</sup>                 | [NestedScrollOptions](ts-container-scroll.md#nestedscrolloptions10)         | Nested scrolling options. You can set the nested scrolling mode in the forward and backward directions to implement scrolling linkage with the parent component.|
 
 Depending on the settings of the **rowsTemplate** and **columnsTemplate** attributes, the **\<Grid>** component supports the following layout modes:
 
@@ -71,10 +73,6 @@ Depending on the settings of the **rowsTemplate** and **columnsTemplate** attrib
 - If the width and height of a grid are not set, the grid adapts to the size of its parent component by default.
 - The size of the grid rows and columns is the size of the grid content area minus the gap between rows and columns. It is allocated based on the proportion of each row and column.
 - By default, the grid items fill the entire grid.
-- In this mode, if a grid item has both **rowStart** and **columnStart** set, it is placed in the position based on the settings. If a grid item already exists in this position, overlapping occurs.
-- If a grid item has only **rowStart** or **columnStart** set, the system traverses the previous grid item layout to search for an idle position that meets the settings. If no idle position meets the requirements, the grid item is not laid out.
-- If a grid item has neither **rowStart** nor **columnStart** set, the system traverses the previous grid item layout to search for an idle position. If no idle position is available, the grid item is not laid out.
-- If a grid item has **rowEnd** set but not **rowStart**, **rowStart** is considered as set to the same value as **rowEnd**. If a grid item has **columnEnd** set but not **columnStart**, **columnStart** is considered as set to the same value as **columnEnd**.
 
 2. Either **rowsTemplate** or **columnsTemplate** is set
 
@@ -84,19 +82,14 @@ Depending on the settings of the **rowsTemplate** and **columnsTemplate** attrib
 - In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, minCount, and **cellLength**.
 - The cross axis size of the grid is the cross axis size of the grid content area minus the gaps along the cross axis. It is allocated based on the proportion of each row and column.
 - The main axis size of the grid is the maximum height of all grid items in the cross axis direction of the current grid.
-- In this mode, if a grid item has both **rowStart** and **columnStart** set, it is placed in the position based on the settings. If a grid item already exists in this position, overlapping occurs.
-- If a grid item has only **rowStart** or **columnStart** set, the system traverses the previous grid item layout to search for an idle position that meets the settings.
-- If a grid item has neither **rowStart** nor **columnStart** set, the system traverses the previous grid item layout to search for an idle position.
-- If a grid item has **rowEnd** set but not **rowStart**, **rowStart** is considered as set to the same value as **rowEnd**. If a grid item has **columnEnd** set but not **columnStart**, **columnStart** is considered as set to the same value as **columnEnd**.
 
 3. Neither **rowsTemplate** nor **columnsTemplate** is set
 
 - The **\<Grid>** component arranges elements in the direction specified by **layoutDirection**. The number of columns is jointly determined by the grid width, width of the first element, **minCount**, **maxCount**, and **columnsGap**.
 - The number of rows is jointly determined by the grid height, height of the first element, **cellLength**, and **rowsGap**. Elements outside the determined range of rows and columns are not displayed and cannot be viewed through scrolling.
 - In this mode, only the following attributes take effect: **layoutDirection**, **maxCount**, **minCount**, **cellLength**, **editMode**, **columnsGap**, and **rowsGap**.
-- When **layoutDirection** is set to **Row**, elements are arranged from left to right. When a row is full, a new row will be added. If the remaining height is insufficient, no more elements will be laid out, and the top of the content is centered.
-- When **layoutDirection** is set to **Column**, elements are arranged from top to bottom. When a column is full, a new column will be added. If the remaining height is insufficient, no more elements will be laid out, and the top of the content is centered.
-- In this mode, **rowStart** and **columnStart** of the grid item do not take effect.
+- When **layoutDirection** is set to **Row**, elements are arranged row by row from left to right. If the remaining height is insufficient, no more elements will be laid out, and the whole content is centered at the top.
+- When **layoutDirection** is set to **Column**, elements are arranged column by column from top to bottom. If the remaining height is insufficient, no more elements will be laid out, and the whole content is centered at the top.
 
 ## GridDirection<sup>8+</sup>
 
@@ -141,6 +134,8 @@ In addition to the [universal events](ts-universal-events-click.md), the followi
 
 ## Example
 
+### Example 1
+
 ```ts
 // xxx.ets
 @Entry
@@ -196,12 +191,11 @@ struct GridExample {
         console.info(first.toString())
       })
       .onScrollBarUpdate((index: number, offset: number) => {
-        return {totalOffset: (index / 5) * (80 + 10) - 10 + offset, totalLength: 80 * 5 + 10 * 4}
+        return {totalOffset: (index / 5) * (80 + 10) - 10 - offset, totalLength: 80 * 5 + 10 * 4}
       })
       .width('90%')
       .backgroundColor(0xFAEEE0)
       .height(300)
-      .scrollBar(BarState.Off)
       Button('next page')
         .onClick(() => {// Click to go to the next page.
           this.scroller.scrollPage({ next: true })
@@ -212,3 +206,82 @@ struct GridExample {
 ```
 
 ![en-us_image_0000001219744183](figures/en-us_image_0000001219744183.gif)
+
+### Example 2
+
+1.  Set **editMode\(true\)** to enable the grid to enter editing mode, where the user can drag the grid items.
+
+2.  Through [onItemDragStart](#events), set the image to be displayed during dragging.
+
+3.  Through [onItemDrop](#events), obtain the initial position of the dragged item and the position to which the dragged item will be dropped. Through [onDrag](#events), complete the array position exchange logic.
+
+```ts
+@Entry
+@Component
+struct GridExample {
+  @State numbers: String[] = []
+  scroller: Scroller = new Scroller()
+  @State text: string = 'drag'
+
+  @Builder pixelMapBuilder () { // Style for the drag event.
+    Column() {
+      Text(this.text)
+        .fontSize(16)
+        .backgroundColor(0xF9CF93)
+        .width(80)
+        .height(80)
+        .textAlign(TextAlign.Center)
+    }
+  }
+
+  aboutToAppear() {
+    for (let i = 1;i <= 15; i++) {
+      this.numbers.push(i + '')
+    }
+  }
+
+  changeIndex(index1: number, index2: number) { // Exchange the array position.
+    [this.numbers[index1], this.numbers[index2]] = [this.numbers[index2], this.numbers[index1]];
+  }
+
+  build() {
+    Column({ space: 5 }) {
+      Grid(this.scroller) {
+        ForEach(this.numbers, (day: string) => {
+          GridItem() {
+            Text(day)
+              .fontSize(16)
+              .backgroundColor(0xF9CF93)
+              .width(80)
+              .height(80)
+              .textAlign(TextAlign.Center)
+              .onTouch((event: TouchEvent) => {
+                if (event.type === TouchType.Up) {
+                  this.text = day
+                }
+              })
+          }
+        })
+      }
+      .columnsTemplate('1fr 1fr 1fr')
+      .columnsGap(10)
+      .rowsGap(10)
+      .onScrollIndex((first: number) => {
+        console.info(first.toString())
+      })
+      .width('90%')
+      .backgroundColor(0xFAEEE0)
+      .height(300)
+      .editMode(true) // Enable the grid to enter editing mode, where the user can drag the grid items.
+      .onItemDragStart((event: ItemDragInfo, itemIndex: number) => { // Triggered when a grid item starts to be dragged.
+        return this.pixelMapBuilder() // Set the image to be displayed during dragging.
+      })
+      .onItemDrop((event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => { // Triggered when the dragged item is dropped on the drop target of the grid.
+        console.info('beixiang' + itemIndex + '', insertIndex + '') // itemIndex indicates the initial position of the dragged item. insertIndex indicates the position to which the dragged item will be dropped.
+        this.changeIndex(itemIndex, insertIndex)
+      })
+    }.width('100%').margin({ top: 5 })
+  }
+}
+```
+<!--no_check-->
\ No newline at end of file