Pro الإصدار

Chart

لمحة سريعة

يَعرض ⁨NextPDF Pro⁩ الرسوم البيانية الشريطية والخطية والدائرية مباشرةً داخل صفحة ⁨PDF⁩ بوصفها مُعامِلات محتوى متجهية. لا توجد خطوة تنقيط ولا اعتماد على متصفّح بلا واجهة، لذا تكون المخرجات حتمية وقابلة للاستنساخ.

التثبيت

composer require nextpdf/pro:^3

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

توفّر وحدة ⁨Chart⁩ ثلاثة عارضات رسوم بيانية أصلية. كل عارض بدائية رسم قائمة بذاتها: يَعرض داخل مربّع مستطيل ثابت تزوّده، دون إعادة تدفّق، ودون وعي بالحاوية، ودون تفاوض على التخطيط. أنت تضع المربّع، والعارض يملؤه.

الرسم الشريطي — رسم شريطي عمودي بلون شريط ولون محور وفجوة شريط وحجم خط بطاقة قابلة للضبط.
الرسم الخطي — رسم خطي بسلسلة واحدة أو سلاسل متعددة بلون لكل سلسلة، ومؤشّرات نقاط بيانية اختيارية، وشبكة اختيارية، وعرض خط قابل للضبط.
الرسم الدائري — رسم دائري بإسناد لوحة ألوان تلقائي، وبطاقات نسب مئوية اختيارية، ووسيلة إيضاح اختيارية.

يتبع كل عارض الشكل نفسه: مصنع fromData(...)، وتهيئة انسيابية بـ with*()، واستدعاء render(ChartBox $box): string يُعيد مُعامِلات دفق محتوى ⁨PDF.⁩ المخرجات حتمية — يُنتج المُدخَل والتهيئة المتطابقان مُعامِلات متطابقة، ما يُبقي المستندات المُرسَّمة قابلة للاستنساخ وآمنة للتوقيع أو الأرشفة.

ولأن العارضات تُصدِر مُعامِلات متجهية بدلًا من الصور، تبقى الرسوم البيانية واضحة عند أي تكبير ولا تضيف أي حمولة نقطية إلى المستند.

لماذا يعمل بهذه الطريقة

القرار الحامل هو إصدار مُعامِلات ⁨PDF⁩ متجهية أصلية بدلًا من تنقيط صورة أو تشغيل متصفّح بلا واجهة. هذا الخيار يجعل المخرجات حتمية: تُنتج البيانات والتهيئة المتطابقة دائمًا مُعامِلات متطابقة بايتًا ببايت. المُعامِلات الحتمية تُبقي المستند المُرسَّم قابلًا للاستنساخ، ومن ثَمّ آمنًا للتوقيع أو الأرشفة. كما أن تجنّب عارض خارجي يُزيل اعتمادًا على عملية، فتتدرّج الإنتاجية بعدد نقاط البيانات بدلًا من كلفة بدء تشغيل المتصفّح. يلفّ كل عارض مُعامِلاته في زوج حالة رسم q/Q ولا يُعيد التدفّق أبدًا، فيتركّب على نحو متوقَّع وزهيد.

خلفية التصميم: توليد المستندات عالي الحجم.

سطح الـ ⁨API⁩

composer require nextpdf/pro:^3

سطح ⁨Chart⁩ العام هو خمسة أصناف في NextPDF\Pro\Chart:

BarChart — fromData()، withBarColor()، withAxisColor()، withBarGap()، withFontSize()، render().
LineChart — create()، fromData()، addSeries()، withAxisColor()، withLineWidth()، withFontSize()، withDots()، withGrid()، render().
PieChart — fromData()، withColors()، withStrokeColor()، withFontSize()، withPercentages()، withLegend()، render().
ChartBox — مستطيل الوضع؛ يحوّل fromUserSpace() مستطيل فضاء المستخدم ذا الأصل في الزاوية العليا اليسرى إلى أصل ⁨PDF⁩ في الزاوية السفلى اليسرى؛ وinset() للحشو.
ChartColor — rgb()، hex()، palette()، إضافةً إلى مُصدِرات مُعامِلات الحدّ/التعبئة.

مثال شيفرة — بداية سريعة

use NextPDF\Pro\Chart\BarChart;
use NextPDF\Pro\Chart\ChartBox;

$box = ChartBox::fromUserSpace(72, 72, 400, 240, pageHeight: 842);
$stream = BarChart::fromData(['Q1', 'Q2', 'Q3', 'Q4'], [100, 200, 150, 300])
    ->render($box);
// $stream is appended to the target page content.

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

use NextPDF\Pro\Chart\ChartBox;
use NextPDF\Pro\Chart\ChartColor;
use NextPDF\Pro\Chart\LineChart;

$box = ChartBox::fromUserSpace(72, 72, 460, 260, pageHeight: 842)
    ->inset(8, 8, 8, 8);

$stream = LineChart::create(['Jan', 'Feb', 'Mar', 'Apr'])
    ->addSeries('Revenue', [120, 180, 150, 220], ChartColor::hex('#336699'))
    ->addSeries('Cost', [80, 90, 110, 130], ChartColor::palette(1))
    ->withGrid(true)
    ->withDots(true, 2.5)
    ->withLineWidth(1.2)
    ->render($box);

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

البيانات الفارغة تُعيد سلسلة فارغة بدلًا من رمي استثناء، فمجموعة البيانات الغائبة لا تَعرض شيئًا بدلًا من أن تكسر الصفحة.
الرسم الدائري الذي مجموعه صفر أو سالب يُعيد سلسلة فارغة.
سلسلة خطية بنقطة واحدة لا ترسم أي قطعة خط (النقطة الواحدة بلا مسار).
مربّع ChartBox بأبعاد صفرية لا يَعرض شيئًا ذا معنى؛ حدّد حجم المربّع قبل العرض.
لا تقتطع العارضات إلى المربّع؛ زوّد مربّعًا يلائم منطقة الصفحة التي تقصدها.

الأداء

العرض من تمريرة واحدة وخطّي بعدد نقاط البيانات. لا يوجد تنقيط، ولا مخزن صور مؤقت، ولا أي عملية خارجية. يحدّ حجم سلسلة المُعامِلات المُصدَرة تكلفة الذاكرة. تتدرّج الرسوم الخطية متعددة السلاسل خطّيًا بإجمالي النقاط عبر السلاسل.

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

تستهلك عارضات الرسوم البيانية بيانات عددية وبطاقات فقط؛ ولا تُقيّم المُدخَل ولا تُنفّذه. تُصدِر العارضات البطاقات بوصفها مُعامِلات نص ⁨PDF⁩ ولا تفسّرها أبدًا. لا تُسجّل الوحدة أي بيانات رسم بياني؛ وعلى التطبيق تنقية البطاقات الحسّاسة قبل الترسيم.

المطابقة

الرسوم البيانية لا يحكمها معيار خارجي؛ والمخرجات دفق محتوى ⁨PDF⁩ مَعروض داخل الصفحة وفق دلالات دفق المحتوى في ⁨ISO 32000-2.⁩ لا يوجد سطح مطابقة ترميزية أو تشفيرية لهذه الوحدة.

حدود النشر

تُوثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح الـ ⁨API⁩ العام المدعوم فقط. أما مسارات فضاء الأسماء الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر فخارج النطاق.