MPDF项目中的textcircle标签详解：创建环形文本效果

什么是textcircle标签

textcircle是MPDF库(版本5.4及以上)提供的一个特殊HTML控制标签，用于在PDF文档中创建环形排列的文本效果。这个标签可以将指定的文本沿着圆形路径排列，形成独特的视觉效果，非常适合用于设计徽章、印章或装饰性文本元素。

基本语法结构

textcircle标签的基本语法如下：

<textcircle 
  r="半径值" 
  top-text="顶部文本" 
  bottom-text="底部文本"
  [divider="分隔符"]
  [space-width="间距百分比"]
  [char-width="字符宽度百分比"]
  [href="链接地址"] />

核心参数详解

1. 半径参数 (r)

定义环形文本的半径大小，接受任何有效的长度单位：

• 绝对单位：mm(毫米)、cm(厘米)、in(英寸)、pt(点)
• 相对单位：em、ex等

示例：r="30mm" 表示半径为30毫米的圆

2. 文本内容参数

top-text：定义显示在圆环顶部的文本内容
bottom-text：定义显示在圆环底部的文本内容

注意：

• 至少需要指定top-text或bottom-text中的一个
• 文本中不能直接包含特殊字符(<, >, &, ', ")，需要使用HTML实体
• 建议使用htmlspecialchars('内容', ENT_QUOTES)处理文本内容

3. 样式控制参数

divider：在顶部和底部文本之间添加分隔符号
space-width：字符间距(相对于正常的百分比)
char-width：字符宽度(相对于正常的百分比)

支持的CSS样式

textcircle标签支持以下CSS样式属性：

• 边框：border
• 边距：margin
• 内边距：padding
• 颜色：color
• 背景色：background-color
• 字体：font-family, font-size, font-weight, font-style
• 显示：display, visibility
• 透明度：opacity

重要提示：

• 从MPDF 5.6开始，背景默认为透明(之前版本为白色)
• CSS样式不会从父元素继承
• 从MPDF 5.6开始支持font-size: auto，可以自动调整文本大小填满半圆或整圆

实际应用示例

$mpdf->WriteHTML('
<textcircle 
  r="25mm" 
  space-width="130" 
  char-width="120"
  top-text="&bull; 公司印章 &bull;" 
  bottom-text="2023年度"
  divider="&diams;"
  style="background-color: #FFEEEE; 
         border:1px solid #AA0000; 
         padding: 0.2em; 
         color: #AA0000; 
         font-size: 18pt; 
         font-family: SimHei" 
/>');

版本变更历史

版本	重要变更
5.4	首次引入textcircle标签
5.6	修复透明背景问题 添加分隔符支持 添加自动字体大小功能

使用建议

1. 字符处理：对于包含特殊字符的文本，务必使用HTML实体或htmlspecialchars函数处理
2. 字体选择：选择适合环形排列的字体，等宽字体效果通常更好
3. 半径调整：根据文本长度和字体大小合理设置半径，避免文字过于拥挤或稀疏
4. 视觉平衡：适当调整space-width和char-width参数，获得最佳视觉效果

textcircle标签为PDF文档设计提供了强大的文本装饰能力，合理使用可以显著提升文档的专业性和视觉吸引力。