رسم الرسوميات المتجهة — الأشكال والألوان وأنماط الخطوط

لمحة سريعة

استخدم هذه الوصفة لرسم الأشكال الأولية ذات التعبئة والحدود: المستطيلات والمستطيلات ذات الزوايا المستديرة والدوائر والأشكال البيضاوية والخطوط. اضبط لكل شكل لون التعبئة ولون الحدّ وعرض الخط. تتبع هذه الوصفة examples/06-colors-and-drawing.php.

يقابل كل شكل أولي كائن مسار في ⁨ISO 32000-2.⁩ كائن المسار شكل يتكوّن من مقاطع خطية ومنحنية، وينتهي بمُعامِل طلاء يوجّه العارض إلى رسم الحدّ أو التعبئة أو كليهما.

التثبيت

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' ينفّذان الأمرين معًا. داخليًّا، المستطيل المعبّأ هو مُعامِل بناء المسار re متبوعًا بمُعامِل طلاء التعبئة. يحدِّد ⁨ISO 32000-2⁩ §8.5.3 المُعامِل S لرسم الحدّ وf للتعبئة بوصفهما مُعامِلَي طلاء المسار الرئيسيَّين.

الألوان هنا ألوان جهاز. تختار 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');

نموذج شفرة — الإنتاج

يلتزم هذا المثال الكامل الجاهز للتشغيل بقيمة 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.⁩ وليست الصيغة ذات الوسيط الواحد “⁨red 128⁩”.
يمتد المحور ⁨Y⁩ من الأعلى إلى الأسفل في واجهة ⁨API.⁩ تعتمد توابع الرسم المساعِدة نقطة الأصل في أعلى يسار المستند. ويحوّل المحرك ذلك نيابةً عنك إلى فضاء مستخدِم ⁨PDF⁩ ذي نقطة الأصل في أسفل اليسار.

الأداء

ينتج كل شكل أولي مجموعة صغيرة من مُعامِلات دفق المحتوى. تظل آلاف الأشكال في كل صفحة ضمن ميزانية 2000 ⁨ms⁩ / 64 ⁨MB⁩ بهامش واسع. تنمو التكلفة خطيًّا مع عدد الأشكال الأولية. لا توجد عملية تنقيط، لذا يظل الناتج متجهيًّا.

ملاحظات أمنية

ترسم هذه الوصفة الهندسة التي تحدِّدها شفرتك فقط. لا تحلِّل أي مدخلات ولا تُجري أي وصول إلى الشبكة. تحقّق من نطاق أي إحداثيات تأتي من بيانات غير موثوقة. يمنع هذا التحقّق قيمةً عدائية من إزاحة العلامات بعيدًا خارج الصفحة.

المطابقة

العبارة	المواصفة	البند
كائن المسار هو خطوط ومستطيلات ومنحنيات بيزييه تنتهي بمُعامِل طلاء.	⁨ISO 32000-2⁩	§8.5
يرسم `S` حدّ المسار ويُعبّئ `f` المسار.	⁨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 في المُذيّل وذرّات تاريخ. كما ينص ⁨ISO 32000-2⁩ §8.3.4 على أن الترتيب الدقيق لمُعامِلات حالة الرسوميات لا أهمية دلالية له، لذا قد يُعيد المُطبِّع ترتيب الحالة المكافئة. الادّعاء المدعوم هو التساوي البنيوي بعد التطبيع بـ⁨qpdf.⁩ تصف هذه الوصفة كيف يُنتج ⁨NextPDF⁩ هذه البنية، ولا تؤكّد المطابقة مع ⁨ISO 32000-2⁩ بوصفها ادّعاءً شاملًا.

السياق التجاري

غير منطبق. الرسم المتجهي إمكانية ضمن ⁨Core⁩ من دون أي بوابة ⁨Premium.⁩