排版 (HasTypography)
HasTypography trait 控制文字的视觉呈现:字体家族、样式、大小、间距、伸缩、颜色、阴影与渲染模式。所有方法皆返回 static,支持链式API 串接。
设置字体
setFont()
以单一调用设置当前的字体家族、样式与大小。
php
use Yeeefang\TcpdfNext\Core\Document;
$pdf = Document::create()
->addPage()
->setFont('Helvetica', '', 12)
->cell(0, 10, 'Normal text', newLine: true)
->setFont('Helvetica', 'B', 14)
->cell(0, 10, 'Bold text', newLine: true)
->setFont('Helvetica', 'BI', 16)
->cell(0, 10, 'Bold Italic text', newLine: true);字体样式
组合样式字符可同时应用多种效果:
| 代码 | 样式 |
|---|---|
'' | 常规(Regular) |
'B' | 粗体(Bold) |
'I' | 斜体(Italic) |
'BI' | 粗斜体(Bold Italic) |
'U' | 下划线(Underline) |
'D' | 删除线(Strikethrough) |
'O' | 上划线(Overline) |
样式可自由组合:'BIU' 会产生粗体、斜体加下划线的文字。
php
$pdf->setFont('Helvetica', 'BU', 12)
->cell(0, 10, 'Bold + Underline', newLine: true)
->setFont('Helvetica', 'ID', 12)
->cell(0, 10, 'Italic + Strikethrough', newLine: true)
->setFont('Helvetica', 'BO', 12)
->cell(0, 10, 'Bold + Overline', newLine: true);setFontSize()
仅变更字体大小,不切换字体家族或样式。
php
$pdf->setFont('Helvetica', 'B', 12)
->cell(0, 10, '12pt heading', newLine: true)
->setFontSize(10)
->cell(0, 10, '10pt body text', newLine: true)
->setFontSize(8)
->cell(0, 10, '8pt footnote', newLine: true);间距与伸缩
setFontSpacing()
调整每对字符之间额外插入的空间(以点为单位)。
php
$pdf->setFont('Helvetica', '', 12)
->setFontSpacing(0)
->cell(0, 10, 'Normal spacing', newLine: true)
->setFontSpacing(1.5)
->cell(0, 10, 'Expanded spacing', newLine: true)
->setFontSpacing(-0.5)
->cell(0, 10, 'Tight spacing', newLine: true)
->setFontSpacing(0);setFontStretching()
对字形应用水平缩放。值为 100 时为正常宽度。
php
$pdf->setFont('Helvetica', '', 14)
->setFontStretching(100)
->cell(0, 10, 'Normal width (100%)', newLine: true)
->setFontStretching(130)
->cell(0, 10, 'Stretched (130%)', newLine: true)
->setFontStretching(75)
->cell(0, 10, 'Condensed (75%)', newLine: true)
->setFontStretching(100);测量文字
getStringWidth()
返回以当前字体和大小渲染指定字符串所需的宽度(用户单位)。可在绘制前用于计算布局。
php
$pdf->setFont('Helvetica', '', 12);
$width = $pdf->getStringWidth('Invoice Total: $1,250.00');
// 使用测量宽度来右对齐单元格
$pageWidth = $pdf->getPageWidth();
$rightMargin = $pdf->getRightMargin();
$pdf->setX($pageWidth - $rightMargin - $width)
->cell($width, 10, 'Invoice Total: $1,250.00');文字渲染模式
PDF 定义了 8 种文字渲染模式,通过 TextRenderer 枚举控制。这些模式决定文字是填充、描边、用作裁切路径,还是隐藏。
| 模式 | 值 | 效果 |
|---|---|---|
| Fill | 0 | 常规填充文字(默认) |
| Stroke | 1 | 仅显示轮廓 |
| FillStroke | 2 | 填充加轮廓 |
| Invisible | 3 | 隐藏但可选取/可搜索 |
| FillClip | 4 | 填充后加入裁切路径 |
| StrokeClip | 5 | 描边后加入裁切路径 |
| FillStrokeClip | 6 | 填充加描边后裁切 |
| Clip | 7 | 仅加入裁切路径 |
php
$pdf->setFont('Helvetica', 'B', 36)
->setTextRenderingMode(0)
->cell(0, 15, 'Filled text', newLine: true)
->setTextRenderingMode(1)
->cell(0, 15, 'Outlined text', newLine: true)
->setTextRenderingMode(2)
->cell(0, 15, 'Fill + Stroke', newLine: true)
->setTextRenderingMode(3)
->cell(0, 15, 'Invisible (but searchable)', newLine: true)
->setTextRenderingMode(0);Invisible 模式(值为 3)特别适合 OCR 叠加层 — 将识别出的文字放置于扫描图片上方,使 PDF 可被搜索,同时图片仍然可见。
文字颜色
setTextColor()
使用 RGB 值设置文字颜色。
php
$pdf->setTextColor(0, 0, 0) // 黑色
->cell(0, 10, 'Black text', newLine: true)
->setTextColor(220, 50, 50) // 红色
->cell(0, 10, 'Red text', newLine: true)
->setTextColor(0, 102, 204) // 蓝色
->cell(0, 10, 'Blue text', newLine: true)
->setTextColor(0, 0, 0); // 重置为黑色仅传入单一参数时,会设置灰阶值(0 = 黑色,255 = 白色)。
php
$pdf->setTextColor(128)
->cell(0, 10, 'Gray text', newLine: true);文字阴影
setTextShadow()
为文字应用阴影效果。阴影以关联数组定义。
php
$pdf->setFont('Helvetica', 'B', 28)
->setTextShadow([
'enabled' => true,
'depth_w' => 0.4, // 水平偏移(mm)
'depth_h' => 0.4, // 垂直偏移(mm)
'color' => [180, 180, 180],
'opacity' => 0.5,
'blend_mode' => 'Normal',
])
->cell(0, 15, 'Heading with Shadow', newLine: true)
->setTextShadow(['enabled' => false]);完整示例
php
use Yeeefang\TcpdfNext\Core\Document;
$pdf = Document::create()
->addPage()
// 标题 — 大字、粗体、蓝色
->setFont('Helvetica', 'B', 24)
->setTextColor(0, 51, 102)
->cell(0, 14, 'Monthly Report', newLine: true)
// 副标题 — 常规字体、灰色、加大间距
->setFont('Helvetica', '', 12)
->setTextColor(100, 100, 100)
->setFontSpacing(1.0)
->cell(0, 10, 'February 2026', newLine: true)
->setFontSpacing(0)
->ln(5)
// 正文 — 黑色、常规
->setFont('Times', '', 11)
->setTextColor(0, 0, 0)
->multiCell(0, 6, 'Revenue increased 12% compared to the previous quarter. Operating costs remained stable, and net margin improved by 3 percentage points.')
->ln(3)
// 脚注 — 小字、斜体、灰色
->setFont('Times', 'I', 8)
->setTextColor(150, 150, 150)
->cell(0, 5, '* All figures are unaudited.')
->save('report.pdf');