引言

在HarmonyOS应用开发中，Canvas画布绘制是构建自定义UI和复杂图形界面的核心技术。开发者经常需要在Canvas上绘制文本内容，特别是多行文本段落。然而，一个常见的技术难题是：如何将文本段落精准地水平和垂直居中于Canvas画布中？许多开发者在使用text.Paragraph进行文本绘制时，发现文本总是偏离中心位置，无法实现完美的居中效果。本文将深入剖析这一问题的技术根源，并提供一套完整、可直接复用的解决方案。

问题现象

开发者期望在Canvas画布中实现以下效果：

1. 文本在画布中水平居中显示

2. 文本在画布中垂直居中显示

3. 支持多行文本自动换行

4. 适配不同尺寸的画布容器

但在实际开发中，使用text.Paragraph绘制文本时经常遇到以下问题：

• 文本位置偏移，无法准确居中

• 多行文本换行后位置计算错误

• 固定坐标值无法适应动态画布尺寸

• 字体大小和样式影响居中精度

问题代码的典型表现：

// 常见错误做法：使用固定坐标
paragraph.paint(canvas, 100, 100); // 硬编码坐标，无法自适应

技术原理深度解析

1. text.Paragraph布局机制

text.Paragraph是HarmonyOS ArkTS的文本布局引擎，它采用异步布局模型。要正确使用Paragraph，必须理解其核心工作机制：

• 布局宽度必须明确：通过layoutSync(width)方法指定文本布局的宽度，这个宽度通常应该等于画布的可用宽度

• 实际尺寸与布局尺寸的区别：文本的实际宽度可能小于布局宽度（特别是短文本），实际高度由行数和行高决定

• 尺寸获取方法：

  • getMaxWidth()：获取文本段落的最大宽度（实际内容宽度）

  • getHeight()：获取文本段落的总高度（包含所有行）

2. 居中计算的数学原理

要实现文本在画布中的精准居中，需要基于以下公式进行计算：

水平居中公式：

起始X坐标 = (画布宽度 - 文本实际宽度) / 2

垂直居中公式：

起始Y坐标 = (画布高度 - 文本实际高度) / 2

关键点：

• 必须使用文本的实际尺寸（getMaxWidth()和getHeight()），而不是布局宽度

• 坐标计算需要在同一度量单位下进行（通常使用像素px）

• 需要考虑文本对齐方式对起始位置的影响

3. 坐标系统转换

HarmonyOS中使用多种坐标单位：

• vp（虚拟像素）：与屏幕密度无关的相对单位

• px（物理像素）：实际屏幕像素点

在Canvas绘制中，通常使用px单位进行计算。需要使用vp2px()方法进行单位转换，确保计算精度。

完整解决方案

方案架构设计

本解决方案采用模块化设计，包含以下核心组件：

1. 动态尺寸获取：实时获取画布的实际尺寸

2. 文本布局引擎：使用text.Paragraph进行文本排版

3. 智能居中计算：基于实际文本尺寸计算居中坐标

4. 自适应渲染：适配不同屏幕尺寸和密度

核心实现代码

import { NodeController, FrameNode, RenderNode, DrawContext, UIContext } from '@kit.ArkUI';
import { text } from '@kit.ArkGraphics2D';

// 全局UI上下文，用于单位转换
let UContext: UIContext;

/**
 * 自定义渲染节点，负责文本绘制
 */
class CenteredTextRenderNode extends RenderNode {
  // 文本内容配置
  private textContent: string = 'HarmonyOS Canvas文本居中绘制示例：这是一段用于测试的多行文本内容，演示自动换行和精准居中效果。';
  private fontSize: number = 30;
  private fontColor = { alpha: 255, red: 26, green: 26, blue: 26 };
  
  async draw(context: DrawContext) {
    const canvas = context.canvas;
    
    // 1. 动态获取画布实际尺寸
    const canvasWidth = this.frame.width;      // 画布宽度（vp单位）
    const canvasHeight = this.frame.height;    // 画布高度（vp单位）
    
    // 2. 初始化字体集合
    let fontCollection = text.FontCollection.getGlobalInstance();
    
    // 加载自定义字体（可选）
    try {
      // 注意：实际路径需要根据应用资源调整
      fontCollection.loadFontSync(
        'CustomFontFamily', 
        'file:///system/fonts/NotoSansMalayalamUI-SemiBold.ttf'
      );
    } catch (error) {
      console.log('使用系统默认字体');
    }
    
    // 3. 配置文本样式
    const myFontFamily: Array<string> = ['CustomFontFamily', 'sans-serif'];
    const myTextStyle: text.TextStyle = {
      color: this.fontColor,
      fontSize: this.fontSize,
      fontFamilies: myFontFamily,
      fontWeight: text.FontWeight.NORMAL,
      fontStyle: text.FontStyle.NORMAL
    };
    
    // 4. 配置段落样式
    const myParagraphStyle: text.ParagraphStyle = {
      textStyle: myTextStyle,
      align: text.TextAlign.CENTER,      // 文本对齐方式：居中
      wordBreak: text.WordBreak.NORMAL,  // 单词换行规则
      maxLines: 0,                       // 0表示不限制行数
      textOverflow: { overflow: text.TextOverflow.CLIP } // 文本溢出处理
    };
    
    // 5. 构建文本段落
    let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
    paragraphBuilder.pushStyle(myTextStyle);
    paragraphBuilder.addText(this.textContent);
    let paragraph = paragraphBuilder.build();
    
    // 6. 执行文本布局（关键步骤）
    // 使用画布宽度作为布局宽度，确保正确换行
    const layoutWidth = canvasWidth;
    paragraph.layoutSync(layoutWidth);
    
    // 7. 计算居中坐标（核心算法）
    const textWidth = paragraph.getMaxWidth();     // 获取文本实际宽度
    const textHeight = paragraph.getHeight();      // 获取文本实际高度
    
    // 单位转换：vp -> px
    const canvasWidthPx = UContext!.vp2px(canvasWidth);
    const canvasHeightPx = UContext!.vp2px(canvasHeight);
    
    // 居中计算
    const startX = (canvasWidthPx - textWidth) / 2;
    const startY = (canvasHeightPx - textHeight) / 2;
    
    // 8. 绘制文本到Canvas
    paragraph.paint(canvas, startX, startY);
    
    // 可选：绘制参考线，用于调试
    this.drawReferenceLines(canvas, canvasWidthPx, canvasHeightPx);
  }
  
  /**
   * 绘制参考线（调试用）
   */
  private drawReferenceLines(
    canvas: CanvasRenderingContext2D, 
    width: number, 
    height: number
  ): void {
    // 保存当前画布状态
    canvas.save();
    
    // 设置参考线样式
    canvas.strokeStyle = 'rgba(255, 0, 0, 0.3)';
    canvas.lineWidth = 1;
    
    // 绘制水平中线
    canvas.beginPath();
    canvas.moveTo(0, height / 2);
    canvas.lineTo(width, height / 2);
    canvas.stroke();
    
    // 绘制垂直中线
    canvas.beginPath();
    canvas.moveTo(width / 2, 0);
    canvas.lineTo(width / 2, height);
    canvas.stroke();
    
    // 恢复画布状态
    canvas.restore();
  }
}

// 渲染节点实例
let textRenderNode: CenteredTextRenderNode | null = null;

/**
 * 节点控制器，管理渲染节点的生命周期
 */
class TextNodeController extends NodeController {
  private rootNode: FrameNode | null = null;
  
  // 创建根节点
  makeNode(uiContext: UIContext): FrameNode {
    this.rootNode = new FrameNode(uiContext);
    if (!this.rootNode) {
      return this.rootNode;
    }
    
    const renderNode = this.rootNode.getRenderNode();
    if (renderNode) {
      // 设置画布尺寸
      renderNode.frame = {
        x: 0,
        y: 0,
        width: 380,    // 初始宽度
        height: 600    // 初始高度
      };
      renderNode.pivot = { x: 0, y: 0 };
    }
    
    return this.rootNode;
  }
  
  // 添加文本渲染节点
  addTextNode(): void {
    if (!textRenderNode) {
      textRenderNode = new CenteredTextRenderNode();
      // 设置渲染节点尺寸（与画布一致）
      textRenderNode.frame = {
        x: 0,
        y: 0,
        width: 380,
        height: 600
      };
    }
    
    this.rootNode?.getRenderNode()?.appendChild(textRenderNode);
  }
  
  // 清除所有节点
  clearNodes(): void {
    this.rootNode?.getRenderNode()?.clearChildren();
    textRenderNode = null;
  }
  
  // 更新文本内容
  updateTextContent(newText: string): void {
    if (textRenderNode) {
      // 这里可以通过扩展RenderNode类来支持动态文本更新
      this.clearNodes();
      this.addTextNode();
    }
  }
}

/**
 * 主页面组件
 */
@Entry
@Component
struct CanvasTextCenterDemo {
  // 节点控制器实例
  private textController: TextNodeController = new TextNodeController();
  
  // 状态变量
  @State currentText: string = 'HarmonyOS Canvas文本居中示例';
  @State canvasWidth: number = 380;
  @State canvasHeight: number = 600;
  @State fontSize: number = 30;
  
  // 获取UI上下文
  aboutToAppear(): void {
    UContext = this.getUIContext();
  }
  
  build() {
    Column({ space: 20 }) {
      // 标题区域
      Text('Canvas文本居中绘制演示')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 30, bottom: 10 });
      
      // Canvas绘制区域
      Row() {
        NodeContainer(this.textController)
          .width(this.canvasWidth)
          .height(this.canvasHeight)
          .backgroundColor(Color.White)
          .border({ width: 1, color: Color.Gray })
          .shadow({ radius: 10, color: Color.Black, offsetX: 2, offsetY: 2 });
      }
      .height('60%')
      .justifyContent(FlexAlign.Center);
      
      // 控制面板
      Column({ space: 15 }) {
        // 文本输入
        TextInput({ placeholder: '输入要显示的文本', text: this.currentText })
          .width('90%')
          .height(40)
          .onChange((value: string) => {
            this.currentText = value;
          });
        
        // 字体大小调节
        Row({ space: 10 }) {
          Text('字体大小:')
            .fontSize(16);
          
          Slider({
            value: this.fontSize,
            min: 12,
            max: 60,
            step: 2,
            style: SliderStyle.OutSet
          })
          .width('70%')
          .onChange((value: number) => {
            this.fontSize = value;
          });
          
          Text(`${this.fontSize}px`)
            .fontSize(14)
            .fontColor(Color.Blue);
        }
        .width('90%');
        
        // 画布尺寸调节
        Row({ space: 10 }) {
          Text('画布宽度:')
            .fontSize(16);
          
          Slider({
            value: this.canvasWidth,
            min: 200,
            max: 500,
            step: 10,
            style: SliderStyle.OutSet
          })
          .width('60%')
          .onChange((value: number) => {
            this.canvasWidth = value;
          });
          
          Text(`${this.canvasWidth}vp`)
            .fontSize(14)
            .fontColor(Color.Green);
        }
        .width('90%');
        
        // 操作按钮
        Row({ space: 20 }) {
          Button('绘制文本')
            .width(120)
            .height(40)
            .backgroundColor('#007DFF')
            .onClick(() => {
              this.textController.clearNodes();
              this.textController.addTextNode();
            });
          
          Button('清除画布')
            .width(120)
            .height(40)
            .backgroundColor('#FF3B30')
            .onClick(() => {
              this.textController.clearNodes();
            });
        }
        .margin({ top: 10 });
      }
      .width('100%')
      .padding(20)
      .backgroundColor('#F5F5F5')
      .borderRadius(15);
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#FFFFFF')
    .padding(10);
  }
}

关键代码解析

1. 动态尺寸获取机制

// 关键：从RenderNode的frame属性获取实际画布尺寸
const canvasWidth = this.frame.width;
const canvasHeight = this.frame.height;

重要性：使用动态尺寸而非硬编码值，确保代码能适应不同容器尺寸和屏幕分辨率。

2. 文本布局与尺寸计算

// 步骤1：指定布局宽度（通常等于画布宽度）
paragraph.layoutSync(layoutWidth);

// 步骤2：获取文本实际尺寸
const textWidth = paragraph.getMaxWidth();  // 实际内容宽度
const textHeight = paragraph.getHeight();   // 实际内容高度

注意点：

• layoutSync()必须在获取尺寸之前调用

• getMaxWidth()返回的是文本内容的最大宽度，可能小于布局宽度

• getHeight()包含所有行的高度，考虑行间距

3. 精准居中计算

// 单位转换：vp -> px
const canvasWidthPx = UContext!.vp2px(canvasWidth);
const canvasHeightPx = UContext!.vp2px(canvasHeight);

// 居中坐标计算
const startX = (canvasWidthPx - textWidth) / 2;
const startY = (canvasHeightPx - textHeight) / 2;

数学原理：

• 水平居中：(画布宽度 - 文本宽度) / 2

• 垂直居中：(画布高度 - 文本高度) / 2

• 必须确保所有值在同一单位（px）下计算

4. 文本对齐方式的影响

const myParagraphStyle: text.ParagraphStyle = {
  textStyle: myTextStyle,
  align: text.TextAlign.CENTER,  // 设置文本对齐方式
  // ... 其他配置
};

对齐方式选项：

• TextAlign.LEFT：左对齐

• TextAlign.CENTER：居中对齐

• TextAlign.RIGHT：右对齐

• TextAlign.JUSTIFY：两端对齐

高级优化方案

方案一：支持富文本和混合样式

// 创建支持多种样式的段落
const paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);

// 添加第一段文本（大标题）
paragraphBuilder.pushStyle({
  ...myTextStyle,
  fontSize: 36,
  fontWeight: text.FontWeight.BOLD
});
paragraphBuilder.addText('HarmonyOS 6\n');

// 添加第二段文本（正文）
paragraphBuilder.pushStyle({
  ...myTextStyle,
  fontSize: 24,
  fontWeight: text.FontWeight.NORMAL
});
paragraphBuilder.addText('Canvas文本居中绘制技术详解\n\n');

// 添加第三段文本（小字说明）
paragraphBuilder.pushStyle({
  ...myTextStyle,
  fontSize: 16,
  fontColor: { alpha: 255, red: 100, green: 100, blue: 100 }
});
paragraphBuilder.addText('本文介绍如何在HarmonyOS Canvas中实现精准的文本居中效果。');

const paragraph = paragraphBuilder.build();

方案二：响应式布局适配

class ResponsiveTextRenderer extends RenderNode {
  async draw(context: DrawContext) {
    const canvas = context.canvas;
    const { width: canvasWidth, height: canvasHeight } = this.frame;
    
    // 根据画布尺寸动态调整字体大小
    let baseFontSize = 16;
    if (canvasWidth > 400) {
      baseFontSize = 24;
    } else if (canvasWidth > 300) {
      baseFontSize = 20;
    }
    
    // 根据宽高比调整布局
    const aspectRatio = canvasWidth / canvasHeight;
    let layoutWidth = canvasWidth;
    if (aspectRatio > 1.5) {
      // 宽屏：使用80%宽度
      layoutWidth = canvasWidth * 0.8;
    }
    
    // ... 后续绘制逻辑
  }
}

方案三：动画与过渡效果

// 添加文本显示动画
@State textOpacity: number = 0;
@State textScale: number = 0.8;

// 在绘制前添加动画效果
animateTo({
  duration: 500,
  curve: Curve.EaseOut
}, () => {
  this.textOpacity = 1;
  this.textScale = 1;
});

// 在draw方法中应用动画效果
canvas.save();
canvas.globalAlpha = this.textOpacity;
canvas.scale(this.textScale, this.textScale);
paragraph.paint(canvas, startX, startY);
canvas.restore();

常见问题与解决方案

Q1：文本绘制位置仍然不居中怎么办？

A：检查以下可能原因：

1. 单位不一致：确保画布尺寸和文本尺寸使用相同单位（建议都转换为px）

2. 布局宽度错误：layoutSync()的参数应该是画布宽度，不是文本宽度

3. 字体加载问题：自定义字体可能影响文本尺寸计算，添加字体加载错误处理

4. 坐标系原点：Canvas的坐标系原点在左上角，计算时注意坐标方向

Q2：多行文本换行后高度计算错误？

A：getHeight()方法已经考虑了多行行高。确保：

1. 正确设置了ParagraphStyle中的maxLines（0表示无限制）

2. 布局宽度足够容纳文本换行

3. 检查是否有特殊字符影响换行计算

Q3：如何支持动态文本更新？

A：实现动态更新机制：

updateTextContent(newText: string): void {
  this.textContent = newText;
  // 重新创建RenderNode
  this.textController.clearNodes();
  this.textController.addTextNode();
  // 触发重绘
  this.getUIContext()?.requestLayout();
}

Q4：性能优化建议？

A：

1. 缓存Paragraph对象：如果文本内容不变，避免重复创建

2. 批量绘制：多个文本段落尽量一次绘制完成

3. 避免频繁布局：文本尺寸不变时，缓存getMaxWidth()和getHeight()结果

4. 使用离屏Canvas：复杂文本效果可以先在离屏Canvas绘制

最佳实践总结

1. 始终使用动态尺寸：通过this.frame.width/height获取画布尺寸，避免硬编码

2. 先布局后计算：调用layoutSync()后再获取文本尺寸

3. 单位统一转换：使用vp2px()确保计算精度

4. 考虑文本对齐：设置合适的TextAlign属性

5. 错误处理完善：添加字体加载失败的回退机制

6. 性能优化：缓存计算结果，避免重复计算

7. 响应式设计：根据容器尺寸动态调整字体大小和布局

扩展应用场景

场景一：自定义图表标签

// 在图表中居中显示数据标签
drawChartLabel(canvas: CanvasRenderingContext2D, text: string, x: number, y: number) {
  const paragraph = this.createParagraph(text);
  paragraph.layoutSync(200); // 固定标签宽度
  
  const textWidth = paragraph.getMaxWidth();
  const textHeight = paragraph.getHeight();
  
  // 计算居中坐标
  const labelX = x - textWidth / 2;
  const labelY = y - textHeight / 2;
  
  paragraph.paint(canvas, labelX, labelY);
}

场景二：水印文字居中

// 在图片上添加居中水印
drawWatermark(canvas: CanvasRenderingContext2D, watermarkText: string) {
  const paragraph = this.createParagraph(watermarkText);
  paragraph.layoutSync(canvas.width);
  
  const textWidth = paragraph.getMaxWidth();
  const textHeight = paragraph.getHeight();
  
  // 计算画布中心
  const centerX = (canvas.width - textWidth) / 2;
  const centerY = (canvas.height - textHeight) / 2;
  
  // 设置透明度
  canvas.globalAlpha = 0.3;
  paragraph.paint(canvas, centerX, centerY);
  canvas.globalAlpha = 1.0;
}

场景三：居中按钮文字

// 自定义按钮组件，文字居中
@Component
struct CenteredTextButton {
  @Prop text: string = '';
  
  build() {
    Button() {
      Canvas(this.drawButtonText)
        .width('100%')
        .height('100%')
    }
  }
  
  drawButtonText(canvas: CanvasRenderingContext2D) {
    const paragraph = this.createParagraph(this.text);
    paragraph.layoutSync(canvas.width);
    
    const textWidth = paragraph.getMaxWidth();
    const textHeight = paragraph.getHeight();
    
    const x = (canvas.width - textWidth) / 2;
    const y = (canvas.height - textHeight) / 2;
    
    paragraph.paint(canvas, x, y);
  }
}

总结

通过本文的详细解析和完整实现，我们彻底解决了HarmonyOS Canvas中文本段落居中绘制的技术难题。关键要点总结如下：

1. 核心原理：理解text.Paragraph的布局机制和尺寸计算方法

2. 精准计算：使用(画布尺寸 - 文本尺寸) / 2的数学公式

3. 动态适配：通过this.frame获取实际尺寸，支持响应式布局

4. 单位统一：使用vp2px()确保计算精度

5. 完整方案：提供从基础实现到高级优化的完整代码

掌握Canvas文本居中技术后，开发者可以：

• 实现精美的自定义文本渲染效果

• 构建复杂的图表和数据可视化组件

• 开发富文本编辑器和水印功能

• 创建自定义UI控件和动画效果

希望本文能为HarmonyOS开发者在Canvas文本绘制方面提供全面的技术指导和实践参考。通过深入理解布局原理和精准计算，开发者可以创造出更加精美、专业的应用界面。