HarmonyOS鸿蒙Next开发者技术支持-头像拼接特效案例

一、项目概述

1.1 功能特性

• 基于HarmonyOS 4.0+ API实现
• 支持多张头像拼接组合
• 多种布局模式（圆形、网格、重叠、螺旋）
• 动态添加/删除头像
• 平滑的动画过渡效果
• 支持头像裁剪和边框定制

二、架构设计

2.1 核心组件结构

头像拼接系统
├── AvatarComposer.ets (主组件)
├── AvatarLayout.ets (布局管理器)
├── AvatarItem.ets (头像项)
├── AvatarCanvas.ets (Canvas渲染)
└── AvatarAnimation.ets (动画管理)

2.2 数据模型定义

// AvatarModel.ets
// 头像数据模型
export interface AvatarData {
  id: string;
  image: Resource;           // 头像资源
  name?: string;            // 用户姓名
  color?: ResourceColor;    // 背景色
  borderColor?: ResourceColor; // 边框颜色
  borderWidth?: number;     // 边框宽度
  size: number;            // 头像尺寸
  x: number;               // X坐标
  y: number;               // Y坐标
  zIndex: number;          // Z轴层级
  rotation: number;        // 旋转角度
  scale: number;           // 缩放比例
  opacity: number;         // 透明度
}

// 布局配置
export interface LayoutConfig {
  type: 'circle' | 'grid' | 'overlap' | 'spiral'; // 布局类型
  containerWidth: number;  // 容器宽度
  containerHeight: number; // 容器高度
  avatarSize: number;     // 基础头像尺寸
  spacing: number;        // 头像间距
  maxAvatars: number;     // 最大头像数量
  animationDuration: number; // 动画时长
  enableRotation: boolean; // 是否启用旋转
  enableScale: boolean;   // 是否启用缩放
}

// 默认配置
export class AvatarDefaultConfig {
  static readonly DEFAULT_LAYOUT_CONFIG: LayoutConfig = {
    type: 'circle',
    containerWidth: 300,
    containerHeight: 300,
    avatarSize: 60,
    spacing: 10,
    maxAvatars: 12,
    animationDuration: 500,
    enableRotation: true,
    enableScale: true
  };
}

这里定义了头像拼接系统的核心数据模型。AvatarData接口包含每个头像的所有属性，包括位置、样式和变换参数。LayoutConfig接口定义布局的配置参数，支持多种布局类型和动画效果。AvatarDefaultConfig提供默认配置值。

三、核心实现

3.1 头像项组件

// AvatarItem.ets
@Component
export struct AvatarItem {
  [@Prop](/user/Prop) avatar: AvatarData;
  [@Prop](/user/Prop) layoutConfig: LayoutConfig;
  [@Prop](/user/Prop) isDragging: boolean = false;
  [@Prop](/user/Prop) onAvatarClick?: (avatar: AvatarData) => void;
  [@Prop](/user/Prop) onAvatarLongPress?: (avatar: AvatarData) => void;
  
  [@State](/user/State) private scale: number = 1;
  [@State](/user/State) private rotation: number = 0;
  [@State](/user/State) private glowEffect: boolean = false;
  
  private animationController: animation.Animator = new animation.Animator();
  
  aboutToAppear() {
    this.rotation = this.avatar.rotation;
    this.scale = this.avatar.scale;
  }

AvatarItem组件是单个头像的展示单元。@Prop装饰器接收头像数据、布局配置和交互状态。@State装饰器管理动画相关的状态变量。animationController用于控制头像的动画效果。

// 点击处理
  private onAvatarClickHandler(): void {
    // 点击动画
    this.animateClick();
    
    // 触发回调
    this.onAvatarClick?.(this.avatar);
  }
  
  // 长按处理
  private onAvatarLongPressHandler(): void {
    // 长按动画
    this.animateLongPress();
    
    // 触发回调
    this.onAvatarLongPress?.(this.avatar);
  }
  
  // 点击动画
  private animateClick(): void {
    this.animationController.stop();
    
    this.animationController.update({
      duration: 200,
      curve: animation.Curve.EaseOut
    });
    
    this.animationController.onFrame((progress: number) => {
      this.scale = 1 + 0.1 * Math.sin(progress * Math.PI);
    });
    
    this.animationController.play();
  }
  
  // 长按动画
  private animateLongPress(): void {
    this.glowEffect = true;
    
    this.animationController.stop();
    this.animationController.update({
      duration: 300,
      curve: animation.Curve.EaseInOut
    });
    
    this.animationController.onFrame((progress: number) => {
      this.rotation = 360 * progress;
      this.scale = 1 + 0.2 * progress;
    });
    
    this.animationController.onFinish(() => {
      this.glowEffect = false;
      this.rotation = this.avatar.rotation;
      this.scale = this.avatar.scale;
    });
    
    this.animationController.play();
  }

onAvatarClickHandler和onAvatarLongPressHandler处理头像的交互事件。animateClick实现点击时的缩放动画，animateLongPress实现长按时的旋转和缩放动画，并添加发光效果。

// 构建头像内容
  @Builder
  private buildAvatarContent() {
    Stack({ alignContent: Alignment.Center }) {
      // 背景圆形
      Circle()
        .width(this.avatar.size)
        .height(this.avatar.size)
        .fill(this.avatar.color || '#4D94FF')
        .shadow(this.glowEffect ? {
          radius: 15,
          color: this.avatar.borderColor || '#4D94FF',
          offsetX: 0,
          offsetY: 0
        } : null)
      
      // 头像图片
      Image(this.avatar.image)
        .width(this.avatar.size - (this.avatar.borderWidth || 0) * 2)
        .height(this.avatar.size - (this.avatar.borderWidth || 0) * 2)
        .borderRadius(this.avatar.size / 2)
        .objectFit(ImageFit.Cover)
        .interpolation(ImageInterpolation.High) // 高质量插值
      
      // 边框
      if (this.avatar.borderWidth && this.avatar.borderWidth > 0) {
        Circle()
          .width(this.avatar.size)
          .height(this.avatar.size)
          .stroke(this.avatar.borderColor || '#FFFFFF')
          .strokeWidth(this.avatar.borderWidth)
          .fill(Color.Transparent)
      }
      
      // 用户姓名标签
      if (this.avatar.name && this.isDragging) {
        Text(this.avatar.name)
          .fontSize(12)
          .fontColor(Color.White)
          .backgroundColor('#00000080')
          .padding({ left: 4, right: 4, top: 2, bottom: 2 })
          .borderRadius(4)
          .position({ x: 0, y: this.avatar.size / 2 + 5 })
          .maxLines(1)
          .textOverflow({ overflow: TextOverflow.Ellipsis })
      }
    }
  }

buildAvatarContent方法构建头像的完整视觉表现。使用Stack布局叠加背景圆形、头像图片、边框和姓名标签。背景圆形支持发光效果，头像图片使用高质量插值，边框可定制，姓名标签在拖拽时显示。

build() {
    Column()
      .width(this.avatar.size)
      .height(this.avatar.size)
      .position({ x: this.avatar.x, y: this.avatar.y })
      .scale({ x: this.scale, y: this.scale })
      .rotate({ angle: this.rotation })
      .opacity(this.avatar.opacity)
      .zIndex(this.avatar.zIndex)
      .animation({
        duration: this.layoutConfig.animationDuration,
        curve: animation.Curve.EaseInOut
      })
      .onClick(() => this.onAvatarClickHandler())
      .gesture(
        LongPressGesture({ repeat: false })
          .onAction(() => this.onAvatarLongPressHandler())
      )
    {
      this.buildAvatarContent()
    }
  }
}

build方法创建头像容器，应用位置、缩放、旋转、透明度和层级等变换效果。使用animation属性实现平滑的过渡动画。绑定点击和长按手势事件处理器。

3.2 布局管理器

// AvatarLayout.ets
export class AvatarLayout {
  private config: LayoutConfig;
  
  constructor(config: LayoutConfig) {
    this.config = config;
  }
  
  // 计算布局
  calculateLayout(avatars: AvatarData[]): AvatarData[] {
    const sortedAvatars = [...avatars].sort((a, b) => a.zIndex - b.zIndex);
    
    switch (this.config.type) {
      case 'circle':
        return this.calculateCircleLayout(sortedAvatars);
      case 'grid':
        return this.calculateGridLayout(sortedAvatars);
      case 'overlap':
        return this.calculateOverlapLayout(sortedAvatars);
      case 'spiral':
        return this.calculateSpiralLayout(sortedAvatars);
      default:
        return sortedAvatars;
    }
  }

AvatarLayout类负责计算不同布局模式下头像的位置。calculateLayout方法根据配置的布局类型调用对应的布局计算方法，首先对头像按zIndex排序确保正确的层级关系。

// 圆形布局
  private calculateCircleLayout(avatars: AvatarData[]): AvatarData[] {
    const centerX = this.config.containerWidth / 2;
    const centerY = this.config.containerHeight / 2;
    const radius = Math.min(centerX, centerY) - this.config.avatarSize / 2;
    
    return avatars.map((avatar, index) => {
      const angle = (index / avatars.length) * Math.PI * 2;
      const x = centerX + Math.cos(angle) * radius - avatar.size / 2;
      const y = centerY + Math.sin(angle) * radius - avatar.size / 2;
      
      return {
        ...avatar,
        x,
        y,
        rotation: this.config.enableRotation ? angle * 180 / Math.PI : 0,
        scale: this.config.enableScale ? 1 + Math.sin(angle) * 0.1 : 1
      };
    });
  }
  
  // 网格布局
  private calculateGridLayout(avatars: AvatarData[]): AvatarData[] {
    const cols = Math.ceil(Math.sqrt(avatars.length));
    const rows = Math.ceil(avatars.length / cols);
    const cellWidth = this.config.containerWidth / cols;
    const cellHeight = this.config.containerHeight / rows;
    
    return avatars.map((avatar, index) => {
      const col = index % cols;
      const row = Math.floor(index / cols);
      const x = col * cellWidth + (cellWidth - avatar.size) / 2;
      const y = row * cellHeight + (cellHeight - avatar.size) / 2;
      
      return {
        ...avatar,
        x,
        y,
        rotation: 0,
        scale: 1
      };
    });
  }

calculateCircleLayout方法实现圆形布局，将头像均匀分布在圆周上，支持根据角度调整旋转和缩放。calculateGridLayout方法实现网格布局，将头像排列在等分的网格中，确保均匀分布。

// 重叠布局
  private calculateOverlapLayout(avatars: AvatarData[]): AvatarData[] {
    const centerX = this.config.containerWidth / 2;
    const centerY = this.config.containerHeight / 2;
    const maxOffset = this.config.avatarSize * 0.3;
    
    return avatars.map((avatar, index) => {
      const angle = (index / avatars.length) * Math.PI * 2;
      const offsetX = Math.cos(angle) * maxOffset;
      const offsetY = Math.sin(angle) * maxOffset;
      const x = centerX + offsetX - avatar.size / 2;
      const y = centerY + offsetY - avatar.size / 2;
      
      return {
        ...avatar,
        x,
        y,
        rotation: this.config.enableRotation ? index * 15 : 0,
        scale: this.config.enableScale ? 1 - index * 0.05 : 1,
        zIndex: avatars.length - index
      };
    });
  }
  
  // 螺旋布局
  private calculateSpiralLayout(avatars: AvatarData[]): AvatarData[] {
    const centerX = this.config.containerWidth / 2;
    const centerY = this.config.containerHeight / 2;
    const maxRadius = Math.min(centerX, centerY) - this.config.avatarSize / 2;
    
    return avatars.map((avatar, index) => {
      const spiralProgress = index / Math.max(avatars.length - 1, 1);
      const angle = spiralProgress * Math.PI * 6; // 3圈螺旋
      const radius = spiralProgress * maxRadius;
      
      const x = centerX + Math.cos(angle) * radius - avatar.size / 2;
      const y = centerY + Math.sin(angle) * radius - avatar.size / 2;
      
      return {
        ...avatar,
        x,
        y,
        rotation: this.config.enableRotation ? angle * 180 / Math.PI : 0,
        scale: this.config.enableScale ? 0.7 + spiralProgress * 0.3 : 1
      };
    });
  }
  
  // 添加新头像时的布局动画
  calculateEntryAnimation(avatar: AvatarData, index: number): AvatarData {
    const centerX = this.config.containerWidth / 2;
    const centerY = this.config.containerHeight / 2;
    
    return {
      ...avatar,
      x: centerX - avatar.size / 2,
      y: centerY - avatar.size / 2,
      scale: 0,
      opacity: 0,
      rotation: 360
    };
  }
}

calculateOverlapLayout方法实现重叠布局，头像从中心向外轻微偏移，后添加的头像层级更高。calculateSpiralLayout方法实现螺旋布局，头像沿螺旋线排列。calculateEntryAnimation方法计算新头像的入场动画起始状态，从中心缩放进入。

3.3 Canvas组合渲染

// AvatarCanvas.ets
@Component
export struct AvatarCanvas {
  private canvasRef: CanvasRenderingContext2D | null = null;
  private canvasWidth: number = 300;
  private canvasHeight: number = 300;
  
  [@Prop](/user/Prop) avatars: AvatarData[] = [];
  [@Prop](/user/Prop) layoutConfig: LayoutConfig = AvatarDefaultConfig.DEFAULT_LAYOUT_CONFIG;
  [@Prop](/user/Prop) onCanvasReady?: (context: CanvasRenderingContext2D) => void;
  
  // Canvas就绪回调
  private onCanvasReadyCallback(context: CanvasRenderingContext2D): void {
    this.canvasRef = context;
    const canvas = this.canvasRef.canvas;
    this.canvasWidth = canvas.width;
    this.canvasHeight = canvas.height;
    
    this.onCanvasReady?.(context);
    this.render();
  }

AvatarCanvas组件使用Canvas 2D API渲染头像组合效果。canvasRef存储Canvas上下文，onCanvasReadyCallback在Canvas就绪时初始化并开始渲染。

// 渲染头像组合
  private render(): void {
    if (!this.canvasRef) return;
    
    const ctx = this.canvasRef;
    
    // 清除画布
    ctx.clearRect(0, 0, this.canvasWidth, this.canvasHeight);
    
    // 绘制背景
    this.drawBackground(ctx);
    
    // 绘制所有头像
    for (const avatar of this.avatars) {
      this.drawAvatar(ctx, avatar);
    }
    
    // 绘制组合效果
    this.drawCompositeEffect(ctx);
  }
  
  // 绘制背景
  private drawBackground(ctx: CanvasRenderingContext2D): void {
    // 创建径向渐变背景
    const gradient = ctx.createRadialGradient(
      this.canvasWidth / 2,
      this.canvasHeight / 2,
      0,
      this.canvasWidth / 2,
      this.canvasHeight / 2,
      Math.max(this.canvasWidth, this.canvasHeight) / 2
    );
    
    gradient.addColorStop(0, '#1A1A2E');
    gradient.addColorStop(1, '#16213E');
    
    ctx.fillStyle = gradient;
    ctx.fillRect(0, 0, this.canvasWidth, this.canvasHeight);
  }

render方法执行完整的绘制流程，包括清除画布、绘制背景、绘制头像和组合效果。drawBackground方法创建径向渐变背景，从中心向外颜色变深。

// 绘制单个头像
  private drawAvatar(ctx: CanvasRenderingContext2D, avatar: AvatarData): void {
    ctx.save();
    
    // 应用变换
    ctx.translate(avatar.x + avatar.size / 2, avatar.y + avatar.size / 2);
    ctx.rotate(avatar.rotation * Math.PI / 180);
    ctx.scale(avatar.scale, avatar.scale);
    ctx.globalAlpha = avatar.opacity;
    
    // 绘制头像背景
    ctx.beginPath();
    ctx.arc(0, 0, avatar.size / 2, 0, Math.PI * 2);
    
    if (avatar.color) {
      ctx.fillStyle = avatar.color.toString();
      ctx.fill();
    }
    
    // 绘制头像图片（简化实现）
    // 在实际应用中，这里需要将Resource转换为ImageBitmap
    this.drawAvatarImage(ctx, avatar);
    
    // 绘制边框
    if (avatar.borderWidth && avatar.borderWidth > 0) {
      ctx.beginPath();
      ctx.arc(0, 0, avatar.size / 2, 0, Math.PI * 2);
      ctx.lineWidth = avatar.borderWidth;
      ctx.strokeStyle = avatar.borderColor?.toString() || '#FFFFFF';
      ctx.stroke();
    }
    
    ctx.restore();
  }
  
  // 绘制头像图片（简化实现）
  private drawAvatarImage(ctx: CanvasRenderingContext2D, avatar: AvatarData): void {
    // 在实际实现中，这里