uni-app群头像合并展示的多图渲染技巧

在开发社交类应用时，群聊头像的合并展示是一个常见的需求，类似于微信那种将多个成员头像组合成一个群头像的效果。这个功能在uni-app中可以实现，但并非简单的图片叠加，其核心在于利用Canvas进行精确的绘制计算。

核心三步：加载、计算与绘制

实现群头像合并，本质上是一个标准的三步走流程：加载图片资源、计算布局坐标、执行Canvas绘制。无论是2×2、3×3还是其他不规则的L形排列，其底层逻辑都是为每张头像计算出在画布上的精确位置和大小，然后依次绘制上去。

• 第一步：加载与转换。首先，需要使用 uni.getImageInfo 接口加载所有网络头像的URL，并将其转换为本地临时文件路径。这一步至关重要，因为Canvas的 drawImage 方法在小程序等平台无法直接使用网络图片，否则会静默失败。
• 第二步：创建画布与上下文。创建一个固定尺寸（例如300×300rpx）的Canvas元素，并通过 uni.createCanvasContext('canvasId') 获取其绘图上下文对象。
• 第三步：计算坐标并绘制。手动计算每张头像的坐标。以4人头像排成2×2为例，假设画布边长为300，头像间距为5，那么每张头像的宽高就是 (300 - 5×3) / 2。左上角第一张的位置是(5, 5)，第二张的位置则是(5 + 宽 + 5, 5)，依此类推。计算完成后，循环调用上下文的 drawImage 方法进行绘制。

需要注意的是，虽然H5和小程序端的行为基本一致，但在App端（尤其是iOS）需要格外留意Canvas的尺寸和像素比设置，否则容易出现图像模糊或被意外裁切的问题。

避开Canvas ID与渲染的常见陷阱

开发过程中，经常遇到 canvasToTempFilePath: fail canvas is empty 这类错误。这通常不是因为图片没画上去，而是Canvas节点本身没有正确挂载或ID冲突导致的。特别是在使用 v-if 条件渲染Canvas时，如果切换页面，绘图上下文可能会失效。

• Canvas ID必须静态声明。在模板中，canvas 标签的 canvas-id 属性必须写死为一个唯一字符串（例如 canvas-id="myCanvas"），注意使用短横线命名法，不能使用动态绑定。
• 避免使用DOM访问方式。不要试图通过 ref 和 this.$refs.canvas 来获取Canvas节点，因为uni-app的小程序端不支持这种原生DOM操作。
• 确保绘制时机正确。调用 uni.createCanvasContext 之前，必须确保Canvas组件已经完成渲染。可以将绘制逻辑放在页面的 onReady 生命周期中，或者使用一个简短的延时（如 setTimeout）来确保节点就绪。
• 注意平台差异。在H5端，你可以使用原生的 标签和 getContext('2d') API；但在小程序端，必须使用uni-app提供的 canvas-id 和 uni.createCanvasContext 这一套方案。

用原生API实现视觉细节

uni-app本身没有提供现成的“群头像组件”，因此所有视觉效果都需要开发者使用Canvas的原生API手动绘制。例如，圆角头像并非给image标签设置border-radius，而是需要在Canvas上通过路径剪裁来实现。

• 绘制圆角头像：流程是 ctx.beginPath() → ctx.arc(x + r, y + r, r, 0, 2 * Math.PI) → ctx.clip()，最后再调用 drawImage。这样图片就会被限制在绘制的圆形路径内。
• 添加头像边框：如果想加一个2像素的白边，可以在调用 clip 之前，先设置 ctx.strokeStyle = '#FFFFFF' 和 ctx.lineWidth = 2，然后执行 ctx.stroke()。
• 处理阴影效果：Canvas的阴影属性（shadowColor, shadowOffsetX等）对 drawImage 绘制的图片无效。如果想给头像添加阴影，一个变通方法是先画一个带阴影的灰色矩形作为底衬，然后再将头像图片覆盖上去。

这些API的调用顺序非常关键，一旦出错，效果就无法实现。

关键一步：异步绘制与图片导出

这是最容易出错的一个环节：ctx.draw() 方法是一个异步操作，但很多开发者会以同步思维编码，在调用 draw() 后立即执行 uni.canvasToTempFilePath 来导出图片，结果导出的只是一张空白画布。

• 使用回调确保绘制完成。正确的做法是使用 ctx.draw(true, callback) 方法，并将导出图片的逻辑放在回调函数中。参数 true 表示清空画布缓冲区，避免上一帧的内容残留。
• 检查画布尺寸匹配。如果回调函数没有触发，很可能是Canvas的实际绘制内容超出了预设的宽高，导致绘制过程被截断。导出前务必检查画布尺寸是否与目标分辨率匹配。小程序对生成的临时图片宽高有要求（通常不超过1600px），H5端虽无硬性限制，但尺寸过大会导致性能问题。
• 处理App端兼容性。在安卓App端，如果导出的是黑图，可以尝试检查Canvas的样式宽高（如 width: 300rpx）与其实际的 width、height 属性值是否成比例，避免因像素拉伸导致的失真。

说到底，技术实现上的绘制本身并不算最复杂的部分。真正的难点在于设计一个灵活的布局算法，能够根据动态的人数（2人、5人、9人）自动计算头像的位置和画布大小。建议将这部分排列规则抽象成独立的函数，输入人数和画布总宽高，输出每张图的坐标和尺寸，避免将布局逻辑硬编码在绘制流程中，这样后续维护和调整会轻松很多。