Feature: defaultFocus/groupDefaultFocus/focusOnTouch/requestFocus

Signed-off-by: Nbixuefeng <bixuefeng@huawei.com>
Change-Id: I81d9c3300df385a72b82b76126b4f18102cab21f

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-focus.md

@@ -13,63 +13,271 @@
 
 ## 属性
 
-
 | **名称**               | **参数类型** | **默认值** | **描述**                                   |
 | -------------------- | -------- | ------- | ---------------------------------------- |
 | focusable            | boolean  | false   | 设置当前组件是否可以获焦。                            |
-| tabIndex<sup>9+<sup> | number   | 0       | 自定义组件tab键走焦能力，走焦顺序为：tabIndex大于0的组件依次递增走焦, tabIndex等于0的组件按组件树先后顺序走焦。<br />- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素，按照tabIndex的数值递增而先后获焦。如果多个元素拥有相同的tabIndex，按照元素在当前组件树中的先后顺序获焦<br />- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素 |
+| tabIndex<sup>9+<sup> | number   | 0       | 自定义组件tab键走焦能力，走焦顺序为：tabIndex大于0的组件依次递增走焦, tabIndex等于0的组件按组件树先后顺序走焦。<br />- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素，按照tabIndex的数值递增而先后获焦。如果多个元素拥有相同的tabIndex，按照元素在当前组件树中的先后顺序获焦<br />- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素。 |
+| defaultFocus<sup>9+<sup> | boolean  | false   | 设置当前组件是否为当前页面上的默认焦点，仅在初次创建的页面第一次进入时生效。 |
+| groupDefaultFocus<sup>9+<sup> | boolean  | false   | 设置当前组件是否为当前组件所在容器获焦时的默认焦点，仅在初次创建容器节点第一次获焦时生效。<br />**说明：** 必须与tabIndex联合使用，当某个容器设置了tabIndex，且容器内某子组件设置了groupDefaultFocus，当该容器首次获焦时，会自动将焦点转移至该组件上。 |
+| focusOnTouch<sup>9+<sup> | boolean | false | 设置当前组件是否支持点击获焦能力。<br />**说明：** 仅在组件可点击时才能正常获取焦点。 |
+
+## focusControl<sup>9+</sup>
+
+### requestFocus<sup>9+</sup>
+
+requestFocus(value: string): boolean
+
+方法语句中可使用的全局接口，调用此接口可以主动让焦点转移至参数指定的组件上。
 
+**参数：**
+
+| 名称 | 类型 | 必填 | 描述 |
+| ----- | ------ | ---- | ---- |
+| value | string | 是   | 目标组件使用接口key(value: string)绑定的字符串。 |
+
+**返回值：**
+
+| 类型 | 说明 |
+| ------- | ---- |
+| boolean | 返回是否成功给目标组件申请到焦点。若参数指向的目标组件存在，且目标组件可获焦，则返回true，否则返回false。 |
 
 >  **说明：**
->  支持焦点控制的组件：Button、Text、Image、List、Grid。
+>  支持焦点控制的组件：Button、Text、Image、List、Grid。焦点事件当前仅支持在真机上显示运行效果。
 
 ## 示例
 
-焦点事件当前仅支持在真机上显示运行效果。
+### 示例1
 
+defaultFocus/groupDefaultFocus/focusOnTouch示例代码：
+
+defaultFocus可以使绑定的组件成为页面创建后首次获焦的焦点。groupDefaultFocus可以使绑定的组件成为tabIndex容器创建后首次获焦的焦点。focusOnTouch可以使绑定的组件点击后立即获焦。
 ```ts
-// xxx.ets
+// focusTest.ets
 @Entry
 @Component
 struct FocusableExample {
-  @State text1: string = 'TabIndex=3'
-  @State text2: string = 'TabIndex=2'
-  @State text3: string = 'focusable=false'
-  @State text4: string = 'TabIndex=-1'
-  @State text5: string = 'TabIndex=1'
-  @State text6: string = 'TabIndex=1'
-  @State text7: string = 'focusable=true'
-  @State text8: string = 'focusable=true'
+  @State inputValue: string = ''
+
+  build() {
+    Scroll() {
+      Row({ space: 20 }) {
+        Column({ space: 20 }) {
+          Column({ space: 5 }) {
+            Button('Group1')
+              .width(165)
+              .height(40)
+              .fontColor(Color.White)
+              .focusOnTouch(true)           //该Button组件点击后可获焦
+            Row({ space: 5 }) {
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+                .focusOnTouch(true)           //该Button组件点击后可获焦
+            }
+            Row({ space: 5 }) {
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+            }
+          }.borderWidth(2).borderColor(Color.Red).borderStyle(BorderStyle.Dashed)
+          .tabIndex(1)                      //该Column组件为按TAB键走焦的第一个获焦的组件
+          Column({ space: 5 }) {
+            Button('Group2')
+              .width(165)
+              .height(40)
+              .fontColor(Color.White)
+            Row({ space: 5 }) {
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+                .groupDefaultFocus(true)      //该Button组件上级Column组件获焦时获焦
+            }
+            Row({ space: 5 }) {
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+              Button()
+                .width(80)
+                .height(40)
+                .fontColor(Color.White)
+            }
+          }.borderWidth(2).borderColor(Color.Green).borderStyle(BorderStyle.Dashed)
+          .tabIndex(2)                      //该Column组件为按TAB键走焦的第二个获焦的组件
+        }
+        Column({ space: 5 }) {
+          TextInput({placeholder: 'input', text: this.inputValue})
+            .onChange((value: string) => {
+              this.inputValue = value
+            })
+            .defaultFocus(true)             //该TextInput组件为页面的初始默认焦点
+          Button('Group3')
+            .width(165)
+            .height(40)
+            .fontColor(Color.White)
+          Row({ space: 5 }) {
+            Button()
+              .width(80)
+              .height(40)
+              .fontColor(Color.White)
+            Button()
+              .width(80)
+              .height(40)
+              .fontColor(Color.White)
+          }
+          Button()
+            .width(165)
+            .height(40)
+            .fontColor(Color.White)
+          Row({ space: 5 }) {
+            Button()
+              .width(80)
+              .height(40)
+              .fontColor(Color.White)
+            Button()
+              .width(80)
+              .height(40)
+              .fontColor(Color.White)
+          }
+          Button()
+            .width(165)
+            .height(40)
+            .fontColor(Color.White)
+          Row({ space: 5 }) {
+            Button()
+              .width(80)
+              .height(40)
+              .fontColor(Color.White)
+            Button()
+              .width(80)
+              .height(40)
+              .fontColor(Color.White)
+          }
+        }.borderWidth(2).borderColor(Color.Orange).borderStyle(BorderStyle.Dashed)
+        .tabIndex(3)                      //该Column组件为按TAB键走焦的第三个获焦的组件
+      }.alignItems(VerticalAlign.Top)
+    }
+  }
+}
+```
+示意图：
+
+首次按下TAB键，焦点切换到defaultFocus绑定的组件上：
+
+![defaultFocus](figures/defaultFocus.png)
+
+第二次按TAB键，焦点切换到tabIndex(1)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上：
+
+![groupDefaultFocus1](figures/groupDefaultFocus1.png)
+
+第三次按TAB键，焦点切换到tabIndex(2)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上：
+
+![groupDefaultFocus2](figures/groupDefaultFocus2.png)
+
+第四次按TAB键，焦点切换到tabIndex(3)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上：
+
+![groupDefaultFocus3](figures/groupDefaultFocus3.png)
+
+点击绑定了focusOnTouch的组件，组件自身获焦：
+
+![focusOnTouch](figures/focusOnTouch.png)
+
+### 示例2
+
+focusControl.requestFocus示例代码：
+
+使用focusContrl.requestFocus接口使指定组件获取焦点。
+```ts
+// requestFocus.ets
+import prompt from '@system.prompt';
+
+@Entry
+@Component
+struct RequestFocusExample {
+  @State idList: string[] = ['A', 'B', 'C', 'D', 'E', 'F', 'LastPageId']
+  @State selectId: string = 'LastPageId'
 
   build() {
     Column({ space:20 }){
-      Button(this.text1)  // 按下TAB键第四个获焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .tabIndex(3)
-      Button(this.text2)  // 按下TAB键第三个获焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .tabIndex(2)
-      Button(this.text3)  // 无法获焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .focusable(false)
-      Button(this.text4)  // 无法使用TAB键，但可以使用方向键走焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .tabIndex(-1)
-      Button(this.text5)  // 按下TAB键第一个获焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .tabIndex(1)
-      Button(this.text6)  // 按下TAB键第二个获焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .tabIndex(1)
-      Button(this.text7)  // 按下TAB键第五个获焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .focusable(true)
-      Button(this.text8)  // 按下TAB键第六个获焦的组件
-        .width(300).height(70).fontColor(Color.Black)
-        .focusable(true)
+      Row({space: 5}) {
+        Button("id: " + this.idList[0] + " focusable(false)")
+          .width(200).height(70).fontColor(Color.White)
+          .key(this.idList[0])
+          .focusable(false)
+        Button("id: " + this.idList[1])
+          .width(200).height(70).fontColor(Color.White)
+          .key(this.idList[1])
+      }
+      Row({space: 5}) {
+        Button("id: " + this.idList[2])
+          .width(200).height(70).fontColor(Color.White)
+          .key(this.idList[2])
+        Button("id: " + this.idList[3])
+          .width(200).height(70).fontColor(Color.White)
+          .key(this.idList[3])
+      }
+      Row({space: 5}) {
+        Button("id: " + this.idList[4])
+          .width(200).height(70).fontColor(Color.White)
+          .key(this.idList[4])
+        Button("id: " + this.idList[5])
+          .width(200).height(70).fontColor(Color.White)
+          .key(this.idList[5])
+      }
+      Row({space: 5}) {
+        Select([{value: this.idList[0]},
+                {value: this.idList[1]},
+                {value: this.idList[2]},
+                {value: this.idList[3]},
+                {value: this.idList[4]},
+                {value: this.idList[5]},
+                {value: this.idList[6]}])
+          .value(this.selectId)
+          .onSelect((index: number) => {
+            this.selectId = this.idList[index]
+          })
+        Button("RequestFocus")
+          .width(200).height(70).fontColor(Color.White)
+          .onClick(() => {
+            var res = focusControl.requestFocus(this.selectId)      //使选中的this.selectId的组件获焦
+            if (res) {
+              prompt.showToast({message: 'Request success'})
+            } else {
+              prompt.showToast({message: 'Request failed'})
+            }
+          })
+      }
     }.width('100%').margin({ top:20 })
   }
 }
 ```
 
-![focus](figures/focus.png)
+示意图：
+
+按下TAB键，激活焦点态显示。
+申请不存在的组件获焦：
+
+![requestFocus1](figures/requestFocus1.png)
+
+申请不可获焦的组件获焦：
+
+![requestFocus2](figures/requestFocus2.png)
+
+申请存在且可获焦的组件获焦：
+
+![requestFocus3](figures/requestFocus3.png)
\ No newline at end of file