iText 8签名锁定字段异常：首次签名后二次签名报错

我正在评估iText（版本8）是否符合需求，需为PDF表单添加签名字段并在签名后锁定指定文本字段。现有代码生成含2个文本字段与2个签名字段的PDF：签名SignField1后，TextFormField1可正常锁定，但直接签名SignField2时会出现“函数参数值不正确”的报错，关闭并重新打开文档后则可正常签名。请问该如何修复此问题，是否有更优实现方案？

PdfWriter writer = new PdfWriter("AddSignFieldItext77.pdf");
iText.Kernel.Pdf.PdfDocument pdf = new iText.Kernel.Pdf.PdfDocument(writer);

var newPage = pdf.AddNewPage(new PageSize(PageSize.A4));
PdfAcroForm form = PdfAcroForm.GetAcroForm(pdf, true);

var formRectangle = new iText.Kernel.Geom.Rectangle(100, 800, 200, 20);
var formFieldBuilder = new TextFormFieldBuilder(pdf, "TextFormField1");
formFieldBuilder.SetPage(newPage);

formFieldBuilder.SetWidgetRectangle(formRectangle);
var formfield = formFieldBuilder.CreateText();
form.AddField(formfield);

var formRectangle2 = new iText.Kernel.Geom.Rectangle(100, 700, 200, 20);
var formFieldBuilder2 = new TextFormFieldBuilder(pdf, "TextFormField2");
formFieldBuilder2.SetPage(newPage);

formFieldBuilder2.SetWidgetRectangle(formRectangle2);
var formfield2 = formFieldBuilder2.CreateText();
form.AddField(formfield2);

var signatureRectangle1 = new iText.Kernel.Geom.Rectangle(36, 448, 200, 100);
var signatureField1 = new SignatureFormFieldBuilder(pdf, "SignField1");
signatureField1.SetPage(newPage);
signatureField1.SetWidgetRectangle(signatureRectangle1);
PdfSignatureFormField sig1 = signatureField1.CreateSignature();
        
PdfSigFieldLock pdfSigFieldLock1 = new PdfSigFieldLock();          
string[] fieldToLock1 = new string[] { "TextFormField1" };
pdfSigFieldLock1.SetFieldLock(PdfSigFieldLock.LockAction.INCLUDE, fieldToLock1);         

PdfDictionary dict = sig1.GetPdfObject();
dict.Put(PdfName.Lock,pdfSigFieldLock1.GetPdfObject());
form.AddField(sig1);

var signatureRectangle2 = new iText.Kernel.Geom.Rectangle(36, 248, 200, 100);
var signatureField2 = new SignatureFormFieldBuilder(pdf, "SignField2");
signatureField2.SetPage(newPage);
signatureField2.SetWidgetRectangle(signatureRectangle2);
PdfSignatureFormField sig2 = signatureField2.CreateSignature();

PdfSigFieldLock pdfSigFieldLock2 = new PdfSigFieldLock();         
string[] fieldToLock2 = new string[] { "TextFormField2" };
pdfSigFieldLock2.SetFieldLock(PdfSigFieldLock.LockAction.INCLUDE,fieldToLock2);

PdfDictionary dict2 = sig2.GetPdfObject();
dict2.Put(PdfName.Lock, pdfSigFieldLock2.GetPdfObject());
form.AddField(sig2);

pdf.Close();

问题原因 #

直接签名SignField2报错的核心原因是：手动通过dict.Put(PdfName.Lock, ...)添加锁字典时，未正确关联签名字段的交互状态，导致PDF阅读器首次加载时无法解析锁规则的依赖关系；重新打开后阅读器完成了文档结构初始化，因此能正常处理。

修复方法 #

不要直接操作底层PdfDictionary添加锁字典，改用iText官方提供的PdfSignatureFormField.SetSigFieldLock()方法，该方法会自动处理字段间的关联逻辑，确保阅读器能正确识别锁规则。

修改后的签名字段创建代码：

// 创建第一个签名字段并设置锁定规则
var signatureRectangle1 = new iText.Kernel.Geom.Rectangle(36, 448, 200, 100);
var signatureField1 = new SignatureFormFieldBuilder(pdf, "SignField1");
signatureField1.SetPage(newPage);
signatureField1.SetWidgetRectangle(signatureRectangle1);
PdfSignatureFormField sig1 = signatureField1.CreateSignature();

PdfSigFieldLock pdfSigFieldLock1 = new PdfSigFieldLock();          
string[] fieldToLock1 = new string[] { "TextFormField1" };
pdfSigFieldLock1.SetFieldLock(PdfSigFieldLock.LockAction.INCLUDE, fieldToLock1);         
sig1.SetSigFieldLock(pdfSigFieldLock1); // 改用官方方法设置锁
form.AddField(sig1);

// 创建第二个签名字段并设置锁定规则
var signatureRectangle2 = new iText.Kernel.Geom.Rectangle(36, 248, 200, 100);
var signatureField2 = new SignatureFormFieldBuilder(pdf, "SignField2");
signatureField2.SetPage(newPage);
signatureField2.SetWidgetRectangle(signatureRectangle2);
PdfSignatureFormField sig2 = signatureField2.CreateSignature();

PdfSigFieldLock pdfSigFieldLock2 = new PdfSigFieldLock();         
string[] fieldToLock2 = new string[] { "TextFormField2" };
pdfSigFieldLock2.SetFieldLock(PdfSigFieldLock.LockAction.INCLUDE,fieldToLock2);
sig2.SetSigFieldLock(pdfSigFieldLock2); // 改用官方方法设置锁
form.AddField(sig2);

更优实现方案 #

1. 封装通用字段创建方法：避免重复代码，提升可维护性

// 通用文本字段创建方法
private static TextFormField CreateTextField(PdfDocument pdf, PdfAcroForm form, PdfPage page, string fieldName, Rectangle rect)
{
    var builder = new TextFormFieldBuilder(pdf, fieldName)
        .SetPage(page)
        .SetWidgetRectangle(rect);
    var field = builder.CreateText();
    form.AddField(field);
    return field;
}

// 通用签名字段创建方法（带锁定规则）
private static PdfSignatureFormField CreateSignatureFieldWithLock(PdfDocument pdf, PdfAcroForm form, PdfPage page, string fieldName, Rectangle rect, string[] fieldsToLock)
{
    var builder = new SignatureFormFieldBuilder(pdf, fieldName)
        .SetPage(page)
        .SetWidgetRectangle(rect);
    var sigField = builder.CreateSignature();
    
    if (fieldsToLock != null && fieldsToLock.Length > 0)
    {
        var lockObj = new PdfSigFieldLock();
        lockObj.SetFieldLock(PdfSigFieldLock.LockAction.INCLUDE, fieldsToLock);
        sigField.SetSigFieldLock(lockObj);
    }
    
    form.AddField(sigField);
    return sigField;
}

调用示例：

// 创建文本字段
var textField1 = CreateTextField(pdf, form, newPage, "TextFormField1", new Rectangle(100, 800, 200, 20));
var textField2 = CreateTextField(pdf, form, newPage, "TextFormField2", new Rectangle(100, 700, 200, 20));

// 创建带锁定的签名字段
var sigField1 = CreateSignatureFieldWithLock(pdf, form, newPage, "SignField1", new Rectangle(36, 448, 200, 100), new[] { "TextFormField1" });
var sigField2 = CreateSignatureFieldWithLock(pdf, form, newPage, "SignField2", new Rectangle(36, 248, 200, 100), new[] { "TextFormField2" });

2. 确保文档结构完整性：关闭文档前调用form.FlattenFields(false)（不扁平化字段，保留交互性），确保表单字段属性正确写入，避免阅读器解析异常：

form.FlattenFields(false);
pdf.Close();

内容的提问来源于stack exchange，提问作者Dorian