กำหนดสไตล์ HTML ด้วย CSS

ภาพรวมโดยย่อ

สูตรนี้แสดงการใช้ Cascading Style Sheets (CSS) กับเนื้อหา Hypertext Markup Language (HTML) ผ่านแอตทริบิวต์ style แบบอินไลน์และบล็อก <style> รวมถึงวิธีตรวจสอบว่าคุณสมบัตินั้นผ่านการยืนยันแล้วก่อนจะพึ่งพาคุณสมบัตินั้น

การติดตั้ง

composer require nextpdf/core:^3

ใช้ข้อจำกัดเวอร์ชันนี้กับแพ็กเกจ nextpdf/core ตัวอย่างนี้ทำงานบน PHP 8.4

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

เอนจิน HTML คำนวณสไตล์ผ่านการเรียงซ้อนของ CSS การเรียงซ้อนกำหนดว่าสไตล์ใดมีผลเมื่อกฎหลายรายการกำหนดเป้าหมายไปยังองค์ประกอบเดียวกัน เอนจินอ่านบล็อก <style> ในอินพุตก่อน จากนั้นจึงอ่านแอตทริบิวต์ style แบบอินไลน์ แล้วจับคู่ทั้งสองกับองค์ประกอบและคำนวณผลลัพธ์ตามลำดับการเรียงซ้อน เมทริกซ์การรองรับจัดระดับโมดูล CSS Cascading and Inheritance เป็น Verified ซึ่งหมายความว่ามีชุดฟิกซ์เจอร์เฉพาะครอบคลุมพฤติกรรมของการเรียงซ้อนและการสืบทอด

คุณสมบัติสำหรับการแสดงผลข้อความ เช่น text-align text-indent และ letter-spacing ถูกกำหนดไว้ในตารางคุณสมบัติของโมดูล CSS Text ของ World Wide Web Consortium (W3C) (W3C CSS Text Level 3) การเลือกฟอนต์ใช้โมเดล CSS Fonts รูปแบบย่อ font กำหนด font-style font-variant font-weight font-size และ font-family พร้อมกัน (W3C CSS Fonts Level 3)

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

พื้นผิว API

คุณกำหนดสไตล์ผ่าน HTML ที่ส่งไปยัง writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput) ไม่มี application programming interface (API) แยกต่างหากสำหรับ CSS การเรียงซ้อนทำงานภายใน ตาราง PHPDoc ฉบับเต็มถูกสร้างขึ้นจากซอร์ส

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

$doc->writeHtml(
    '<style>.lead { color: #1E3A8A; text-align: center; }</style>'
    . '<p class="lead">Styled with a style block.</p>'
);

$doc->save(__DIR__ . '/out.pdf');

ตัวอย่างโค้ด — ระดับใช้งานจริง

ตัวอย่างแบบครบในตัวนี้สามารถรันในฮาร์เนสได้ โดยใช้บล็อก <style> ตัวเลือกแบบคลาส สไตล์แบบอินไลน์ และเส้นทาง font สำหรับตระกูลและน้ำหนัก

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('CSS Styling');
$doc->addPage();

$html = <<<'HTML'
<style>
    h1        { color: #1E3A8A; }
    .lead     { color: #D97706; font-size: 14px; }
    .callout  { background-color: #EFF6FF; padding: 8px; border: 1px solid #BFDBFE; }
    .centered { text-align: center; }
</style>

<h1>Styling HTML with CSS</h1>

<p class="lead">This paragraph is styled through a class selector in a
style block.</p>

<p class="callout">This paragraph has a background, padding, and a border
from a class selector.</p>

<p class="centered" style="font-weight: bold;">Centered, with an inline
override for weight.</p>

<p style="color: #6B7280; font-size: 9px;">Inline style only.</p>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/style-with-css.pdf');

echo "Wrote style-with-css.pdf\n";

เอาต์พุตมาตรฐาน (STDOUT) ที่คาดว่าจะได้:

Wrote style-with-css.pdf

กรณีขอบและข้อควรระวัง

• ลำดับการเรียงซ้อน ในการเรียงซ้อน style แบบอินไลน์จะมีผลเหนือกว่าตัวเลือกในบล็อก <style> ที่มีความจำเพาะเท่ากัน หากคุณเห็นสีที่ไม่คาดคิด ให้ตรวจสอบการแทนที่แบบอินไลน์ก่อน
• Claimed เทียบกับ Verified text-align text-indent และ color ถูกจัดระดับเป็น “Claimed” ในเมทริกซ์ คุณสมบัติเหล่านี้ถูกนำไปใช้งานแล้ว แต่ไม่มีฟิกซ์เจอร์ของโมดูลเฉพาะ คุณสมบัติเหล่านี้แสดงผลได้ แต่คุณควรตรวจสอบผลลัพธ์ด้านภาพก่อนอนุมัติให้นำไปใช้จริง
• ไม่มีการเก็บแผนผัง เอนจินแบบสตรีมมิงตามที่อธิบายไว้ใน Architecture Decision Record (ADR-001) ไม่เก็บแผนผังเอกสาร จึงไม่สามารถใช้ตัวเลือกที่ให้องค์ประกอบพี่น้องลำดับถัดไปย้อนกลับไปจัดสไตล์องค์ประกอบก่อนหน้าใหม่ได้ ผลที่ตามมาคือ ตัวเลือกที่ไม่ขึ้นกับลำดับจะมีข้อจำกัด
• คุณสมบัติที่ไม่รองรับ คุณสมบัติที่ไม่รองรับจะถูกละเว้น ไม่ใช่ทำให้เกิดข้อผิดพลาด ให้ตรวจสอบเมทริกซ์ก่อนพึ่งพาคุณสมบัตินั้น
• ปริภูมิสี ค่า Lab, LCH และ OKLab สามารถแยกวิเคราะห์ได้ แต่ความเที่ยงตรงของปริภูมิสีของ Portable Document Format (PDF) สำหรับฟังก์ชันเหล่านั้นไม่ได้รับการยืนยัน (เมทริกซ์: “Claimed” สำหรับ CSS Color 4)

ประสิทธิภาพ

การคำนวณการเรียงซ้อนเกิดขึ้นในรอบการประมวลผลเดียว ต้นทุนยังคงเป็นเชิงเส้นตามจำนวนโทเค็น O(n) งบประมาณคือ wall_ms: 1500, peak_mb: 96 บล็อก <style> เพิ่มต้นทุนการแยกวิเคราะห์ตัวเลือกครั้งเดียวซึ่งเป็นสัดส่วนกับจำนวนกฎ

ข้อความตัดตอนจากเมทริกซ์การรองรับ CSS (เฉพาะแถว Verified)

ข้อความตัดตอนนี้แสดงเฉพาะแถว Verified จากเมทริกซ์การรองรับ CSSที่ตรวจสอบความถูกต้องแล้ว

โมดูล W3C	ระดับ	สถานะ	หลักฐาน
CSS Cascading and Inheritance (css_cascade_3)	3	Verified	src/Html/Cascade/, tests/Unit/Html/Cascade/
CSS Cascading (css_cascade_4)	4	Verified	Cascade/Layer/ + ชุดทดสอบ revert/layer
CSS Cascading (css_cascade_5)	5	Verified	AtRule/Layer/ + Cascade/Layer/ ชุดทดสอบ
CSS Fonts (css_fonts_3)	3	Verified	src/Html/Font/, tests/Unit/Font/ + การทดสอบ FontResolver
CSS Fonts (css_fonts_4)	4	Verified	src/Html/FontFace/, tests/Unit/Html/FontFace/

text-align, text-indent, color และ background-color เป็น “Claimed” ในเมทริกซ์ ตารางนี้จึงตั้งใจละเว้นคุณสมบัติเหล่านี้ออกจากแถว Verified

ข้อจำกัดของการสตรีมแบบรอบเดียว (ADR-001)

การเรียงซ้อนทำงานบนรายการโทเค็นแบบสตรีมโดยไม่มี Document Object Model (DOM) ดังนั้นตัวเลือกจึงถูกคำนวณเทียบกับบริบทตามลำดับเอกสาร กรณีตัวเลือกที่ต้องอาศัยทั้งแผนผังมีข้อจำกัดตาม ADR-006 ให้เขียน CSS ที่พึ่งพาเฉพาะลำดับเอกสารและบริบทของบรรพบุรุษเท่านั้น

สัญญาของเลเยอร์ (ADR-010)

การแยกวิเคราะห์ CSS เป็นหน้าที่ของเลเยอร์การเรียงซ้อน และการส่งงานไปยังเค้าโครงต้องไม่อ่านค่า $css[...] ดิบโดยตรง พื้นผิวสาธารณะคืออินพุต HTML ไม่มีวิธีที่รองรับในการแทรกสไตล์ที่คำนวณแล้วโดยตรงจากการเรียงซ้อน

งบประมาณหน่วยความจำสำหรับเอกสารขนาดใหญ่

การเรียงซ้อนเก็บชุดกฎที่ใช้งานอยู่และสแตกสไตล์แบบ push และ pop ไม่ใช่แผนผังโหนด บริบทที่ถูกกำหนดขอบเขตไว้ที่ระดับคอนเทนเนอร์เป็นไปตามงบประมาณ ADR-020 (5,000 โหนดต่อบริบท เพดานการใช้งาน 50 MB) สไตล์ชีตขนาดใหญ่ทำให้หน่วยความจำของชุดกฎเพิ่มขึ้นเชิงเส้น ดังนั้นให้จำกัดจำนวนตัวเลือกไว้

หมายเหตุด้านความปลอดภัย

CSS ใน HTML ที่ไม่น่าเชื่อถือไม่สามารถรันโค้ดได้ แต่สามารถส่งผลต่อเค้าโครงและการอ้างอิงทรัพยากร เช่น background-image โดยค่าเริ่มต้น นโยบายทรัพยากรภายนอกจะไม่ดึง URL ระยะไกลโดยพลการ ให้ทำความสะอาด HTML และ CSS ทั้งหมดที่คุณประกอบจากอินพุตของผู้ใช้ก่อนเรนเดอร์

ความสอดคล้อง

ข้อความระบุ	ข้อกำหนด	อนุประโยค	รหัสอ้างอิง (reference_id)
คุณสมบัติข้อความ (text-align, text-indent, letter-spacing) ถูกกำหนดโดยตารางคุณสมบัติ CSS Text	W3C CSS Text Level 3	css_text_3#x1.x24
รูปแบบย่อ font กำหนด font-style, font-variant, font-weight, font-size และ font-family	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

สูตรนี้แสดงวิธีที่ NextPDF ใช้ชุดย่อย CSS ที่รองรับ ไม่ใช่การยืนยันการรองรับ CSS อย่างสมบูรณ์ สำหรับสถานะที่ผ่านการยืนยันในแต่ละโมดูล โปรดดูเมทริกซ์การรองรับ CSS

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง

ดูเพิ่มเติม

• เรนเดอร์ HTML เป็นหน้า PDF
• จัดวางตาราง HTML
• เมทริกซ์การรองรับ CSS