رسم التدرجات اللونية واستخدام الشفافية وأوضاع المزج

لمحة سريعة

املأ منطقة بتدرج لوني محوري (خطي) أو شعاعي باستخدام محطتي لون. ثم ركّب الأشكال المتراكبة بقيمة ألفا ثابتة ووضع مزج اختياري. تعتمد الشيفرة على المثالين examples/25-gradients.php وexamples/20-transparency.php.

يُمثّل التدرج اللوني تظليلًا وفق ⁨ISO 32000-2.⁩ تُصدِر linearGradient() تظليلًا من النوع 2 (محوري)، وتُصدِر radialGradient() تظليلًا من النوع 3 (شعاعي). تستخدم الشفافية ثابت ألفا الخاص بحالة الرسوميات. تضبط setAlpha() قيمة ca غير المحدِّدة للحد وقيمة CA المحدِّدة للحد.

التثبيت

composer require nextpdf/core:^3

لا تحتاج إلى امتداد اختياري. بقيت واجهة برمجة التطبيقات الخاصة بالتدرج اللوني وألفا ووضع المزج مستقرة منذ 1.0.0، وتعمل ضمن مصفوفة النقل الخلفي 8.1–8.4.

نظرة عامة مفاهيمية

ترسم linearGradient(x, y, w, h, start, end) مزجًا لونيًا على امتداد محور المنطقة بين محطتي Color. يُعرّف ⁨ISO 32000-2⁩ قيمة Coords للتظليل المحوري بوصفها [x0 y0 x1 y1]. إذا تطابقت نقطتا النهاية، فلا يُرسم شيء. تمزج radialGradient(...) بين دائرتين. قيمة Coords الشعاعية هي [x0 y0 r0 x1 y1 r1]، ويجب أن يكون كلا نصفي القطر ≥ 0.

تضبط setAlpha($alpha, $mode) عتامة ثابتة للرسم اللاحق. المعامل الأول هو ثابت ألفا (ca/CA). يحدد المعامل الثاني وضع المزج (BM في نموذج التصوير الشفاف). أعِد ضبط ألفا إلى 1.0 ووضع المزج إلى Normal قبل أن ترسم محتوى غير ذي صلة.

سطح واجهة برمجة التطبيقات

يُولَّد سطح واجهة برمجة التطبيقات من ⁨PHPDoc.⁩ تعتمد هذه الوصفة على الأساليب الآتية:

linearGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
radialGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal): static
توفر Color::rgb(int $r, int $g, int $b) وColor::white() وColor::black() محطات ألوان التدرج اللوني.
تضبط setFillColor(...) اللون الذي تركّبه قيمة ألفا ووضع المزج.

نموذج الشيفرة — البدء السريع

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

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

// Axial gradient: blue -> white across a 190 x 40 box.
$doc->linearGradient(10, 30, 190, 40, Color::rgb(30, 58, 138), Color::white());

// Two overlapping rectangles at 70% opacity with Multiply blend.
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, 90, 60, 40, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(50, 90, 60, 40, 'F');
$doc->setAlpha(1.0, BlendMode::Normal); // reset

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

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

هذا هو المثال الكامل الجاهز لإطار الاختبار. يحترم NEXTPDF_COOKBOOK_OUTPUT ولا يضيف أي إنتروبيا من جانبه.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

$doc = Document::createStandalone();
$doc->setTitle('Gradients and Transparency');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Gradients and Transparency', newLine: true);
$doc->ln(4);

// 1. Axial gradient — blue to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '1. Axial gradient', newLine: true);
$doc->ln(2);
$doc->linearGradient(
    x: 10, y: $doc->getY(), w: 190, h: 40,
    start: Color::rgb(30, 58, 138), end: Color::white(),
);
$doc->ln(44);

// 2. Radial gradient — red centre fading to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '2. Radial gradient', newLine: true);
$doc->ln(2);
$doc->radialGradient(
    x: 50, y: $doc->getY(), w: 110, h: 55,
    start: Color::rgb(220, 38, 38), end: Color::white(),
);
$doc->ln(59);

// 3. Constant alpha + blend mode over a light backdrop.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '3. Alpha 0.7 with Multiply blend', newLine: true);
$doc->ln(2);
$baseY = $doc->getY();
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(245, 245, 245);
$doc->rect(15, $baseY, 90, 40, 'F');
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, $baseY + 5, 40, 30, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(40, $baseY + 5, 40, 30, 'F');

// Always reset compositing state before continuing.
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(255);

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

echo "Created gradients.pdf\n";

الحالات الحدية والمزالق

نقطتا نهاية التدرج اللوني المتطابقتان لا ترسمان شيئًا. المربع ذو الحجم الصفري الذي ينهار فيه المحور بسبب w أو h يُنتج تظليلًا محوريًا فارغًا وفق ⁨ISO 32000-2.⁩ تأكد من أن للمربع امتدادًا.
يجب أن تكون أنصاف الأقطار غير سالبة. تمرير نصف قطر سالب إلى radialGradient() غير صالح. نصفا قطر يساويان صفرًا لا يرسمان شيئًا.
تظل قيمة ألفا قائمة عبر عمليات الرسم. تبقى setAlpha(0.7, …) سارية في كل عملية رسم لاحقة حتى تعيد ضبطها. أعِد ضبط setAlpha(1.0, BlendMode::Normal) بعد كتلة شفافة، وإلا فسيظهر المحتوى اللاحق باهتًا.
يحتاج وضع المزج إلى خلفية. يُطبَّق وضع مزج مثل ⁨Multiply⁩ أو ⁨Screen⁩ فوق ما رُسم بالفعل. فوق صفحة فارغة يكون التأثير غير مرئي، لذا ارسم خلفية أولًا.
مصفوفة وضع المزج في ⁨PDF 2.0⁩ مهملة. يُصدِر ⁨NextPDF⁩ اسم وضع مزج واحدًا، وهي صيغة ⁨PDF 2.0.⁩ تُهمل المواصفة صيغة المصفوفة القديمة.

الأداء

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

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

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

المطابقة

البيان	المواصفة	البند
`ShadingType` 2 محوري، و3 شعاعي.	⁨ISO 32000-2⁩	§8.7.4.3
قيمة `Coords` المحورية هي `[x0 y0 x1 y1]`؛ نقطتا النهاية المتطابقتان لا ترسمان شيئًا.	⁨ISO 32000-2⁩	§8.7.4.5.3
قيمة `Coords` الشعاعية هي `[x0 y0 r0 x1 y1 r1]`؛ أنصاف الأقطار ≥ 0.	⁨ISO 32000-2⁩	§8.7.4.5.4
`CA`/`ca` هما ثابتا ألفا ⁨stroking/non-stroking⁩ (المحدِّد للحد/غير المحدِّد للحد).	⁨ISO 32000-2⁩	§8.4.5
`BM` هو وضع المزج الحالي.	⁨ISO 32000-2⁩	§11.3.5

ملف إمكانية إعادة الإنتاج — بنيوي. تتغير ذرّة /ID في المقطورة وذرّات التاريخ في كل عملية حفظ. يجرّد إطار الاختبار تلك الذرّات، ثم يقارن البنية المُسوّاة باستخدام ⁨qpdf.⁩ تصف هذه الوصفة كيفية إنتاج ⁨NextPDF⁩ للبنية. وهي لا تقدّم ادعاءً شاملًا بالمطابقة لـ ⁨ISO 32000-2.⁩

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

لا ينطبق. التدرجات اللونية وألفا وأوضاع المزج قدرات في ⁨Core.⁩ ولا تتطلب أي بوابة ⁨Premium.⁩