光汐 LumaTide 是一个 ArkTS + ArkUI Canvas 的光场应用,零位图素材,靠一块会呼吸的屏幕呈现氛围光。原文没有按功能清单复盘,而是把开发中的九次误判拆成事故档案:现象、最初误判、推翻误判的证据、真正根因和落地处方。对 HarmonyOS 开发者来说,这些案卷集中在 Canvas 绘制、材质、布局、命中测试、生命周期和状态写入上,适合按排障主题重组。
一、绘制量先把管线堵死:截图失败不是截图 API 的错
Case 01 的现象很有迷惑性:功能全部跑通,滑动滑杆时眼睛能看出卡顿,想截屏给同事看,pixelMap 却返回空,等十秒也没有结果。最初的误判是截图 API 用法不对,于是反复换 componentSnapshot 的调用位置,加延时、加重试,全部无效。偶尔能截到一张花屏,反而让人相信“再调一下参数就成了”。
推翻误判的证据来自 render 末尾的绘制次数打点:一帧的 opCount 冲到 15 万以上。截图失败不是 API 的问题,而是管线被自己的绘制量堵住了。根因是三层叠加的挥霍:每帧重建 5 条全屏渐变;150 个尘埃加 64 个颗粒逐个 fill,等于每帧两百多个独立绘制批次;再叠 shadowBlur,而它是软件光栅化的重灾区。三者相乘,单帧耗时早已超过帧间隔,队列永远排不完。
处方一是静态渐变做缓存,缓存键只含三要素。关键在 Math.round(bright * 12) 这个量化:滑杆是连续值,直接拼进键会导致每帧都不命中;压成 12 档后,一次完整拖动最多重建 12 次。缓存键的粒度,就是性能与精度的兑换率。
- private ensureBaseGradients(ctx: CanvasRenderingContext2D, w: number, h: number, bright: number): void {
- let key: string = this.scene.id + '|' + Math.round(bright * 12) + '|'
- + Math.round(w) + 'x' + Math.round(h);
- if (key === this.cacheKey) { return; }
- this.cacheKey = key;
- // 天空、地平线、暗角、上下遮罩,五条渐变在这里一次性重建
- }
复制代码
处方二是同类图元合成一条路径,只发一次绘制。处方三是粒子数量下调,帧间隔定在 42ms。这不是认输,而是重新定义“够用”:氛围光在 24fps 下的观感比 60fps 更稳,因为它不再暴露每一次抖动的细节。15 万这个数字后来成了阈值,任何改动之后,第一件事是看 opCount 有没有涨回去。
- ctx.fillStyle = Luma.alpha(glow, a);
- ctx.beginPath();
- for (let i = 0; i < this.dust.length; i++) {
- let d: Dust = this.dust[i];
- ctx.moveTo(d.px + d.r, d.py);
- ctx.arc(d.px, d.py, d.r, 0, 6.2832);
- }
- ctx.fill();
复制代码
二、材质、对齐与弹性:三个 ArkUI 布局陷阱
Case 02 是深色玻璃变成浅灰卡片。给调校面板加毛玻璃后,深色底上立刻浮出一张浅灰色卡片,白字几乎看不见。最初以为是背景色透明度不够,把 #E6070910 一层层往深里调,从 90% 调到 96%,卡片确实暗了一点,但白字依旧发灰,而且面板与背后的光场彻底断开。把 backgroundBlurStyle 注释掉后文字立刻清晰,问题不在颜色,而在模糊本身。根因是没告诉系统按哪种色彩模式取样,系统默认跟随浅色模式,从背景取平均色后再按浅色主题的材料规则叠加,结果把深色背景“提亮”成中灰。处方是显式指定深色取样:
- .backgroundBlurStyle(BlurStyle.Thick, { colorMode: ThemeColorMode.DARK })
复制代码
这个案子留下的经验是:凡是“结果比预期亮/比预期淡”的材质问题,先怀疑取样模式,再怀疑颜色值。颜色只能改亮度,改不了材料的组成规则。
Case 03 是面板全部跑到屏幕顶上。调校面板和底部导航一起塞进 Stack,想让它贴底,于是给子组件加 .align(Alignment.Bottom),运行后两块面板齐刷刷跑到屏幕顶部,中间大片空白。真正根因是 Stack 的位置由父容器的 alignContent 决定;子组件的 .align() 管的是它自己内部内容的排布,不改变它在父容器里的基准位置。两个 align 同名不同义。处方是让“贴底”成为布局属性,而不是位置补偿:用 Stack 的 justifyContent(FlexAlign.End),配合 padding 的 bottom 108,并给不拦截的装饰层设置 hitTestBehavior(HitTestMode.Transparent)。用位置微调解决的问题都会复发,因为它在抵抗布局规则而不是利用它。
Case 04 是文字压在光球上。呼吸页画布写 layoutWeight(1) 想撑满剩余空间,结果光球胀大时文字被盖住,按钮贴着内容边缘,垂直方向没有节奏。给文字加 zIndex、给按钮加 margin 都不稳定。根因是把“弹性”当成“自适应”:layoutWeight 参与的是剩余空间分配,同列里文字层和按钮层也在争这份空间,三层一起抢,谁也拿不到稳定尺寸。处方是画布给固定高度,上下各放一个 Blank() 撑开。一个屏幕上最多只能有一个“弹性主角”,主角定了高度,其他元素才有参照系。
- Blank()
- Canvas(this.ctx).width('100%').height(340).onReady(() => { /* ... */ })
- Blank()
复制代码
三、看不见的层与不死的定时器:命中测试和生命周期
Case 05 是看不见的控件仍在吃点击。沉浸模式里控件淡出后,点击和拖动全部失效,画面还在呼吸,手指像点在玻璃上。最初怀疑 Canvas 触摸回调没注册,又怀疑手势被父组件拦截。证据是:把控件透明度改成 0 但不做动画,依然点不动;把控件整块删掉,立刻正常。凶手是那个“看不见但还在”的容器。opacity(0) 只改变绘制,不改变命中,透明层依然参与事件分发,把整个屏幕的触摸吞掉了。处方是可见性与命中必须同时切换:
- .opacity(this.showChrome ? 1 : 0)
- .hitTestBehavior(this.showChrome ? HitTestMode.Default : HitTestMode.None)
复制代码
反过来,常驻但不该拦截的装饰层要用 HitTestMode.Transparent,它自己收不到事件,但事件能穿透到下面的兄弟节点。以后每加一个有透明度动画的层,都先问一句:它隐藏时该不该收事件。
Case 06 是离开页面还在耗电。切到别的 Tab 再切回来,感觉光场“跳了一下”;放后台半小时,手机明显发热。最初以为是渲染太重,回去继续压绘制量,压了没用,因为问题不在画得多,而在于还在画。在定时器回调里打日志后发现,离开页面后日志仍在刷,还开始出现 Canvas is not attached 之类的警告。根因是 setInterval 的句柄没有在组件销毁时清除。ArkUI 的 Tab 切换会真正销毁组件实例,但定时器属于 JS 运行时,不会跟着消失。它继续以每秒 24 次的频率往一个已经不存在的画布上画,既耗电,又在内核里堆警告。处方是:
- aboutToDisappear(): void {
- if (this.timer !== -1) {
- clearInterval(this.timer);
- this.timer = -1;
- }
- }
复制代码
这里有个容易漏的细节:句柄要置回 -1。如果只 clearInterval 不重置,下次 start() 里那句 if (this.timer !== -1) return; 会以为还在运行,从此再也起不来,表现是“第二次进入页面就静止”,比耗电更难查。这类 bug 没有异常、没有红色日志,只有一个缓慢升高的电量和一条不动的画面。
Case 08 是拖不动的光。五颗光在页面上呼吸、漂移,但手指按上去毫无反应,偶尔能拖动一次。加上 onTouch 后能拿到坐标,但依然拖不动;打印 pick 的返回值永远是 -1,说明命中测试一次都没通过。检查热区计算:写的是固定 60px,而光晕半径在大屏上已经两百多像素。热区用常量,视觉用比例,两者在真机尺寸下差了三倍,用户看着光晕按下去,实际落在了热区之外。处方是热区跟着视觉走,并且选最近的那颗,因为光晕会重叠,用户按下去想抓的通常是中心最近的那颗。
- let reach: number = Math.min(this.w, this.h) * n.r * 0.42;
- if (Math.sqrt(dx * dx + dy * dy) < reach) { /* 命中 */ }
复制代码
0.42 这个系数之后又调过两次。它不是几何常数,是手感常数,只能靠手指试出来。
四、Canvas 路径语义与状态写入:症状常长在别的模块身上
Case 07 是半径为零的圆,和一张网。尘埃层合并成单路径之后,画面上多出一堆细线,把二十多个点连成了一张蜘蛛网,暗部尤其明显。最初以为是噪点透明度太高,把 grain 一路调低;又怀疑暗角径向渐变出现色环,调了两小时,网还在。把 fill 改成 stroke 逐段看,发现每条线都从一个圆的终点连到下一个圆的起点,这是路径连接的典型特征。根因是:同一条路径里连续调用 arc,Canvas 会把上一段子路径的终点和下一段的起点用直线接起来。这不是 bug,是路径语义,arc 只追加子路径,不主动断开。处方是每个圆之前先 moveTo 到它的起点:
- ctx.moveTo(d.px + d.r, d.py); // 断开上一条子路径
- ctx.arc(d.px, d.py, d.r, 0, 6.2832);
复制代码
这个 bug 的恶劣之处在于外观。看起来像“噪点没调好”,于是你去调噪点;看起来像“暗角有脏点”,于是你去调暗角。绘制语义的错误,症状总长在别的模块身上。
Case 09 是倒计时把界面拖垮。呼吸页开始计时后,帧率肉眼可见地掉,进度弧一卡一卡地走,而画布本身并不复杂。最初以为 Canvas 与状态驱动混用导致整页重建,尝试把倒计时文字移出组件、改成 TextTimer,效果有限。在 tick 里统计状态写入次数,发现每秒三十几次:this.remain 被写成了 3.87 这种浮点值,每帧一个新值。根因是 ArkUI 的状态“写一次刷新一次”。倒计时只需要显示整数,却每帧写入小数,等于每秒触发三十多次文本节点重建,还连带整块布局重算。处方是只在语义发生变化的瞬间写状态:
- let r: number = Math.max(1, Math.ceil(step.seconds - this.stepElapsed));
- if (r !== this.lastRemain) {
- this.lastRemain = r;
- this.remain = r;
- }
复制代码
lastRemain 这个影子变量看着多余,其实是这类计时界面的标准件:它把状态写入从“随帧率”变成“随语义”。同理,phaseLabel 只在切步时写,cycles 只在整轮结束时写。三个状态三种频率,UI 线程曲线才平得下来。每次写 @State 之前,先问一句“这个值真的变了吗,还是只是算得不一样了”。
归档:处方之间没有巧合
九个案子摊开看,处方可以归成四类,每一类都对应一种思维方式的纠正。第一类是把常量换成比例:Case 08 的热区 0.42、Case 01 的粒子数随屏幕密度调整。常量在开发机上永远是对的,因为开发机就是那一个尺寸。第二类是把每帧的事改成每次的事:Case 01 的渐变缓存、Case 09 的状态写入。凡是“不会每帧变”的东西,都不该每帧重建。第三类是把视觉属性与行为属性分开管:Case 05 的透明度与命中、Case 03 的对齐与位置。UI 框架里同名不同义的 API,是这类错误的高发区。第四类是把生命周期当一等公民:Case 06 的定时器、Case 05 的隐藏层。组件会真正被销毁重建,而 JS 运行时里的东西不会自动跟着死。
原文还提到两个没归档的模块:光记页的落盘和节律的配置化。它们一次都没犯病,反倒说明一件事:当数据结构先想清楚,代码往往不需要抢救。节律被写成“每步只描述这几秒里半径从哪到哪”的纯数据,于是换节律等于换配置;光记被写成一条 JSON 存一个 key,于是加字段不用改读取逻辑。做对的设计不会出现在事故档案里,这本身是它存在的证据。
事故档案比成功案例有用,因为失败的方向是可复用的。下次遇到“结果比预期亮”,先想色彩模式;遇到“透明却点不动”,先想命中;遇到“画面多出一堆线”,先想路径有没有断开成子路径。九次误判换来的就是这些条件反射,它们比架构图更接近真实工程的形状:真实工程不是设计出来的,是排除出来的。 |