如何通过DocuSign Apex Toolkit在添加Recipient前为Envelope添加Custom Tab？

核心结论 #

不能直接在不添加收件人的情况下为文档添加Custom Tab。因为DocuSign的自定义标签（包括dfsle.TextTab这类）从设计上就必须关联到具体收件人——标签是属于收件人的交互元素，系统需要通过收件人上下文来定位和渲染这些标签。

实现需求的替代方案 #

如果希望先添加所有合并字段并在添加正式收件人前查看效果，可以用以下两种方式：

1. 临时占位收件人过渡

创建一个临时的占位收件人，将所有Custom Tab关联到该收件人并添加到信封，此时就能预览文档中的字段显示效果。后续添加正式收件人时，再替换临时收件人并将标签重新关联到正式收件人。

修改后的示例代码：

// 创建临时占位收件人
dfsle.Recipient tempRecipient = dfsle.Recipient.fromSource(
    '临时用户',
    'temp@example.com',
    null,
    'TempRole', 
    null);

// 创建Custom Tab并关联到临时收件人
dfsle.TextTab tab5 = new dfsle.TextTab();
tab5.withDataLabel('Test');
tab5.withValue(UserInfo.getName());
List<dfsle.Tab> tabList = new List<dfsle.Tab>{tab5};
tempRecipient = tempRecipient.withTabs(tabList);

// 将临时收件人加入信封，此时可预览文档字段
myEnvelope = myEnvelope.withRecipients(new List<dfsle.Recipient>{tempRecipient});

// 后续添加正式收件人时，替换临时收件人
if(templateRecipientsJson != null){
    List<RecipientObject> templateRecipients = (List<RecipientObject>)JSON.deserialize(templateRecipientsJson, List<RecipientObject>.class);
    if(templateRecipients != null && templateRecipients.size() > 0){
        List<dfsle.Recipient> recipientList = new List<dfsle.Recipient>();
        for(RecipientObject obj :templateRecipients){
            dfsle.Recipient rec = dfsle.Recipient.fromSource(
                obj.name,
                obj.email,
                null,
                obj.role, 
                null).withTabs(tabList);
            recipientList.add(rec);
        }
        // 替换为正式收件人
        myEnvelope = myEnvelope.withRecipients(recipientList);
    }
}

// 发送信封
envelope = dfsle.EnvelopeService.sendEnvelope(envelope, false);

2. 使用信封/文档级自定义字段

如果你的需求是预填充内容（无需收件人交互），可以使用信封级自定义字段，这类字段属于信封本身，不需要关联收件人，且可以设置为在文档中显示，满足添加后查看的需求。

示例代码：

// 创建信封级字符串自定义字段
dfsle.StringCustomField envMergeField = new dfsle.StringCustomField();
envMergeField.withName('TestMergeField');
envMergeField.withValue(UserInfo.getName());
envMergeField.withShowInDocuments(true); // 开启在文档中显示

// 添加字段到信封
myEnvelope = myEnvelope.withCustomFields(new List<dfsle.CustomField>{envMergeField});

// 此时无需收件人即可查看信封中的预填充字段，后续可通过模板映射到文档指定位置

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