一、问题背景:填个表咋就这么费劲

做帆软报表开发的人,十有八九都跟数据填报打过交道。填报功能用起来确实方便,用户打开网页,往表格里敲数据,点一下提交,数据就进库了。但方便归方便,真出了问题,排查起来能让人挠头。

我最近就遇到一个特别典型的坑:表单里有两组校验规则,单独跑都没事,合在一起就提交失败,而且报错信息模棱两可,说“数据校验未通过”,但具体是哪一条没过,压根看不出来。用户急,开发更急。

这其实不是个别现象。帆软的填报校验逻辑,默认是“所有校验通过才允许提交”,一旦多条规则之间产生冲突——比如一条规则要求某个字段必填,另一条规则又要求该字段在特定条件下必须为空——那么用户不管怎么填,总有一方校验会挂掉。提交按钮变成灰色,或者点击后弹出错误提示,但又不告诉你到底该改哪里。

二、冲突根因:为啥两条规则会打架

2.1 帆软填报校验的执行机制

帆软填报页面里,校验规则通常分两类:一类是前端JS校验,在单元格的“事件”里写脚本;另一类是数据字典或内置的“数据校验”配置,由帆软引擎在提交前统一跑。这两类校验默认是“AND”关系,也就是全都得通过。

问题就出在“全都得通过”上。如果你在JS里写了一个判断,又在配置里写了一个相反的逻辑,那等于让用户同时满足两个互相排斥的条件。

2.2 常见的三种冲突模式

第一种:必填与条件可空。A规则说“客户姓名必填”,B规则说“当客户类型为‘个人’时,客户姓名允许为空”。这两条直接对立。

第二种:联动字段的先后顺序。比如“选择省份后,城市必填”,但如果你在JS里判断城市非空时才允许选择省份,那用户先选城市,省份还没选,校验就报了“省份必填”,用户只能先选省份,结果城市又没选,又报“城市必填”,死循环。

第三种:提交时机不一致。有的校验绑定在单元格失去焦点时触发,有的绑定在提交前。焦点校验通过,不代表提交时还通过,因为用户可能在中间改过其他字段,导致关联数据变了,但焦点校验没重新跑。

2.3 报错信息的迷惑性

帆软默认的校验失败提示,通常只显示“校验未通过”或“数据不完整”,并不会自动定位到具体单元格。就算你写了自定义提示,如果多个规则同时失败,帆软只会弹出第一条失败的提示,后面几条被吞掉。你修好第一条,再提交,又弹出第二条,用户来回试,体验极差。

三、解决方案:把校验逻辑收拢到一处

3.1 核心思路:单一校验入口,合并规则再执行

不要再把校验散落在各个单元格的事件里。统一在“提交”按钮的点击事件(或者帆软的“数据校验”配置)中,写一个完整的校验函数。这个函数里,把所有规则按优先级排列,逐条检查,一旦发现失败,就收集所有失败信息,一次性展示给用户,同时高亮对应单元格。

这样做的最大好处是:规则之间不再各自为政,你可以在同一个函数里,用条件判断来消除冲突。比如,当“客户类型”为“个人”时,直接跳过“客户姓名必填”的检查,这样两个规则就不再打架了。

3.2 实战示例:用JavaScript实现统一校验

我们采用的技术栈是 JavaScript(帆软填报前端脚本),以下所有代码均在帆软报表的“提交按钮”事件中执行。

// 帆软填报 - 统一校验入口
// 技术栈:JavaScript(帆软前端脚本)

// 1. 定义一个数组,存放所有校验规则
// 每条规则包含:检查函数、失败时的提示信息、需要高亮的单元格名称
var validationRules = [
  {
    name: "客户姓名必填",
    check: function() {
      // 获取“客户姓名”单元格的值,假设单元格名称为“A2”
      var name = this.getValue("A2");
      // 如果客户类型为“个人”,跳过该规则,避免与下面的条件可空规则冲突
      var type = this.getValue("B2");
      if (type === "个人") {
        return true; // 直接通过
      }
      return name != null && name.trim() !== "";
    },
    errorMsg: "客户姓名不能为空(非个人客户时必填)",
    cell: "A2"
  },
  {
    name: "城市必填(当省份已选)",
    check: function() {
      var province = this.getValue("C2");
      var city = this.getValue("D2");
      // 如果省份没选,就不校验城市,避免“省份先选”的死循环
      if (province == null || province === "") {
        return true;
      }
      return city != null && city.trim() !== "";
    },
    errorMsg: "请选择城市",
    cell: "D2"
  },
  {
    name: "金额范围校验",
    check: function() {
      var amount = parseFloat(this.getValue("E2"));
      if (isNaN(amount)) {
        return false; // 金额必须为数字
      }
      return amount >= 0 && amount <= 100000;
    },
    errorMsg: "金额必须在0到100000之间",
    cell: "E2"
  }
];

// 2. 执行所有规则,收集失败信息
var failedRules = [];
for (var i = 0; i < validationRules.length; i++) {
  var rule = validationRules[i];
  // 注意:这里的this指向当前填报对象,具体取决于帆软的脚本上下文
  // 实际开发中,需要根据帆软API调整取值方式,这里用抽象写法演示
  if (!rule.check.call(this)) {
    failedRules.push({
      msg: rule.errorMsg,
      cell: rule.cell
    });
  }
}

// 3. 如果有失败项,统一提示并高亮单元格
if (failedRules.length > 0) {
  // 构建错误提示信息,将所有失败原因拼起来
  var errorText = "提交失败,请检查以下内容:\n";
  for (var j = 0; j < failedRules.length; j++) {
    errorText += "- " + failedRules[j].msg + "\n";
    // 高亮对应单元格,假设使用帆软的单元格高亮API
    this.highlightCell(failedRules[j].cell); 
  }
  // 弹出提示框,替代默认的模糊提示
  alert(errorText);
  // 中断提交流程,阻止数据入库
  return false;
} else {
  // 所有校验通过,继续执行提交逻辑
  // 实际提交代码由帆软自动处理,这里只需返回true
  return true;
}

上面这段代码的关键点在于,把每一条规则都写成了独立的 check 函数,并且用 failedRules 数组收集所有失败原因。这样即使多条规则同时失败,用户也能一次性看到所有问题,不用反复提交、反复试错。

同时,在规则内部,我们通过判断前置条件来避免冲突。比如“客户姓名必填”这条规则,先判断客户类型是否为“个人”,如果是,就直接返回 true,不再强制要求姓名非空。这样,原来两条互相矛盾的规则就变成了有优先级的条件校验,用户只需要按照逻辑填一次就能通过。

3.3 更优雅的做法:使用“先决条件”机制

上面的示例已经解决了基本冲突,但在实际项目中,规则可能会更复杂。我们可以把规则设计成“先决条件+检查”的结构,让每条规则都知道自己什么时候该生效。

// 帆软填报 - 带先决条件的规则校验
// 技术栈:JavaScript(帆软前端脚本)

// 定义规则工厂函数,支持传入先决条件
function createRule(ruleName, precondition, checkFn, errorMsg, cellName) {
  return {
    name: ruleName,
    precondition: precondition,  // 返回true时,该规则才生效
    check: checkFn,
    errorMsg: errorMsg,
    cell: cellName
  };
}

// 规则集
var rules = [];

// 规则1:客户姓名必填(仅当客户类型不是“个人”时生效)
rules.push(createRule(
  "客户姓名必填",
  function() {
    // 获取客户类型
    var type = this.getValue("B2");
    return type !== "个人";  // 先决条件:非个人客户
  },
  function() {
    var name = this.getValue("A2");
    return name != null && name.trim() !== "";
  },
  "客户姓名不能为空",
  "A2"
));

// 规则2:城市必填(仅当省份已选时生效)
rules.push(createRule(
  "城市必填",
  function() {
    var province = this.getValue("C2");
    return province != null && province !== "";
  },
  function() {
    var city = this.getValue("D2");
    return city != null && city.trim() !== "";
  },
  "请选择城市",
  "D2"
));

// 统一执行
var errors = [];
for (var i = 0; i < rules.length; i++) {
  var r = rules[i];
  // 先判断先决条件,如果不满足,直接跳过
  if (!r.precondition.call(this)) {
    continue;
  }
  // 满足先决条件,执行检查
  if (!r.check.call(this)) {
    errors.push(r.errorMsg);
    this.highlightCell(r.cell);
  }
}

if (errors.length > 0) {
  // 显示所有错误信息,用换行分隔
  alert("请修正以下问题:\n" + errors.join("\n"));
  return false; // 阻止提交
}
return true; // 允许提交

这种写法的好处是,先决条件清晰可见,每个规则单独维护,后续新增规则时只需要往数组里 push 一条就行,不用改动其他逻辑。而且当规则很多时,这种结构一目了然,再也不会出现“改了A规则导致B规则失效”的连锁反应。

四、技术优缺点与注意事项

4.1 优点

第一,冲突消除彻底。所有规则在同一个作用域内,可以互相引用变量和条件,不存在先后顺序导致的死锁。

第二,错误提示友好。一次性列出所有问题,用户不用猜,开发也不用为了看全错误而反复测试。

第三,维护成本低。新增或修改规则,只需改动数组中的一个对象,不影响其他规则。

第四,兼容帆软原有能力。不需要修改帆软底层配置,只需在提交事件中覆盖默认校验,风险可控。

4.2 缺点

第一,需要熟悉帆软的单元格取值API。不同版本的帆软,获取单元格值的方法可能略有不同,需要查阅对应版本的手册。

第二,如果填报页面非常复杂(比如几百个单元格),把所有校验写在一个函数里会导致函数过长,可读性下降。建议按业务模块拆分多个函数,再统一调用。

第三,高亮单元格的API依赖帆软版本,某些旧版本可能不支持 highlightCell,需要替换为给单元格添加背景色等其他方式。

4.3 注意事项

首先,务必确保“先决条件”本身不依赖被校验字段的当前值,否则会形成递归判断。比如,不要写“当城市为空时,城市必填”这种自相矛盾的条件。

其次,在提交事件中返回 false 只能阻止本次提交,但不会自动清除之前的失败状态。如果用户修正了数据再次点击提交,需要重新执行整个校验逻辑,所以校验函数应当是无状态的——每次执行都从头开始。

第三,对于异步校验(比如调用接口校验数据是否重复),不能简单返回 false 或 true,而要用回调或 Promise 方式处理。帆软的提交事件支持异步,但需要确保在异步结果返回后再决定是否继续提交,否则会出现“校验还没跑完,提交已经发出去了”的竞态问题。

第四,不要为了省事而关闭帆软自带的“数据校验”配置。如果你在JS中写了统一校验,又保留了帆软配置里的校验,两者会叠加,可能导致重复报错。正确的做法是:要么只用JS,要么只用配置,二选一,千万不要混用。

第五,测试时要覆盖所有分支。尤其是先决条件为 true 和 false 的情况,以及规则中每个字段为 null、空字符串、空格、非数字类型等边界值。很多冲突都是在边界条件下才暴露出来的。

五、文章总结

数据填报是帆软产品里最常用也最容易出问题的地方。表单校验逻辑冲突,看似是配置问题,本质上是规则之间的耦合度过高。通过把散落在各处的校验规则统一收拢到一个入口,用“先决条件”来控制每条规则的生效时机,不仅解决了提交失败的问题,还大大提升了用户体验。

如果你手头也遇到了类似的“校验不过”情况,不妨试试把校验逻辑集中写一遍,把所有错误一次性抛出来。相信我,用户会感谢你的,开发也会感谢你——至少不用再反复点“提交”来试错了。

最后再提醒一句:帆软版本更新频繁,API可能会有调整。写代码之前,先确认你项目所用版本的正确取值方法,避免辛辛苦苦写完,结果因为一个API不兼容而前功尽弃。