จากฟอร์มที่กรอกได้สู่บันทึกที่ตรึงไว้: การกรอกและ flatten AcroForm

SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7

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

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

เหตุใดเรื่องนี้จึงสำคัญ

ช่องว่างระหว่าง “สิ่งที่ฉันกรอก” กับ “สิ่งที่คุณเห็น” คือจุดที่ฟอร์มผิดพลาด

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

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

ฉบับย่อ

• AcroForm คือฟอร์มแบบโต้ตอบของเอกสาร: ต้นไม้ของฟิลด์ที่ระบุชนิดซึ่งประกาศไว้ใน catalogue (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7)
• แต่ละฟิลด์ถูกทำให้มองเห็นได้ด้วย widget annotation — สี่เหลี่ยมบนหน้าที่คุณคลิกหรือพิมพ์ลงไป (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5)
• NextPDF มาพร้อมตัวสร้างที่ระบุชนิดสำหรับตัวควบคุมฟอร์มที่ไม่ใช่ลายเซ็นทุกตัวที่รองรับ — text, checkbox, radio, list box และ combo box (choice) และ push button — รวมถึงตัวจัดการฟิลด์ที่เขียนมันเป็นอ็อบเจกต์ PDF ที่ถูกต้อง
• การ flatten เรนเดอร์ค่าของแต่ละฟิลด์ลงในสตรีมเนื้อหาของหน้า และนำฟอร์มแบบโต้ตอบที่ไม่จำเป็นแล้วออกไป เหลือไว้เป็นบันทึกที่ตรึงไว้
• หากคุณขอ flatten เอกสารที่ ไม่มีหน้า NextPDF จะไม่ทำลายค่าฟิลด์ของคุณอย่างเงียบๆ มันรักษาฟอร์มไว้ เตือนคุณ และให้คุณเพิ่มหน้าแล้ว flatten อย่างถูกต้อง

NextPDF จัดการเรื่องนี้อย่างไร

โมเดลทางความคิดคือสองชั้น ฟิลด์ คือข้อมูล: ชื่อ ชนิด ค่า และชุดของแฟล็ก widget คือภาพ: สี่เหลี่ยมบนหน้าที่เฉพาะเจาะจงที่ให้โปรแกรมอ่านโต้ตอบกับฟิลด์ (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5) ฟิลด์หนึ่งสามารถปรากฏผ่านหลาย widget ได้ด้วยซ้ำ — นั่นคือวิธีที่ radio group ทำงานพอดี: ตัวเลือกบนหน้าหลายตัวที่ต่อสายเข้ากับค่าเบื้องล่างค่าเดียว

NextPDF ให้ตัวสร้างที่ระบุชนิดของตัวเองแก่ฟิลด์แต่ละชนิด ดังนั้นคุณจึงไม่ต้องประกอบ dictionary ดิบด้วยมือ ชนิดพกรายละเอียดที่ถูกต้องตาม PDF มาให้คุณ checkbox, radio button และ push button ล้วนใช้ชนิดฟอร์มเบื้องล่างเดียวกันในข้อกำหนดและถูกแยกแยะด้วยแฟล็กของมัน เอนจินตั้งแฟล็กเหล่านั้นจากชนิดที่คุณเลือก แทนที่จะขอให้คุณจำว่าบิตไหนหมายถึง “radio” list box และ combo box ต่างก็เป็นฟิลด์ choice อีกครั้ง ตัวสร้างเลือกการเข้ารหัสที่ถูกต้องเอง คุณระบุชนิดฟิลด์ครั้งเดียว เป็นถ้อยคำ แล้วไบต์ก็ตามมา

การ flatten คือครึ่งที่สอง ตัว flatten จัดกลุ่ม widget annotation ตามหน้าที่มันเป็นเจ้าของ โดยใช้สี่เหลี่ยมของแต่ละ widget สำหรับการจัดวางบนหน้านั้น จากนั้นเรนเดอร์แต่ละค่าเป็นชุดสั้นๆของโอเปอเรเตอร์ในสตรีมเนื้อหา — ตั้งสี ตั้งตำแหน่งข้อความ วาด glyph — ต่อท้ายเข้ากับเนื้อหาที่มีอยู่ของหน้านั้น (SpecSpec: ISO 32000-2, §8.4ISO 32000-2 §8.4) ค่าเลิกเป็นฟิลด์ที่มีชีวิตและกลายเป็นหมึกที่วาดลงไป เนื่องจากฟอร์มไม่มีฟิลด์แบบโต้ตอบใดๆอีก เอนจินจึงนำรายการ AcroForm ออก: ไม่มีอะไรเหลือให้โต้ตอบด้วยแล้ว

1. Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
2. Place the widgetsEach field is drawn as a widget annotation — a rectangle on a chosen page that a viewer can type into, tick, or pick from.
3. Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
4. Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
5. Drop the interactive formWith every value baked in, remove the AcroForm so nothing remains editable — a frozen record of what was agreed.

From a fillable form to a frozen record: declare typed fields, draw their on-page widgets, fill in values, then flatten those values into immutable page graphics and drop the now-empty interactive form.

ตัวอย่างเชิงปฏิบัติ

ฟอร์มเล็กๆที่เป็นตัวแทน: สร้างฟิลด์ที่ระบุชนิดไม่กี่ตัว แล้ว flatten มันให้เป็นบันทึกที่ตรึงไว้

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

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

// Typed builders, called straight on the document. You pick the field
// type by choosing its builder method — textField, checkBox, comboBox —
// and you pass the value to freeze at creation time. The engine writes
// the spec-correct PDF type and flags for you.
$document->textField('full_name', x: 40, y: 700, w: 220, h: 18, default: 'Ada Lovelace');
$document->checkBox('agree_terms', x: 40, y: 660, size: 14, checked: true);
$document->comboBox(
    'plan',
    x: 40,
    y: 620,
    w: 160,
    h: 18,
    items: ['Starter', 'Team', 'Enterprise'],
    selected: 'Team',
);

// Flatten: the values become immutable page graphics and the
// interactive AcroForm is dropped. The result is a frozen record.
$document->flattenForms();

$bytes = $document->getPdfData();

ก่อน flattenForms() นี่คือฟอร์มที่กรอกได้ หลังจากนั้น ค่าเดียวกันถูกพิมพ์ลงในหน้าและไม่มีฟิลด์เหลือให้เปลี่ยน คุณเลือกชนิดฟิลด์ด้วยการเลือกเมธอดตัวสร้างของมัน — textField, checkBox, comboBox — ดังนั้นชนิดที่ผิดจึงไม่อาจถูกเข้ารหัสเป็นสตริงหลวมๆได้: การพิมพ์ผิดคือการเรียกเมธอดที่ไม่มีอยู่ ซึ่งถูกจับได้ก่อนที่จะมีการเขียนฟิลด์ใด ไม่ใช่ฟิลด์ที่ผิดอย่างเงียบๆ นั่นคือจุดยืนปฏิเสธที่จะเดาเดียวกันที่ส่วนที่เหลือของเอนจินยึดถือ ดู API ที่ปฏิเสธจะเดา

ความเข้าใจผิดที่พบบ่อย

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

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

Human-factors note:Human-factors note

There is one operability nuance worth knowing. If you ask the engine to flatten a document that has no pages, it does not silently bin your field values. There is no page surface to paint them onto, so instead of stripping the interactive form and nulling its values — a total, invisible data loss — NextPDF preserves the form, keeps every value intact and still interactive, and surfaces a warning telling you what happened. You add a page and flatten again. This is a deliberate no-data-loss design: the engine would rather hand back a still-fillable document and a clear warning than a quietly emptied one. The values you were trusted with are the one thing a flatten must never throw away.

ขีดจำกัดและขอบเขต

การรองรับฟอร์มของ NextPDF เป็นคอร์เต็มรูปแบบ: ตัวสร้างที่ระบุชนิดสำหรับตัวควบคุมฟิลด์แบบโต้ตอบที่พบบ่อย ตัว flatten ฟอร์ม และตัวจัดการฟิลด์ที่เขียนฟิลด์เป็นอ็อบเจกต์ PDF ที่ถูกต้อง หน้านี้อธิบายพื้นผิวคอร์นั้น

AcroForm fields and flattening — edition availability

Edition	Availability
Core	○ Typed builders for text, checkbox, radio, choice (list box and combo box), and push-button fields; widget placement; a field manager; and a form flattener that bakes values into page graphics. Available in every edition.
Pro	○Not in this edition
Enterprise	○Not in this edition

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

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

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

เอกสารที่เกี่ยวข้อง

• สิ่งที่ทำให้ PDF เข้าถึงได้ — ฟิลด์ฟอร์มที่ติดแท็กและชื่อที่เข้าถึงได้ สำหรับขั้นที่กรอกได้
• API ที่ปฏิเสธจะเดา — เหตุใดชนิดฟิลด์จึงเป็น enum ที่ระบุชนิด ไม่ใช่สตริงที่เอนจินต้องตีความ
• กายวิภาคของไฟล์ PDF — ตำแหน่งที่ catalogue, หน้า และ annotation ที่ฟอร์มถูกสร้างขึ้นจากนั้นอยู่จริง
• วิธีที่ลายเซ็นอยู่ใน PDF — วิธีทำให้บันทึกที่ตรึงไว้ พิสูจน์ได้ ว่าเป็นฉบับที่ตกลงกัน

อภิธานศัพท์

• AcroForm — ฟอร์มแบบโต้ตอบของ PDF: ต้นไม้ของฟิลด์ที่ระบุชนิดซึ่งประกาศไว้ใน document catalogue ที่ทำให้ไฟล์กรอกได้ (SpecSpec: ISO 32000-2, §12.7ISO 32000-2 §12.7)
• Field — ด้านข้อมูลของตัวควบคุมฟอร์ม: ชื่อ ชนิด ค่า และแฟล็ก เป็นอิสระจากรูปลักษณ์บนหน้า
• Widget annotation — สี่เหลี่ยมที่มองเห็นและคลิกได้บนหน้าซึ่งโปรแกรมอ่านโต้ตอบกับฟิลด์ผ่านมัน (SpecSpec: ISO 32000-2, §12.5ISO 32000-2 §12.5) ฟิลด์หนึ่งอาจมีหลายตัว
• Choice field — ฟิลด์ที่เสนอชุดของตัวเลือก: list box แสดงตัวเลือกแบบเปิด ส่วน combo box แสดงแบบดร็อปดาวน์ ทั้งสองเป็นชนิดฟิลด์ PDF เดียวกัน
• Flatten — การเรนเดอร์ค่าปัจจุบันของแต่ละฟิลด์ลงในหน้าในฐานะกราฟิกที่เปลี่ยนแปลงไม่ได้ และนำฟอร์มแบบโต้ตอบออก เกิดเป็นบันทึกที่ตรึงไว้
• Frozen record — เอกสารที่ flatten แล้ว: มันแสดงสิ่งตายตัวสิ่งเดียวในโปรแกรมอ่านทุกตัวและไม่มีฟิลด์เหลือให้แก้ไข