Skip to content
PDF Oxide

XFA-Formulare — Python, Rust, Node.js, Go, C#

XFA-Formulare erkennen und analysieren — als einzige Bibliothek auf dem Markt, die die XML-Templates direkt versteht, statt nur auf den AcroForm-Fallback zu schauen:

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) ist ein veraltetes Formularformat, das von vielen Behörden, Finanzinstituten und Unternehmenssystemen verwendet wird. Die meisten Python-PDF-Bibliotheken können XFA-Formulare überhaupt nicht verarbeiten. PDF Oxide kann sie erkennen, analysieren und Daten daraus extrahieren.

Was ist XFA?

XFA-Formulare verwenden XML-basierte Vorlagen, die in ein PDF eingebettet sind, anstelle von Standard-AcroForm-Feldern. Sie wurden von Adobe erstellt und sind verbreitet in:

  • Behördenformulare — Finanzamt, Einwanderungsbehörden, staatliche Formulare
  • Finanzformulare — Kreditanträge, Versicherungsansprüche
  • Unternehmensformulare — Personaleinführung, Beschaffung, Compliance

XFA wurde in PDF 2.0 (ISO 32000-2:2020) als veraltet markiert, aber Millionen bestehender XFA-Dokumente sind weiterhin im Umlauf.

XFA vs AcroForm

Merkmal AcroForm XFA
Format PDF-Objekte XML-Vorlagen
Unterstützt von Allen PDF-Bibliotheken Wenigen PDF-Bibliotheken
Dynamische Layouts Nein Ja
PDF-2.0-Status Unterstützt Veraltet
Typische Quelle Die meisten Formularersteller Adobe LiveCycle, Adobe Designer

Warum PyMuPDF und pypdf keine XFA-Formulare verarbeiten können

Wenn Sie versucht haben, XFA-Formulare mit gängigen Python-PDF-Bibliotheken zu lesen, haben Sie wahrscheinlich leere Ergebnisse ohne Fehler oder Warnung erhalten. Das liegt daran, dass PyMuPDF, pypdf, pdfplumber und pdfminer keine XFA-Unterstützung haben.

PyMuPDF (fitz) — gibt stillschweigend leere Ergebnisse zurück

Die Methoden doc.get_form_fields() und .widgets() von PyMuPDF lesen nur AcroForm-Felder. Wenn ein PDF reine XFA-Formulare verwendet (häufig bei Finanzamt-, Einwanderungs- und Behördendokumenten), gibt PyMuPDF ohne jede Warnung leere Ergebnisse zurück:

# PyMuPDF — übersieht XFA-Daten stillschweigend
import fitz
doc = fitz.open("government-form.pdf")
fields = doc[0].widgets()  # Gibt [] bei reinen XFA-Formularen zurück
form_data = doc.get_form_fields()  # Gibt {} bei reinen XFA-Formularen zurück

Wenn das XFA-Formular eine AcroForm-Fallback-Ebene enthält, kann PyMuPDF eine Teilmenge der Felder zurückgeben — aber die eigentlichen XFA-Daten (dynamische Layouts, berechnete Werte, verschachtelte Unterformulare) sind unsichtbar.

pypdf — gibt bei XFA-Formularen ebenfalls leere Ergebnisse zurück

Das Lesen von Formularfeldern mit pypdf stößt auf dieselbe Einschränkung. Es kann nur auf AcroForm-Felder zugreifen und hat keine XFA-Unterstützung:

# pypdf — kann XFA-Inhalte nicht lesen
from pypdf import PdfReader
reader = PdfReader("government-form.pdf")
fields = reader.get_form_text_fields()  # Gibt {} bei reinen XFA-Formularen zurück

pdfplumber und pdfminer — keinerlei XFA-Unterstützung

pdfplumber und pdfminer versuchen nicht, Formularfelder aus XFA-Formularen zu lesen. Sie haben keine API zur XFA-Erkennung oder -Extraktion.

PDF Oxide — liest XFA nativ

PDF Oxide analysiert die XFA-XML-Vorlagen direkt und extrahiert alle Felder, Werte und die Formularstruktur:

# PDF Oxide — liest XFA nativ
from pdf_oxide import PdfDocument
doc = PdfDocument("government-form.pdf")
xfa = doc.analyze_xfa()
print(f"{len(xfa.fields)} fields found")  # Alle XFA-Felder extrahiert

Dies funktioniert bei Behördenformularen, Finanzamtsdokumenten, Versicherungsanträgen und jedem anderen XFA-basierten PDF — einschließlich Formularen ohne AcroForm-Fallback-Ebene.

Installation

pip install pdf_oxide

XFA-Formulare erkennen

Prüfen, ob ein PDF XFA-Inhalte enthält:

Python

from pdf_oxide import PdfDocument

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

if xfa:
    print("Dieses PDF verwendet XFA-Formulare")
    print(f"  Felder: {len(xfa.fields)}")
    print(f"  Hat Vorlage: {xfa.has_template}")
    print(f"  Hat Datensätze: {xfa.has_datasets}")
else:
    print("Standard-AcroForm (oder keine Formulare)")

WASM

In WASM können Sie XFA-Formulare erkennen und auf AcroForm-Felder zurückfallen:

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

const doc = new WasmPdfDocument(bytes);
if (doc.hasXfa()) {
  console.log("Dieses PDF verwendet XFA-Formulare");
  // AcroForm-Fallback-Felder lesen
  const fields = doc.getFormFields();
  console.log(`AcroForm-Fallback-Felder: ${fields.length}`);
}
doc.free();

XFA-Felder analysieren

Details zu jedem Feld im XFA-Formular abrufen:

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-Daten lesen

Aktuelle Feldwerte aus den XFA-Datensätzen extrahieren:

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)

Stapelverarbeitung von XFA-Formularen

Ein Verzeichnis durchsuchen, um zu identifizieren, welche PDFs XFA verwenden:

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-Formulare: {len(xfa_files)}")
print(f"Standardformulare: {len(acroform_files)}")

Rust-API

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);
}

Warum XFA wichtig ist

Die meisten Python-PDF-Bibliotheken ignorieren XFA-Inhalte stillschweigend — extract_text() und Formularfeld-APIs sehen nur die AcroForm-Fallback-Ebene (falls vorhanden). Viele reine XFA-Formulare haben kein AcroForm-Fallback, wodurch sie für andere Tools unsichtbar sind:

  • PyMuPDF (pymupdf) XFA-Formulare — get_form_fields() und .widgets() geben bei reinen XFA-PDFs leere Ergebnisse zurück. PyMuPDF hat keine XFA-Unterstützung und plant nicht, diese hinzuzufügen.
  • pypdf XFA-Unterstützung — get_form_text_fields() von pypdf kann XFA-Inhalte nicht lesen. Nur AcroForm-Fallback-Felder sind sichtbar, falls sie überhaupt existieren.
  • pdfplumber — keine XFA-Unterstützung. Formularextraktion ist auf AcroForm-Felder beschränkt.
  • pdfminer — keine XFA-Unterstützung. Kann XFA-Formulardaten weder erkennen noch extrahieren.

PDF Oxide ist die einzige Python-PDF-Bibliothek, die XFA-XML-Vorlagen direkt liest und Ihnen Zugriff auf Formularstruktur und Daten gibt, die PyMuPDF, pypdf, pdfplumber und pdfminer nicht sehen können.

Verwandte Seiten