Layout API¶

namespace NextPDF\Core\Layout;

final class PageManager

/**
 * 新增頁面並回傳 Page 物件。
 *
 * @param PageSize|null $size    頁面大小（null = 使用文件預設）
 * @param Margin|null   $margin  頁面邊距（null = 使用文件預設）
 */
public function add(
    ?PageSize $size   = null,
    ?Margin   $margin = null,
): Page

/** 取得指定頁面（1-based）*/
public function get(int $pageNumber): Page

/** 取得當前活動頁面 */
public function current(): Page

/** 切換到指定頁面 */
public function goTo(int $pageNumber): Page

/** 總頁數 */
public function count(): int

/** 在指定頁面前插入新頁面 */
public function insertBefore(int $pageNumber, ?PageSize $size = null): Page

/** 移除指定頁面 */
public function remove(int $pageNumber): void

/** 所有頁面的集合 */
public function all(): PageCollection

/**
 * 設定頁首渲染回呼（套用至後續所有新增頁面）。
 *
 * @param callable(int $pageNumber, int $totalPages): void $callback
 * @param bool $skipFirstPage 是否跳過第 1 頁（封面）
 */
public function setHeaderTemplate(
    callable $callback,
    bool     $skipFirstPage = false,
): void

/**
 * 設定頁尾渲染回呼。
 *
 * @param callable(int $pageNumber): void $callback
 */
public function setFooterTemplate(
    callable $callback,
    bool     $skipFirstPage = false,
): void

final class Page
{
    /** 頁碼（1-based）*/
    public readonly int      $number;
    public readonly PageSize $size;
    public readonly Margin   $margin;

    /** 可用內容寬度（頁面寬度 - 左邊距 - 右邊距，mm）*/
    public function contentWidth(): float

    /** 可用內容高度（頁面高度 - 上邊距 - 下邊距，mm）*/
    public function contentHeight(): float

    /** 旋轉頁面（90、180、270 度）*/
    public function rotate(int $degrees): self

    /** 設定頁面的 ViewerPreferences（縮放、佈局）*/
    public function withViewerPreference(ViewerPreference $preference): self
}

namespace NextPDF\Core\Layout;

final class ColumnLayout

/**
 * 建立等寬多欄版面。
 *
 * @param int         $columns 欄數（2–12）
 * @param float       $gap     欄間距（mm）
 * @param Page        $page    目標頁面
 */
public static function equal(
    int   $columns,
    float $gap  = 5.0,
    Page  $page,
): self

/**
 * 建立自訂比例多欄版面。
 *
 * @param list<float> $ratios 各欄比例（如 [1, 2] 代表 1:2 的雙欄）
 */
public static function proportional(
    array $ratios,
    float $gap = 5.0,
    Page  $page,
): self

/** 取得指定欄的可用區域（Rectangle）*/
public function column(int $index): ColumnArea

/** 切換到下一欄（超出最後一欄時自動換頁）*/
public function nextColumn(): ColumnArea

/** 跨越所有欄的全寬區域 */
public function fullWidth(): Rectangle

final readonly class ColumnArea
{
    public int       $index;   // 0-based 欄索引
    public Rectangle $bounds;  // 欄的邊界（含上邊距）
    public float     $x;       // 欄起始 X（mm）
    public float     $y;       // 欄起始 Y（mm，從文件頂部）
    public float     $width;   // 欄寬（mm）
    public float     $height;  // 欄高（mm，扣除上下邊距）
}

namespace NextPDF\Core\Layout;

final class BookletLayout

/**
 * 建立書冊版面（自動計算拼版頁面順序）。
 *
 * @param int                       $contentPages 正文頁數（自動補全至 4 的倍數）
 * @param 'saddle-stitch'|'perfect' $bindingType  裝訂方式
 * @param PageSize                  $sheetSize    印刷用紙尺寸（通常比內文頁大一倍）
 */
public static function create(
    int    $contentPages,
    string $bindingType = 'saddle-stitch',
    PageSize $sheetSize = PageSize::A3,
): self

/** 取得拼版後的頁面順序（可直接傳給印刷廠）*/
public function impositionOrder(): list<int>

/** 取得正面印刷的頁面集合 */
public function frontSides(): list<ImpositionSheet>

/** 取得反面印刷的頁面集合 */
public function backSides(): list<ImpositionSheet>