做TV端应用的人都知道，遥控器方向键按下去，焦点能不能落到用户预期的那块组件上，基本决定了这个应用好不好用。我在HarmonyOS NEXT 5.0.0(12)也就是API 12+的环境上，用ArkUI重构了一个视频应用的遥控器导航模块，整个过程里对HarmonyOS ArkUI焦点事件的理解经历了三次刷新：第一次以为只是"获得焦点时变个样式"；第二次发现焦点还牵扯按键分发和组件树遍历；第三次才意识到，真正复杂的是焦点在容器、列表、弹窗之间的转移。这篇文章我会把这三个阶段拆开来讲，把焦点事件的原理、API用法、样式定制、实战代码和踩坑记录一次性说清楚，适合正在做HarmonyOS应用、尤其是TV端或需要兼容遥控器、键盘操作的朋友。
1. 焦点事件在ArkUI里的真实定位：一个"当前操作对象"的指针
1.1 焦点事件和触摸事件到底有什么区别
很多从移动端转过来的开发者，第一次接触ArkUI焦点事件时都会有一个困惑：我明明已经写了onClick，为什么还要管什么焦点？
区别在于，触摸场景下用户用手指直接指定了目标，onClick是被"点"出来的；但在遥控器和键盘场景里，系统必须自己维护一个"当前操作对象"——用户按上、下、左、右或者Tab键的时候，系统需要知道该把按键事件交给哪个组件。这个"当前操作对象"就是焦点。
用一句直白的话来说：焦点是组件树上的一个"指针"，它指向某个组件，表示"现在正在操作这个组件"。焦点事件，就是组件获得这个指针、失去这个指针时触发的事件。
在实际开发里，焦点和按键分发、滚动联动、无障碍播报都是绑在一起的。组件在获得焦点的瞬间，不止会触发onFocus回调，还会影响后续onKeyEvent的事件流向，以及系统辅助功能对用户播报的内容。你只有把"焦点在哪"这件事搞清楚，才能理解为什么遥控器按下键之后，列表会滚动、tab会切换、详情区会更新——这些都是焦点位置变化带来的连锁反应。
1.2 哪些组件默认能获得焦点，哪些不能
ArkUI里组件默认是否可聚焦，不同版本之间的表现并不完全一致，这是第一个需要留意的点。
就我在API 12上的实测来看，Button、TextInput、Checkbox、Slider这类本身承担交互功能的组件，通常天然具备可聚焦能力；而Text、Image、Column、Row这类偏展示和布局的组件，往往需要显式设置.focusable(true)才能稳定地进入焦点链路。
我的建议是：不要依赖"默认值"，在关键交互路径上显式声明focusable。尤其是自定义组合卡片，比如一个由Row包着Image和Text的视频卡片，如果想让整张卡片作为一个焦点单元出现，就需要给最外层容器设置.focusable(true)，同时把内部子组件设置为.focusable(false)。否则遥控器按下去，焦点可能先落在Image上，再落到Text上，在用户看来就是焦点在卡片内部"跳了两下"，体验非常割裂。
1.3 焦点管理的三个核心场景
结合我做TV端的经验，ArkUI焦点事件主要在三类场景里绕不开：
- 遥控器导航：机顶盒、智慧屏应用里，用户通过方向键在页面内移动焦点。这是焦点事件最核心的战场。
- 键盘操作：需要外接键盘的平板模式、教育场景，用户用Tab、Shift+Tab、方向键在表单和页面元素间移动。
- 无障碍服务：系统辅助功能需要"读取"焦点所在组件的信息并进行播报，焦点如果乱跑，视力障碍用户的使用体验会直接崩溃。
这三个场景有一个共同点：输入设备都不能直接"点"到目标，必须依靠系统维护的焦点位置来完成操作。所以什么时候触发onFocus、什么时候触发onBlur，以及焦点转移到哪个组件，不是玄学，而是有明确规则的。
2. 焦点API实测：focusOn、onFocus/onBlur、requestFocus到底怎么用
2.1 focusOn和onFocus/onBlur怎么选
ArkUI提供焦点事件的方式有新旧两套。早期版本常用focusOn，通过传入enter和exit回调来监听焦点进出。我习惯把它理解为"把焦点监听绑定在一个组件上，这个组件成为焦点节点时触发进入，离开时触发退出"。
// focusOn的经典写法 Text('推荐') .focusOn({ enter: () => { console.info('焦点进入推荐Tab') }, exit: () => { console.info('焦点离开推荐Tab') } })在API 12+的环境里，我更推荐用onFocus和onBlur这对事件，语义更清晰，写起来也更接近Web开发者的直觉：
Text('推荐') .focusable(true) .onFocus(() => { console.info('获得了焦点') }) .onBlur(() => { console.info('失去了焦点') })实测下来，onFocus/onBlur在热度上比focusOn更精准，适合做纯监听；而focusOn某些场景下会改变容器自身的焦点属性，如果只是想让一个容器"感知"焦点变化，而不是成为真正的焦点节点，用onFocus/onBlur更安全。
2.2 程序化控制焦点：focusControl.requestFocus
被动监听焦点之外，另一个高频需求是"主动把焦点送到某个组件上"，比如页面加载后直接选中某个按钮，或者弹窗打开后让焦点落到"确认"按钮。
这时候用focusControl.requestFocus。它需要目标组件上设置key属性，这个key在整个当前能力范围内必须是唯一的。
import { focusControl } from '@kit.ArkUI'; Button('确认') .key('confirmButton') .onClick(() => { // 跳转到新页面后，手动把焦点交给列表首项 focusControl.requestFocus('firstVideo') }) // 列表首个卡片 Stack() { // ... } .key('firstVideo') .focusable(true)这里有个实操细节：requestFocus传入的是一个字符串key，不是组件引用。如果组件没设key、key重复，或者组件当前不在焦点树上，调用可能会没有效果。我排查过一次半天没反应的问题，最后发现是key拼写不一致。所以建议把焦点相关的key统一抽成常量管理，不要手写字符串到处撒。
2.3 defaultFocus和groupDefaultFocus：页面打开时焦点停在哪
页面加载之后，总要有第一个获得焦点的组件。如果没有明确指定，系统会按照组件树的构建顺序找一个"默认焦点"。
.defaultFocus(true)就是干这个的——告诉系统进入页面时优先把焦点给到哪个组件。比如TV端首页，我通常希望焦点落在用户最容易注意到的入口上：
Column() { // 左侧Tab栏 ForEach(this.tabs, (tab: string, index: number) => { Text(tab) .defaultFocus(index === 0) .focusable(true) }) }另外一个容易被忽略的是.groupDefaultFocus(true)。它用于焦点组内部，当用户用方向键移入某个大的容器区域时，系统不知道该选容器里哪个子组件作为焦点落点，groupDefaultFocus就用来指定"进入这个区域时，默认把焦点给谁"。
场景很典型：左侧Tab栏是一个整体区域，右侧视频区域是另一个整体区域。遥控器按右键从Tab栏切到右侧列表时，焦点应该落到右侧列表的第一项，而不是列表里任意一个"中间产物"。通过groupDefaultFocus可以把这种进入行为固定下来，避免用户每次按右键进去焦点位置都不一样。
2.4 tabIndex：干预键盘Tab的遍历顺序
TV遥控器方向键的移动规则更多依赖组件在屏幕上的几何位置，而键盘的Tab键则依赖组件在焦点树里的遍历顺序。.tabIndex就是用来调整这个顺序的。
Text('第一个元素') .tabIndex(1) Text('第二个元素') .tabIndex(2)实际开发中我很少手动改tabIndex，因为ArkUI默认的遍历顺序通常已经符合从上到下、从左到右的直觉。但在某些复杂表单场景，比如"先填邮箱再填密码最后点登录"，如果组件创建顺序跟用户视觉顺序不一致，就需要通过tabIndex纠正。要注意设置过大的tabIndex可能导致焦点顺序脱离视觉位置，反而更难用，能不改就不改。
3. 焦点反馈的呈现：从默认焦点框到自定义视觉方案
3.1 默认焦点样式够用吗
HarmonyOS组件获得焦点时，系统默认会给一个焦点框效果。这个效果在系统应用里看起来还行，但在TV大屏上往往不够醒目。
有个朋友跟我吐槽：智慧屏投屏播放页里，焦点框是一条细细的蓝边，坐在三米外的沙发上根本看不清焦点在哪。做TV端应用，焦点反馈的视觉强度必须比手机端高一个量级，不然遥控器操作起来全程都是"盲人摸象"。
所以焦点事件不只是逻辑层面的问题，它直接决定了产品给用户的反馈级别。每次焦点变化，都应该有一个对应的视觉状态切换。
3.2 用focusBoxStyle定制焦点框
如果需要保留"外框"这种形态，但又想改成符合产品方案的颜色和尺寸，可以用focusBoxStyle。
Column() { Text('推荐') .fontSize(18) .padding({ left: 20, right: 20, top: 12, bottom: 12 }) } .focusable(true) .focusBoxStyle({ strokeColor: '#FFD231', strokeWidth: 4, borderRadius: 12, margin: 2, animationDuration: 150 })这里解释下每个字段的含义：
strokeColor：焦点框颜色。TV端建议用高饱和度的亮色，比如明黄、亮蓝，能明显区别于背景。strokeWidth：焦点框粗细。大屏场景4-6px比较合适，太细会被忽略。margin：焦点框和组件本身的间距。默认的焦点框紧贴着组件，视觉上像"描边"；加大一点会更像"光环"，反而醒目。borderRadius：圆角。要跟组件自身的圆角保持一致，不然焦点框和组件形状对不上，会有一种"套错壳"的感觉。animationDuration：焦点框出现的动画时长。TV端我建议150-200ms，太快显得生硬，太慢影响跟手。
3.3 用状态样式实现更灵活的视觉方案
focusBoxStyle能改边框，但产品想要的效果往往是"焦点卡片放大1.1倍+加阴影+改变背景色"。这类复合视觉效果，focusBoxStyle就不够用了，需要在onFocus/onBlur回调里自己维护状态：
@State isFocused: boolean = false; Column() { Text('视频标题') } .width(220) .height(124) .borderRadius(12) .backgroundColor(this.isFocused ? '#333333' : '#1A1A1A') .scale({ x: this.isFocused ? 1.1 : 1.0, y: this.isFocused ? 1.1 : 1.0 }) .shadow({ radius: this.isFocused ? 24 : 8, color: this.isFocused ? 'rgba(255,210,49,0.35)' : 'rgba(0,0,0,0.4)' }) .focusable(true) .onFocus(() => { this.isFocused = true; }) .onBlur(() => { this.isFocused = false; })这种做法的好处是所有效果都自己控制，不会跟系统默认样式冲突。但代价是需要自己保证onFocus和onBlur一定会配对触发。
这里有个我踩过的坑：如果组件移出了可视区域，或者所在的容器被设置成不参与焦点遍历了，onBlur不一定会按预期触发。比如滚出屏幕外的卡片失去焦点时，有时直接销毁了，状态还没重置。因此在实现上，不要在onBlur里做太多"非幂等"的事情——最好的做法是焦点样式完全由当前焦点组件索引驱动，而不是靠每张卡片各自维护一个isFocused。
4. 实战：用焦点事件重构TV端遥控器导航的视频列表页
4.1 这个实战要解决什么问题
业务形态很常见：一个视频应用首页，左侧是分类Tab栏（推荐、电视剧、电影、综艺），右侧是当前分类下的视频列表。用户用遥控器左右键在Tab栏和列表之间切换，上下键在某个区域内移动焦点。
难点不在"做出一个能跑的原型"，而在于以下几个细节：
- 页面加载后，焦点默认落在第一个Tab上还是第一个视频上？不同产品定义不一样。
- 焦点从右侧列表切到左侧Tab栏时，右侧列表应该记录刚才的位置，还是重置到顶部？
- 焦点在列表里上下移动时，列表要跟着滚动，不能让焦点跑到屏幕外面。
这些都需要用焦点事件来驱动，而不是简单地给每个组件写onClick。
4.2 核心页面结构与代码
我先给一个简洁版本，去掉封面图和过多装饰，保留关键焦点逻辑：
import { focusControl } from '@kit.ArkUI'; interface VideoItem { id: string; title: string; duration: string; } @Entry @Component struct TvHomePage { @State currentTabIndex: number = 0; @State focusedVideoIndex: number = 0; private tabs: string[] = ['推荐', '电视剧', '电影', '综艺']; private videos: VideoItem[] = []; private listScroller: Scroller = new Scroller(); build() { Row() { // 左侧Tab栏 Column({ space: 12 }) { ForEach(this.tabs, (tab: string, index: number) => { Text(tab) .width(160) .height(56) .textAlign(TextAlign.Center) .fontSize(this.currentTabIndex === index ? 20 : 16) .fontWeight(this.currentTabIndex === index ? FontWeight.Bold : FontWeight.Normal) .backgroundColor(this.currentTabIndex === index ? '#FFD231' : 'transparent') .fontColor(this.currentTabIndex === index ? '#000000' : '#999999') .borderRadius(8) .focusable(true) .onFocus(() => { this.currentTabIndex = index; this.loadVideos(index); }) }, (tab: string) => tab) } .width(176) .padding({ top: 48, left: 16 }) // 右侧视频列表 List({ space: 16, scroller: this.listScroller }) { ForEach(this.videos, (item: VideoItem, index: number) => { ListItem() { Row({ space: 12 }) { Stack() { // 这里放封面图，为了简洁省略背景色占位 } .width(200) .height(112) .borderRadius(8) .backgroundColor('#3A3A3A') Column({ space: 6 }) { Text(item.title) .fontSize(18) .fontColor('#FFFFFF') .maxLines(1) Text(item.duration) .fontSize(14) .fontColor('#AAAAAA') } .layoutWeight(1) .alignItems(HorizontalAlign.Start) } .width('100%') .padding(12) .borderRadius(12) .backgroundColor(this.focusedVideoIndex === index ? '#404040' : '#202020') .focusable(true) .onFocus(() => { this.focusedVideoIndex = index; this.listScroller.scrollToIndex({ index: index, smooth: true }); }) }, (item: VideoItem) => item.id) }) } .layoutWeight(1) .padding({ top: 48, right: 24, bottom: 24 }) .groupDefaultFocus(true) } .width('100%') .height('100%') .backgroundColor('#0D0D0D') } private loadVideos(tabIndex: number) { // 根据tab切换数据源 } }这套代码有几个关键点，我拆开说。
4.3 为什么用onFocus驱动业务联动，而不是onClick
左侧Tab栏的选中态由currentTabIndex驱动，右侧列表项的高亮由focusedVideoIndex驱动。这两个状态量的更新源都是onFocus，而不是onClick。
原因是：遥控器场景下，用户移动的是焦点，焦点移动到哪，业务上就认为当前交互对象是哪。如果只监听onClick，用户按了好几次方向键却没有任何反馈——因为他还没"确认"，自然没有点击事件。但对TV用户来说，焦点移动本身就应该触发内容预览、Tab切换、详情更新这些"软反馈"。
从右侧列表切回左侧Tab时，Tab获得焦点、onFocus触发，对应的视频分类同步切换。这个过程完全跟着焦点走，不会出现"焦点已经在某个Tab上，但内容还是旧列表"的割裂感。
4.4 列表滚动跟随：焦点和可视区域的绑定
焦点在List里移动时，一个让人抓狂的问题是：焦点选中了屏幕外的卡片，用户按了两下方向键，焦点跑出可视区域了，列表却纹丝不动。
处理方式就是上面代码里的scrollToIndex。当卡片获得焦点时，主动调用this.listScroller.scrollToIndex({ index: index, smooth: true })，把当前获得焦点的卡片滚到可视范围。
这里有两个细节值得注意：
smooth: true会让滚动有动画，但如果焦点移动速度很快（用户连续按方向键），动画会显得拖沓。实测里，我通常只在"焦点从Tab栏跳回列表"这种跨区域场景用smooth: true，在列表内部连续移动时用smooth: false或者直接scrollToIndex(index)，保证跟手。scrollToIndex并不是每次调用都能精确命中最后一项，因为List有缓冲机制。如果滚动距离太长，可以先计算目标项在页面中的位置再配合scrollToOffset，这在焦点场景里属于后续优化，基础版本用scrollToIndex足够。
4.5 区域的默认焦点和跨区切换
groupDefaultFocus(true)放在右侧List上，作用就是：当用户通过遥控器把焦点从左侧Tab栏区域移进右侧列表区域时，系统优先把焦点落在列表的第一个可聚焦项上，而不是根据几何位置猜一个。
这里要说明白：TV上焦点在组件树里的"跨区移动"规则，本质上是系统在查找焦点转移候选时，基于方向和距离做的一次"最近邻"匹配。如果你有两个区域离得很近，又没有用groupDefaultFocus指定进入后的落点，移动结果可能会不符合预期——系统觉得离得近的那个组件更合适，但你希望的是"进入这个区域就选中这个区域的第一项"。groupDefaultFocus就是给这种跨区行为上锁。
5. 五个容易让人心态爆炸的焦点"坑"
5.1 焦点"丢了"：事件回调不触发，先查焦点树
焦点事件最常见的故障是：onFocus不触发，或者组件明明设置了focusable(true)却怎么都聚焦不到。
我排查过的案例里，绝大部分原因都出在"组件不在焦点树上"。焦点树和渲染树是两回事——渲染出来了不代表能参与焦点遍历。常见的阻断原因包括：
- 组件被
visibility: Hidden或Off属性隐藏，隐藏组件会退出焦点树。 - 父容器设置了
focusable(true)且抢占了焦点，子组件的焦点能力被父容器"包住"了。 - 页面切换或组件状态更新时，旧组件被销毁，焦点落到一个悬空的位置，后续方向键没有可聚焦的新候选。
遇到这类问题，我的排查顺序是：先把目标组件的focusable显式设成true排除默认值问题；再检查它有没有被父容器或兄弟组件遮挡；最后用临时onFocus日志确认它到底有没有进焦点树。不要一上来就怀疑API有问题。
5.2 弹窗场景的焦点逃逸
TV端弹窗是个重灾区。打开一个确认框后，遥控器按上下键，焦点居然还在背后的页面上乱跑，弹窗完全不受控。
这是因为弹窗默认并不一定抢走焦点。在API 12的ArkUI里，弹窗打开后需要主动把焦点请求到弹窗内的指定组件上。
this.dialogController.open(); focusControl.requestFocus('dialogConfirmButton');弹窗关闭后也要处理焦点归还。否则可能出现"弹窗没了，焦点也没了"的短暂空白，用户再按一次方向键才恢复正常。我的做法是在弹窗关闭回调里，重新把焦点请求到打开弹窗之前的那个组件上，保证焦点状态闭环。
5.3 连续快速按键时焦点漂移
TV用户用遥控器连续按方向键的频率，比手机用户敲屏幕快得多。焦点移动是有动画过程的，如果用户在组件还没完全进入稳定状态时连续按键，可能出现两个问题：一是焦点移动速度跟不上按键速度，二是onFocus回调里做的状态更新被高频触发，导致页面卡顿。
对第二点，我建议把焦点回调里的逻辑做"瘦身"。不要在onFocus里做复杂的计算、网络请求、大数组遍历，尽量只更新索引状态。数据加载放到onChange或者去抖之后再触发。实测中，把Tab切换的数据加载从onFocus移到setTimeout去抖后，快速按键的卡顿明显缓解。
5.4 scrollToIndex和List的复用冲突
List进入焦点移动模式后，ListItem是会被复用的。如果某个卡片获得焦点时滚动到了顶部，卡片被回收，接着另一张卡片复用了它的组件实例，那么"哪个卡片是当前焦点卡片"这个状态，光靠组件实例已经不够了，必须以索引为准。
这也是为什么我在上面的实战代码里，高亮色用的是this.focusedVideoIndex === index这种全量比较，而不是某个卡片自己维护布尔值。用索引状态驱动，即使组件被复用，当前索引对应的组件重新构建时也能正确呈现焦点态。
5.5 调试焦点的两个实用技巧
最后分享两个我用着很顺手的调试方法。
第一个，在获得焦点的组件里临时输出日志：
.onFocus(() => { console.info(`[FocusDebug] current index = ${index}`); })这是最朴素的定位方式，能快速看出焦点实际落在哪个组件上。
第二个，全局打印当前焦点key。可以在页面顶层或调试面板里调用focusControl.getFocus()。这个方法返回当前聚焦组件，可以看到组件的key信息。我把返回结果放在一个Debug面板上，走查焦点问题时基本不用猜，直接看当前焦点的key是哪里的，立刻就知道焦点是不是跑偏了。
这套组合拳打下来，大部分焦点问题都能在十分钟内定位到根因。我自己的经验是：焦点事件相关的bug，90%都不是"事件没触发"，而是"焦点根本不在我以为的那个组件上"。所以与其反复检查代码逻辑，不如先把"当前焦点在哪"这件事可视化。
做HarmonyOS ArkUI开发到现在，我最大的感受是：焦点事件在手机端常常被忽略，但走到TV、键盘、无障碍这些"非触摸"场景时，它才是交互体验的主干。花点时间把焦点树、焦点转移、焦点样式这套体系吃透，收益远比想象中高。希望这篇基于API 12+实测的拆解，能帮你少走几段我走过的弯路。
