一、前言Canvas 逐帧动画的三道坎在鸿蒙上写死一个静态 Canvas 很容易但要写一个「活的」Canvas 头像会立刻撞上三道坎几何坎眼睛不是贴在脸上的贴纸它会「越球面转动」——转到侧面会变窄、转到背面应该消失。这需要投影而不是简单的translate。物理坎表情切换不能瞬跳要有「弹一下又阻尼停下」的质感但数值积分方程写不对动画会越弹越大甚至发散。调度坎要 60fps 逐帧但头像静止时Idle 且无动画又不能让 DisplaySync 空转耗电。GrokBot 的渲染引擎正是围绕这三道坎设计。下面逐一拆解。二、坐标映射259 逻辑空间 → 物理 Canvas2.1 为什么所有数据都落在 259 的 viewBoxGrokBotExpressionData.ets里 25×2×48 个点坐标都是 0259 的逻辑值。真正画到屏幕前paintGrokBotFrame做统一缩放const GROKBOT_VIEWBOX_SIZE 259; const GROKBOT_VIEWBOX_INSET 15; const GROKBOT_BODY_WIDTH 228.541; export function paintGrokBotFrame(ctx, size, rings, shape, gaze, turn, eyeScale, blinkScale, flipX, emphasis, showGuides, theme): void { const w ctx.width 0 ? ctx.width : size; const h ctx.height 0 ? ctx.height : size; ctx.clearRect(0, 0, w, h); ctx.save(); const side Math.min(w, h); // 取短边保证不拉伸 const canvasScale side / GROKBOT_VIEWBOX_SIZE; // 逻辑 → 物理的缩放系数 ctx.translate((w - side) / 2, (h - side) / 2); // 居中 ctx.scale(canvasScale, canvasScale); ctx.translate(GROKBOT_VIEWBOX_INSET, GROKBOT_VIEWBOX_INSET); // 留白 // ... }要点canvasScale是唯一的分辨率入口数据永远在 259 空间size变了只改这一个系数。DPR 无关、vp/px 无关一套数据适配所有屏。取Math.min(w, h)短边避免在非正方形画布上产生非等比缩放否则眼睛会被拉椭圆。先translate再scale再translate的顺序不能反这是把「内边距 居中 缩放」正确叠加的标准写法。2.2flipX的水平镜像if (flipX) { ctx.translate(GROKBOT_BODY_WIDTH, 0); ctx.scale(-1, 1); }镜像不是去改 96 个点的 x 坐标而是在 Canvas 变换层做一次scale(-1, 1)。这样数据层完全不用动性能也更好一次矩阵变换 vs 逐点翻符号。用于道具「从右看」的场景Lab 里的 Horizontal mirror。三、躯干CSSborder-radius语法在 Canvas 的重现3.1 形状数据里的圆角18 种形状的核心差异之一就是「圆角」。形状数据里的radius字段直接用了CSSborder-radius的语法[GrokBotShape.Blob, new GrokBotShapeData(0, 0, 1, 1, 1, false, 50%, 1, 1)], [GrokBotShape.Capsule, new GrokBotShapeData(0, 0, .64, .92, .81, false, 50% / 32%, .64, 1.08)], [GrokBotShape.Egg, new GrokBotShapeData(0, 2, .77, .97, .93, false, 50% 50% 56% 44%, .88, 1.05)], [GrokBotShape.Teardrop, new GrokBotShapeData(0, 22, .79, .79, .88, false, 50% 50% 62% 38%, .9, 1.05)], // ...50% / 32%是椭圆角rx / ry50% 50% 56% 44%是四个角左上/右上/右下/左下50%是全覆盖。这直接复用了前端熟知的语义但 ArkUI 的 Canvas 没有现成的「按 CSS 圆角画圆角矩形」API所以必须自己解析 用贝塞尔画。3.2 解析grokBotParseBorderRadiusfunction expandRadius(values: Arraystring): Arraystring { if (values.length 0) return [0, 0, 0, 0]; if (values.length 1) return [values[0], values[0], values[0], values[0]]; if (values.length 2) return [values[0], values[1], values[0], values[1]]; if (values.length 3) return [values[0], values[1], values[2], values[1]]; return values.slice(0, 4); } export function grokBotParseBorderRadius(css, width, height): ArrayGrokBotRadius { const parts css.split(/); // 水平 / 垂直 const horizontal expandRadius(radiusTokens(parts[0])); const vertical expandRadius(radiusTokens(parts.length 1 ? parts[1] : parts[0])); const radii []; for (let i 0; i 4; i) { radii.push(new GrokBotRadius( parseRadiusToken(horizontal[i], width), // 百分比按 width 换算 parseRadiusToken(vertical[i], height))); // 百分比按 height 换算 } clampRadiusPair(radii, 0, 1, width, true); // 水平方向约束 clampRadiusPair(radii, 3, 2, width, true); clampRadiusPair(radii, 0, 3, height, false); // 垂直方向约束 clampRadiusPair(radii, 1, 2, height, false); return radii; }百分比会被换算成绝对像素水平圆角按width垂直圆角按height。这一步看似琐碎却正是「数据层用 CSS 语义、渲染层用绝对几何」的桥。3.3 比例 clamp圆角和不能超过边长CSS 规范里有一条相邻两角的半径之和不能超过对应边长否则要按比例缩小。Canvas 自己不会做这件事所以 GrokBot 手动实现function clampRadiusPair(radii, a, b, size, horizontal): void { const first horizontal ? radii[a].x : radii[a].y; const second horizontal ? radii[b].x : radii[b].y; const sum first second; if (sum size || sum 0) return; const scale size / sum; if (horizontal) { radii[a].x * scale; radii[b].x * scale; } else { radii[a].y * scale; radii[b].y * scale; } }这是GrokBot.test.ets里preservesEllipticalCssRadiusAndClampsPairs锁定的行为——不 clamp 的话90% 90%这种输入会画出重叠的畸形角。3.4 用 KAPPA 贝塞尔画圆角矩形真正的appendGrokBotBodyPath用四段贝塞尔 直线拼出圆角矩形圆角用标准 KAPPA 常数≈0.55228近似四分之一圆const KAPPA 0.5522847498307936; function appendCorner(ctx, cx, cy, rx, ry, startX, startY, endX, endY, c1x, c1y, c2x, c2y): void { ctx.bezierCurveTo( cx c1x * rx, cy c1y * ry, cx c2x * rx, cy c2y * ry, cx endX * rx, cy endY * ry ); } export function appendGrokBotBodyPath(ctx, shape): void { const b grokBotBodyBounds(shape); // [x, y, w, h] const r grokBotParseBorderRadius(shape.radius, b[2], b[3]); ctx.beginPath(); ctx.moveTo(b[0] r[0].x, b[1]); ctx.lineTo(b[0] b[2] - r[1].x, b[1]); // 右上角 ... ctx.closePath(); }四、球面投影眼睛「越球面转动」的核心这是整个引擎最「技术」的部分。眼睛不是贴在平面上的而是贴在**一个横向的球面圆柱**上转动时会变窄、转到背面会消失。4.1 从「环的质心」到「投影后位置」每只眼睛的 48 点先算出质心再由质心相对脸部中心的水平偏移算出它在球面上的「基准经度」加上turn转动角得到当前经度export function grokBotProjectEye(centroid, origin, radius, turn, gaze, scale, blinkScale): GrokBotProjection { const offset centroid.x - origin.x; const baseLongitude Math.asin(grokBotClamp(offset / Math.max(radius, 1), -1, 1)); const longitude baseLongitude turn; // 加上转动角 const depth Math.cos(longitude); // 深度 cos(经度)转到侧面 → 0 const perspective Math.max(depth, 0.02) / Math.max(Math.cos(baseLongitude), 0.02); return new GrokBotProjection( new GrokBotPoint(origin.x radius * Math.sin(longitude) gaze.x, // 投影后的屏幕 x centroid.y gaze.y), // y 保持 视线偏移 grokBotClamp(perspective * scale, 0.02, 2.4), // 水平缩放 grokBotClamp(blinkScale * scale, 0.02, 2.4), // 垂直缩放含眨眼 depth 0.02 // 是否可见 ); }4.2 逐行拆解变量含义offset眼睛质心相对脸部中心的水平偏移baseLongitudeasin(offset / radius)把水平偏移「反投影」回球面的基准经度longitude加上turn后的当前经度depthcos(longitude)正面 1侧面 0背面 负perspectivedepth / cos(baseLongitude)相对自身的透视缩放转到侧面趋近 0scaleX/scaleY最终的水平/垂直缩放clamp 到[0.02, 2.4]防除零visibledepth 0.02转到背面就隐藏关键点scaleX用perspective会被depth压窄scaleY用blinkScale会被眨眼压扁。两者解耦——转动只影响宽度眨眼只影响高度这让「边转边眨眼」的组合动作依然自然。4.3 为什么是asin而不是atan普通透视用atan足够但 GrokBot 模拟的是球面圆柱一个点绕圆柱转它在屏幕上的 x 位置是radius * sin(经度)而不是radius * tan(经度)。这正是「越到侧面越慢、到背面消失」的球面观感来源。测试里锁定了这个行为// 正面可见、缩放为 1 const front grokBotProjectEye(origin, origin, 105, 0, new GrokBotPoint(), 1, 1); expect(front.visible).assertTrue(); expect(near(front.scaleX, 1)).assertTrue(); // 转过 PI反面不可见、缩放钳到 0.02 const back grokBotProjectEye(origin, origin, 105, Math.PI, new GrokBotPoint(), 1, 1); expect(back.visible).assertFalse(); expect(back.scaleX).assertEqual(0.02);4.4grokBotMapGaze视线方向映射gaze是{x, y} ∈ [-1, 1]的归一化向量映射成眼睛的像素偏移export function grokBotMapGaze(gaze: GrokBotGaze): GrokBotPoint { return new GrokBotPoint( grokBotClamp(gaze.x, -1, 1) * 13.2, // 水平最大偏 13.2 grokBotClamp(gaze.y, -1, 1) * 8.4 // 垂直最大偏 8.4 ); }然后这个偏移直接加到投影后的眼睛中心上见 4.1 里的 gaze.x/ gaze.y。所以「看方向」本质上也是纯几何的平移走onVisualChanged一帧重绘即可不触发任何弹簧动画。五、弹簧物理为什么选半隐式欧拉 固定步长子步进表情切换的「弹一下再停」由一个二阶弹簧驱动。这是数值积分最容易翻车的地方。5.1 弹簧类export class GrokBotSpring { value: number 1; // 当前位置目标恒为 1 velocity: number 0; start(): void { this.value 0; this.velocity 0; } active(): boolean { return Math.abs(this.value - 1) 0.001 || Math.abs(this.velocity) 0.001; } step(rawDt: number, frequency: number): void { let remaining: number Math.min(Math.max(rawDt, 0), 0.1); const omega: number Math.max(frequency, 0.001); while (remaining 0) { const dt: number Math.min(remaining, 1 / 120); // 半隐式欧拉先更新速度再用新速度更新位置 this.velocity (-2 * omega * this.velocity - omega * omega * (this.value - 1)) * dt; this.value this.velocity * dt; remaining - dt; } if (Math.abs(this.value - 1) 0.001 Math.abs(this.velocity) 0.001) { this.value 1; this.velocity 0; // 收敛后吸到稳态 } } }5.2 三个工程细节半隐式欧拉semi-implicit Euler先算velocity再用新velocity 更新value。相比显式欧拉用旧 velocity 更新位置它对二阶系统更稳定、能量更守恒不容易越弹越大。固定步长子步进rawDt可能因为一帧抖动而忽大忽小比如卡顿后一帧 100ms。直接拿大dt积分会导致不稳定。GrokBot 把rawDtclamp 到0.1秒再切成一个个≤ 1/120秒的子步逐段积分把可变帧间隔变成固定步长稳定性大幅提升。阻尼 频率系数的写法加速度项-2ω·v - ω²·(x-1)是临界阻尼对应的系数阻尼比 ζ 1保证「最快回到目标且不过冲」。frequency默认 7可调值越大回弹越快越硬。5.3 显式欧拉会怎样反例如果用户手滑写成显式欧拉value velocity * dt; velocity accel * dt当dt偏大、omega偏高时模拟会「绕目标震荡甚至发散」表情切换会抽风。GrokBot 的测试用 300 次step(1/120, 7)验证弹簧能收敛到 1near(spring.value, 1, 0.002)且active()为 false把这个稳定性守护住。六、blink / spin 的缓动节奏6.1 眨眼快闭慢睁的 0.32 秒眨眼不是线性开合而是「快速闭上、缓慢睁开」的不对称节奏export function grokBotBlinkScale(seconds: number): number { const progress: number seconds / 0.32; // 总时长 0.32 秒 // 前 42% 时间从 1 快速降到 0.04闭眼后 58%从 0.04 缓慢回到 1 return Math.max( progress 0.42 ? 1 - progress / 0.42 : (progress - 0.42) / 0.58, 0.04 ); }0.32秒是眨眼总时长写死在组件里blinkSeconds 0.32就完成。0.42/0.58是闭/睁的时间分配比例——闭得快0.13 秒、睁得慢0.19 秒符合真实眨眼。0.04是最小眼裂不会完全闭死留一丝避免整只眼「啪」消失的突兀。blinkScale最终作用在 4.1 的scaleY blinkScale * scale上把眼睛垂直压扁成一条缝。6.2 spineaseInOutCubic 的整圈旋转controller.spin(turns, duration)让整只 GrokBot 做「原地打转」。转动角由缓动函数驱动export function grokBotEaseInOutCubic(t: number): number { const p: number grokBotClamp(t, 0, 1); return p 0.5 ? 4 * p * p * p : 1 - Math.pow(-2 * p 2, 3) / 2; } // onFrame 里 this.spinSeconds dt; const progress clamp(this.spinSeconds * 1000 / this.spinDuration, 0, 1); this.spinAngle grokBotEaseInOutCubic(progress) * Math.PI * 2 * this.spinTurns;easeInOutCubic是缓入缓出开头加速、结尾减速让旋转有「蓄力 → 甩出 → 停稳」的手感而不是机械匀速。spinAngle直接加进turnthis.turn this.spinAngle参与 4.1 的球面投影所以 spin 时眼睛会随躯干一起「转过去再转回来」。七、DisplaySync60fps 逐帧 静止停表这是鸿蒙自定义动画最重要也最容易被写错的一环。setInterval做动画会有帧率不稳、后台空转、与屏幕 vsync 脱节等问题GrokBot 用的是 ArkGraphics2D 的displaySync。7.1 创建与配置import { displaySync } from kit.ArkGraphics2D; private ensureSync(): void { if (this.sync ! null) return; const sync: displaySync.DisplaySync displaySync.create(); sync.setExpectedFrameRateRange({ expected: 60, min: 0, max: 120 }); const callback (_info: displaySync.IntervalInfo): void this.onFrame(); this.frameCallback callback; sync.on(frame, callback); this.sync sync; }setExpectedFrameRateRange({ expected: 60, min: 0, max: 120 })表达「期望 60fps但允许 0120 自适应」——min: 0让系统在静止时可以不给帧配合下面的停表逻辑这是节能的关键。7.2 按需启动 / 停表DisplaySync 不是一直跑而是需要动画时才start静止就stopprivate startAnimation(): void { if (!this.appeared || !this.visible || !this.canvasReady || this.running) return; this.ensureSync(); if (this.sync ! null) { this.lastFrameMs Date.now(); this.sync.start(); this.running true; } } private stopIfIdle(): void { if (this.spring.active() || this.blinkSeconds 0 || this.spinSeconds 0) return; if (this.sync ! null this.running) this.sync.stop(); this.running false; this.lastFrameMs 0; }stopIfIdle在每帧末尾调用只要弹簧不再动、没有眨眼、没有 spin就立刻停表。这样 Idle 静止时 DisplaySync 完全不耗电而一旦有动作弹簧/眨眼/spin又立即start。7.3 帧循环与 delta timeprivate onFrame(): void { const now Date.now(); const dt this.lastFrameMs 0 ? (now - this.lastFrameMs) / 1000 : 0; this.lastFrameMs now; if (this.spring.active()) { this.spring.step(dt, Math.max(this.springFrequency, 0.001)); this.resolveDisplayedRings(); } if (this.blinkSeconds 0) { this.blinkSeconds dt; if (this.blinkSeconds 0.32) { this.blinkSeconds -1; this.completeBlink(); } } if (this.spinSeconds 0) { this.spinSeconds dt; const progress clamp(this.spinSeconds * 1000 / this.spinDuration, 0, 1); this.spinAngle grokBotEaseInOutCubic(progress) * Math.PI * 2 * this.spinTurns; if (progress 1) { this.spinSeconds -1; this.spinAngle 0; this.completeSpin(); } } this.paintNow(); this.stopIfIdle(); }第一帧dt 0的处理lastFrameMs初始为 0startAnimation里会先赋Date.now()所以第一帧dt0只画不推——避免停表后重新启动时出现一次大跳变。7.4 teardown 与可见性联动private teardownSync(): void { if (this.sync ! null) { if (this.running) this.sync.stop(); if (this.frameCallback ! null) this.sync.off(frame, this.frameCallback); else this.sync.off(frame); } this.sync null; this.frameCallback null; this.running false; this.lastFrameMs 0; } // build 里的 onVisibleAreaChange .onVisibleAreaChange([0.0, 1.0], (visible, _ratio): void { this.visible visible; if (visible) { this.paintNow(); this.scheduleBlink(); this.scheduleExpression(); if (this.spring.active() || this.blinkSeconds 0 || this.spinSeconds 0) this.startAnimation(); } else { this.clearTimers(); if (this.sync ! null this.running) this.sync.stop(); this.running false; } })这是最容易被忽略的生命周期细节组件滚出可视区→visiblefalse→ 停表 清定时器绝不后台空转。组件重新可见→ 重绘 重排眨眼/表情 若动画未完成则续跑。组件销毁aboutToDisappear→teardownSync移除frame监听防止内存泄漏。八、绘制装配paintGrokBotFrame的全流程把前面的几何、物理、调度串起来一帧的完整装配是private paintNow(): void { if (!this.canvasReady) return; const shapeData GROKBOT_SHAPES.get(this.shape); if (shapeData undefined) return; this.resolveDisplayedRings(); // 1. 弹簧插值出当前眼睛形状 paintGrokBotFrame(this.context, Math.max(1, this.botSize), this.displayRings, shapeData, this.gaze, this.turn this.spinAngle, // 2. 转动角 手动 turn spin 动画 Math.max(this.eyeScale, 0.001), this.blinkValue(), this.flipX, this.emphasis, this.showGuides, this.theme); }paintGrokBotFrame内部的绘制顺序关键步骤clearRect清屏 →save。计算canvasScale做居中 缩放的坐标映射。可选flipX镜像。画躯干appendBodyPath 填bodyColor先做squashOnTurn的身体压扁。用躯干 path 做clip()让眼睛只在躯干范围内绘制。对每只眼射影 → 若visible则translate/scale后填eyeColor。可选showGuides画投影引导线 质心点用于 Lab 调试。其中squashOnTurn转动时身体压扁是形状层的一个布尔const bodyScale shape.squashOnTurn ? Math.max(Math.cos(turn), 0.55) : 1;Bean、Tablet、Cloud这类形状在转动时会「压扁」cos(turn)衰减下限 0.55模拟 3D 纸片转动而Blob等不压扁保持恒定宽度。九、踩坑速查现象根因修复眼睛越球面转到侧面不消失投影depth没判断visible depth 0.02表情切换越弹越大、抽搐用显式欧拉 大 dt半隐式欧拉 固定步长子步进静止时设备发烫耗电DisplaySync 一直start没停每帧末尾stopIfIdle返回页面后动画卡死/泄漏未移除frame监听aboutToDisappear里 teardown滚出可视区还在逐帧画未监听可见性onVisibleAreaChange停表 清定时器眼睛被拉成椭圆非等比 Canvas 直接用 w/h 缩放取Math.min(w,h)短边做canvasScale圆角叠成畸形角CSS 百分比圆角没 clamp 和clampRadiusPair按边长比例缩放深色模式眼睛还是白主题没随 dark 切换eyeColor传GrokBotThemeData.dark()眨眼「啪」一下消失最小眼裂没设下限blinkScale下限 0.04spin 机械匀速生硬没加缓动easeInOutCubic缓入缓出十、已知边界当前是约 60fps 的 Canvas 逐帧绘制不涉及离屏渲染或硬件合成超大尺寸数百 vp 以上前应做帧率专项评测。弹簧、投影、缓动等纯函数有单测帧率、功耗、后台恢复需真机仪器化不在本文「已证明」结论内。displaySync的min: 0依赖系统调度实际节能效果因设备/系统版本而异。球面投影是「圆柱投影」的近似不包含完整 3D 旋转矩阵roll/pitch 全自由的 3D 眼球不在当前模型内。十一、写在最后GrokBot 这一篇把「让它活起来」的底层原理讲透了。核心结论坐标只映射一次数据永不关心像素。球面投影用asin/cos转动只压宽度、眨眼只压高度。弹簧选半隐式欧拉 固定步长数值稳定比炫技重要。DisplaySync 按需启停静止就停表绝不空转。缓动用不对称节奏快闭慢睁、缓入缓出才有「生命感」。