我第一次接到聊天页面这个需求的时候心想这不就是个消息列表加输入框嘛ArkUI里List一套、TextInput一放半天应该能做完。真正动手之后才发现聊天页面大概是HarmonyOS 6应用开发里最容易在细节上翻车的页面之一键盘一弹起来输入框被挡、消息一多列表开始卡、发完消息列表不自动滚到底随便一个坑都足够让你在测试同事面前抬不起头。这篇文章就把我做的一个HarmonyOS 6聊天页面实战案例完整拆开讲从需求拆解到代码实现再到调试过程中踩过的那些泥坑希望你看完能少走点弯路。1. 需求拆解与整体设计思路这个案例的背景很简单做一个即时通讯应用的聊天页面以文本消息为主要支持左右气泡、时间显示、消息发送、自动滚动到底部、键盘避让和长按操作。听起来很常规但聊天页面最特殊的地方在于它不是一个静态展示页而是一个一直在变化的页面。消息在变、输入框的内容在变、键盘的弹出状态在变、历史消息的加载在变所以整个页面的设计核心不是气泡怎么画好看而是数据怎么流动、状态怎么管理。这一节先把这个思路讲透。1.1 聊天页面的真实使用场景想一想用户进入一个聊天会话之后会做什么先滑动查看历史消息然后点击输入框系统弹出键盘输入内容点击发送消息出现在列表底部列表自动滚动到底部键盘继续保持弹出用户可以连续输入下一条。这个过程里输入框的焦点、键盘高度、消息列表的长度都在动态变化而且这些变化是交替发生、互相影响的。所以聊天页面和普通列表页最大的区别在于状态密集。普通列表页的数据可能一天变一次聊天页面的数据是几秒钟变一条。如果一开始就把页面当成一个静态布局去做后面接需求的时候会非常痛苦。我建议动手前先画一条数据流用户输入 - 点击发送 - 生成消息对象 - 追加到消息数组 - 列表响应刷新 - 滚动到底部 - 清空输入框。这条链路里的每一个环节都要在代码里找到对应的位置这就是所谓的状态驱动思维。这个案例的另一个特点是上下行消息不对称。自己的消息在右侧、蓝底白字对方的在左侧、灰底深色字。这个不对称不仅体现在样式上也体现在操作上自己的消息长按可以撤回或删除对方的消息通常只能复制。所以消息模型里必须有一对一标识双方身份的字段这一点在数据设计阶段就要定下来不然写到一半你会发现样式判断逻辑到处散落。1.2 方案选型为什么用 List ForEach聊天页面最底层的组件选型我见过不少新手拿Scroll Column做列表消息一多直接卡成PPT。原因很简单Scroll不会复用子组件每一条消息都是一个独立的组件实例100条消息就是100个组件常驻内存。聊天场景动辄几千条记录这条路走不通。HarmonyOS 6的ArkUI里正确做法是用List配合ForEach。List是原生列表组件ListItem会做渲染复用配合cachedCount可以控制前后预加载的数量性能上比Scroll高一个数量级。再往上还有LazyForEach它更适合数据量上万、需要按需实例化的场景但要额外实现数据源接口编写和维护成本明显更高。聊天页面如果以文本消息为主几千条的体量用List ForEach已经足够流畅没必要一上来就上LazyForEach。这个选择背后其实是够用就好的工程原则。我从实际项目里得到的教训是不要为了展示技术栈而引入复杂度。一个聊天Demo如果连产品形态都没跑通就去啃LazyForEach的数据源和增量更新机制大概率会在优化细节里消耗掉整个开发周期。先用List跑通全流程等真实压测发现瓶颈了再升级这是更务实的路径。1.3 状态管理规划让数据流保持单向清晰聊天页面的状态大体分成三类消息列表数据、输入框文本、键盘和滚动相关的临时状态。在ArkUI里分别对应State、Prop这些装饰器。我的分工方式是消息数组和输入框文本放在页面根组件的State里消息气泡子组件通过Prop接收单条消息对象。这样父组件只负责数据的增删子组件只负责单条消息的展示各司其职。这里要特别提醒一个事不要把所有状态都塞进AppStorage或LocalStorage尤其是聊天消息流。全局状态存储适合放会话ID、用户信息、主题偏好这类跨页面共享的数据而聊天消息的实时性很强放在全局存储里会让排查问题的难度成倍上升——你根本不知道是哪个页面改了它。页面内能解决的页面内解决这是我给所有新项目定的一条规矩。另外聊天列表里的单条消息在发送成功后通常不会反复修改内容所以消息类可以先不做成Observed观察对象。真正需要Observed的场景是什么是消息状态来回切换比如发送中变成已发送再变成发送失败UI要实时响应单条消息的内部变化。我们这个案例用不到就不过度设计。等你真要做消息状态机的时候再引入那个复杂度单独开一篇文章都讲不完。2. 核心功能实现与代码解析这一节进入正题从消息模型开始把聊天页面的核心代码逐段拆开讲。代码并不复杂但每一段背后都有一个我在实际开发中反复调整过的细节。建议你跟着思路敲一遍而不是直接复制粘贴完事。2.1 消息模型与数据结构设计先看消息模型的定义。聊天页面的最小数据单元我建议至少包含四个字段唯一ID、消息内容、是否自己发送、时间戳。预留一个消息类型字段后面接图片、语音消息的时候不用改表结构。// MessageItem.ets export class MessageItem { msgId: string content: string isSelf: boolean timestamp: number msgType: string constructor(msgId: string, content: string, isSelf: boolean, timestamp: number) { this.msgId msgId this.content content this.isSelf isSelf this.timestamp timestamp this.msgType text } }为什么msgId必须唯一且稳定因为后面ForEach做列表渲染时每一项都需要一个key而key就是msgId。如果你用数组下标做key一旦消息插入或删除下标全部变化列表会从错误的起始位置渲染轻则UI闪烁重则出现消息错位和重复。msgId的生成我习惯用时间戳加随机数拼接比如msg_1720000000000_8362基本可以保证单会话内不重复。isSelf字段是聊天页的分叉点。气泡左右方向、背景颜色、文字颜色、长按菜单内容都由它决定。你可以在build里到处写if (item.isSelf)但更好的做法是把这些判断收敛到消息气泡组件内部页面主结构里只负责传入数据这样后续改动样式不需要动页面主体。时间戳保存毫秒值展示时再格式化成xx:xx不要在数据层提前格式化成字符串不然你以后想做今天/昨天分组或者国际化就麻烦了。2.2 消息气泡组件左右布局与样式隔离消息气泡应该是整个聊天页面里复用率最高的组件。我把它的职责限定为接收一条消息对象渲染出对应的气泡和时间并把长按事件抛给外层处理。这样组件既不知道消息从哪里来也不知道长按之后要做什么耦合度非常低。// MessageBubble.ets Component export struct MessageBubble { Prop message: MessageItem onLongPress: () void () {} build() { Row() { if (this.message.isSelf) { Blank() } Column() { Text(this.formatTime(this.message.timestamp)) .fontSize(10) .fontColor(#999999) Text(this.message.content) .fontSize(16) .fontColor(this.message.isSelf ? #FFFFFF : #182431) .padding({ left: 12, right: 12, top: 8, bottom: 8 }) .backgroundColor(this.message.isSelf ? #007DFF : #F1F3F5) .borderRadius(12) } .alignItems(this.message.isSelf ? HorizontalAlign.End : HorizontalAlign.Start) if (!this.message.isSelf) { Blank() } } .width(100%) .onLongPress(() this.onLongPress()) } private formatTime(timestamp: number): string { const date new Date(timestamp) const h date.getHours().toString().padStart(2, 0) const m date.getMinutes().toString().padStart(2, 0) return ${h}:${m} } }注意Prop这个装饰器。它的特点是单向同步父组件状态变更时子组件的Prop变量会跟着更新但子组件内部不能直接赋值修改这个变量改也改不回去。我刚接触ArkUI时吃过一次亏想让子组件更新消息内容直接在子组件里写this.message.content xxx结果界面一动不动排查了半天才想起来这是Prop正确做法应该是通过回调事件让父组件来改。所以这个组件里我把长按事件通过onLongPress函数传出去就是为了避免在子组件内部直接操作数据。时间格式化放在子组件里的方案在数据量小的时候没问题但消息列表长的时候每条消息在渲染时都会执行一次new Date()。这一点在后面的性能优化里我会再讲这里先记住能提前算好的不要在渲染时现算。2.3 输入区与发送逻辑完整实现输入区是TextInput加一个发送按钮。很多新手以为发送就是把输入框的值往数组里一塞完事其实里面有三个动作校验非空、追加消息、滚动到底部。还涉及一个细节什么时候清空输入框我建议在消息追加成功后再清空因为如果校验或生成对象失败输入内容还在用户不用重打一遍。private sendMessage() { const text this.inputText.trim() if (!text) { return } const newMsg new MessageItem( msg_${Date.now()}_${Math.floor(Math.random() * 10000)}, text, true, Date.now() ) this.messageList [...this.messageList, newMsg] this.inputText this.scrollToBottom() }这里有个ArkTS状态管理的经典坑数组的修改必须让State能感知到。如果你这样写this.messageList.push(newMsg)大概率页面不会刷新。因为State监听的是数组引用本身的变化push是原地修改数组引用没变UI框架不知道该重新渲染。正确的做法是像上面代码里那样创建一个新数组再赋值。这一点我会在第三章展开讲因为它真的是聊天页不刷新的头号元凶。键盘的回车发送也要接上TextInput的onSubmit回调里直接调同一个sendMessage方法。这样用户不用非得点屏幕上的发送按钮打字流利很多。手机输入法右下角的回车键通常有发送和换行两种模式具体取决于输入法配置但从产品角度出发聊天场景的输入框回车就应该是发送。2.4 键盘避让与安全区适配真实可靠的处理方式键盘避让是聊天页面绕不开的环节。iPhone上键盘弹起页面跟着顶起来是系统默认行为但HarmonyOS 6里你需要手动处理不然就会看到输入框被键盘挡住一半的尴尬场景。我在这个案例里采用组合方案根容器设置expandSafeArea让页面布局向底部安全区延伸同时监听键盘高度变化动态给消息列表加上底部padding。这样键盘弹起时输入区被顶到键盘上方而且列表的底部padding同步增加最后一条消息不会被输入区挡住。.expandSafeArea({ type: SafeAreaType.SYSTEM, edges: SafeAreaEdge.BOTTOM })键盘高度监听我把它放在页面级获取到键盘高度后设置给列表的paddingBottom。这个方案的优点是对布局的控制力最强缺点是你得自己处理好动画时序。实测中最容易翻车的是键盘动画还在进行中你立刻去调scrollToEdge结果滚动距离是拿键盘最终高度算的动画没走完导致滚动位置不准。解决办法是滚动调用加上一个小延时或者监听键盘动画结束的回调再滚动。这看起来是个很小的细节但实际体验差别很明显。还有一类设备有底部导航条expandSafeArea设置不当消息列表会被底部导航条挡掉一块。我的建议是在真机上反复切几个页面验证模拟器和真机的安全区行为经常不一样。3. 关键环节优化滚动定位、缓存与渲染性能功能跑通只是第一步。聊天页面是用户高频使用的界面滚动手感、刷新流畅度这些隐性指标直接决定用户愿不愿意用。这一节讲我实测过有效的三个优化点。3.1 消息自动滚动到底部的实现方案聊天页面最经典的动作就是发完消息滚到底部有新消息进来也要滚到底部。我在代码里用的是Scroller的scrollToEdge方法。第一版实现我是发送后立刻调用结果发现经常滚不到位后来排查发现是列表的布局还没完成滚动命令发出去了但数据都还没渲染出来自然滚不动。private scrollToBottom() { setTimeout(() { this.listScroller.scrollToEdge(Edge.Bottom) }, 50) }这50毫秒的延时看着土但实测非常有效。你也可以用ArkUI提供的组件状态回调在列表数据刷新完成后的时机再滚动。核心思想是滚动动作必须发生在列表布局结束之后而不是发送动作之后。还有一个容易被忽略的点当用户正在往上翻历史消息时新消息到达要不要强制滚到底部如果强制用户就会被粗暴打断。正确的产品做法是判断用户当前是否在底部附近如果在底部附近才自动滚动如果正在看历史消息则静默更新消息列表在底部显示一个新消息提示条用户点击后再滚下去。这个逻辑在这个案例里我简化掉了但真实项目中几乎必做提前知道可以少返一次工。3.2 列表缓存策略与key的稳定性List组件性能优化的核心是控制同时存在的子组件数量。List本身会复用ListItem但复用范围需要你主动控制这就是cachedCount属性的作用。cachedCount表示当前可视区域之外还要预加载多少个ListItem的缓存。聊天场景里我习惯设置成5个左右。设置太多会白白占用内存设置太少滑快了会出现白屏。ForEach的第三个参数是key生成器这可能是聊天页最容易埋雷的地方。我见过有人图省事直接传indexForEach(this.messageList, (item, index) { ... }, (item, index) index)这是大忌。index作为key消息插入或删除时后续所有项的key都会变化列表会把这些项全部重建表现就是数据明明没变UI却闪来闪去。真正常用的key是msgId因为消息的唯一ID永远不变。用msgId做key列表才能精准知道哪条是新增、哪条是复用。3.3 状态刷新流程为什么你改了数组但UI不动我在2.3节提到了push不刷新的问题这里展开讲。ArkUI的State对数组的观测是基于引用替换的。你用了push、splice这种原地修改的方法数组的引用没有变框架认为数据没变自然不刷新。我刚开始从web开发切过来的时候也特别不习惯因为在JavaScript里直接push是常态。在ArkTS里你需要这样// 错误示范不触发刷新 this.messageList.push(newMsg) // 正确示范创建新数组触发刷新 this.messageList [...this.messageList, newMsg]如果你实现的是一次删除操作同理this.messageList this.messageList.filter(item item.msgId ! targetId)记住一个判断标准只要你想让State管理的数组变化被UI响应就必须让数组变量被重新赋值。这不是玄学是框架的数据变更检测机制决定的。3.4 扩展能力图片消息、时间分隔与长按菜单文本聊天只是起点真实产品几乎都要加图片消息、系统通知、时间分隔这类元素。我在设计MessageItem时预留了msgType字段就是为了让这些扩展不动骨架。图片消息的思路是msgType变成imagecontent字段存图片的本地路径或网络地址气泡组件里根据msgType切换文本组件和图片组件。组件内用if判断消息类型页面主结构完全不用变。时间分隔的话比较轻量的做法是在渲染前对消息数组做一次预处理遍历数组如果本条消息和上一条的timestamp间隔超过5分钟就插入一条纯时间文本的数据项。注意这条插入项也要有唯一的msgId可以把时间戳乘以一个数再加个固定前缀避免和其他消息撞key。长按菜单我建议用bindContextMenu或弹窗实现。点击复制走系统剪贴板点击删除就从消息数组里filter掉。这些操作因为涉及修改数组全都走创建新数组再赋值这条路径。把这些扩展话题放在这儿是为了让你看到好的架构能把未来的改动成本压到最低而聊天页面最忌讳的就是把所有逻辑堆在页面主组件里变成一个两千行的Monster。4. 常见问题与排查技巧实录这一节全部来自我实际开发和测试中遇到的真实问题。花几分钟看完可能帮你省掉一个下午的排查时间。4.1 键盘弹起后输入区被遮挡的三种解法我在不同设备上测试发现键盘避让并没有一个一劳永逸的写法不同版本和机型的行为有差异。总结下来有三种办法方案做法优点缺点监听键盘高度获取键盘高度动态给列表设置padding控制力最强动画可自定义需要处理时序问题安全区扩展根容器expandSafeArea到底部简单一行配置解决底部导航条遮挡键盘弹出时不一定完全避让组件避让模式使用keyboardAvoidMode类属性系统自动避让代码量最少行为相对黑盒特殊布局容易失效我的建议是主用第一种辅以第二种。监听键盘高度的代码看起来繁琐但它能让你明确知道键盘现在弹了多少、列表底部应该空出多少后面做沉浸式聊天背景的时候也方便。单纯依赖系统避让遇到和底部安全区叠加的场景会很难调。4.2 消息发送后列表不刷新的排查流程如果你遇到发消息后列表没反应按这个顺序排查先检查messageList的长度有没有变在sendMessage里加一行日志长度变了但UI没变那就是数组引用没有替换检查是不是用了push长度没变那就是发送逻辑本身没执行检查TextInput的onChange和输入绑定如果其他都正常但滚动没到底那就是滚动时序问题按3.1的延时方案调。还有一个容易忽略的点如果你在多个地方持有messageList的引用比如在页面加载时做了let copy this.messageList然后往copy里push原始数组的引用没有触发替换UI同样不会刷新。这是一个看似没用push却等同push的坑排查起来更隐蔽。4.3 ForEach的key重复导致渲染错乱这个问题的典型表现是消息列表刷新后有些消息消失了有些消息重复了控制台还会报Duplicate key之类的警告。根本原因就是keyGenerator返回了重复值或者同一个key在不同位置出现。我在开发中就遇到过用时间戳做key的事——同一毫秒内连发了多条消息时间戳完全一样key撞车列表渲染立刻错乱。更隐蔽的情况是不同会话的消息混在一起比如你做全局消息列表时没加会话前缀msgId都是msg_初始时间戳两个会话一合并就炸了。解决方法是msgId生成时加入会话维度比如chat_abc_msg_1720000000000_8362。宁可id长一点也要保证全局唯一。这个教训是生产环境教我做人教出来的。4.4 聊天页卡顿与内存增长问题聊天页的卡顿通常来自三个地方消息渲染开销、图片加载开销、无限增长的历史数据。文本消息本身很轻真正的杀手是图片。聊天列表里的图片如果直接加载原图几十条消息就能让内存飙到可怕的程度。建议在ChatPage里对图片做统一压缩和缓存缩略图走轻量加载点击放大时再加载高清版本。历史数据的无限增长也要处理。几千条消息全挂在List里哪怕有缓存机制也会一直占用内存。正确做法是上滑加载历史记录只保留最近N条配合分页接口做增量加载。在ArkUI里这可以通过列表滑到顶部时触发加载回调插入更早的数据后保持视觉位置不变。4.5 实战自测清单与我的几点体会聊天页面做完后我是拿下面这张清单自测的每一条都是真实用户会操作的路径连续发送20条消息列表是否稳定滚动到底是否出现错位或白屏键盘弹出后发送消息列表最后一条是否完全可见从后台切回聊天页输入框内容是否保留列表位置是否保持深色模式和浅色模式下气泡和文字是否都有足够的对比度系统字体调到最大后气泡是否出现文字截断长按自己的消息和对方的消息弹出的菜单是否不同反复进出页面后内存和帧率是否保持稳定如果这些场景都能通过这个聊天页基本可以见人了。最后想分享一个算是我个人体会最深的东西聊天页面这类高频交互界面90%的体验问题都出在状态不同步上要么是数据和UI不同步要么是动画和布局不同步。所以每次动手改代码前我都会先在纸上把状态变化捋一遍捋清楚了代码往往自己就顺了。希望这个案例里拆解的思路也能帮你在自己的项目里少踩几个坑。