茶器艺科智造HarmonyOS应用实战-56-新Toast会直接取消旧Toast，导出错误为何一闪而过：加入队列、优先级与安全区

茶器艺科智造HarmonyOS应用实战-56-新Toast会直接取消旧Toast，导出错误为何一闪而过：加入队列、优先级与安全区

应用内 Toast 同时承接切片完成、连接成功、贴图更新、读取失败、智能体错误和 Web 侧 STL 消息。茶器艺科智造当前只有一份文本和一个计时器：任何新消息到来都会清掉旧计时器、覆盖文本并重新计时。于是“正在导出”之后紧接一个普通提示时，重要错误也可能很快被下一条消息替换；固定底部 96vp 又没有显式合并窗口安全区。解决方法不是把所有时长加倍，而是为消息加类型、优先级、最短展示、去重键和可操作性，再由队列统一决定谁能显示。

1. 实际问题：单槽位让最后到达者无条件获胜

当前showToast()先取消已有 timeout，再把chaqiToastText替换成新文本并显示。时长会限制在 1500–10000ms，但这个下限只对“没有新消息打断”的情况有效。

privateshowToast(msg:string,duration:number=2000):void{if(this.chaqiToastTimerId>=0){clearTimeout(this.chaqiToastTimerId)this.chaqiToastTimerId=-1}this.chaqiToastText=msgthis.chaqiToastVisible=trueconstd=Math.max(1500,Math.min(10000,duration))this.chaqiToastTimerId=setTimeout(():void=>{this.chaqiToastVisible=falsethis.chaqiToastTimerId=-1},d)asnumber}

源码没有消息 ID、类别、队列、去重、优先级或“至少展示到何时”。因此，旧消息实际展示时间可能远小于传入 duration。本文把“导出错误一闪而过”视为结构允许的风险，没有声称已经在设备上复现某条具体错误。

2. 来源审计：页面与Web都写入同一个槽位

页面内有切片完成、连接、图片大小、读取不完整、格式不支持、贴图更新、智能体错误、视角重置和 STL 流程等多处调用。CupWeb3d.ets还通过 eventHub 发出 JSON，只包含m文本和d时长；页面解析后仍调用同一个showToast。

privatereadonlyonChaqiToast=(data:object|string):void=>{letmsg=''letdur=3200if(typeofdata==='string'){try{constvalue=JSON.parse(data)asRecord<string,Object>msg=String(value['m']??'')constparsedDuration=Number(value['d'])if(!isNaN(parsedDuration)&&parsedDuration>0){dur=parsedDuration}}catch(_error){msg=data}}if(msg.length>0){this.showToast(msg,dur)}}

调用方只能通过时长暗示重要性，管理器无法知道“读取失败”应压过“已重置视角”，也无法识别连续的导出进度是否属于同一任务。修复应先升级消息协议，再替换计时逻辑。

3. typed消息：把重要性和生命周期写进数据

建议定义ToastMessage。kind 用于视觉和无障碍语义；priority 用于调度；dedupeKey 把同一任务的进度合并；minMs 保证最短阅读时间；maxMs 防止普通消息永久占位；sticky 只给需要用户确认的错误；action 提供“重试”或“查看详情”。

typeToastKind=|'info'|'success'|'warning'|'error'interfaceToastAction{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:number=0privatereadonlymaxPending:number=8enqueue(message:ToastMessage):void{constnormalized=normalizeToast(message)this.mergePendingByDedupeKey(normalized)if(this.current===undefined){this.showNext()return}if(this.canPreempt(normalized,this.current)){this.preemptCurrent(normalized)return}this.insertByPriority(normalized)this.trimLowPriorityOverflow()}}

maxPending=8 是建议初值，不是系统上限。若错误消息超过队列容量，不能静默丢失；应转入持久的错误中心、任务详情或日志，并让顶部状态可发现。Toast 只适合短时反馈，不应承担全部故障恢复。

5. 计时器需要generation，旧回调不能关闭新消息

每次展示新 current 都递增 generation，并在 timeout 中捕获。旧计时器即便在 clear 与执行边界相撞，也只能结束它所属的那一代。sticky 消息不安排自动关闭；普通消息在 maxMs 后完成并拉取下一条。

privatepresent(message:ToastMessage):void{this.clearTimer()constgeneration=++this.generationconstnow=Date.now()this.current={message,shownAtMs:now,earliestDismissAtMs:now+message.minMs}this.publishCurrent()if(!message.sticky){this.timerId=setTimeout(():void=>{if(generation!==this.generation){return}this.finishCurrent('timeout')},message.maxMs)asnumber}}privatefinishCurrent(reason:string):void{this.clearTimer()this.current=undefinedthis.publishHidden()this.showNext()}

若用户点击 action，先记录 message ID 和 actionId，再结束 current；action 执行失败可以入队一个新的 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{constvalue=JSON.parse(raw)asRecord<string,Object>constversion=Number(value['v']??1)consttext=safeToastText(String(value['m']??''))if(version<2){returninfoToast(text,'web3d')}constkind=allowToastKind(String(value['kind']??'info'))constcode=safeCode(value['code'])returnpolicyToast({kind,text,source:'web3d',code,dedupeKey:buildWebDedupeKey(value)})}

旧 JSON 解析失败时直接把整串当文案，可能显示结构化垃圾；建议改为统一的“3D 预览返回了无法解析的消息”，原文只进入截断日志。Web 侧导出开始、进度、成功、失败使用相同 jobId，队列才能合并进度并保留最终错误。

7. 安全区：bottom=96改为由窗口和底栏共同计算

ChaqiToastOverlay.ets当前固定margin({ bottom: 96 })，最大八行，外层hitTestBehavior(HitTestMode.Transparent)。固定值没有表达底部系统避让区、浮动 Tab 高度和额外间距的来源；透明命中也意味着当前浮层没有可点击 action。

@Componentexportstruct ChaqiToastOverlay{@Propmessage:ToastMessage=defaultToast()@PropbottomSafeInsetVp:number=0@ProptabOverlayHeightVp:number=0onAction:(id:string)=>void=()=>{}privatebottomOffsetVp():number{returnthis.bottomSafeInsetVp+this.tabOverlayHeightVp+12}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){case'error':return'错误：'+message.textcase'warning':return'提醒：'+message.textcase'success':return'成功：'+message.textdefault:returnmessage.text}}functionprogressDedupeKey(jobId:string):string{return'stl-export:'+jobId+':progress'}

无障碍公告 API、焦点策略和 action 的组件写法应按项目目标 API 文档核实。错误变成 sticky 时不能强制把焦点从用户当前操作抢走；可以提供清晰的关闭按钮和任务详情入口。用户主动关闭后，重复同一错误应遵循冷却和状态变化规则。

9. 验证矩阵、故障排查与证据边界

输入顺序	预期 current	pending/合并行为	关键断言
info A → info B	A 满足策略后再 B	B 排队	A 不被立即覆盖
progress 1→2→3	最新进度	同 dedupeKey 合并	队列不膨胀
info → export error	error	info 可回队或结束	error 优先
error → success	error	success 排队	error 不一闪而过
error sticky → action	error 到点击	action 后关闭	可恢复
旧 timer → 新 current	新消息	旧 generation 忽略	不误关新消息
队列超过8条	高优先级保留	丢弃/合并低级 info	错误另有记录
底部安全区变化	同一消息	offset 重算	不被手势区遮住
键盘弹出	按产品规则移动	不重复入队	文本和按钮可见
页面离开	隐藏或移交应用级	timer 清理	无离页回调改 State

现象	优先核对	可能原因	处理方向
错误仍被成功提示盖掉	priority 与 canPreempt	所有消息仍同级	由 code/kind 集中映射
同一进度排满队列	dedupeKey	jobId 未传或 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。