Navigation API¶

namespace NextPDF\Core\Navigation;

final class NavigationManager

/** 取得書籤管理器 */
public function bookmarks(): BookmarkManager

/** 取得連結管理器 */
public function links(): LinkManager

/** 取得目錄建構器 */
public function tocBuilder(): TocBuilder

namespace NextPDF\Core\Navigation;

final class BookmarkManager

/**
 * 新增書籤。
 *
 * @param non-empty-string $title 書籤標題
 * @param Page             $page  目標頁面
 * @param float            $y     頁面內的 Y 位置（mm），預設頁面頂部
 * @param int              $level 書籤層級（1 = 頂層，最多 6 層）
 * @param bool             $open  預設展開（僅對有子書籤的節點有效）
 */
public function add(
    string $title,
    Page   $page,
    float  $y     = 0.0,
    int    $level = 1,
    bool   $open  = true,
): BookmarkEntry

/** 取得書籤樹根節點 */
public function root(): BookmarkEntry

/** 取得書籤總數 */
public function count(): int

/** 匯出書籤為巢狀陣列（適用序列化或調試）*/
public function toArray(): array

final class BookmarkEntry
{
    public readonly string $title;
    public readonly int    $pageNumber;
    public readonly int    $level;

    /** 新增子書籤 */
    public function addChild(string $title, Page $page, float $y = 0.0): self

    /** 取得所有子書籤 */
    public function children(): list<BookmarkEntry>

    /** 是否有子書籤 */
    public function hasChildren(): bool
}

namespace NextPDF\Core\Navigation;

final class LinkManager

/**
 * 建立連結至 URL。
 *
 * @param Rectangle        $bounds  可點擊區域
 * @param non-empty-string $url     目標 URL
 * @param Page             $page    包含此連結的頁面
 */
public function addExternalLink(
    Rectangle $bounds,
    string    $url,
    Page      $page,
): LinkAnnotation

/**
 * 建立文件內部連結（跳至指定頁面）。
 *
 * @param Rectangle $bounds     可點擊區域
 * @param Page      $targetPage 目標頁面
 * @param float     $targetY    目標 Y 位置（mm）
 * @param Page      $sourcePage 包含此連結的頁面
 */
public function addInternalLink(
    Rectangle $bounds,
    Page      $targetPage,
    float     $targetY    = 0.0,
    Page      $sourcePage,
): LinkAnnotation

/**
 * 建立電子郵件連結（mailto:）。
 */
public function addEmailLink(
    Rectangle $bounds,
    string    $email,
    Page      $page,
    string    $subject = '',
): LinkAnnotation

namespace NextPDF\Core\Navigation;

final class TocBuilder

/**
 * 在指定位置保留目錄佔位符（尚不知道頁碼時調用）。
 *
 * @param Page             $page     目錄所在頁面
 * @param Position         $position 目錄起始位置
 * @param float            $maxWidth 目錄寬度
 * @param TocStyle         $style    目錄樣式
 */
public function reservePlaceholder(
    Page      $page,
    Position  $position,
    float     $maxWidth = 160.0,
    TocStyle  $style    = TocStyle::DEFAULT,
): void

/**
 * 登記目錄條目。
 *
 * @param non-empty-string $title      章節標題
 * @param int              $pageNumber 頁碼
 * @param int              $level      層級（1 = 頂層，最多 4 層）
 */
public function addEntry(
    string $title,
    int    $pageNumber,
    int    $level = 1,
): void

/**
 * 建立目錄（已知所有頁碼後調用）。
 * 填入之前保留的佔位符。
 */
public function build(): void

enum TocStyle
{
    case DEFAULT;    // 標題 + 點點線 + 頁碼
    case COMPACT;    // 無點點線，更緊湊
    case MINIMAL;    // 只有標題和頁碼
}