วาดกราฟิกเวกเตอร์ — รูปทรง สี และสไตล์เส้น

ภาพรวมโดยสรุป

ใช้สูตรนี้ในการวาดรูปทรงพื้นฐานทั้งแบบเติมสีและแบบเส้นขอบ ได้แก่ สี่เหลี่ยมผืนผ้า สี่เหลี่ยมผืนผ้ามุมโค้ง วงกลม วงรี และเส้น สำหรับแต่ละรูปทรง คุณสามารถกำหนดสีเติม สีเส้น และความกว้างเส้นได้ สูตรนี้อ้างอิงจาก examples/06-colors-and-drawing.php

รูปทรงพื้นฐานแต่ละชนิดจะแมปกับอ็อบเจกต์ path ของ ISO 32000-2 อ็อบเจกต์ path คือรูปทรงที่สร้างจากเซกเมนต์ของเส้นตรงและเส้นโค้ง และจะจบด้วยตัวดำเนินการระบายสีที่สั่งให้โปรแกรมแสดงผลลากเส้น เติมสี หรือทำทั้งสองอย่าง

การติดตั้ง

composer require nextpdf/core:^3

คุณไม่จำเป็นต้องใช้ส่วนขยายเสริมใดๆ อินเทอร์เฟซการเขียนโปรแกรมแอปพลิเคชัน (API) สำหรับการวาดและการกำหนดสีมีความเสถียรมาตั้งแต่เวอร์ชัน 1.0.0 และทำงานได้กับเมทริกซ์ backport 8.1–8.4

ภาพรวมเชิงแนวคิด

กำหนดสถานะก่อน แล้วจึงวาด setFillColor(), setDrawColor() และ setLineWidth() จะอัปเดตสถานะกราฟิก การเรียก rect(), circle(), ellipse(), roundedRect() หรือ line() ครั้งถัดไปจะใช้สถานะนั้น เมท็อดของรูปทรงรับอาร์กิวเมนต์สไตล์ โดย 'F' หมายถึงเติมสี 'S' หมายถึงลากเส้น (เป็นค่าเริ่มต้น) และ 'DF'/'FD' หมายถึงทำทั้งสองอย่าง ภายในระบบ สี่เหลี่ยมผืนผ้าที่เติมสีคือตัวดำเนินการสร้าง path re ตามด้วยตัวดำเนินการระบายสีแบบเติม ISO 32000-2 §8.5.3 กำหนดให้ S ใช้สำหรับลากเส้นและ f ใช้สำหรับเติมสี โดยเป็นตัวดำเนินการระบายสี path หลัก

สีต่างๆ เป็นสีแบบ device setFillColor(r, g, b) จะเลือกใช้ DeviceRGB ISO 32000-2 §8.6.4.3 นิยาม rg เป็นตัวดำเนินการสีแบบไม่ลากเส้นของ DeviceRGB และ g เป็นตัวดำเนินการที่เทียบเท่าสำหรับ DeviceGray setFillColor($v) แบบอาร์กิวเมนต์เดียวจะกำหนดระดับสีเทา ความกว้างเส้นมีค่าเริ่มต้นเป็น 1.0 และรูปแบบเส้นประมีค่าเริ่มต้นเป็นเส้นทึบ (§8.4.3.6)

ขอบเขตของ API

ขอบเขตของ API นี้อ้างอิงจาก PHPDoc สูตรนี้ใช้เมท็อดเหล่านี้:

rect(float $x, float $y, float $w, float $h, string $style = 'S'): static
roundedRect(float $x, float $y, float $w, float $h, float $r, string $style = 'S'): static
circle(float $x, float $y, float $r, string $style = 'S'): static
ellipse(float $x, float $y, float $rx, float $ry, string $style = 'S'): static
line(float $x1, float $y1, float $x2, float $y2): static
setFillColor(int $r, int $g = -1, int $b = -1): static / setDrawColor(...)
setLineWidth(float $width): static

ตัวอย่างโค้ด — เริ่มต้นใช้งานอย่างรวดเร็ว

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->setFillColor(30, 58, 138);
$doc->rect(20, 30, 60, 40, 'F');          // filled rectangle

$doc->setDrawColor(217, 119, 6);
$doc->setLineWidth(1.0);
$doc->circle(140, 50, 20, 'S');           // stroked circle

$doc->setLineWidth(0.3);
$doc->line(20, 90, 190, 90);              // thin rule

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/vector.pdf');

ตัวอย่างโค้ด — สำหรับการใช้งานจริง

ตัวอย่างฉบับสมบูรณ์ที่พร้อมใช้กับ harness นี้รองรับ NEXTPDF_COOKBOOK_OUTPUT และไม่เพิ่มเอนโทรปีใดๆ ของตัวเอง

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Colors and Drawing');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Colors and Drawing', newLine: true);
$doc->ln(5);

// --- Filled rectangles: set fill colour, then draw with style 'F' ---
$palette = [
    [30, 58, 138], [217, 119, 6], [30, 27, 75],
    [239, 66, 35], [21, 128, 61],
];
$x = 15.0;
$rowY = $doc->getY();
foreach ($palette as [$r, $g, $b]) {
    $doc->setFillColor($r, $g, $b);
    $doc->rect($x, $rowY, 30, 20, 'F');
    $x += 35.0;
}
$doc->ln(28);

// --- Outlined shapes: set draw colour + line width, draw with 'S' ---
$doc->setDrawColor(30, 58, 138);
$doc->setLineWidth(0.5);
$y = $doc->getY();
$doc->rect(15, $y, 30, 25, 'S');
$doc->roundedRect(55, $y, 30, 25, 5, 'S');
$doc->circle(110, $y + 12.5, 12.5, 'S');
$doc->ellipse(150, $y + 12.5, 18, 10, 'S');
$doc->ln(33);

// --- Lines at three widths ---
$y = $doc->getY();
$doc->setDrawColor(0);
$doc->setLineWidth(0.2);
$doc->line(15, $y, 195, $y);
$doc->setLineWidth(0.8);
$doc->line(15, $y + 5, 195, $y + 5);
$doc->setLineWidth(1.5);
$doc->line(15, $y + 12, 195, $y + 12);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/vector.pdf';
$doc->save($out);

echo "Created vector.pdf\n";

กรณีขอบและข้อควรระวัง

สไตล์มีค่าเริ่มต้นเป็นการลากเส้น หากคุณไม่ระบุอาร์กิวเมนต์สไตล์ รูปทรงจะถูกลากเส้น ('S') รูปทรงที่ดูเหมือนมองไม่เห็นมักเกิดจากการวาดโดยไม่ได้กำหนดสีเส้น หรือถูกเติมด้วยสีพื้นหลังของหน้า ให้ส่งค่า 'F' เพื่อเติมสีรูปทรงนั้น
สถานะของสีคงอยู่ต่อเนื่อง setFillColor() จะมีผลต่อไปจนกว่าคุณจะเปลี่ยนแปลง ควรรีเซ็ตค่า เช่น ใช้ setFillColor(255) ก่อนเริ่มบล็อกถัดไปที่ไม่เกี่ยวข้องกัน มิฉะนั้นสีจะถูกนำมาใช้ต่อ
สีเทาเทียบกับการโอเวอร์โหลดแบบ RGB setFillColor(128) คือระดับสีเทา setFillColor(128, 0, 0) คือ RGB รูปแบบที่ใช้อาร์กิวเมนต์เดียวไม่ได้หมายถึง “สีแดง 128”
แกน Y ใน API ไล่จากบนลงล่าง ตัวช่วยวาดใช้จุดกำเนิดที่มุมบนซ้ายของเอกสาร เอนจินจะแมปจุดกำเนิดนั้นไปยังพื้นที่ผู้ใช้ของ PDF ที่มุมล่างซ้ายให้โดยอัตโนมัติ

ประสิทธิภาพ

รูปทรงพื้นฐานแต่ละรูปสร้างตัวดำเนินการ content-stream เพียงไม่กี่ตัว รูปทรงหลายพันรูปต่อหน้ายังคงอยู่ภายในงบประมาณ 2000 ms / 64 MB ได้อย่างไม่มีปัญหา ต้นทุนเพิ่มขึ้นเชิงเส้นตามจำนวนรูปทรงพื้นฐาน ไม่มีการแปลงเป็นภาพแรสเตอร์ ดังนั้นผลลัพธ์จึงยังคงเป็นเวกเตอร์

หมายเหตุด้านความปลอดภัย

สูตรนี้วาดเฉพาะรูปทรงเรขาคณิตที่โค้ดของคุณระบุไว้เท่านั้น สูตรนี้ไม่แยกวิเคราะห์ข้อมูลนำเข้าใดๆ และไม่มีการเข้าถึงเครือข่าย ควรตรวจสอบช่วงค่าของพิกัดใดๆ ที่มาจากข้อมูลที่ไม่น่าเชื่อถือ การตรวจสอบนี้ป้องกันไม่ให้ค่าที่เป็นอันตรายผลักงานวาดออกไปไกลนอกหน้า

ความสอดคล้องตามมาตรฐาน

ข้อความระบุ	ข้อกำหนด	ข้อ
อ็อบเจกต์ path คือเส้น สี่เหลี่ยมผืนผ้า และเส้นโค้งเบซิเยร์ที่จบลงด้วยตัวดำเนินการระบายสี	ISO 32000-2	§8.5
`S` ลากเส้นและ `f` เติมสี path	ISO 32000-2	§8.5.3
`rg` กำหนดสีแบบไม่ลากเส้นของ DeviceRGB; `g` กำหนด DeviceGray	ISO 32000-2	§8.6.4.3
ค่าเริ่มต้นของรูปแบบเส้นประคือ `[] 0` ซึ่งเป็นเส้นทึบ	ISO 32000-2	§8.4.3.6

โปรไฟล์การทำซ้ำได้ — เชิงโครงสร้าง การวาดแบบเวกเตอร์ไม่มีเอนโทรปีของตัวเอง ถึงกระนั้น เอกสารทุกฉบับที่บันทึกก็ยังมี /ID ใน trailer และอะตอมของวันที่ ISO 32000-2 §8.3.4 ยังระบุด้วยว่าการจัดเรียงตัวดำเนินการสถานะกราฟิกแบบเฉพาะเจาะจงไม่มีนัยสำคัญเชิงความหมาย ดังนั้นตัวนอร์มอลไลซ์จึงอาจจัดเรียงสถานะที่เทียบเท่ากันใหม่ได้ ข้อรับรองที่สนับสนุนคือความเท่ากันเชิงโครงสร้างหลังการนอร์มอลไลซ์ด้วย qpdf สูตรนี้อธิบายว่า NextPDF สร้างโครงสร้างนี้อย่างไร สูตรนี้ไม่ได้ยืนยันความสอดคล้องตาม ISO 32000-2 แบบครอบคลุมทั้งหมด

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง การวาดแบบเวกเตอร์เป็นความสามารถใน Core และไม่ถูกจำกัดด้วย Premium