Zones de signature

Ce guide détaille la création de zones de signature sur les documents PDF.

La classe ZoneBuilder

La classe ZoneBuilder est l'approche recommandée pour créer des zones de signature. Elle ouvre le document PDF une seule fois et met en cache les dimensions des pages pour des performances optimales.

using (var zoneBuilder = new ZoneBuilder("document.pdf", isPki: false))
{
    var signZone = zoneBuilder.CreateFieldSignZone(1, "signature1", 10, 300, 100, 40);
    var textZone = zoneBuilder.CreateFieldTextZone(1, "text1", 10, 400, 200, 30);
    var dateZone = zoneBuilder.CreateFieldDateSignZone(2, "date1", 10, 500, 100, 25);
}

Propriétés

Propriété Type Description
PageCount int Nombre total de pages dans le document PDF
FilePath string Chemin du fichier PDF
IsPki bool Indique si le mode PKI est activé (permet TextArea, OptionList, Dropdown)

Constructeur

public ZoneBuilder(string filePath, bool isPki)
Paramètre Type Description
filePath string Chemin vers le fichier PDF
isPki bool Active le mode PKI pour les types de zones avancés

Paramètres communs

Toutes les méthodes CreateField*Zone partagent ces paramètres :

Paramètre Type Description
page int Numéro de page (1 = première page)
fieldName string Identifiant unique du champ
x float Position horizontale (depuis la gauche)
y float Position verticale (depuis le haut)
width float Largeur du champ
height float Hauteur du champ
Note

Les dimensions de page standard Letter sont 612 x 792 points (72 DPI). Utilisez GetPageDimensions(page) pour obtenir les dimensions exactes d'une page.

Obtenir les dimensions d'une page

using (var zoneBuilder = new ZoneBuilder(filePath, isPki: false))
{
    var (pageWidth, pageHeight) = zoneBuilder.GetPageDimensions(1);
    Console.WriteLine($"Page 1: {pageWidth} x {pageHeight} points");
}

Types de zones

Zone de signature

using (var zoneBuilder = new ZoneBuilder(filePath, isPki: false))
{
    var signZone = zoneBuilder.CreateFieldSignZone(
        page: 1,
        fieldName: "signature_client",
        x: 100, y: 650,
        width: 200, height: 50
    );
}

Zone d'initiales

var initialsZone = zoneBuilder.CreateFieldInitialZone(
    page: 1,
    fieldName: "initiales_client",
    x: 500, y: 700,
    width: 60, height: 30
);

Zone de texte

var textZone = zoneBuilder.CreateFieldTextZone(
    page: 1,
    fieldName: "nom_complet",
    x: 100, y: 600,
    width: 200, height: 25,
    defaultValue: "",      // Valeur par défaut
    fontSize: 12,
    required: true         // Champ obligatoire
);

Zone de nombre

var numberZone = zoneBuilder.CreateFieldNumberZone(
    page: 1,
    fieldName: "montant",
    x: 100, y: 550,
    width: 100, height: 25,
    defaultValue: 0,
    fontSize: 12,
    required: true
);

Zone de date (auto-remplie à la signature)

Cette zone est automatiquement remplie avec la date de signature.

var dateSignZone = zoneBuilder.CreateFieldDateSignZone(
    page: 1,
    fieldName: "date_signature",
    x: 100, y: 500,
    width: 100, height: 25,
    fontSize: 12
);

Zone de date (sélecteur)

Permet au signataire de choisir une date via un sélecteur.

var dateZone = zoneBuilder.CreateFieldDateZone(
    page: 1,
    fieldName: "date_contrat",
    x: 100, y: 450,
    width: 100, height: 25,
    fontSize: 12,
    required: true
);

Case à cocher

var checkbox = zoneBuilder.CreateFieldCheckBoxZone(
    page: 1,
    fieldName: "accepte_conditions",
    x: 100, y: 400,
    isChecked: false,       // État coché par défaut
    required: true,         // Obligatoire
    requiredFocus: false    // Doit recevoir le focus avant soumission
);
Note

Les dimensions de la case à cocher sont fixes (10x10 points). Si required est true, la case ne peut pas être pré-cochée (isChecked sera ignoré).

Bouton radio

Les boutons radio sont regroupés par groupId. Un seul bouton peut être sélectionné par groupe.

// Groupe de boutons radio
var radio1 = zoneBuilder.CreateFieldRadioZone(
    page: 1,
    fieldName: "Option A",        // Valeur de cette option
    x: 100, y: 350,
    groupId: "choix_option",      // Identifiant du groupe
    isSelected: true              // Option sélectionnée par défaut
);

var radio2 = zoneBuilder.CreateFieldRadioZone(
    page: 1,
    fieldName: "Option B",        // Valeur de cette option
    x: 130, y: 350,
    groupId: "choix_option",      // Même groupe
    isSelected: false
);
Note

Les dimensions du bouton radio sont fixes (10x10 points).

Types de zones PKI uniquement

Les types de zones suivants nécessitent isPki: true lors de l'initialisation du ZoneBuilder.

Zone de texte multiligne (TextArea)

using (var zoneBuilder = new ZoneBuilder(filePath, isPki: true))
{
    var textAreaZone = zoneBuilder.CreateFieldTextAreaZone(
        page: 1,
        fieldName: "description",
        x: 100, y: 300,
        width: 300, height: 100,
        defaultValue: "Entrez votre description ici...",
        fontSize: 12,
        required: false
    );
}

Liste d'options (sélection multiple)

var optionListZone = zoneBuilder.CreateFieldOptionListZone(
    page: 1,
    fieldName: "services",
    x: 100, y: 150,
    width: 200, height: 80,
    options: new[] { "Service A", "Service B", "Service C", "Service D" },
    selectedValues: new[] { "Service A", "Service C" },  // Valeurs pré-sélectionnées (optionnel)
    multiSelect: true,
    required: false
);

Pour une sélection unique :

var singleSelectZone = zoneBuilder.CreateFieldOptionListZone(
    page: 1,
    fieldName: "pays",
    x: 100, y: 250,
    width: 150, height: 25,
    options: new[] { "Canada", "États-Unis", "France", "Belgique" },
    selectedValues: new[] { "Canada" },
    multiSelect: false,
    required: true
);

Liste déroulante (Dropdown)

var dropdownZone = zoneBuilder.CreateFieldDropdownZone(
    page: 1,
    fieldName: "province",
    x: 100, y: 200,
    width: 150, height: 25,
    options: new[] { "Québec", "Ontario", "Alberta", "Colombie-Britannique" },
    selectedValue: "Québec",    // Valeur pré-sélectionnée (optionnel)
    fontSize: 12,
    required: true
);

Exemple complet : Formulaire de contrat

public SignZoneDetails[] CreateContractFormZones(string filePath)
{
    var zones = new List<SignZoneDetails>();

    using (var zoneBuilder = new ZoneBuilder(filePath, isPki: false))
    {
        // Informations client
        zones.Add(zoneBuilder.CreateFieldTextZone(1, "nom", 150, 700, 200, 25, "", 12, true));
        zones.Add(zoneBuilder.CreateFieldTextZone(1, "prenom", 150, 670, 200, 25, "", 12, true));
        zones.Add(zoneBuilder.CreateFieldTextZone(1, "courriel", 150, 640, 250, 25, "", 12, true));

        // Montant
        zones.Add(zoneBuilder.CreateFieldNumberZone(1, "montant", 150, 600, 100, 25, 0, 12, true));

        // Acceptation des conditions
        zones.Add(zoneBuilder.CreateFieldCheckBoxZone(1, "conditions", 50, 400, false, true));

        // Date auto-remplie
        zones.Add(zoneBuilder.CreateFieldDateSignZone(1, "date_contrat", 350, 300, 100, 25, 12));

        // Signature
        zones.Add(zoneBuilder.CreateFieldSignZone(1, "signature", 100, 150, 200, 60));

        // Initiales sur chaque page
        for (int i = 1; i <= zoneBuilder.PageCount; i++)
        {
            zones.Add(zoneBuilder.CreateFieldInitialZone(i, $"initiales_p{i}", 500, 50, 50, 25));
        }
    }

    return zones.ToArray();
}

Exemple avec mode PKI

public SignZoneDetails[] CreateAdvancedFormZones(string filePath)
{
    var zones = new List<SignZoneDetails>();

    using (var zoneBuilder = new ZoneBuilder(filePath, isPki: true))
    {
        // Champs texte standard
        zones.Add(zoneBuilder.CreateFieldTextZone(1, "nom", 150, 700, 200, 25));

        // Zone de texte multiligne (PKI uniquement)
        zones.Add(zoneBuilder.CreateFieldTextAreaZone(1, "commentaires", 150, 500, 300, 100));

        // Liste déroulante (PKI uniquement)
        zones.Add(zoneBuilder.CreateFieldDropdownZone(
            1, "type_contrat", 150, 450, 200, 25,
            new[] { "Standard", "Premium", "Enterprise" },
            "Standard"
        ));

        // Signature
        zones.Add(zoneBuilder.CreateFieldSignZone(1, "signature", 100, 150, 200, 60));
    }

    return zones.ToArray();
}

Association des zones aux destinataires

string filePath = @"c:\temp\document.pdf";

// Obtenir le hash SHA512 du fichier PDF
string sha512 = CryptoHelper.GetSHA512OfFile(filePath);

// Créer le destinataire
var recipient = new RecipientInfo { Email = "signataire@example.com" };

// Construire les définitions de zones
var zones = CreateContractFormZones(filePath);

var recipientIndex = new Dictionary<RecipientInfo, List<FileZoneDefinition>>
{
    {
        recipient,
        new List<FileZoneDefinition>
        {
            new FileZoneDefinition
            {
                UniqueName = sha512,
                ZonesDef = new SignZoneDefinition
                {
                    Mode = "define",
                    Zones = zones
                }
            }
        }
    }
};

// Convertir en liste pour l'API
var zoneDefList = SignHelper.ConvertRecipientIndexToList(recipientIndex);

Gestion des erreurs

Exceptions du constructeur

Exception Cause
ArgumentException Le chemin du fichier est vide ou null
FileNotFoundException Le fichier PDF n'existe pas

Exceptions des méthodes CreateField*Zone

Exception Cause
ArgumentOutOfRangeException Le numéro de page est invalide (< 1 ou > nombre de pages)
ObjectDisposedException Le ZoneBuilder a été disposé
NotSupportedException Type de zone PKI utilisé sans isPki: true
ArgumentException Options invalides (ex: liste vide pour OptionList/Dropdown) 
try
{
    using (var zoneBuilder = new ZoneBuilder(filePath, isPki: false))
    {
        var zone = zoneBuilder.CreateFieldSignZone(1, "signature", 100, 100, 200, 50);
    }
}
catch (FileNotFoundException ex)
{
    Console.WriteLine($"Fichier non trouvé: {ex.FileName}");
}
catch (ArgumentOutOfRangeException ex)
{
    Console.WriteLine($"Page invalide: {ex.Message}");
}
catch (NotSupportedException ex)
{
    Console.WriteLine($"Type de zone non supporté: {ex.Message}");
}

Bonnes pratiques

  1. Utilisez using : Le ZoneBuilder implémente IDisposable. Utilisez toujours un bloc using pour libérer les ressources.

  2. Créez toutes les zones d'un PDF en une seule session : Pour de meilleures performances, créez toutes vos zones d'un PDF dans un seul bloc using.

  3. Noms de champs uniques : Assurez-vous que chaque fieldName est unique dans le document, sauf pour les boutons radio du même groupe.

Voir aussi