【OpenHarmony/HarmonyOs 】ArkUI 对话界面实战消息状态、气泡布局与 AI 云函数接入设计前言AI 助手页面看似只是消息列表和输入框实际包含消息模型、角色布局、不可变状态更新、快捷提示、加载态、失败重试与密钥安全。LinkOS 链界已经实现了完整的对话 UI 骨架当前回复由本地定时器模拟正适合作为真实 AI 接入前的界面原型。一、先定义消息模型typeChatRole user|assistant;interfaceChatMessage { id:string; role: ChatRole; content:string; time:string; }role决定气泡方向与颜色id为 ForEach 提供稳定标识time用于界面展示。真实产品建议继续增加typeMessageStatus sending|success|failed; interface ChatMessage { id:string; role: ChatRole; content:string;time:string;status: MessageStatus; requestId?:string; }状态字段可支持发送动画、失败图标和点击重试requestId可关联服务端日志。二、不可变更新触发 ArkUI 刷新privateaddUserMessage(text: string) {constvalue text.trim();if(!value)return;this.messages [ ...this.messages, { id: m${this.nextIdSeq}, role:user, content: value, time:this.getNowTime() } ]; }重新赋值数组比原地push()更容易保证State变化被框架观察。对于小型会话这种写法直观可靠长会话需要分页、虚拟列表和本地数据库避免数组无限增长。三、发送动作的正确顺序privateonSend() {consttext this.inputText;if(!text.trim())return;this.inputText ;this.addUserMessage(text); setTimeout(() {this.addAssistantMessage(我已收到你的问题……); },200); }当前实现用于演示交互清空输入、添加用户消息、延时生成模拟回复。接入真实接口后推荐流程是添加状态为 sending 的用户消息添加一条“正在生成”的助手占位消息调用云函数流式更新助手内容成功后标记完成失败则保留重试入口。四、按角色构建不同气泡ForEach(this.messages, (message: ChatMessage) {if(message.roleassistant) {Row(){Text()Column(){Text(message.content).lineHeight(22)Text(message.time).fontSize(11)} .backgroundColor(Color.White)} }else{Row(){Text(message.content).lineHeight(22)} .margin({ left:56, right:16}) .backgroundColor(rgba(97, 95, 255, 0.10)) } })助手消息带头像并靠左用户消息缩进显示。除了视觉差异还应加入语义与无障碍描述让读屏软件能说出“用户消息”或“助手回复”。五、快捷提示降低空白页压力首次进入对话页时用户经常不知道该问什么。项目提供四个快捷提示例如“推荐一些开发工具”“如何提高工作效率”。点击后复用统一发送逻辑privatesendQuickPrompt(text: string){this.inputText text;this.onSend(); }快捷提示应结合当前身份动态变化开发者看到代码相关提示学生看到学习计划设计师看到灵感与作品集建议。这能把身份系统和 AI 页面连接起来。六、为什么必须通过云函数调用模型客户端不能直接保存 DeepSeek 或其他供应商的 API Key。HAP 在用户设备上运行静态密钥无法真正保密。推荐架构ArkUI 对话页 ↓ HTTPS请求携带用户 Token AGC CloudFunction├─校验用户身份 ├─ 限流与内容长度检查 ├─ 从服务端环境变量读取 AI Key └─ 请求模型并返回结果云函数还应设置超时、最大 Token、敏感内容策略和成本配额。客户端只拿业务结果不接触第三方密钥。七、真实接口的状态设计建议页面至少维护StateinputText: string ;Statemessages: ChatMessage[] [];StateisGenerating: boolean false;StateerrorText: string ;发送期间禁用重复提交但应提供“停止生成”。超时后不要清掉用户问题应将消息标为失败并允许重试。网络恢复后是否自动重发要谨慎避免产生重复计费。八、流式输出与性能流式回复能让用户更快看到首字但不要每收到一个字符就刷新整个消息列表。可以累计一小段文本或按固定时间间隔更新最后一条消息。长回答还应使用可滚动列表并在用户主动向上阅读时停止自动滚到底部。其他值得补齐的能力包括Markdown 渲染与代码块复制会话历史与新建会话消息长按复制、重新生成联网搜索来源引用对输入长度和附件大小进行限制页面退出时取消尚未完成的请求。九、总结AI 页面应先把消息状态机和交互边界做好再连接模型接口。LinkOS 当前的 ArkUI 原型已经验证了气泡布局、快捷提示和状态数组下一步应通过 AGC 云函数安全接入服务补充生成态、失败重试、流式节流与历史持久化。这样才能从“看起来像聊天”成长为可用的 AI 助手。✨
