⁨Chart⁩ — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لوحدة ⁨NextPDF Pro Chart⁩. السطح هو خمس فئات عامة في NextPDF\Pro\Chart: مُصيِّرات BarChart وLineChart وPieChart، ومستطيل التموضع ChartBox، وكائن القيمة ChartColor. كل مُصيِّر هو أوليّة رسم. يُنشئه مصنع ساكن، وتُهيّئه استدعاءات with*() الانسيابية، ويُعيد render(ChartBox $box): string مُعامِلات تدفّق محتوى ⁨PDF⁩ للمستطيل المُعطى. المخرجات متجهية فقط وحتمية: المُدخل والتهيئة المتطابقان يُنتجان بايتات متطابقة. المُدخلات المُنحلّة تُعيد سلسلة فارغة بدلًا من الرمي، فلا يكسر المخطّط الصفحة المُحيطة أبدًا. تعيش الرؤية الموجّهة نحو المهام في صفحة القدرة.

التوفّر والترخيص

تُشحن هذه القدرة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص من فئة ⁨Pro⁩. النشر بلا ذلك الاستحقاق لا يُحمّل فئات القدرة. قارن الإصدارات واحصل على ترخيص.

مُصيِّرات المخطّطات مُرخَّصة على مستوى القدرة ضمن عائلة القدرات chart.*. عند عدم ترخيص القدرة، لا تتوفّر مُصيِّرات المخطّطات.

سطح ⁨API⁩ العام

composer require nextpdf/pro:^3

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
BarChart::fromData()	list<string> $labels، list<int|float> $values	تُحوَّل القيم إلى ⁨float⁩	self	لا يرمي	مسار الإنشاء الوحيد؛ المُنشئ خاص
BarChart::withBarColor()	ChartColor $color	تعبئة الشريط؛ الافتراضي هو مُدخل اللوحة 0	self	لا يرمي	انسيابي؛ يُحوّر المُستقبِل
BarChart::withAxisColor()	ChartColor $color	حدّ المحور؛ الافتراضي #333333	self	لا يرمي	—
BarChart::withBarGap()	float $gap	الفجوة كنسبة من عرض الفتحة؛ الافتراضي 0.2	self	لا يرمي	مُقيَّد إلى 0.0–0.9؛ المُدخل خارج النطاق يُقيَّد، لا يُرفض
BarChart::withFontSize()	float $size	حجم خط التسمية بالنقاط؛ الافتراضي 7.0	self	لا يرمي	—
BarChart::render()	ChartBox $box	محاور، وأشرطة، وتسميات الفئات، وخمس علامات قيمة	مُعامِلات string	لا يرمي؛ البيانات الفارغة تُعيد ''	الحد الأقصى غير الموجب يُقاس مقابل 1.0
LineChart::create()	list<string> $labels	مخطّط بلا سلاسل	self	لا يرمي	المُنشئ خاص
LineChart::fromData()	list<string> $labels، list<int|float> $values	يُضيف سلسلة واحدة بلا اسم	self	لا يرمي	اختصار لسلسلة واحدة
LineChart::addSeries()	string $name، list<int|float> $values، ?ChartColor $color = null	لون null يُسنَد تلقائيًا من اللوحة حسب فهرس السلسلة	self	لا يرمي	اسم السلسلة محجوز لاستخدام وسيلة الإيضاح
LineChart::withAxisColor()	ChartColor $color	حدّ المحور؛ الافتراضي #333333	self	لا يرمي	—
LineChart::withLineWidth()	float $width	عرض حدّ السلسلة؛ الافتراضي 1.5	self	لا يرمي	—
LineChart::withFontSize()	float $size	حجم خط التسمية؛ الافتراضي 7.0	self	لا يرمي	—
LineChart::withDots()	bool $show، float $radius = 2.5	علامات نقاط البيانات؛ مُفعّلة افتراضيًا	self	لا يرمي	تُرسم العلامات كدوائر مُقرّبة بـ ⁨Bezier⁩
LineChart::withGrid()	bool $show	شبكة رُبيعية أفقية؛ مُفعّلة افتراضيًا	self	لا يرمي	—
LineChart::render()	ChartBox $box	شبكة، ومحاور، ومسار واحد لكل سلسلة، وتسميات	مُعامِلات string	لا يرمي؛ عدم وجود سلاسل يُعيد ''	السلسلة الأقصر من نقطتين لا ترسم مسارًا
PieChart::fromData()	list<string> $labels، list<int|float> $values	تُحسب النِّسب من مجموع القيم	self	لا يرمي	المُنشئ خاص
PieChart::withColors()	list<ChartColor> $colors	لون واحد لكل شريحة، بالترتيب	self	لا يرمي	المُدخلات الناقصة تعود إلى اللوحة
PieChart::withStrokeColor()	ChartColor $color	مُخطَّط الشريحة؛ الافتراضي أبيض	self	لا يرمي	—
PieChart::withFontSize()	float $size	حجم خط التسمية؛ الافتراضي 7.0	self	لا يرمي	—
PieChart::withPercentages()	bool $show	تسميات النِّسبة المئوية؛ مُفعّلة افتراضيًا	self	لا يرمي	تُصيَّر التسميات فقط على الشرائح التي تكتسح أكثر من 15 درجة
PieChart::withLegend()	bool $show	وسيلة إيضاح على اليمين؛ مُفعّلة افتراضيًا	self	لا يرمي	تحجز وسيلة الإيضاح 80 نقطة من عرض الصندوق
PieChart::render()	ChartBox $box	قطاعات، وتسميات اختيارية، ووسيلة إيضاح اختيارية	مُعامِلات string	لا يرمي؛ البيانات الفارغة أو مجموع عند الصفر أو دونه يُعيد ''	تنقسم الأقواس إلى قطع ⁨Bezier⁩ بحد أقصى 90 درجة
ChartBox::__construct()	float $x، float $y، float $width، float $height	أصل ⁨PDF⁩ أسفل اليسار، بالنقاط	—	لا يرمي	final readonly؛ الأبعاد غير مُتحقَّق منها
ChartBox::fromUserSpace()	float $x، float $y، float $width، float $height، float $pageHeight	يقلب مستطيلًا أصله أعلى اليسار إلى إحداثيات ⁨PDF⁩	self	لا يرمي	—
ChartBox::right()	لا شيء	x + width	float	لا يرمي	دالة، لا خاصية
ChartBox::top()	لا شيء	y + height	float	لا يرمي	دالة، لا خاصية
ChartBox::inset()	float $left، float $bottom، float $right، float $top	صندوق فرعي مُصغَّر بالمقادير المُعطاة	self	لا يرمي	المقادير المُفرطة تُنتج أبعادًا سالبة؛ غير مُتحقَّق منها
ChartColor::__construct()	float $r، float $g، float $b، كلٌّ 0.0–1.0	—	—	لا يرمي	final readonly؛ المُكوّنات غير مُقيَّدة
ChartColor::rgb()	int $r، int $g، int $b، كلٌّ 0–255	يُحجّم المُكوّنات إلى 0.0–1.0	self	لا يرمي	—
ChartColor::hex()	string $hex	يقبل ست خانات سِتّ عشرية مسبوقة بـ # أو مجرّدة	self	لا يرمي	الخانات النهائية الغائبة تُفكَّك كصفر
ChartColor::palette()	int $index	لوحة مدمجة من 12 لونًا	self	TypeError على فهرس سالب	الفهارس غير السالبة تلتف دوريًا بمقياس 12
ChartColor::strokeOperator()	لا شيء	مُعامِل لون الحدّ (RG)، ثلاث خانات عشرية	string	لا يرمي	دالة، لا خاصية
ChartColor::fillOperator()	لا شيء	مُعامِل لون التعبئة (rg)، ثلاث خانات عشرية	string	لا يرمي	دالة، لا خاصية

توقيعات نقطة الدخول

public static function fromData(array $labels, array $values): self
public function withBarColor(ChartColor $color): self
public function withAxisColor(ChartColor $color): self
public function withBarGap(float $gap): self
public function withFontSize(float $size): self
public function render(ChartBox $box): string

public static function create(array $labels): self
public static function fromData(array $labels, array $values): self
public function addSeries(string $name, array $values, ?ChartColor $color = null): self
public function withAxisColor(ChartColor $color): self
public function withLineWidth(float $width): self
public function withFontSize(float $size): self
public function withDots(bool $show, float $radius = 2.5): self
public function withGrid(bool $show): self
public function render(ChartBox $box): string

public static function fromData(array $labels, array $values): self
public function withColors(array $colors): self
public function withStrokeColor(ChartColor $color): self
public function withFontSize(float $size): self
public function withPercentages(bool $show): self
public function withLegend(bool $show): self
public function render(ChartBox $box): string

public function __construct(
    public float $x,
    public float $y,
    public float $width,
    public float $height,
)

public static function fromUserSpace(
    float $x,
    float $y,
    float $width,
    float $height,
    float $pageHeight,
): self

public function right(): float
public function top(): float
public function inset(float $left, float $bottom, float $right, float $top): self

public static function rgb(int $r, int $g, int $b): self
public static function hex(string $hex): self
public static function palette(int $index): self
public function strokeOperator(): string
public function fillOperator(): string

عقد السلوك

الشكل المشترك للمُصيِّر

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

التحجيم والتخطيط

تحجز المخطّطات الشريطية والخطّية مقدار رسم ثابتًا داخل الصندوق: 40 نقطة يسارًا، و20 أسفل، و10 يمينًا، و10 أعلى. تُحجّم منطقة الرسم المتبقّية القيم خطّيًا مقابل الحد الأقصى للسلسلة. الحد الأقصى الذي يساوي صفرًا أو دونه يُحجَّم مقابل 1.0 بدلًا من ذلك، فتُصيِّر البيانات الصفرية بالكامل المحاور بمحتوى مسطّح بدلًا من القسمة على صفر. يرسم كلاهما محورَي ⁨X⁩ و⁨Y⁩ بعرض ⁨0.5⁩ نقطة وخمس علامات قيمة عند المواضع الرُّبيعية. تُنسّق المخطّطات الشريطية قيم العلامات باللاحقتين K وM فوق الألف والمليون؛ وتطبع المخطّطات الخطّية أرقامًا عادية.

المخطّط الشريطي

تشغل كل قيمة فتحة متساوية عبر عرض الرسم. يملأ الشريط الفتحة ناقصًا نسبة الفجوة المُهيَّأة ويتوسّط الفتحة. تُرسم تسميات الفئات 12 نقطة أسفل منطقة الرسم.

المخطّط الخطّي

ترسم الشبكة، عند تفعيلها، أربعة خطوط رُبيعية أفقية باللون الرمادي الفاتح (0.85 0.85 0.85 RG) أسفل المحاور والسلاسل. ترسم كل سلسلة متعدّد خطوط واحدًا عبر نقاطها، ممتدًّا على كامل عرض الرسم. تُرسم العلامات الاختيارية كدوائر ⁨Bezier⁩ من أربع قطع عند كل نقطة بيانات. تعود ألوان السلاسل افتراضيًا إلى مُدخلات اللوحة المتتالية بترتيب الإدراج.

المخطّط الدائري

تُرتَّب الشرائح بترتيب البيانات، بدءًا من محور ⁨X⁩ الموجب واكتساحًا عكس عقارب الساعة. يُغلق مسار كل قطاع ويُطلى بتعبئة وحدّ مُدمجين (h B)؛ وتنقسم الأقواس إلى قطع ⁨Bezier⁩ بحد أقصى 90 درجة. تُقرّب تسميات النِّسبة المئوية إلى نسبة صحيحة وتُصيَّر فقط على الشرائح التي تكتسح أكثر من 15 درجة. تحجز وسيلة الإيضاح، عند تفعيلها، 80 نقطة من عرض الصندوق على اليمين وتُصيِّر عيّنة لونية بحجم 8 نقاط لكل مُدخل بارتفاع سطر 12 نقطة. نصف القطر هو نصف الأصغر من العرض المتبقّي وارتفاع الصندوق، ناقصًا هامش 10 نقاط.

كائنات قيمة التموضع واللون

ChartBox هو مستطيل غير قابل للتغيير بوحدات مستخدم ⁨PDF⁩ (نقاط) بأصل أسفل اليسار. يُحوّل ChartBox::fromUserSpace() مستطيلًا أصله أعلى اليسار بقلبه مقابل ارتفاع الصفحة المُعطى. يُعيد inset() صندوقًا جديدًا أصغر؛ وright() وtop() دالتا وصول. ChartColor مُكتفٍ ذاتيًا ولا يعتمد على فئات لون ⁨Core⁩. تُسنِد لوحته المؤلَّفة من 12 مُدخلًا ألوان السلاسل والشرائح عندما لا يُقدّم المُستدعي أيًّا.

مصفوفة الدعم (مدعومة بالأدلة)

لا يكسب نوع مخطّط أو ميزة وصف مُتحقَّق منه إلا عندما تُمارسه تثبيتة pro/tests/**. لا يحكم المخطّطاتِ أي معيار خارجي، فالدليل هو تغطية سلوكية على مستوى الوحدة.

نوع المخطّط / الميزة	الحالة	الدليل (مسار الاختبار)	الثقة	ملاحظات
المخطّط الشريطي — التصيير، والمحاور، ومستطيلات الأشرطة، وتقييد الفجوة، والبيانات الفارغة/الصفرية بالكامل، وتنسيق قيم ⁨K/M⁩	مُتحقَّق منه	pro/tests/Unit/Chart/BarChartTest.php؛ BarChartArithmeticCoverageTest.php؛ BarChartBoundaryCoverageTest.php	عالية	لفّ حالة الرسم، وخطوط المحاور، ونسب ارتفاع الأشرطة، وعدد العلامات، وحدود التنسيق مؤكَّدة.
المخطّط الخطّي — سلسلة واحدة ومتعدّدة، ومسار الخط، والمحاور، والنقاط، والشبكة، والنقطة الواحدة	مُتحقَّق منه	pro/tests/Unit/Chart/LineChartTest.php؛ LineChartCoverageTest.php؛ LineChartArithmeticCoverageTest.php؛ LineChartTypeCastCoverageTest.php	عالية	تغطية متعدّد السلاسل، والنقطة الواحدة بلا خط، والسلسلة الفارغة، ومسارات الشبكة والنقاط.
المخطّط الدائري — القطاعات، وتقطيع ⁨Bezier⁩، والنِّسب المئوية، ووسيلة الإيضاح، والمجموع الصفري/السالب	مُتحقَّق منه	pro/tests/Unit/Chart/PieChartTest.php؛ PieChartArithmeticCoverageTest.php؛ PieChartBoundaryCoverageTest.php	عالية	تغطية مسارات القطاعات، وأعداد القطع لكل اكتساح، وعتبة تسمية 15 درجة، وهندسة وسيلة الإيضاح، وسلوك السلسلة الفارغة.
ChartBox — تحويل الإحداثيات (فضاء المستخدم إلى ⁨PDF⁩)، وأعلى/أسفل الصفحة، والأبعاد الصفرية، والمقادير	مُتحقَّق منه	pro/tests/Unit/Chart/ChartBoxTest.php	عالية	التحويل من أصل أعلى اليسار إلى أصل أسفل اليسار عند أعلى الصفحة وأسفلها وحواف البُعد الصفري.
ChartColor — تحجيم ⁨RGB⁩، وتحليل السِّتّ عشري، واللوحة، ومُعامِلات الحدّ/التعبئة	مُتحقَّق منه	pro/tests/Unit/Chart/ChartColorTest.php	عالية	التحجيم من 0–255 إلى 0–1، والسِّتّ عشري المسبوق بـ # والمجرّد، والحالة المختلطة، والتفاف اللوحة بعد 12 مُدخلًا.
تصليب الانحدار عبر المُصيِّرات	مُتحقَّق منه	pro/tests/Unit/Chart/ChartCoverageTest.php	عالية	مجموعة انحدار مشتركة عبر المُصيِّرات الثلاثة إضافةً إلى حسابيات تنسيق القيم.
أنواع المخطّطات ما عدا الشريطي/الخطّي/الدائري (المساحي، والمبعثر، والمكدّس، والحلقي، إلخ)	غير مدعوم	—	عالية	لا يُشحن أي مُصيِّر. سطح الوحدة هو بالضبط الشريطي والخطّي والدائري. مذكور بصدق: هذا ليس «كل نوع مخطّط».

عدّ صادق: 6 صفوف مُتحقَّق منها، و0 مُدَّعاة، و1 غير مدعوم (أي نوع مخطّط غير الشريطي والخطّي والدائري).

الحالات الحدّية وأنماط الإخفاق

• لا يرمي أي مُصيِّر على البيانات. المُدخل المُنحلّ يتدهور إلى سلسلة فارغة: بيانات شريطية أو خطّية فارغة، وقائمة سلاسل فارغة، ومجموع دائري عند الصفر أو دونه، كلها تُعيد ''.
• سلسلة خطّية بأقل من نقطتين لا ترسم مسارًا ولا علامات؛ ومع ذلك تُصيَّر المحاور والتسميات.
• قيم الأشرطة السالبة غير مرفوضة؛ ويمتدّ مستطيل الشريط أسفل محور ⁨X⁩.
• عددا التسميات والقيم غير مُتحقَّق منهما تقاطُعيًا. يُقدّم المُستدعي قوائم بأطوال متطابقة.
• يُقبل ChartBox بأبعاد صفرية أو سالبة ويُنتج مخرجات مُنحلّة؛ على المُستدعين تحديد حجم الصندوق.
• لا تقصّ المُصيِّرات. يمكن لمخطّط مُفرط الحجم، أو تسميات فئاته أسفل الرسم، أو وسيلة إيضاح طويلة أن تفيض عن منطقة الصفحة المقصودة.
• صفحة تفتقر إلى خط باسم مورد خط المخطّط تترك مُعامِلات النص تشير إلى مورد غير مُعرَّف؛ وسلوك العارض عندئذٍ غير مُعرَّف.
• ChartColor::hex() لا يُجري أي تحقّق؛ المُدخل الأقصر من ست خانات يُفكِّك المُكوّنات الغائبة كصفر. يفشل ChartColor::palette() بـ TypeError على فهرس سالب، لأن باقي القسمة السالب في ⁨PHP⁩ لا يحلّ أي مفتاح لوحة.
• لا تُجري الوحدة أي تعمية؛ ووضع ⁨FIPS⁩ لا سلوك خاصًّا بالمخطّطات له.

المطابقة

تبعث وحدة ⁨Chart⁩ مُعامِلات تدفّق محتوى ⁨PDF⁩. لا يحكم مخرجاتِها أي معيار مخطّطات أو ترميز رموز أو تعمية خارجي، فسطح المطابقة الوحيد هو تدفّق المُعامِلات المبعوث.

الادّعاء	المعيار	البند
تتبع الرسوميات المبعوثة نموذج مُعامِل تدفّق المحتوى؛ وتتداخل المخرجات داخل حالة رسم محفوظة ومُستعادة.	ISO 32000-2	§8.1
الأشرطة والخطوط والقطاعات والعلامات كائنات مسار: يبدأ الإنشاء بـ m أو re ويختتم بمُعامِل طلاء مسار.	ISO 32000-2	§8.5.2
تُصيَّر التسميات ككائنات نص: يُحدَّد الموضع بعد BT، وتُطلى المحارف بمُعامِل إظهار النص Tj.	ISO 32000-2	§9.2.2, §9.4.3

كل البنود مُعاد صياغتها؛ ولا تُعيد هذه الصفحة إنتاج أي نص معياري. هذه بيانات قدرة، لا شهادات؛ ⁨NextPDF⁩ لا تحمل أي شهادة ولا تمنح أيًّا. يعتمد التصيير الصحيح للتدفّق أيضًا على كون المستند المُحيط سليم التكوين، وهو مسؤولية كاتب المستند.

ملاحظات التطوير

• تحمل الفئات الخمس جميعها @since 1.9.0 وهي حالية في nextpdf/pro 3.1.0.
• الوحدة مُكتفية ذاتيًا: تعتمد المُصيِّرات على ChartBox وChartColor فقط، بلا اقتران بـ ⁨Core⁩.
• تُبقي المخرجات الحتمية المستنداتِ المُخطَّطة قابلة لإعادة الإنتاج، ومستقرّة على الفروق، وآمنة للتوقيع أو الأرشفة.
• سجّل خطًا باسم مورد خط المخطّط مرة واحدة لكل صفحة تستضيف مخطّطات.
• أعد استخدام مُصيِّر مُهيَّأ عبر الصناديق بحرّية؛ render() لا يُجري أي تحوير للحالة.
• يعيش دليل الاختبار تحت pro/tests/Unit/Chart/؛ وتربط مصفوفة الدعم كل صف مُتحقَّق منه بمجموعته.

حدود النشر

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

انظر أيضًا

• Chart (القدرة) — نظرة عامة موجّهة نحو المهام، والتثبيت، وعيّنات الكود.
• Barcode — مرجع متعمّق — سطح الرسم الشقيق في ⁨Pro⁩ بمصفوفة دعمه المدعومة بالأدلة الخاصة به.