DocuSign模板中多个复选框独立勾选方法

使用 DocuSign API 动态添加多个复选框时，若未为每个复选框设置唯一 TabLabel，系统会将其识别为同一逻辑控件，导致点击任一复选框时全部联动选中；正确做法是为每个 Checkbox 实例显式指定唯一的 TabLabel。

不少开发者在通过 DocuSign API 动态添加复选框时，都曾遇到同一个问题：明明在文档的不同位置放置了多个复选框，用户点击其中一个，所有框却同时被勾选。这个现象看似奇怪，但根源很清楚——控件的逻辑身份没有区分开。

在 DocuSign 体系中，AnchorString 只负责一件事：告诉系统“把控件放在文档的哪个位置”。而真正决定“这个控件是谁”的，是 TabLabel 字段。如果多个复选框共用同一个 TabLabel，或者都没有设置，DocuSign 就会把它们当作同一组互斥选项来处理，自然就出现了“一点全选”的联动效果。

因此，解决方案的核心只有一句话：给每个复选框一个独一无二的“身份标识”，也就是唯一的 TabLabel。

正确的实现代码

以下 C# 示例代码展示了如何正确构建多个独立的复选框。关键修复点已经标出：

List checkBoxes = new List();
for (int index = 1; index <= 21; index++)
{
    var clickCheckboxHere = new Checkbox
    {
        AnchorString = $"/cb{index}/",
        AnchorUnits = "pixels",
        // AnchorXOffset/AnchorYOffset 可留空（自动对齐）或按需设置偏移量
        TabLabel = $"checkBox{index}", //  关键修复：必须设置唯一 TabLabel
        TabGroupLabels = new List { $"checkBox{index}" }, // （可选）如需分组操作可保留，但非必需
        Shared = "false",
        Required = "false", // 根据业务需要设置
        Selected = "false" // 初始状态设为未选中
    };
    checkBoxes.Add(clickCheckboxHere);
}

必须留意的几个细节

仅仅修改代码还不够，理解背后的规则才能避免后续麻烦：

• TabLabel 是唯一性的核心：该字段不能为空、不能重复，也不能用 AnchorString 来代替。它是 DocuSign 后端识别控件的根本依据。
• TabGroupLabels 的作用不要混淆：这个属性用于定义标签组，例如将几个签名框归为一组。它不影响单个复选框的独立勾选行为，通常可按需设置或不设置。
• 小心历史模板中的“坑”：如果使用的模板中已存在同名的 TabLabel，可能会引发冲突。稳妥的做法是清理旧模板，或在命名时加入前缀（如 "template_cb_001"）来建立新的命名空间。
• 测试环节不能省略：建议先在创建信封时将状态设为 "created" 生成草稿，然后通过 DocuSign 的 Web 控制台预览表单，逐一点击确认每个复选框都能独立操作后，再正式发送。

让代码更优雅：数据驱动配置

如果复选框数量较多或配置复杂，可以考虑将配置信息抽象出来，使代码更清晰、更易于维护：

var checkboxConfigs = Enumerable.Range(1, 21)
    .Select(i => new { Index = i, Label = $"agreement_term_{i}", Anchor = $"/cb{i}/" })
    .ToList();

foreach (var cfg in checkboxConfigs)
{
    checkBoxes.Add(new Checkbox
    {
        AnchorString = cfg.Anchor,
        TabLabel = cfg.Label,
        // ... 其他属性
    });
}

按照上述思路调整后，那 21 个复选框就会彻底“解耦”。用户点击任何一个，都只会改变它自己的状态，完全符合预期的交互逻辑。说到底，DocuSign 的这套机制设计得很清晰，只要理解了 TabLabel 的核心作用，这类问题都能迎刃而解。