茶器艺科智造HarmonyOS应用实战-56-新Toast会直接取消旧Toast导出错误为何一闪而过加入队列、优先级与安全区应用内 Toast 同时承接切片完成、连接成功、贴图更新、读取失败、智能体错误和 Web 侧 STL 消息。茶器艺科智造当前只有一份文本和一个计时器任何新消息到来都会清掉旧计时器、覆盖文本并重新计时。于是“正在导出”之后紧接一个普通提示时重要错误也可能很快被下一条消息替换固定底部 96vp 又没有显式合并窗口安全区。解决方法不是把所有时长加倍而是为消息加类型、优先级、最短展示、去重键和可操作性再由队列统一决定谁能显示。1. 实际问题单槽位让最后到达者无条件获胜当前showToast()先取消已有 timeout再把chaqiToastText替换成新文本并显示。时长会限制在 1500–10000ms但这个下限只对“没有新消息打断”的情况有效。privateshowToast(msg:string,duration:number2000):void{if(this.chaqiToastTimerId0){clearTimeout(this.chaqiToastTimerId)this.chaqiToastTimerId-1}this.chaqiToastTextmsgthis.chaqiToastVisibletrueconstdMath.max(1500,Math.min(10000,duration))this.chaqiToastTimerIdsetTimeout(():void{this.chaqiToastVisiblefalsethis.chaqiToastTimerId-1},d)asnumber}源码没有消息 ID、类别、队列、去重、优先级或“至少展示到何时”。因此旧消息实际展示时间可能远小于传入 duration。本文把“导出错误一闪而过”视为结构允许的风险没有声称已经在设备上复现某条具体错误。2. 来源审计页面与Web都写入同一个槽位页面内有切片完成、连接、图片大小、读取不完整、格式不支持、贴图更新、智能体错误、视角重置和 STL 流程等多处调用。CupWeb3d.ets还通过 eventHub 发出 JSON只包含m文本和d时长页面解析后仍调用同一个showToast。privatereadonlyonChaqiToast(data:object|string):void{letmsgletdur3200if(typeofdatastring){try{constvalueJSON.parse(data)asRecordstring,ObjectmsgString(value[m]??)constparsedDurationNumber(value[d])if(!isNaN(parsedDuration)parsedDuration0){durparsedDuration}}catch(_error){msgdata}}if(msg.length0){this.showToast(msg,dur)}}调用方只能通过时长暗示重要性管理器无法知道“读取失败”应压过“已重置视角”也无法识别连续的导出进度是否属于同一任务。修复应先升级消息协议再替换计时逻辑。3. typed消息把重要性和生命周期写进数据建议定义ToastMessage。kind 用于视觉和无障碍语义priority 用于调度dedupeKey 把同一任务的进度合并minMs 保证最短阅读时间maxMs 防止普通消息永久占位sticky 只给需要用户确认的错误action 提供“重试”或“查看详情”。typeToastKind|info|success|warning|errorinterfaceToastAction{label:stringactionId:string}interfaceToastMessage{id:stringkind:ToastKind priority:numbertext:stringcreatedAtMs:numberminMs:numbermaxMs:numbersticky:booleandedupeKey?:stringaction?:ToastAction source:page|web3d|agent}id必须唯一dedupeKey 才是同一逻辑消息的稳定键。例如 STL 导出可用stl-export:jobId进度更新替换同组 pending 项error 使用新 ID 并提高优先级。priority 的范围和各类默认值要集中定义不让调用点随手写 999。文本也应有长度和字符策略。来自 Web 或异常的原始字符串先映射为用户文案详细堆栈写受控日志不要把路径、内部对象或敏感值塞进 Toast。4. 调度规则同级排队高优先级才允许抢占建议的默认规则是没有 current 时立即展示新消息优先级小于或等于 current 时进入队尾更高优先级只有在 current 已满足 minMs 或 current 允许被抢占时才切换error 可以抢占普通进度但被抢占的可恢复消息按剩余时间回队。队列要设上限并优先丢弃重复低优先级 info。classToastQueue{privatecurrent?:ToastRuntimeprivatepending:ToastMessage[][]privatetimerId:number-1privategeneration:number0privatereadonlymaxPending:number8enqueue(message:ToastMessage):void{constnormalizednormalizeToast(message)this.mergePendingByDedupeKey(normalized)if(this.currentundefined){this.showNext()return}if(this.canPreempt(normalized,this.current)){this.preemptCurrent(normalized)return}this.insertByPriority(normalized)this.trimLowPriorityOverflow()}}maxPending8 是建议初值不是系统上限。若错误消息超过队列容量不能静默丢失应转入持久的错误中心、任务详情或日志并让顶部状态可发现。Toast 只适合短时反馈不应承担全部故障恢复。5. 计时器需要generation旧回调不能关闭新消息每次展示新 current 都递增 generation并在 timeout 中捕获。旧计时器即便在 clear 与执行边界相撞也只能结束它所属的那一代。sticky 消息不安排自动关闭普通消息在 maxMs 后完成并拉取下一条。privatepresent(message:ToastMessage):void{this.clearTimer()constgenerationthis.generationconstnowDate.now()this.current{message,shownAtMs:now,earliestDismissAtMs:nowmessage.minMs}this.publishCurrent()if(!message.sticky){this.timerIdsetTimeout(():void{if(generation!this.generation){return}this.finishCurrent(timeout)},message.maxMs)asnumber}}privatefinishCurrent(reason:string):void{this.clearTimer()this.currentundefinedthis.publishHidden()this.showNext()}若用户点击 action先记录 message ID 和 actionId再结束 currentaction 执行失败可以入队一个新的 error不能重新使用旧 ID。页面离开时应取消 timer、增加 generation、清掉内存队列或把队列所有权提升到应用级两种生命周期语义要选一种并写清。6. Web协议升级m和d兼容读取新增kind与dedupeKey迁移期可以继续接受旧{m,d}但默认归类为 info新格式带协议版本、kind、code、jobId 和 progress。页面只接受白名单 kind限制时长和文本长度并由 code 映射 priority。外部消息不能直接指定任意高优先级。interfaceWebToastPayloadV2{v:2m:stringkind:stringcode?:stringjobId?:stringprogress?:number}functionfromWebToast(raw:string):ToastMessage{constvalueJSON.parse(raw)asRecordstring,ObjectconstversionNumber(value[v]??1)consttextsafeToastText(String(value[m]??))if(version2){returninfoToast(text,web3d)}constkindallowToastKind(String(value[kind]??info))constcodesafeCode(value[code])returnpolicyToast({kind,text,source:web3d,code,dedupeKey:buildWebDedupeKey(value)})}旧 JSON 解析失败时直接把整串当文案可能显示结构化垃圾建议改为统一的“3D 预览返回了无法解析的消息”原文只进入截断日志。Web 侧导出开始、进度、成功、失败使用相同 jobId队列才能合并进度并保留最终错误。7. 安全区bottom96改为由窗口和底栏共同计算ChaqiToastOverlay.ets当前固定margin({ bottom: 96 })最大八行外层hitTestBehavior(HitTestMode.Transparent)。固定值没有表达底部系统避让区、浮动 Tab 高度和额外间距的来源透明命中也意味着当前浮层没有可点击 action。Componentexportstruct ChaqiToastOverlay{Propmessage:ToastMessagedefaultToast()PropbottomSafeInsetVp:number0ProptabOverlayHeightVp:number0onAction:(id:string)void(){}privatebottomOffsetVp():number{returnthis.bottomSafeInsetVpthis.tabOverlayHeightVp12}build(){Stack(){this.ToastCard()}.margin({bottom:this.bottomOffsetVp()})}}建议由页面读取 bottom avoid area和当前手机/宽屏底栏实际占用高度一起传入。键盘显示时 Toast 放在键盘上方还是贴窗口底部需要单独定义。若 message 有 action卡片必须可命中且不让全屏透明层吞掉后方操作具体 ArkUI 命中层级要用组件测试确认。错误内容超过八行时不应简单拉长 Toast。主文案保持短详情转到弹窗或错误页action 标签要明确例如“重试导出”“查看详情”不要只有“确定”。8. 无障碍与去重消息可读、可操作、不过度打扰状态不能只靠边框颜色区分。浮层应给出“错误”“成功”等文字前缀或图标语义设置合适的辅助说明并验证屏幕阅读器能在新消息出现时感知。连续进度不应每 1% 都重复播报可按 10% 或阶段去重最终成功和失败必须播报一次。functionannounceText(message:ToastMessage):string{switch(message.kind){caseerror:return错误message.textcasewarning:return提醒message.textcasesuccess:return成功message.textdefault:returnmessage.text}}functionprogressDedupeKey(jobId:string):string{returnstl-export:jobId:progress}无障碍公告 API、焦点策略和 action 的组件写法应按项目目标 API 文档核实。错误变成 sticky 时不能强制把焦点从用户当前操作抢走可以提供清晰的关闭按钮和任务详情入口。用户主动关闭后重复同一错误应遵循冷却和状态变化规则。9. 验证矩阵、故障排查与证据边界输入顺序预期 currentpending/合并行为关键断言info A → info BA 满足策略后再 BB 排队A 不被立即覆盖progress 1→2→3最新进度同 dedupeKey 合并队列不膨胀info → export errorerrorinfo 可回队或结束error 优先error → successerrorsuccess 排队error 不一闪而过error sticky → actionerror 到点击action 后关闭可恢复旧 timer → 新 current新消息旧 generation 忽略不误关新消息队列超过8条高优先级保留丢弃/合并低级 info错误另有记录底部安全区变化同一消息offset 重算不被手势区遮住键盘弹出按产品规则移动不重复入队文本和按钮可见页面离开隐藏或移交应用级timer 清理无离页回调改 State现象优先核对可能原因处理方向错误仍被成功提示盖掉priority 与 canPreempt所有消息仍同级由 code/kind 集中映射同一进度排满队列dedupeKeyjobId 未传或 key 每次变化稳定任务键合并新消息莫名消失timer generation旧 timeout 关闭新 current代次核对Toast挡住底栏bottom inset 与底栏高度仍固定 96vp动态合并三个偏移按钮点不到hitTest 和层级沿用全透明命中仅操作卡片可命中页面离开仍弹消息队列所有权eventHub/timer 未清明确页面级或应用级屏幕阅读反复播报进度更新频率每条都公告阶段化播报详情泄露路径文案映射直接显示底层异常诊断码与用户文案分离本文静态核对了当前单文本、单 timer 的showToast()新消息先 clear 旧 timer、时长 clamp、eventHub 的m/d协议、多种成功与错误调用点以及浮层固定 bottom 96、最多八行和透明命中。这些是 live 源码事实。它们说明新消息会覆盖旧消息但不能证明某次导出错误已经在真机一闪而过。ToastMessage、优先队列、generation、sticky/action、Web v2 协议、动态安全区和无障碍策略均为本文建议未改入参考项目。本文没有运行构建、组件测试、屏幕阅读器、键盘/手势导航或真实 STL 导出。因此队列调度、点击命中、辅助公告和各窗口模式的偏移仍需在实现后逐项验证短暂反馈之外的关键错误还应落到可回看的任务记录不能只靠 Toast。