文字輸出 (HasTextOutput)
HasTextOutput trait 提供在頁面上放置文字的主要方法。每個方法對應不同的排版模型：固定儲存格、流式文字、絕對定位，以及 HTML 渲染。
快速參考
| 方法 | 排版模型 | 自動換行 |
|---|---|---|
cell() | 單行方框 | 否 — 超出部分會被裁切 |
multiCell() | 多行區塊 | 是 — 自動在儲存格寬度處換行 |
text() | 絕對定位 | 否 |
write() | 行內流式 | 是 — 如同文書處理器般自然流動 |
writeHtml() | HTML 區塊 | 是 — 完整 HTML 排版 |
writeHtmlCell() | 定位的 HTML 儲存格 | 是 |
ln() | 換行 | 不適用 |
基本範例
php
use Yeeefang\TcpdfNext\Core\Document;
$pdf = Document::create()
->addPage()
->setFont('Helvetica', '', 12)
->cell(0, 10, 'Single line cell', newLine: true)
->multiCell(0, 10, 'This is a longer text that will automatically wrap to multiple lines when it reaches the edge of the printable area.')
->ln(5)
->text(50.0, 100.0, 'Absolute positioned text')
->write(10, 'Inline text that ')
->write(10, 'continues flowing.');所有方法皆回傳 static，因此每個呼叫都可以鏈式串接。
cell()
繪製一個單行矩形儲存格，可選擇性地加上邊框、背景填充、對齊方式與連結。
php
$pdf->cell(
float $w, // 寬度（0 = 延伸至右邊界）
float $h, // 高度
string $txt, // 文字內容
mixed $border = 0, // 0、1 或 'LTRB' 組合
bool $newLine = false,
string $align = '', // L、C、R、J
bool $fill = false,
mixed $link = '',
);游標會移動到儲存格右側（若 $newLine 為 true，則移至下一行）。
對齊方式
php
use Yeeefang\TcpdfNext\Contracts\Enums\Alignment;
$pdf->cell(0, 10, 'Left aligned')
->ln()
->cell(0, 10, 'Centered', align: 'C')
->ln()
->cell(0, 10, 'Right aligned', align: 'R')
->ln()
->cell(0, 10, 'Justified text in a cell', align: 'J');可用的對齊選項：
| 值 | 說明 |
|---|---|
'L' 或留空 | 靠左對齊（預設） |
'C' | 置中對齊 |
'R' | 靠右對齊 |
'J' | 左右對齊（齊行） |
儲存格邊框
php
// 無邊框
$pdf->cell(60, 10, 'No border', border: 0);
// 完整外框
$pdf->cell(60, 10, 'Full frame', border: 1);
// 個別邊 — L（左）、T（上）、R（右）、B（下）
$pdf->cell(60, 10, 'Top and bottom', border: 'TB');
$pdf->cell(60, 10, 'Left only', border: 'L');邊框參數說明：
| 值 | 說明 |
|---|---|
0 | 無邊框 |
1 | 完整外框（四邊皆有） |
'L' | 左邊框 |
'T' | 上邊框 |
'R' | 右邊框 |
'B' | 下邊框 |
'LTRB' | 可自由組合，例如 'TB' 表示上下邊框 |
填充模式
php
$pdf->setFillColor(230, 230, 250)
->cell(0, 10, 'Lavender background', fill: true, newLine: true);設定 fill: true 時，儲存格會以目前的填充色彩作為背景。請先呼叫 setFillColor() 設定所需的背景色。
multiCell()
渲染多行文字區塊，自動在指定寬度處換行。輸出後游標會移至儲存格下方。
php
$pdf->multiCell(
float $w, // 寬度（0 = 延伸至右邊界）
float $h, // 最小行高
string $txt, // 文字內容
mixed $border = 0,
string $align = 'J',
bool $fill = false,
);php
$pdf->setFont('Helvetica', '', 11)
->multiCell(80, 6, 'This paragraph will wrap at 80mm width. The text flows naturally, respecting word boundaries and hyphenation rules.', border: 1, align: 'J');text()
在絕對座標 (x, y) 放置一段文字。呼叫後游標不會移動 — 這是一個「放置即完成」的方法。
php
$pdf->text(20.0, 50.0, 'Positioned at x=20, y=50');適合用於浮水印、標籤，或需要精確控制位置的疊加內容。
write()
在目前游標位置以行內方式寫入文字。當文字到達右邊界時會自動換行，就像在文書處理器中輸入一樣。
php
$pdf->setFont('Helvetica', '', 12)
->write(6, 'This sentence starts here and ')
->setFont('Helvetica', 'B', 12)
->write(6, 'this part is bold')
->setFont('Helvetica', '', 12)
->write(6, ' then back to normal.');第一個參數（$h）是行高。當需要在句子中間切換字型或樣式時，請使用 write()。
writeHtml()
使用內建 HTML 解析器渲染 HTML 字串。支援常見標籤，包括標題、段落、表格、清單與行內樣式。
php
$pdf->writeHtml('<h2>Section Title</h2><p>Paragraph with <b>bold</b> and <i>italic</i> text.</p>');HTML 表格
php
$html = '
<table border="1" cellpadding="4">
<thead>
<tr>
<th>Product</th>
<th>Qty</th>
<th>Price</th>
</tr>
</thead>
<tbody>
<tr>
<td>Widget A</td>
<td align="center">10</td>
<td align="right">$25.00</td>
</tr>
<tr>
<td>Widget B</td>
<td align="center">5</td>
<td align="right">$42.50</td>
</tr>
</tbody>
</table>';
$pdf->writeHtml($html);writeHtmlCell()
結合 HTML 渲染與儲存格定位。HTML 內容會被放置在指定座標的儲存格內。
php
$pdf->writeHtmlCell(
float $w, // 寬度
float $h, // 最小高度
float $x, // X 位置
float $y, // Y 位置
string $html,
mixed $border = 0,
bool $fill = false,
);php
$pdf->writeHtmlCell(90, 0, 10, 50, '<p style="color:#336699;">Positioned HTML content with <b>formatting</b>.</p>', border: 1);ln()
插入換行。游標會移至左邊界並向下移動指定高度。
php
$pdf->ln(); // 使用上一個儲存格高度作為間距
$pdf->ln(10); // 換行並加入 10mm 垂直間距
$pdf->ln(0); // 移至左邊界，不做垂直移動方法選擇指南
| 使用情境 | 建議方法 |
|---|---|
| 表格儲存格、標籤、單行資料 | cell() |
| 段落、描述、長篇文字 | multiCell() |
| 浮水印、印章、絕對定位標籤 | text() |
| 行內混合格式文字 | write() |
| 含 HTML 標記的豐富內容 | writeHtml() |
| 定位在特定位置的 HTML 內容 | writeHtmlCell() |