Pro รุ่น

Chart

ภาพรวมโดยสังเขป

NextPDF Pro เรนเดอร์แผนภูมิแท่ง เส้น และวงกลมลงในหน้า PDF โดยตรงในรูปของตัวดำเนินการเนื้อหาแบบเวกเตอร์ ไม่มีขั้นตอนการแรสเตอร์และไม่มีการพึ่งพา headless browser ดังนั้นผลลัพธ์จึงเป็นแบบกำหนดได้แน่นอนและทำซ้ำได้

การติดตั้ง

composer require nextpdf/pro:^3

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

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

แผนภูมิแท่ง แผนภูมิแท่งแนวตั้งที่กำหนดค่าสีแท่ง สีแกน ระยะห่างระหว่างแท่ง และขนาดฟอนต์ของป้ายกำกับได้
แผนภูมิเส้น แผนภูมิเส้นแบบชุดข้อมูลเดียวหรือหลายชุด พร้อมสีต่อชุดข้อมูล ตัวทำเครื่องหมายจุดข้อมูลที่เลือกได้ เส้นกริดที่เลือกได้ และความกว้างเส้นที่กำหนดค่าได้
แผนภูมิวงกลม แผนภูมิวงกลมพร้อมการกำหนดจานสีอัตโนมัติ ป้ายกำกับเปอร์เซ็นต์ที่เลือกได้ และคำอธิบายสัญลักษณ์ที่เลือกได้

ตัวเรนเดอร์ทุกตัวมีรูปแบบเดียวกัน ได้แก่ แฟกทอรี fromData(...) การกำหนดค่าแบบ fluent with*() และการเรียก render(ChartBox $box): string ที่คืนค่าตัวดำเนินการสตรีมเนื้อหา PDF ผลลัพธ์เป็นแบบกำหนดได้แน่นอน คืออินพุตและการกำหนดค่าเดียวกันจะให้ตัวดำเนินการชุดเดียวกัน ซึ่งทำให้เอกสารที่มีแผนภูมิทำซ้ำได้และปลอดภัยต่อการลงนามหรือจัดเก็บถาวร

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

เหตุใดจึงทำงานเช่นนี้

การตัดสินใจที่สำคัญที่สุดคือการปล่อยตัวดำเนินการเวกเตอร์ PDF เนทีฟแทนที่จะแรสเตอร์ภาพหรือขับเคลื่อน headless browser การเลือกนี้ทำให้ผลลัพธ์เป็นแบบกำหนดได้แน่นอน คือข้อมูลและการกำหนดค่าเดียวกันจะให้ตัวดำเนินการที่เหมือนกันทุกไบต์เสมอ ตัวดำเนินการแบบกำหนดได้แน่นอนทำให้เอกสารที่มีแผนภูมิทำซ้ำได้ จึงปลอดภัยต่อการลงนามหรือจัดเก็บถาวร การหลีกเลี่ยงตัวเรนเดอร์ภายนอกยังขจัดการพึ่งพากระบวนการ ดังนั้นปริมาณงานจึงปรับขนาดตามจุดข้อมูลแทนที่จะเป็นต้นทุนการเริ่มต้นของเบราว์เซอร์ ตัวเรนเดอร์แต่ละตัวห่อหุ้มตัวดำเนินการไว้ในคู่สถานะกราฟิก 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() พร้อมตัวปล่อยตัวดำเนินการ stroke/fill

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

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 สาธารณะที่รองรับเท่านั้น เส้นทางเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต