Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs
提交 14205ef4 编写于 作者: B bixuefeng
浏览文件
操作

Feature: defaultFocus/groupDefaultFocus/focusOnTouch/requestFocus 

Signed-off-by: Nbixuefeng <bixuefeng@huawei.com>
Change-Id: I81d9c3300df385a72b82b76126b4f18102cab21f
上级 69dff079
隐藏空白更改
内联 并排
Showing with 246 addition and 38 deletion
zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-focus.md
浏览文件 @ 14205ef4
...@@ -13,63 +13,271 @@ ...@@ -13,63 +13,271 @@
## 属性 ## 属性
| **名称** | **参数类型** | **默认值** | **描述** | | **名称** | **参数类型** | **默认值** | **描述** |
| -------------------- | -------- | ------- | ---------------------------------------- | | -------------------- | -------- | ------- | ---------------------------------------- |
| focusable | boolean | false | 设置当前组件是否可以获焦。 | | 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 ```ts
// xxx.ets // focusTest.ets
@Entry @Entry
@Component @Component
struct FocusableExample { struct FocusableExample {
@State text1: string = 'TabIndex=3' @State inputValue: string = ''
@State text2: string = 'TabIndex=2'
@State text3: string = 'focusable=false' build() {
@State text4: string = 'TabIndex=-1' Scroll() {
@State text5: string = 'TabIndex=1' Row({ space: 20 }) {
@State text6: string = 'TabIndex=1' Column({ space: 20 }) {
@State text7: string = 'focusable=true' Column({ space: 5 }) {
@State text8: string = 'focusable=true' 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() { build() {
Column({ space:20 }){ Column({ space:20 }){
Button(this.text1) // 按下TAB键第四个获焦的组件 Row({space: 5}) {
.width(300).height(70).fontColor(Color.Black) Button("id: " + this.idList[0] + " focusable(false)")
.tabIndex(3) .width(200).height(70).fontColor(Color.White)
Button(this.text2) // 按下TAB键第三个获焦的组件 .key(this.idList[0])
.width(300).height(70).fontColor(Color.Black) .focusable(false)
.tabIndex(2) Button("id: " + this.idList[1])
Button(this.text3) // 无法获焦的组件 .width(200).height(70).fontColor(Color.White)
.width(300).height(70).fontColor(Color.Black) .key(this.idList[1])
.focusable(false) }
Button(this.text4) // 无法使用TAB键，但可以使用方向键走焦的组件 Row({space: 5}) {
.width(300).height(70).fontColor(Color.Black) Button("id: " + this.idList[2])
.tabIndex(-1) .width(200).height(70).fontColor(Color.White)
Button(this.text5) // 按下TAB键第一个获焦的组件 .key(this.idList[2])
.width(300).height(70).fontColor(Color.Black) Button("id: " + this.idList[3])
.tabIndex(1) .width(200).height(70).fontColor(Color.White)
Button(this.text6) // 按下TAB键第二个获焦的组件 .key(this.idList[3])
.width(300).height(70).fontColor(Color.Black) }
.tabIndex(1) Row({space: 5}) {
Button(this.text7) // 按下TAB键第五个获焦的组件 Button("id: " + this.idList[4])
.width(300).height(70).fontColor(Color.Black) .width(200).height(70).fontColor(Color.White)
.focusable(true) .key(this.idList[4])
Button(this.text8) // 按下TAB键第六个获焦的组件 Button("id: " + this.idList[5])
.width(300).height(70).fontColor(Color.Black) .width(200).height(70).fontColor(Color.White)
.focusable(true) .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 }) }.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
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或