单据开发前端指导文档

一、相关说明

1、单据模板、上级模板、父级模板

指代【配置平台-基础配置-单据模板】中配置的模板，由产品开发内置并维护，其余人员不能也不允许修改。

2、单据设计、子级模板

指代【配置平台-基础配置-单据配置】配置的单据，所有人员可对当前单据进行相关配置。

3、动态展示、动态必填、动态编辑填写规则

目前支持两种格式的解析。

运算符号（action）可选范围为（持续更新）：

action	说明
>	code 大于 value
<	code 小于 value
=	code 等于 value
<>	code 不等于 value
>=	code 大于等于 value
<=	code 小于等于 value
in	value包含code，其中value用 ^ 分割（3.6及以上版本才支持）
nin	value不包含code，其中value用 ^ 分割（3.6及以上版本才支持）

【method】可选范围为：

method	说明
some	数组格式中没有method的值，其默认值为 some,表示有一个满足即成立
every	conditions中所有条件都满足才成立

4、展示、编辑、必填控制规则

3.8.4 及以上版本控制字段展示、编辑、必填逻辑 (fieldDynamicConfig.js/getDynamicConfig)

3.8.3 及以前版本控制字段展示、编辑、必填逻辑

二、配置说明

页面入口：配置平台-基础配置-单据配置，页面点击【单据设计】按钮，进入单据配置页面。

页面展示如下

2.1 区域配置

2.1.1 基本配置

1. 区域类型

选项范围：表格、表单、模板。

pc端：表格、表单内容已经内置，区域类型为模板时，需要通过代码控制页面展示内容。

移动端：表格、表单区域样式没有区分。区域类型为模板时，产品代码内置了卡片样式来展示模板类型的区域，有需要时，同样可以通过修改代码控制页面展示内容

注：pc端由于历史设计缺陷（计划在3.8后续版本中逐步解决），模板类型的区域无法触发字段必填、计算、前置、后置等事件，如果有相关需求，应该避免配置区域类型为【模板】。

2. 新增行、删除行：勾选配置后，页面出现【新增】、【删除】操作按钮

3. 编辑非本人创建的行、删除非本人创建的行：用于控制，当提单人A提交单据至业务审批人B处，审批人B有单据编辑权限时，是否可以编辑/删除提单人A填写的行。

注：当【单据模板】没有勾选该配置时，【单据设计】页面即使没有勾选此配置项，此配置默认值是true，即可以编辑/删除非本人创建的行。当【单据模板】勾选了该配置项，【单据设计】取消勾选时，不允许编辑/删除非本人创建的行。

4. 必填：勾选配置，操作区域上的删除按钮，删除至最后一行时，会保留一行空行（带默认值），即区域行不会被删空。

5. 默认数据：勾选配置，新增单据时，如果区域内有字段设置了默认值或者有金额类字段（金额类字段本身带有默认值逻辑），会添加一行数据，且数据带默认值。区域没有勾选该配置时，区域内字段配置了默认值只有在用户手动新增行时才会生效。

6. 保存成模板：勾选后，页面左侧【区域模板】处会出现一个可拖动的区域，将区域拖动至单据页面，可快速新增区域。

7. 预算控制：配置项与【配置平台-基础配置-单据配置-关联配置-预算控制配置】结合使用，配置完成后，进行预算控制。

8. pc端配置-新增并复制：控制pc端页面区域【新增并复制】操作按钮的展示

9. 移动端配置-移动端展示：控制该区域是否在移动端展示

2.1.2 高级配置

1. pc端配置-初审编辑：财务初审时是否可以新增/删除行

2. pc端配置-填单导入、区域导出：勾选后，填单时可以【下载模板导入区域数据】、【导出区域数据】

3. pc端配置-显示借款余额：区域展示个人借款余额

4. pc端配置-查看发票：勾选后，非填单环节，区域展示【查看发票】按钮，点击可弹窗查看发票区数据

5. 空行展示：区域没有行时，是否展示区域头。不勾选区域没有数据时不会展示该区域，勾选后，即使区域没有数据，也会展示一个区域头

6. 显示汇总：区域类型为表格的区域有效，控制是否在表格下方展示区域汇总行

7. 生成凭证：控制区域是否生成凭证（后端），控制财务节点凭证相关按钮的展示（前端）

8. 核销类型：根据【系统管理-系统字典-全局字典-是否开启单据生成/关联台账配置】，展示不同的配置内同

● 未开启台账配置器：预置了可核销台账的类型，勾选后，区域出现【我要核销】按钮，点击按钮弹窗中出现在配置页面勾选了的台账类型数据。

● 开启台账配置器：可结合【配置平台-基础配置-台账配置】，自定义需要配置的台账类型、填单页面核销弹窗中展示的字段、台账赋值单据区域和字段的规则、台账数据回写规则。注：收入报账单模板只支持行核销

9. 冲销类型：预置了可冲销台账的类型，勾选后，区域出现【我要冲销】按钮，点击按钮弹窗中出现在配置页面勾选了的台账类型数据

10. 动态展示：区域满足动态展示规则时才会展示。当区域配置了动态展示规则，且控制由展示到不展示时，区域数据会被清空。如果区域配置了动态展示规则但是展示状态没有发生过改变时，区域数据不会被清空。

11. 动态名称：满足配置的规则时，可以展示对应的名称，配置规则类似于【动态展示、动态必填、动态编辑填写规则】，同时有一点不同。

单据应用实例：应收应付转移单-原应收明细区等。

{"原应付明细区":[{        
    "code":"boeHeaderChild.transferType",        
    "value":"PAYABLE"    
  }]
}

12. 目标公式：当前区域只有一行数据时，根据公式的计算结果A，赋值给该区域中第一个勾选区域汇总的金额字段。如下图中，会把【apportion.expenseAmount金额加总】- 【boeExpenseCavDTOs.cavAmount金额加总】- 【cost.expenseAmount金额加总】的计算结果，赋值给只有一行时的支付区的【支付金额字段】。

注：公式中出现了 cost.expenseAmount.1 这种格式的数据，与字段的【分类汇总】配置有关，见下文【字段配置-分类汇总】详细描述。

2.2 字段配置

2.2.1 基本配置

1. 字段编码：必须，任何字段如果【字段编码】没有值，都是有问题的

2. 字段类型：必须

3. 数据源：选择类字段可进行配置，数据来源为【系统管理-预设数据源】。如需修改，请参考后端单据开发文档

4. 占位：值为1时，表示该字段占一行 1/4 的宽度

5. 数据范围：规定该字段可选择/可输入的数据范围，填单时字段值如果不输入数据范围内，会被校验住，弹窗提示 “区域A第X行字段B字段值超出规定范围，请检查后提交！”

6. 级联：待补充

7. 说明：字段占位提示语（placeholder）

8. 默认值：非选择类字段可配置。优先级低于【高级配置-默认值】，仅允许设置常量（字符串），不能输入字段。

9. 默认选项：选择类字段可进行配置，填单时字段的默认值。（3.8版本以下，该配置项可能存在不生效的情况，3.8版本已修复）

注：单据配置页面，默认选项为自定义时，下面的选择框选中数据不能回显，是因为数据源 fieldSet 设置有问题。后续版本待解决

10. 格式校验：对字段的输入内容进行格式校验，数据来源为【系统管理-系统编码-全局编码-格式校验编码/BOE_FORMAT_CHECK】,在数据来源中的【备注】字段编写对应的正则表达式，在单据字段选择该条数据并重新发布模板即可。

注：目前校验提示语由于没有可配置的地方，需要前端代码手动填写每一条规则的提示语，后续需求需要优化，让校验提示语也取配置内容

11. 预览：

pc端：针对区域类型为表单的区域，操作按钮区有【展开/收起】操作按钮，勾选了预览的字段在【收起】状态展示，没有勾选预览的字段【收起】状态时不展示。

移动端：卡片形式展示区域行时，卡片中展示勾选了预览的前5给字段，全部字段需点击卡片【查看/编辑】按钮才能查看到

12. 清空：字段是否展示清空图标

13. 审批编辑：结合【基础配置-流程配置-流程组件权限配置】一起控制审批节点单据字段是否可编辑。详细控制规则见上文【展示、编辑、必填控制规则】

14. pc端配置-填单显示/编辑：控制字段在pc端是否展示、编辑，与动态展示、编辑、字段控制规则一起控制单据字段是否展示、编辑。详细控制规则见上文【展示、编辑、必填控制规则】

15. pc端配置-打印：打印规则为如下：

● 区域类型为模板的汇总区有数据就会打印

● 区域有数据，且区域内有一个字段勾选了【打印】才会打印

14. pc端配置-审核显示/审核编辑：控制字段在财务节点的展示、编辑权限。详细控制规则见上文【展示、编辑、必填控制规则】

15. 移动端配置-移动端展示/移动端编辑：控制字段在移动端的展示、编辑权限。详细控制规则见上文【展示、编辑、必填控制规则】

2.2.2 高级配置

1. 动态编辑、动态展示、动态必填：控制字段在的动态展示、编辑、必填权限。详细控制规则见上文【展示、编辑、必填控制规则】

2. 校验规则、警告规则：用代码内置了一些字段的校验规则。配置过于局限，建议使用【字段配置-基本配置-格式校验】进行配置

应用实例：

值	规则分类	说明
subsidyDays	校验规则	补贴天数。补贴天数必须为整数，且值不能大于明细行中maxSubsidyDay的值
subsidyAmount	校验规则	补贴金额。补贴金额不能大于明细行中maxSubsidyAmount的值
paymentAmount	校验规则	本次付款金额。核销金额不能大于未核销金额（waitCavAmount）
invoiceNo	校验规则	发票代码。最大长度为12位
invoiceCode	校验规则	发票号码。最大长度为8位
fileSize	校验规则	附件张数。大于0的正整数
writeOffAmount	校验规则	本次核销金额。不能大于未核销金额（waitCavAmount）
travelExpenseAmount	校验规则	差旅总金额。补贴金额不能大于标准金额（standardAmount * maxSubsidyDay）
theTerm	校验规则	大于0的正整数
mobile	校验规则	手机号码
collaborationExpenseAmount	校验规则	申请金额。大于0且不能大于剩余开票金额（waitCavAmount）
numberAndLetterAndSign	校验规则	只支持输入数字、字母、特殊字符

actualEmpNumber	警告规则	实际员工人数。不能大于empNumber
actualAmount	警告规则	实际数额。不能大于emolumentAmount
actualValue	警告规则	实际原值。不能大于propertyValue
actualArea	警告规则	实际面积。不能大于useArea
actualFrequency	警告规则	实际频次。不能大于behaviorFrequency
transportation	警告规则	交通工具。值在transportationStandard中
stayAmount	警告规则	住宿费。值小于stayStandardAmount * hotelDay
travelExpenseAmount	警告规则	差旅总金额。值小于standardAmount * hotelDay

3. 字段归类：后端保存值的位置

● 空值：存入数据库（数据库有字段的话）

● 存入缓存：字段放入单据明细行的extendMap（type: Object）字段中，后端从mongoDB的zfs_boe_header_extend, zfs_boe_header_child_extend, zfs_boe_line_extend 里面取extendMap的数据

● 存入备用字段：使用产品内置的备用字段存储值（字段编码为spareS），使用其余字段编码无效

4. 跳转模式：配置链接相关设置后，可跳转至相关链接

● 内链跳转：跳转当前域名下的地址，需要配置【跳转链接】和【链接参数】

应用实例：

● 外链跳转：3.8版本新增功能。根据配置规则跳转外部链接，支持取字段数据

5. 默认值：配置字段默认值，支持配置字段(${boeHeader.standardCurrency})。新增单据时，字段默认值会覆盖接口返回的值。非新增单据时，字段默认值不会覆盖接口返回的值

6. 拓展公式：可配置字段的计算公式。3.6及以上版本建议使用【计算公式】进行配置。配置参考：${cost.useCurrencyAmount}*${cost.rateValue} 。字段需要使用 ${} 包裹起来。同区域字段计算取同明细行的值进行计算，跨区域字段计算取第一行明细行的值进行计算。

注：头表区配置了【拓展公式】的字段是跨区域计算，所以只会计算第一行的值，单据底部汇总栏金额统计结果与【拓展公式】计算逻辑并不一致，所以不建议将头表区配置了跨区域【拓展公式】的汇总字段展示在填单页面。

7. 扩展配置：字段个性化配置, 可覆盖【字段配置】中所有配置项，配置JSON字符串示例

{  "show": "", // 覆盖【动态展示】配置，可用于清空动态展示  "labelCode": "fromSiteName", // 配置字段【展示编码】  "link": "/boe/#/billSSO", // 覆盖【跳转链接】配置  "linkParams": { // 覆盖【链接参数】配置    "boeNo": "cav_withholding.refBoeNo",    "groupId": "boeHeader.groupId"  }}

8. 计算公式：3.6及以上版本支持。文本、金额、数字类字段可进行计算配置。配置同区域或者跨区域的字段计算均取对应明细行的值进行计算。区域汇总、字段求和等可使用函数功能。

9. 变色规则：可设置字段的变色规则，当字段超标想要提示用户时，可以设置字段值大于某个金额时，字段背景色等变成显目的颜色。

10. 字段说明：3.8版本新增。

11. 单据汇总：头表区金额类字段可以配置，勾选勾配置【拓展公式】，单据底部会展示【拓展公式】配置的区域求和计算结果

12. 区域汇总：非头表区的金额类字段可以配置，勾选后区域头会展示区域内该字段金额的和

13. 分类汇总：非头表区的金额类字段可以配置。用于期望该字段的金额根据某一个字段分类计算结果。

如：期望日常费用报账单-发票区的【总金额】字段根据【是否商旅支付】字段的值分类计算，即能够获取【是商旅支付的金额求和】，【不是商旅支付的金额求和】等结果，就可以在【总金额】字段的【分类汇总】配置中填写【是否商旅支付】字段的字段编码（isPay）,isPay 的值有【1（是）、0（否）】两种，当在头表区配置拓展公式为 ${cost.expenseAmount.1} 时，就可以统计是商旅支付的金额求和。

2.2.3 数据源配置

选择类字段配置选择框的数据范围和赋值逻辑。

1. 展示编码：选择字段后在单据页面展示的字段值同时也是弹窗【我的收藏】中数据的展示值。正确的配置是所有选择类字段都有【字段编码】与【展示编码】，所有非选择类字段都不应该有【展示编码】。

注：由于 table-search 和 city 类型的字段设计的特殊性，【字段编码】与【展示编码】与其余字段是相反的，即这两个字段的【字段编码】是单据页面展示值，【展示编码】是绑定值（id）。

2. 前置字段：prev。配置的前置字段作为入参查询当前字段的数据源，当前置字段发生变化时，当前字段值会被清空

3. 后置字段：nextField。选中弹窗数据后对单据字段进行赋值，使用场景为跨区域字段赋值，如果时同区域字段赋值应该使用【字段转换（trans）】。

如：附加区的供应商字段选择完成后，需要将收款账户信息带入支付区。可进行如下配置，供应商字段选择完成后，支付区已有数据的收款账户信息均会更新，此时手动在支付区新增一行，其收款账户信息也是附加区供应商字段带出来的值

4. 字段转换：trans。选中弹窗数据后对同区域单据字段进行赋值。跨区域字段赋值需要使用【后置字段（nextField）】

5. lovKey: 弹窗组件调 /lov/getLovConfig?lovKey= 接口获取弹窗展示列、查询条件等配置

6. rowKey: 弹窗主键，没有配置时取【字段编码】，没有配置正确时，多选弹窗勾选数据会有问题（如勾选一条，但是选中的数据大于1条）

7. LOV接口：弹窗数据源请求后台接口地址

8. LOV配置：配置弹窗展示列、查询条件等

9. 静态参数：弹窗静态传参，可以传入常量，如下图过滤 "vendorType": "002" 的数据。该配置项与【前置字段（prev）】一起作为弹窗数据过滤条件查询过滤弹窗展示数据

注： tabs类型的字段中，存在公共的 static ，同时每个 tab 下可以存在各自的 static, 每个 tab 中的 static 的优先级更高，即会覆盖公共的 static

2.3 表单属性

2.3.1 校验规则

可以配置单据提交前的校验规则，根据配置内容，校验单据上的内容是否合规，不满足配置内容，则弹出配置好的警告/禁止提示框，警告/禁止用户提交单据

如果所示的配置含义是：当【发票区】所有【业务小类】字段值都包含【服务费】的值时，

校验【附加区】的【关联申请】字段不能为空，如果为空，则弹出禁止提示框，提示内容为”关联申请必填“。

配置说明：

（一）触发条件与校验内容为跨区域字段时，触发条件中跨区域字段的每一行都要满足条件才进行校验

（二）触发条件与校验内容为同区域字段时，满足触发条件的明细行，才进行校验

（三）校验内容中 SUM、SUMIF、COUNT等求和函数没有区域的概念，应该把函数运算结果看成一个常量进行处理，不适用上述【（一）, （二）】两条规则

（四）校验内容中除了AND、OR函数可以嵌套其他函数，其余函数均不能嵌套

（五）针对选择类字段，校验内容使用【字段编码】的值进行比较（计算公式使用【展示编码】的值参与计算）

（六）校验内容中的组织变量从单据头表区字段取值

（七） AND函数每一个参数都满足才是校验通过

（八） OR函数中，如果每个参数（表达式）都是同区域的字段，区域只要某一行满足OR中任意参数即校验通过。如果参数中存在不同区域的字段，则对每个表达式分开校验，某一个参数满足配置（区域每一行都满足这个参数配置）即校验通过

2.3.2 字段控制规则

可配置字段的展示、编辑、必填规则。配置优先级为：流程-组件权限 > 字段控制规则 > 动态展示、编辑、必填 > 单据展示、编辑、必填勾选项。具体控制规则参考上文【展示、编辑、必填控制规则】

下图配置为：当【附加区-收票方】字段值属于【地址测试001,资金供应商】时，不展示【支付区】的【收款账号】和【付款用途】字段

三、产品开发/项目二开

3.1 新增单据/区域（前端）

需要新增一个单据时，大致开发流程为：找到对应的单据文件进行开发 -> 对数据进行初始化 -> 监听数据变化执行相关逻辑 -> 单据提交校验

3.1.1 单据BOE文件

在 src\boeType 目录下的单据文件中进行开发，一般有两种方式（产品开发一般推荐使用第二种方式，便于后续开发和维护。项目二开视需求决定）

1. 如果是新增与现有单据逻辑类似的一张单，或是在已有的单据模板下新增一张单，在 src\boeType 目录下找到单据文件，开发相关逻辑。

2. 如果新增一张单据逻辑与现有单据大不相同的单据，在 src\boeType 目录下新建一个文件如 xxx_BOE，同时通知后端人员将这张单的 boeCategory 字段设置成单据 xxx_BOE ,然后在文件中开发相关逻辑

3.1.2 单据数据初始化

1. initData()：该方法在获取单据数据接口（initBoePage/editDraftBoe）后执行,常用于：

● 根据接口返回的头表区数据设置其他区域的默认值：如【费用归属区】币种、部门、核算主体、成本中心等数据默认取【头表区】币种、部门、核算主体、成本中心

● 根据接口返回的头表区数据，进行相关逻辑处理、控制区域展示等

2. this.$on('template-loaded', () => {}): 单据模板数据 template 获取完成后触发的事件，用于处理基于单据模板的相关逻辑

3.1.3 单据数据变化监听事件

为了便于二开，建议第二个参数使用函数名写法

3.8.4及以上版本：

this.$listen('bill.data.change', () => {}): 单据值变化时触发的事件
this.$listen('area.row.willChange', () => {}): 行即将变化事件
this.$listen('area.row.willChange', () => {}): 行已经变化事件

3.8.3 及以前版本：

1. this.$on('bill.label.change', () => {}): 单据 ['table-search', 'city'] 类型字段 labelCode 绑定值变化时触发的事件

2. this.$on('bill.data.change', () => {}): 单据字段fieldCode 绑定值发生变化触发的事件

3. this.$on('area.row.willChange', () => {}): 行变化前事件，使用场景：删除行前先删除改行关联的发票

4. this.$on('area.row.change', () => {}): 行变化后事件

5. this.$on('bill.row.change', () => {}): 行变化后事件, 推荐统一使用 area.row.change 事件

3.1.4 单据提交校验:

1. beforeSubmit(): 单据提交校验相关逻辑应该在改方法中实现，如金额等校验

2. projectCustomBoforeSubimt(): 开放给项目二开使用

3.2 单据数据流向

排查单据问题时，很头疼的一个问题是数据到底是怎么发生的变化。通过梳理常见的导致变化的场景，帮助排查问题。同时开发过程中应该遵守规范，使得数据流向更加清晰便于排查

3.2.1 单据数据变化

3.8.4及以上版本见：单据-数据流向与事件交互

3.8.3 及以前版本如下图所示：

pc单据数据流向.png

3.2.2 开发规范

待完善

（3.8版本）建议将单据数据相关操作统一到 billTemplate 层，调用 billTemplate/billCommon.js 中的单据数据操作方法去修改数据，而不是随意在组件中修改单据数据

目前 billCommon.js中有的单据数据操作方法：

● updateBoeData：更新单据数据（data[areaCode][rowIndex][fieldCode] = 'xxx'）

● addRowsMixin: 区域连续新增行,支持批量

● deleteRowsMixin：区域连续删除行，支持批量

● replaceAreaDataMixin：重置区域数据，先清空再赋值，取代常用的 data[areaCode] = data[areaCode].filter(() => {})

● replaceRowMixin: 替换指定行数据

● batchReplaceRows: 批量替换连续行数据

四、 FAQ

1. 项目如何清空产品单据配置中的配置项？

使用扩展配置，设置配置项key对应value为空值即可，如想清空某个字段的动态必填规则，可以配置扩展配置为 {"requireSet": ""}

F12选中配置项名称，就可以知道对应的key值，然后就可以在扩展配置中进行覆盖修改

单据开发前端指导文档

单据开发前端指导文档

关于作者

目录