Skip to content

排版 (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 枚举控制。这些模式决定文字是填充、描边、用作裁切路径,还是隐藏。

模式效果
Fill0常规填充文字(默认)
Stroke1仅显示轮廓
FillStroke2填充加轮廓
Invisible3隐藏但可选取/可搜索
FillClip4填充后加入裁切路径
StrokeClip5描边后加入裁切路径
FillStrokeClip6填充加描边后裁切
Clip7仅加入裁切路径
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');

以 LGPL-3.0-or-later 许可证发布。