HarmonyOS6 ArkTS List 设置折行走焦
文章目录
- 一、功能概述
- 二、官方核心 API
- focusWrapMode(mode: FocusWrapMode)
- 枚举值（官方）
- 三、完整可运行代码
- 四、代码关键解析
- 1. 开启多列宫格布局（必须）
- 2. 开启折行走焦（核心）
- 3. 子项必须可聚焦
- 4. 列表内边距（优化体验）
- 5. 子项居中对齐
- 六、运行效果（折行走焦表现）
- 总结
一、功能概述
折行走焦（Focus Wrap Mode）是 List 组件在宫格/多列布局（lanes）下的焦点控制能力。
开启后，用户按方向键焦点移动时，到达行末尾会自动换行到下一行开头，实现连续流畅的焦点导航，这就是折行走焦。
- 核心属性：
focusWrapMode - 作用：设置列表多列布局下的焦点换行环绕规则
- 适用场景：多列列表、宫格布局、TV/盒子/车机等键盘/遥控器焦点操作
- 支持版本：API 9+ / HarmonyOS 6 全兼容
二、官方核心 API
focusWrapMode(mode: FocusWrapMode)
设置列表在多列布局下的焦点换行环绕策略。
枚举值（官方）
| 枚举值 | 含义 |
|---|---|
| FocusWrapMode.AUTO | 系统自动判断（默认） |
| FocusWrapMode.WRAP_WITH_ARROW | 按方向键自动折行走焦（示例使用） |
| FocusWrapMode.NONE | 不换行，到边界即停止 |
你代码中使用的是官方推荐的折行走焦模式：
.focusWrapMode(FocusWrapMode.WRAP_WITH_ARROW)三、完整可运行代码
@Entry @Component struct ListExample { @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] build() { Stack({ alignContent: Alignment.TopStart }) { Column() { List({ space: 40, initialIndex: 0 }) { ForEach(this.arr, (item: number, index?: number) => { ListItem() { Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { Text('' + item) .width(150) .height(93) .fontSize(30) .textAlign(TextAlign.Center) .borderRadius(10) .backgroundColor(0xFFFFFF) .flexShrink(1) .focusable(true) .offset({ left: 5 }) } } }, (item: string, index?: number) => item) } .lanes(2) .contentStartOffset(20) .contentEndOffset(20) .width('100%') .scrollBar(BarState.Off) .friction(0.6) .focusWrapMode(FocusWrapMode.WRAP_WITH_ARROW) .alignListItem(ListItemAlign.Center) .offset({ left: 20 }) }.width('90%') }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) } }运行效果如图：
四、代码关键解析
1. 开启多列宫格布局（必须）
.lanes(2)// 两列布局折行走焦必须在多列列表下才能体现效果。
2. 开启折行走焦（核心）
.focusWrapMode(FocusWrapMode.WRAP_WITH_ARROW)作用：
- 右移到行末尾 →自动换到下一行开头
- 左移到行开头 →自动换到上一行末尾
- 实现连续环绕式焦点移动
3. 子项必须可聚焦
.focusable(true)ListItem 子项必须开启可聚焦，焦点才能移动。
4. 列表内边距（优化体验）
.contentStartOffset(20).contentEndOffset(20)设置列表内容边距，让焦点移动更美观。
5. 子项居中对齐
.alignListItem(ListItemAlign.Center)让两列宫格居中显示，布局更标准。
六、运行效果（折行走焦表现）
- 列表为2列宫格布局
- 焦点右移 → 行尾自动换行到下一行开头
- 焦点左移 → 行首自动换到上一行末尾
- 焦点可在整个宫格内连续环绕移动，不会卡住
- 视觉居中、边距美观、交互流畅
总结
- focusWrapMode 只对多列 List（lanes）生效
- 必须设置 item 可聚焦（focusable: true）
- 遥控器/键盘操作时生效
- 用于 TV、车机、大屏设备最优
- WRAP_WITH_ARROW 是官方标准折行走焦模式
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！