채울 수 있는 양식에서 동결된 기록으로: AcroForm 채우기와 평탄화

Spec: ISO 32000-2, §12.7

한눈에 보기

PDF 양식에는 두 삶이 있습니다. 처음에 그것은 채울 수 있습니다. 즉, 사람이 입력하고, 체크하고, 또는 그중에서 고르는 유형이 있는 필드의 집합입니다. 그런 다음 합의가 이루어지면, 그것은 동결된 기록이 됩니다. 즉, 모든 뷰어가, 모든 기기에서, 합의된 것을 정확히 보도록 값이 페이지 자체에 인쇄됩니다. NextPDF는 첫 번째를 빌드하고 두 번째를 산출하며, 하나의 의도된 보장을 동반합니다 — 그것은 그 도중에 값을 조용히 버리지 않습니다.

왜 중요한가

“내가 채운 것”과 “당신이 보는 것” 사이의 간극이 바로 양식이 잘못되는 곳입니다.

채울 수 있는 필드는, 기술적으로, 페이지 위에 그려진 작은 대화형 위젯입니다. 서로 다른 뷰어가 그것을 다르게 렌더링할 수 있습니다. 어떤 것은 저장된 값을 존중하고, 어떤 것은 여러분이 갖고 있지 않은 폰트로 모양을 재생성하며, 어떤 것은 리더가 그것을 다시 편집하게 합니다. 협업자가 계속 편집하기를 바라는 초안에는, 그것이 요점입니다. 합의된 것의 서명된 사본에는, 그것이 책임 부담입니다. 기록은 어떤 애플리케이션이 그것을 여는지에 의존해서는 안 되며, 사후에 편집 가능해서도 안 됩니다.

평탄화는 그 간극을 닫습니다. 그것은 각 필드의 현재 값을 취하여 평범하고 변경 불가능한 그래픽 — 제목이나 로고와 같은 종류의 콘텐츠 — 으로 페이지에 그려 넣습니다. 그 후에는, 편집할 필드도 없고 재생성할 모양도 없습니다. 문서는 어디서나 한 가지를, 같은 것을 보여 줍니다.

요약

AcroForm은 문서의 대화형 양식입니다. 즉, 카탈로그에 선언된 유형이 있는 필드의 트리입니다 (Spec: ISO 32000-2, §12.7).
각 필드는 위젯 주석 — 여러분이 클릭하거나 입력하는 페이지 위의 직사각형 — 으로 보이게 됩니다 (Spec: ISO 32000-2, §12.5).
NextPDF는 지원되는 모든 비서명 양식 컨트롤 — 텍스트, 체크박스, 라디오, 리스트 박스와 콤보 박스(choice), 그리고 푸시 버튼 — 에 대한 유형이 있는 빌더와 더불어, 그것들을 적합한 PDF 객체로 쓰는 필드 관리자를 제공합니다.
평탄화는 각 필드의 값을 페이지 콘텐츠 스트림으로 렌더링하고 이제 불필요해진 대화형 양식을 제거하여, 동결된 기록을 남깁니다.
페이지가 없는 문서를 평탄화하도록 요청하면, NextPDF는 여러분의 필드 값을 조용히 파괴하지 않습니다. 그것은 양식을 보존하고, 여러분에게 경고하며, 페이지를 추가하여 올바르게 평탄화하도록 해 줍니다.

NextPDF가 접근하는 방식

심상 모델은 두 계층입니다. 필드는 데이터입니다. 즉, 이름, 유형, 값, 그리고 플래그의 집합입니다. 위젯은 그림입니다. 즉, 뷰어가 필드와 상호 작용하게 해 주는, 특정 페이지 위의 직사각형입니다 (Spec: ISO 32000-2, §12.5). 하나의 필드는 여러 위젯을 통해 드러날 수도 있습니다 — 그것이 바로 라디오 그룹이 작동하는 방식으로, 하나의 기저 값에 연결된 여러 페이지 위 선택지입니다.

NextPDF는 각 필드 유형에 자체의 유형이 있는 빌더를 제공하므로, 여러분은 결코 원시 딕셔너리를 손으로 조립하지 않습니다. 유형이 PDF에 맞는 세부 사항을 여러분 대신 담아 줍니다. 체크박스, 라디오 버튼, 그리고 푸시 버튼은 명세에서 모두 같은 기저 양식 유형을 공유하며 자신의 플래그로 구별됩니다. 엔진은 “라디오”가 어느 비트를 뜻하는지 여러분이 기억하도록 요구하는 대신, 여러분이 고른 유형으로부터 그 플래그를 설정합니다. 리스트 박스와 콤보 박스는 둘 다 choice 필드입니다. 다시, 빌더가 올바른 인코딩을 고릅니다. 여러분은 필드 유형을 한 번, 말로 진술하고, 바이트가 뒤따릅니다.

평탄화는 두 번째 절반입니다. 평탄화기는 위젯 주석을 자신이 속한 페이지별로 묶고, 그 페이지 위 배치를 위해 각 위젯의 직사각형을 사용한 다음, 각 값을 작은 콘텐츠 스트림 연산자의 연속 — 색을 설정하고, 텍스트 위치를 설정하고, 글리프를 그리는 — 으로 렌더링하여 그 페이지의 기존 콘텐츠에 덧붙입니다 (Spec: ISO 32000-2, §8.4). 값은 살아 있는 필드이기를 멈추고 그려진 잉크가 됩니다. 양식이 더 이상 어떤 대화형 필드도 담지 않으므로, 엔진은 그런 다음 AcroForm 엔트리를 제거합니다. 대화형으로 남을 것이 아무것도 없는 것입니다.

Declare typed fields텍스트, 체크박스, 라디오, choice, 그리고 버튼 필드를 그 유형이 있는 빌더로 추가한다. 엔진이 명세에 맞는 PDF 유형과 플래그를 설정한다.
Place the widgets각 필드는 위젯 주석으로 그려진다 — 뷰어가 입력하거나, 체크하거나, 그중에서 고를 수 있는, 선택된 페이지 위의 직사각형이다.
Collect input채울 수 있는 상태로 출하한다. 즉, 리더가 값을 제공하거나 여러분의 코드가 값을 설정하여, 채워졌으되 여전히 편집 가능한 문서를 남긴다.
Flatten the values각 필드의 값을 그래픽으로서 페이지 콘텐츠 스트림으로 렌더링한다. 그려진 값은 이제 변경 불가능하다.
Drop the interactive form모든 값이 새겨지면, AcroForm을 제거하여 편집 가능한 것이 아무것도 남지 않게 한다 — 합의된 것의 동결된 기록이다.

채울 수 있는 양식에서 동결된 기록으로: 유형이 있는 필드를 선언하고, 그 페이지 위 위젯을 그리고, 값을 채운 다음, 그 값을 변경 불가능한 페이지 그래픽으로 평탄화하고 이제 비어 있는 대화형 양식을 제거한다.

실용적인 예제

작고 대표적인 양식입니다. 즉, 몇 개의 유형이 있는 필드를 빌드한 다음, 그것을 동결된 기록으로 평탄화합니다.

<?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를 참조하십시오.

흔한 오해

함정은 필드를 채우는 것이 그것을 동결한다고 믿는 것입니다. 그렇지 않습니다. 채워진 필드는 여전히 유능한 뷰어가 편집할 수 있는 살아 있는 값과, 일부 뷰어가 재생성할 모양을 담고 있습니다. “나는 값을 설정했다”와 “문서는 이제 고정된 기록이다”는 두 가지 서로 다른 상태입니다. 오직 평탄화만이 하나에서 다른 하나로 건너갑니다. 오직 평탄화만이 값을 더 이상 필드처럼 행동하지 않는 페이지 그래픽으로 바꾸기 때문입니다.

거울에 비친 듯한 반대의 실수는 여전히 입력을 수집해야 하는 초안을 평탄화하는 것입니다. 일단 평탄화되면, 필드는 사라집니다 — 그것이 바로 요점입니다 — 따라서 여전히 돌리고 있는 것이 아니라 최종으로 의도한 사본을 평탄화하십시오.

알아 둘 가치가 있는 운영성의 미묘함이 하나 있습니다. 페이지가 없는 문서를 평탄화하도록 엔진에 요청하면, 그것은 여러분의 필드 값을 조용히 버리지 않습니다. 그것을 그려 넣을 페이지 표면이 없으므로, 대화형 양식을 벗겨 내고 그 값을 null로 만드는 대신 — 전면적이고 보이지 않는 데이터 손실 — NextPDF는 양식을 보존하고, 모든 값을 온전하게 그리고 여전히 대화형으로 유지하며, 무슨 일이 일어났는지를 알려 주는 경고를 드러냅니다. 여러분은 페이지를 추가하고 다시 평탄화합니다. 이것은 의도된 무데이터 손실 설계입니다. 엔진은 조용히 비워진 문서보다는 여전히 채울 수 있는 문서와 명확한 경고를 돌려주기를 택합니다. 여러분이 맡긴 값은 평탄화가 결코 버려서는 안 되는 단 하나의 것입니다.

한계와 경계

NextPDF의 양식 지원은 완전한 코어입니다. 즉, 흔한 대화형 필드 컨트롤을 위한 유형이 있는 빌더, 양식 평탄화기, 그리고 필드를 적합한 PDF 객체로 쓰는 필드 관리자입니다. 이 페이지는 그 코어 표면을 기술합니다.

AcroForm fields and flattening — edition availability
Edition	Availability
Core	텍스트, 체크박스, 라디오, choice(리스트 박스와 콤보 박스), 그리고 푸시 버튼 필드를 위한 유형이 있는 빌더. 위젯 배치. 필드 관리자. 그리고 값을 페이지 그래픽으로 새기는 양식 평탄화기. 모든 에디션에서 사용 가능합니다.
Pro	Not in this edition
Enterprise	Not in this edition

평탄화는 설계상 단방향입니다. 그것은 기록이 고정되도록 대화형 양식을 제거합니다. 그것은 “일시적으로 잠금” 토글이 아니며, 그려진 그래픽으로부터 편집 가능한 필드를 다시 도출하는 평탄화 해제도 없습니다. 사람들이 계속 편집할 수 있는 사본이 필요하다면, 평탄화되지 않은 양식을 보관하고 복제본을 평탄화하십시오.

평탄화는 또한 서명이 아닙니다. 그것은 문서를 일반 뷰어의 의미에서 편집 불가능하게 만들지만, 누가 그것을 산출했는지 또는 그것이 이후로 변경되지 않았는지를 암호학적으로 입증하지는 않습니다. 기록이 합의된 바로 그것임을 입증 가능하게 해야 할 때는, 평탄화한 다음 서명하십시오. 서명은 PDF 안 어디에 자리 잡는가를 참조하십시오.

마지막으로, 태그가 붙은 접근 가능한 양식은 평탄화된 양식과는 별개의 관심사입니다. 채울 수 있는 버전이 보조 기술로 사용 가능해야 한다면, 필드는 여전히 대화형인 동안 접근 가능한 이름과 구조가 필요합니다. 무엇이 PDF를 접근 가능하게 만드는가를 참조하십시오.

용어집

AcroForm — PDF의 대화형 양식. 즉, 파일을 채울 수 있게 만드는, 문서 카탈로그에 선언된 유형이 있는 필드의 트리 (Spec: ISO 32000-2, §12.7).
필드 — 양식 컨트롤의 데이터 측면. 즉, 이름, 유형, 값, 그리고 플래그입니다. 페이지 위에 어떻게 보이는지와는 무관합니다.
위젯 주석 — 뷰어가 그것을 통해 필드와 상호 작용하는, 페이지 위의 보이고 클릭 가능한 직사각형 (Spec: ISO 32000-2, §12.5). 하나의 필드가 여럿을 가질 수도 있습니다.
choice 필드 — 선택지의 집합을 제공하는 필드. 즉, 리스트 박스는 그것들을 펼쳐 보이고, 콤보 박스는 드롭다운으로 보입니다. 둘 다 같은 PDF 필드 유형입니다.
평탄화 — 각 필드의 현재 값을 변경 불가능한 그래픽으로 페이지에 렌더링하고 대화형 양식을 제거하여, 동결된 기록을 산출하는 것.
동결된 기록 — 평탄화된 문서. 그것은 모든 뷰어에서 하나의 고정된 것을 보여 주고 편집할 필드가 남아 있지 않습니다.