Value Objects API¶
所有 Value Objects 均為不可變（readonly）。修改操作回傳新實例，原實例不受影響。
PHP Compatibility
This example uses PHP 8.5 syntax. If your environment runs PHP 8.1 or 7.4, use NextPDF Backport for a backward-compatible build.
PageSize¶
預定義尺寸¶
// ISO 216 A 系列
PageSize::A0 // 841 × 1189 mm
PageSize::A1 // 594 × 841 mm
PageSize::A2 // 420 × 594 mm
PageSize::A3 // 297 × 420 mm
PageSize::A4 // 210 × 297 mm（最常用）
PageSize::A5 // 148 × 210 mm
PageSize::A6 // 105 × 148 mm
// ISO 216 B 系列
PageSize::B4 // 257 × 364 mm
PageSize::B5 // 182 × 257 mm
// 美規
PageSize::LETTER // 215.9 × 279.4 mm
PageSize::LEGAL // 215.9 × 355.6 mm
PageSize::TABLOID // 279.4 × 431.8 mm
// 名片（ISO 7810）
PageSize::ID1 // 85.6 × 53.98 mm（信用卡大小）
工廠方法¶
/**
* 從毫米建立自訂頁面大小。
*
* @param positive-int|float $widthMm
* @param positive-int|float $heightMm
*/
public static function custom(float $widthMm, float $heightMm): self
/** 從 PDF 點（point，1/72 英吋）建立 */
public static function fromPoints(float $widthPt, float $heightPt): self
實例方法¶
/** 取得橫向版本（寬高互換）*/
public function landscape(): self
/** 取得縱向版本 */
public function portrait(): self
public function widthMm(): float
public function heightMm(): float
public function widthPt(): float
public function heightPt(): float
public function isLandscape(): bool
public function isPortrait(): bool
Margin¶
/** 四邊不同邊距 */
public static function create(
float $top,
float $right,
float $bottom,
float $left,
): self
/** 四邊相同邊距 */
public static function uniform(float $all): self
/** 上下相同、左右相同 */
public static function symmetric(float $vertical, float $horizontal): self
/** 上下左右各別指定 */
public static function fromArray(array $values): self // [top, right?, bottom?, left?]
// 屬性
public readonly float $top;
public readonly float $right;
public readonly float $bottom;
public readonly float $left;
// 工廠常量
public static Margin DEFAULT; // 20mm 四邊
Dimension¶
public static function create(float $width, float $height): self
public static function square(float $size): self // 正方形
public readonly float $width; // mm
public readonly float $height; // mm
/** 縮放（等比或分別）*/
public function scale(float $factor): self
public function scaleWidth(float $width): self // 保持比例
public function scaleHeight(float $height): self // 保持比例
Position¶
/**
* 以毫米指定位置（Y 從頁面頂部算起）。
*
* @param float $x 水平位置（mm，從頁面左邊）
* @param float $y 垂直位置（mm，從頁面頂部）
*/
public static function at(float $x, float $y): self
/** 頁面原點（左上角）*/
public static function origin(): self
public readonly float $x;
public readonly float $y;
public function offset(float $dx, float $dy): self
public function offsetX(float $dx): self
public function offsetY(float $dy): self
Rectangle¶
public static function create(
float $x,
float $y,
float $width,
float $height,
): self
public readonly float $x;
public readonly float $y;
public readonly float $width;
public readonly float $height;
public function right(): float // x + width
public function bottom(): float // y + height
public function topLeft(): Position
public function topRight(): Position
public function bottomLeft(): Position
public function bottomRight(): Position
public function center(): Position
/** 建立向內縮小的 Rectangle */
public function inset(float $amount): self
public function insetBy(float $top, float $right, float $bottom, float $left): self
Color¶
/** 從十六進位字串建立（#RRGGBB 或 #RGB）*/
public static function fromHex(string $hex): self
/** 從 0–255 RGB 值建立 */
public static function fromRgb(int $r, int $g, int $b): self
/** 從 0.0–1.0 RGB 值建立 */
public static function fromRgbFloat(float $r, float $g, float $b): self
/** 從 0.0–1.0 CMYK 值建立（印刷色彩）*/
public static function fromCmyk(float $c, float $m, float $y, float $k): self
/** 取得具指定透明度的新實例（0.0 = 完全透明）*/
public function withAlpha(float $alpha): self
// 預定義顏色
public static Color BLACK;
public static Color WHITE;
public static Color TRANSPARENT;
// 屬性
public readonly float $r; // 0.0–1.0
public readonly float $g;
public readonly float $b;
public readonly float $alpha; // 0.0–1.0
public function toHex(): string // '#RRGGBB'
public function toCmyk(): array // [c, m, y, k] float[]
public function isDark(): bool
public function isLight(): bool
Unit¶
public static function mm(float $value): self
public static function pt(float $value): self // PDF 點（1/72 英吋）
public static function cm(float $value): self
public static function inch(float $value): self
public function toMm(): float
public function toPt(): float
public function toCm(): float
public function toInch(): float
Language¶
/**
* 從 BCP 47 語言標記建立。
*
* @param non-empty-string $tag 如 'zh-TW'、'en-US'、'ar-SA'
* @throws InvalidLanguageTagException
*/
public static function fromBcp47(string $tag): self
public function tag(): string // 原始標記（如 'zh-TW'）
public function language(): string // 主要語言（如 'zh'）
public function region(): string // 地區代碼（如 'TW'），可能為空
public function isRtl(): bool // 是否為從右到左語言
延伸閱讀¶
- API：Document — 使用這些 VO 的主要場景
- API：Graphics — Color、Rectangle 在繪圖中的應用