Skip to content
PDF Oxide

XFA-форми — Python / Rust / Node.js / Go / C#

Виявляйте та аналізуйте XFA-форми — єдина бібліотека, що читає XML-шаблони напряму, а не тільки AcroForm-заглушку:

from pdf_oxide import PdfDocument

doc = PdfDocument("government-form.pdf")
xfa = doc.analyze_xfa()
if xfa:
    print(f"XFA form with {len(xfa.fields)} fields")
    for field in xfa.fields:
        print(f"  {field.name}: {field.field_type}")

XFA (XML Forms Architecture) — це застарілий формат форм, який використовується багатьма державними установами, фінансовими організаціями та корпоративними системами. Більшість бібліотек PDF для Python не можуть працювати з формами XFA взагалі. PDF Oxide може виявляти, аналізувати та витягувати дані з них.

Що таке XFA?

Форми XFA використовують XML-шаблони, вбудовані у PDF, замість стандартних полів AcroForm. Вони були створені Adobe та поширені у:

  • Державних формах — податкові документи, імміграція, документи державних установ
  • Фінансових формах — заявки на кредит, страхові претензії
  • Корпоративних формах — HR-адаптація, закупівлі, відповідність

XFA було визнано застарілим у PDF 2.0 (ISO 32000-2:2020), але мільйони існуючих XFA-документів залишаються в обігу.

XFA проти AcroForm

Характеристика AcroForm XFA
Формат Об’єкти PDF XML-шаблони
Підтримка Усі бібліотеки PDF Небагато бібліотек PDF
Динамічні макети Ні Так
Статус у PDF 2.0 Підтримується Застарілий
Типове джерело Більшість генераторів форм Adobe LiveCycle, Adobe Designer

Чому PyMuPDF та pypdf не можуть працювати з формами XFA

Якщо ви намагалися читати форми XFA за допомогою популярних бібліотек PDF для Python, ви, ймовірно, бачили порожні результати без помилки чи попередження. Це тому, що PyMuPDF, pypdf, pdfplumber та pdfminer не мають підтримки XFA.

PyMuPDF (fitz) — мовчки повертає порожнє

doc.get_form_fields() та .widgets() PyMuPDF читають лише поля AcroForm. Коли PDF використовує форми лише з XFA (поширене для податкових, імміграційних та документів державних установ), PyMuPDF повертає порожні результати без жодного попередження:

# PyMuPDF — мовчки пропускає дані XFA
import fitz
doc = fitz.open("government-form.pdf")
fields = doc[0].widgets()  # Повертає [] для форм лише з XFA
form_data = doc.get_form_fields()  # Повертає {} для форм лише з XFA

Якщо форма XFA включає резервний шар AcroForm, PyMuPDF може повернути часткову підмножину полів — але фактичні дані XFA (динамічні макети, обчислені значення, вкладені підформи) невидимі.

pypdf — також повертає порожнє для форм XFA

Читання полів форм у pypdf стикається з тим самим обмеженням. Він може отримати доступ лише до полів AcroForm та не має підтримки XFA:

# pypdf — не може читати вміст XFA
from pypdf import PdfReader
reader = PdfReader("government-form.pdf")
fields = reader.get_form_text_fields()  # Повертає {} для форм лише з XFA

pdfplumber та pdfminer — жодної підтримки XFA

pdfplumber та pdfminer не намагаються читати поля форм з XFA. Вони не мають API для виявлення чи витягування XFA.

PDF Oxide — читає XFA нативно

PDF Oxide парсить XML-шаблони XFA безпосередньо, витягуючи всі поля, значення та структуру форми:

# PDF Oxide — читає XFA нативно
from pdf_oxide import PdfDocument
doc = PdfDocument("government-form.pdf")
xfa = doc.analyze_xfa()
print(f"{len(xfa.fields)} fields found")  # Усі поля XFA витягнуті

Це працює з державними формами, податковими документами, страховими заявками та будь-якими іншими PDF на основі XFA — включаючи форми без резервного шару AcroForm.

Встановлення

pip install pdf_oxide

Виявлення форм XFA

Перевірте, чи PDF містить вміст XFA:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("form.pdf")
xfa = doc.analyze_xfa()

if xfa:
    print("Цей PDF використовує форми XFA")
    print(f"  Fields: {len(xfa.fields)}")
    print(f"  Has template: {xfa.has_template}")
    print(f"  Has datasets: {xfa.has_datasets}")
else:
    print("Стандартна AcroForm (або без форм)")

WASM

У WASM ви можете виявити форми XFA та використати резервні поля AcroForm:

import { WasmPdfDocument } from "pdf-oxide-wasm";

const doc = new WasmPdfDocument(bytes);
if (doc.hasXfa()) {
  console.log("This PDF uses XFA forms");
  // Читання резервних полів AcroForm
  const fields = doc.getFormFields();
  console.log(`AcroForm fallback fields: ${fields.length}`);
}
doc.free();

Аналіз полів XFA

Отримайте деталі кожного поля у формі XFA:

from pdf_oxide import PdfDocument

doc = PdfDocument("tax-form.pdf")
xfa = doc.analyze_xfa()

if xfa:
    for field in xfa.fields:
        print(f"Name: {field.name}")
        print(f"  Type: {field.field_type}")
        print(f"  Value: {field.value}")
        print()

Читання даних XFA

Витягніть поточні значення полів з наборів даних XFA:

from pdf_oxide import PdfDocument

doc = PdfDocument("filled-xfa.pdf")
xfa = doc.analyze_xfa()

if xfa and xfa.has_datasets:
    data = {}
    for field in xfa.fields:
        if field.value:
            data[field.name] = field.value
    print(data)

Пакетна обробка форм XFA

Сканування директорії для ідентифікації PDF з XFA:

from pdf_oxide import PdfDocument, PdfError
from pathlib import Path

pdf_dir = Path("government-forms/")
xfa_files = []
acroform_files = []

for pdf_path in pdf_dir.glob("*.pdf"):
    try:
        doc = PdfDocument(str(pdf_path))
        xfa = doc.analyze_xfa()
        if xfa:
            xfa_files.append(pdf_path.name)
        else:
            acroform_files.append(pdf_path.name)
    except PdfError as e:
        print(f"Error: {pdf_path.name}: {e}")

print(f"XFA forms: {len(xfa_files)}")
print(f"Standard forms: {len(acroform_files)}")

API Rust

use pdf_oxide::PdfDocument;
use pdf_oxide::xfa::analyze_xfa_document;

let mut doc = PdfDocument::open("xfa-form.pdf")?;
let analysis = analyze_xfa_document(&mut doc)?;

println!("XFA form detected: {} fields", analysis.fields.len());
for field in &analysis.fields {
    println!("  {} ({:?}): {:?}", field.name, field.field_type, field.value);
}

Чому XFA має значення

Більшість бібліотек PDF для Python мовчки ігнорують вміст XFA — extract_text() та API полів форм бачать лише резервний шар AcroForm (якщо він існує). Багато форм лише з XFA не мають резервного шару AcroForm, що робить їх невидимими для інших інструментів:

  • Форми XFA у PyMuPDF (pymupdf) — get_form_fields() та .widgets() повертають порожнє для PDF лише з XFA. PyMuPDF не має підтримки XFA та не планує її додавати.
  • Підтримка XFA у pypdf — get_form_text_fields() pypdf не може читати вміст XFA. Видимі лише резервні поля AcroForm, якщо вони взагалі існують.
  • pdfplumber — без підтримки XFA. Витягування форм обмежене полями AcroForm.
  • pdfminer — без підтримки XFA. Не може виявити чи витягнути дані форм XFA.

PDF Oxide — єдина бібліотека PDF для Python, що читає XML-шаблони XFA безпосередньо, надаючи вам доступ до структури та даних форм, які PyMuPDF, pypdf, pdfplumber та pdfminer не можуть побачити.

Пов’язанi сторінки