diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/defaultFocus.png b/zh-cn/application-dev/reference/arkui-ts/figures/defaultFocus.png new file mode 100644 index 0000000000000000000000000000000000000000..7d0187576fd77ab563034561f5b862bf232ac51d Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/defaultFocus.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/focusOnTouch.png b/zh-cn/application-dev/reference/arkui-ts/figures/focusOnTouch.png new file mode 100644 index 0000000000000000000000000000000000000000..afc9d772307fd103ac57f11211f0c188e82f46b2 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/focusOnTouch.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus1.png b/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus1.png new file mode 100644 index 0000000000000000000000000000000000000000..12eeaab8f9f0f2b4aa9cb619b0fd07776dc18bd9 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus1.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus2.png b/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus2.png new file mode 100644 index 0000000000000000000000000000000000000000..f1cc053a757c9020a0f53fcb3a5076eed7df5c8a Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus2.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus3.png b/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus3.png new file mode 100644 index 0000000000000000000000000000000000000000..115c022b24345fe60008367665feae57ec9fc18f Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/groupDefaultFocus3.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus1.png b/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus1.png new file mode 100644 index 0000000000000000000000000000000000000000..0a0d6cedda78aa62c8d8305686cb651940d9ad52 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus1.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus2.png b/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus2.png new file mode 100644 index 0000000000000000000000000000000000000000..240db2460748f04d64fa7198b749ee95a8a16a48 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus2.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus3.png b/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus3.png new file mode 100644 index 0000000000000000000000000000000000000000..7aa241956ef0e9c2edfdbb683f8e3d1306ac7349 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/requestFocus3.png differ diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-focus.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-focus.md index 7b7beb666c21a330215780a893b9d976e39d2e70..16b62a14b26ee3f5598a8797153c7df0482872f2 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-focus.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-focus.md @@ -13,63 +13,271 @@ ## 属性 - | **名称** | **参数类型** | **默认值** | **描述** | | -------------------- | -------- | ------- | ---------------------------------------- | | focusable | boolean | false | 设置当前组件是否可以获焦。 | -| tabIndex9+ | number | 0 | 自定义组件tab键走焦能力，走焦顺序为：tabIndex大于0的组件依次递增走焦, tabIndex等于0的组件按组件树先后顺序走焦。
- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素，按照tabIndex的数值递增而先后获焦。如果多个元素拥有相同的tabIndex，按照元素在当前组件树中的先后顺序获焦
- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素 | +| tabIndex9+ | number | 0 | 自定义组件tab键走焦能力，走焦顺序为：tabIndex大于0的组件依次递增走焦, tabIndex等于0的组件按组件树先后顺序走焦。
- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素，按照tabIndex的数值递增而先后获焦。如果多个元素拥有相同的tabIndex，按照元素在当前组件树中的先后顺序获焦
- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素。 | +| defaultFocus9+ | boolean | false | 设置当前组件是否为当前页面上的默认焦点，仅在初次创建的页面第一次进入时生效。 | +| groupDefaultFocus9+ | boolean | false | 设置当前组件是否为当前组件所在容器获焦时的默认焦点，仅在初次创建容器节点第一次获焦时生效。
**说明：** 必须与tabIndex联合使用，当某个容器设置了tabIndex，且容器内某子组件设置了groupDefaultFocus，当该容器首次获焦时，会自动将焦点转移至该组件上。 | +| focusOnTouch9+ | boolean | false | 设置当前组件是否支持点击获焦能力。
**说明：** 仅在组件可点击时才能正常获取焦点。 | + +## focusControl9+ + +### requestFocus9+ + +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