一、功能概述

折行走焦（Focus Wrap Mode）是 List 组件在宫格/多列布局（lanes）下的焦点控制能力。
开启后，用户按方向键焦点移动时，到达行末尾会自动换行到下一行开头，实现连续流畅的焦点导航，这就是折行走焦。

• 核心属性：focusWrapMode
• 作用：设置列表多列布局下的焦点换行环绕规则
• 适用场景：多列列表、宫格布局、TV/盒子/车机等键盘/遥控器焦点操作
• 支持版本：API 9+ / HarmonyOS 6 全兼容

二、官方核心 API

focusWrapMode(mode: FocusWrapMode)

设置列表在多列布局下的焦点换行环绕策略。

枚举值（官方）

你代码中使用的是官方推荐的折行走焦模式：

.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列宫格布局
• 焦点右移 → 行尾自动换行到下一行开头
• 焦点左移 → 行首自动换到上一行末尾
• 焦点可在整个宫格内连续环绕移动，不会卡住
• 视觉居中、边距美观、交互流畅

总结

1. focusWrapMode 只对多列 List（lanes）生效
2. 必须设置 item 可聚焦（focusable: true）
3. 遥控器/键盘操作时生效
4. 用于 TV、车机、大屏设备最优
5. WRAP_WITH_ARROW 是官方标准折行走焦模式

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！