Từ form điền được tới bản ghi đông cứng: điền và làm phẳng AcroForm

Spec: ISO 32000-2, §12.7

Tổng quan nhanh

Một form PDF có hai cuộc đời. Đầu tiên nó điền được: một tập các trường có gán kiểu mà một người gõ vào, tích vào, hoặc chọn từ đó. Rồi, khi thỏa thuận được lập, nó trở thành một bản ghi đông cứng: các giá trị được in vào chính trang để mọi trình đọc, trên mọi thiết bị, đều thấy đúng những gì đã được thỏa thuận. NextPDF dựng cái thứ nhất và tạo ra cái thứ hai, với một bảo đảm có chủ ý — nó sẽ không lặng lẽ vứt bỏ các giá trị trên đường vượt qua.

Vì sao điều này quan trọng

Khoảng cách giữa “thứ tôi đã điền” và “thứ bạn thấy” là nơi các form đi sai.

Một trường điền được, về mặt kỹ thuật, là một widget tương tác nhỏ được vẽ phủ lên trang. Các trình đọc khác nhau có thể hiển thị nó khác nhau. Một số tôn trọng một giá trị đã lưu, một số tái tạo dáng vẻ từ một font bạn không có, một số cho một người đọc sửa lại nó. Với một bản nháp mà bạn muốn cộng tác viên tiếp tục biên tập, đó chính là điểm mấu chốt. Với bản đã ký của những gì đã được thỏa thuận, nó là một mối nguy: bản ghi không nên phụ thuộc vào ứng dụng nào mở nó, và nó không nên sửa được sau khi đã rồi.

Làm phẳng khép lại khoảng cách. Nó lấy giá trị hiện thời của mỗi trường và in nó vào trang như đồ họa thông thường, bất biến — cùng loại nội dung như một tiêu đề hay một logo. Sau đó, không còn trường nào để sửa và không còn dáng vẻ nào để tái tạo. Tài liệu hiển thị một thứ, cùng một thứ, ở khắp mọi nơi.

Tóm tắt ngắn gọn

Một AcroForm là form tương tác của tài liệu: một cây các trường có gán kiểu được khai báo trong catalogue (Spec: ISO 32000-2, §12.7).
Mỗi trường được làm cho thấy được bởi một widget annotation — hình chữ nhật trên trang mà bạn nhấp vào hoặc gõ vào (Spec: ISO 32000-2, §12.5).
NextPDF cung cấp các bộ dựng có gán kiểu cho mọi control form không-chữ-ký được hỗ trợ — text, checkbox, radio, list box và combo box (choice), và push button — cộng với một field manager ghi chúng dưới dạng các đối tượng PDF đúng quy cách.
Làm phẳng hiển thị giá trị của mỗi trường vào content stream của trang và loại bỏ form tương tác giờ-đã-thừa, để lại một bản ghi đông cứng.
Nếu bạn yêu cầu làm phẳng một tài liệu không có trang nào, NextPDF không lặng lẽ hủy hoại các giá trị trường của bạn. Nó giữ nguyên form, cảnh báo bạn, và cho bạn thêm một trang rồi làm phẳng cho đúng.

NextPDF tiếp cận điều này như thế nào

Mô hình tư duy là hai tầng. Trường là dữ liệu: một cái tên, một kiểu, một giá trị, và một tập các cờ. Widget là bức tranh: một hình chữ nhật trên một trang cụ thể cho phép một trình đọc tương tác với trường (Spec: ISO 32000-2, §12.5). Một trường thậm chí có thể hiện ra qua nhiều widget — đó chính xác là cách một nhóm radio hoạt động, vài lựa chọn trên trang nối dây vào một giá trị nền tảng duy nhất.

NextPDF cho mỗi kiểu trường một bộ dựng có gán kiểu của riêng nó, nên bạn không bao giờ lắp ráp một dictionary thô bằng tay. Kiểu mang theo các chi tiết PDF-đúng giúp bạn. Một checkbox, một radio button, và một push button đều chia sẻ cùng một kiểu form nền tảng trong spec và được phân biệt nhờ các cờ của chúng; engine đặt các cờ đó từ kiểu bạn đã chọn, thay vì bắt bạn nhớ bit nào nghĩa là “radio”. Một list box và một combo box đều là trường choice; lần nữa, bộ dựng chọn đúng cách mã hóa. Bạn nêu kiểu trường một lần, bằng lời, và các byte đi theo sau.

Làm phẳng là nửa thứ hai. Bộ làm phẳng gom các widget annotation theo trang sở hữu của chúng, dùng hình chữ nhật của mỗi widget để đặt vị trí trên trang đó, rồi hiển thị mỗi giá trị thành một đoạn nhỏ các content-stream operator — đặt một màu, đặt một vị trí văn bản, vẽ các glyph — được nối thêm vào content sẵn có của trang đó (Spec: ISO 32000-2, §8.4). Giá trị thôi không còn là một trường sống và trở thành mực đã in. Vì form không còn mang bất kỳ trường tương tác nào, engine sau đó loại bỏ mục AcroForm: không còn gì để tương tác nữa.

Declare typed fieldsAdd text, checkbox, radio, choice, and button fields through their typed builders; the engine sets the spec-correct PDF type and flags.
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.
Collect inputShip it fillable: a reader supplies values, or your code sets them, leaving a filled but still-editable document.
Flatten the valuesRender each field's value into the page content stream as graphics; the painted value is now immutable.
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.

Ví dụ thực tế

Một form nhỏ, tiêu biểu: dựng một vài trường có gán kiểu, rồi làm phẳng nó thành một bản ghi đông cứng.

<?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();

Trước flattenForms(), đây là một form điền được. Sau nó, cùng các giá trị đó được in vào trang và không còn trường nào để thay đổi. Bạn chọn kiểu trường bằng cách chọn phương thức bộ dựng của nó — textField, checkBox, comboBox — nên một kiểu sai không thể được mã hóa thành một chuỗi lỏng lẻo: một lỗi gõ là một lời gọi tới một phương thức không tồn tại, bị bắt trước khi bất kỳ trường nào được ghi, chứ không phải một trường sai một cách lặng lẽ. Đó là cùng lập trường từ-chối-đoán mà phần còn lại của engine áp dụng; xem một API từ chối đoán.

Hiểu lầm thường gặp

Cái bẫy là tin rằng điền một trường làm nó đông cứng. Không phải vậy. Một trường đã điền vẫn mang một giá trị sống mà một trình đọc có năng lực có thể sửa, và một dáng vẻ mà một số trình đọc sẽ tái tạo. “Tôi đã đặt giá trị” và “tài liệu giờ là một bản ghi cố định” là hai trạng thái khác nhau. Chỉ có làm phẳng vượt từ cái này sang cái kia, vì chỉ làm phẳng mới biến giá trị thành đồ họa trang không còn hành xử như một trường nữa.

Cái sai phản chiếu lại là làm phẳng một bản nháp mà bạn vẫn còn cần thu thập đầu vào trên đó. Một khi đã làm phẳng, các trường biến mất — đó là toàn bộ điểm mấu chốt — nên hãy làm phẳng bản sao mà bạn định để làm bản cuối cùng, chứ không phải bản bạn còn đang lưu hành.

Có một sắc thái về tính vận hành đáng biết. Nếu bạn yêu cầu engine làm phẳng một tài liệu không có trang nào, nó không lặng lẽ vứt các giá trị trường của bạn vào sọt rác. Không có bề mặt trang nào để in chúng lên, nên thay vì tước bỏ form tương tác và làm rỗng các giá trị của nó — một mất mát dữ liệu toàn bộ, vô hình — NextPDF giữ nguyên form, giữ mọi giá trị nguyên vẹn và vẫn tương tác được, và đưa ra một cảnh báo nói cho bạn biết chuyện gì đã xảy ra. Bạn thêm một trang rồi làm phẳng lại. Đây là một thiết kế không-mất-dữ-liệu có chủ ý: engine thà trả lại một tài liệu vẫn-điền-được kèm một cảnh báo rõ ràng còn hơn một tài liệu bị làm rỗng một cách lặng lẽ. Các giá trị bạn được tin tưởng giao cho là thứ duy nhất mà một lần làm phẳng tuyệt đối không bao giờ được vứt bỏ.

Giới hạn và ranh giới

Hỗ trợ form của NextPDF là core đầy đủ: các bộ dựng có gán kiểu cho các control trường tương tác thông dụng, một bộ làm phẳng form, và một field manager ghi các trường dưới dạng các đối tượng PDF đúng quy cách. Trang này mô tả bề mặt core đó.

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

Làm phẳng là một chiều theo thiết kế. Nó loại bỏ form tương tác để bản ghi được cố định; nó không phải một công tắc “khóa tạm thời”, và không có một lệnh hủy-làm-phẳng nào tái dựng lại các trường biên tập được từ đồ họa đã in. Nếu bạn cần một bản sao mà người ta có thể tiếp tục biên tập, hãy giữ form chưa-làm-phẳng và làm phẳng một bản nhân đôi.

Làm phẳng cũng không phải là một chữ ký. Nó làm cho một tài liệu không-biên-tập-được theo nghĩa trình-đọc-thông-thường, nhưng nó không chứng minh bằng mật mã ai đã tạo ra nó hay rằng nó không thay đổi kể từ đó. Khi bản ghi phải chứng minh được là chính bản đã được thỏa thuận, hãy làm phẳng rồi ký; xem chữ ký nằm ở đâu trong một tệp PDF.

Cuối cùng, một form được gắn thẻ, tiếp cận được là một mối quan tâm tách biệt với một form đã làm phẳng. Nếu phiên bản điền được phải dùng được với công nghệ trợ giúp, các trường cần có tên tiếp-cận-được và cấu trúc khi chúng vẫn còn tương tác; xem điều gì làm cho một tệp PDF tiếp cận được.

Tài liệu liên quan

What makes a PDF accessible — các trường form được gắn thẻ và tên tiếp-cận-được, cho giai đoạn điền được.
An API that refuses to guess — vì sao kiểu trường là một typed enum, chứ không phải một chuỗi mà engine phải diễn giải.
The anatomy of a PDF file — nơi catalogue, các trang, và các annotation mà một form được dựng từ đó thực sự nằm.
How signatures sit in a PDF — cách làm cho một bản ghi đông cứng chứng minh được là chính bản đã được thỏa thuận.

Bảng thuật ngữ

AcroForm — form tương tác của một tệp PDF: cây các trường có gán kiểu được khai báo trong document catalogue làm cho tệp điền được (Spec: ISO 32000-2, §12.7).
Trường (Field) — phía dữ liệu của một control form: một cái tên, một kiểu, một giá trị, và các cờ. Độc lập với nó trông như thế nào trên trang.
Widget annotation — hình chữ nhật thấy được, nhấp được trên một trang mà qua đó một trình đọc tương tác với một trường (Spec: ISO 32000-2, §12.5). Một trường có thể có nhiều cái.
Trường choice (Choice field) — một trường đưa ra một tập các tùy chọn: một list box hiển thị chúng mở ra, một combo box hiển thị một danh sách thả xuống. Cả hai đều là cùng một kiểu trường PDF.
Làm phẳng (Flatten) — hiển thị giá trị hiện thời của mỗi trường vào trang như đồ họa bất biến và loại bỏ form tương tác, tạo ra một bản ghi đông cứng.
Bản ghi đông cứng (Frozen record) — một tài liệu đã làm phẳng: nó hiển thị một thứ cố định trong mọi trình đọc và không còn trường nào để biên tập.