# 变更记录 | 产品版本 | 更新内容 | 更新日期 | | --- | --- | --- | | v6.0.1 | 新增了单选基础资料支持配置多行显示的功能，提升了用户体验 | 2023-10-27 | | v6.0.12 | 优化了基础资料字段，支持通过二开参数隐藏打开F7弹窗的图标，满足用户使用场景 | 2024-05-24 | | v7.0.1 | 优化了基础资料下拉面板高度自适应显示，提升阅读体验。新增无选项模式 | 2024-10-24 | # 1 功能介绍 封装了一组基础数据的字段，每条基础数据含有多个属性，是在F7中能够引用的企业基本资料，常见的物料、币别、科目都是基础资料的典型代表。 # 2 控件对象 `kd.bos.form.field.BasedataEdit` # 3 运行效果 基础资料字段支持以下几种效果： - **垂直**  - **水平**  - **模糊搜索**  - **下拉展示数据**  # 4 属性说明 ## 4.1 通用属性 >通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976) ## 4.2 样式属性 >样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336) ## 4.3 业务属性 | 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | 快捷新增 | 复选框 | true | 基础资料模糊查询无记录时显示快捷新增按钮，可快速新增基础资料数据，详见4.3.1 | | 基础资料类型 | 弹框选择 | | 配置关联的基础资料，必须配置 | | 使用组织 | 下拉 | - | 关联对应的组织基础资料，详见4.3.2 | | 编辑显示属性 | 弹框选择 | 编码 | 设置在编辑时基础资料的属性：编码（number）、名称（name）、编码+名称(number,name)、名称+编码(name,number) | | 显示属性 | 弹框选择 | 名称 | 设置基础资料显示的内容:编码（number）、名称（name）、编码+名称(number,name)、名称+编码(name,number) | | 引用属性 | 弹框选择 | - | 设置引用对应自己资料的属性，可以引用多个，详见4.3.3 | | 过滤条件 | 弹框选择 | - | 配置基础资料对应的过滤条件，详见4.3.4 | | 是否只显示启用 | 复选框 | true | 配置F7只显示启用的数据，默认开启 | | 显示风格 | 下拉 | 缺省 | 配置基础资料展示数据样式：缺省（0）、下拉（1） | | 缺省值 | 弹框选择 | | 配置基础资料默认值 | | 列表布局 | 弹框选择 | - | 配置列表布局信息,详见4.3.5 | | 查看详情 | 复选框 | true | 设置查看详情 | | 支持模糊查询 | 复选框 | true | 勾选后开启模糊查询功能，输入时可以匹配基础资料数据 | | 启用我的常用 | 复选框 | false | 开启常用功能，详见4.3.6 | | 为空提示信息 | 文本 | - | 当字段内容为空时，输入框内显示的信息 | | 编辑风格 | 下拉 | 按钮+文本编辑 | 编辑风格有两种：按钮+文本编辑和按钮点击编辑, 默认是按钮+文本编辑模式 | | 按钮图标 | 弹框选择 | - | 基础资料后面的按钮图标 | | 多行 | 复选框 | false | 开启多行属性后，单选基础资料可以换行显示 | ### 4.3.1 快捷新增 开启快捷新增属性，可快速跳转到新增基础资料数据界面进行添加，提高便利性  ### 4.3.2 使用组织 设置使用组织，用于明确引用基础资料的使用主实体，进行数据管控。 在业务层面，基础资料作为业务规则、政策的主要载体，而在系统层面主要体现方式则是通过基础资料的数据管控达到这一目标。 在我们创建基础资料时，系统会记录基础资料的两个关键信息：创建组织与使用组织。基于创建组织我们可以进行纵向的数据管控，即哪些组织可以创建、管理、分配这个基础资料。**而基于使用组织我们可以进行横向的数据协同，即哪些数据可以使用这个基础资料**。所以我们在创建单据时，需要明确引用基础资料的使用主体组织，**配置后，则会依据此使用组织来进行基础资料的数据过滤**。 ### 4.3.3 引用属性 引用属性用于选择基础资料表单中想要携带引用的字段，用于之后的计算和赋值。配置引用属性字段后，可以在单据的业务规则中选择“携带基础资料属性到指定列”，则可以携带已引用的基础资料源字段到目标字段。 举例：引用了基础资料的单价字段，携带给单据体的单价字段。  ### 4.3.4 过滤条件 过滤条件用于控制基础资料的可选范围。在过滤条件中可以对基础资料内的字段添加多条过滤规则，限定用户可选的基础资料。 示例：对基础资料中的单价进行数值过滤，可以得到更精确的基础资料可选范围。  ### 4.3.5 列表布局 列表布局用于对基础资料F7列表的布局选择（F7列表是指弹框列表，此处表示单据运行时点击基础资料字段的放大镜图标得到的弹框列表）。该项属性与基础资料类型关联，基础资料类型有多个布局时，F7列表将以单选按钮提供这些布局选择。  ### 4.3.6 启用我的常用 开启了我的常用，在没输入数据搜索的情况下会展示根据使用频次记录的历史记录  ### 4.3.7 无选项模式 v7.0.1 新增无选项模式属性。 通过二开写ks脚本插件进行设置 `isNoOptionMode` 属性。启用了无选项模式后，如果当前的字段风格为非下拉风格时，则隐藏图标、F7弹窗和模糊查询面板，进行精确匹配。 ``` afterBindData: function(e） { // 单头字段 var basedataField = this.getControl('basedatafield') this.getView().updateControlMetadata('basedatafield', { isNoOptionMode: true }) // 分录以及卡片 var clientViewProxy = this.getView().getClientProxy() clientViewProxy.invokeControlMethod('kdtest_entryentity', 'setColEditorProp', ['basedatafield2', 'isNoOptionMode', true]) } ``` # 5 基础资料接口介绍 ## 5.1 控件编程模型 ### 5.1.1 控件编程模型定义 基础资料控件编程模型为BasedataEdit，派生自字段控件编程模型基类FieldEdit： ```java package kd.bos.form.field; public class BasedataEdit extends FieldEdit implements IFlexEdit, ICloseCallBack { ``` ### 5.1.2 控件方法清单 BasedataEdit，重写、添加了如下方法： | 方法 | 说明 | | --- | --- | | addBeforeF7SelectListener | 监听F7基础资料列表显示前事件 | | bindData | 界面刷新数据时，系统调用此方法：
生成绑定字段值到前端控件的指令 | | click | 用户点击基础资料字段前端控件上的按钮时，调用此方法：
显示F7基础资料列表 | | closedCallBack | F7基础资料列表界面关闭时，系统调用此方法：
接收F7列表返回的基础资料，填写到基础资料字段值中 | | getBindingValue | 输出用于前端控件显示的字段值，包括资料编码、名称 | | getDisplayProp | 基础资料字段显示的属性名，默认显示名称属性 | | getF7ComboList | 向前端输出基础资料模糊查询列表数据 | | getLookUpList | 用户在基础资料字段上，模糊查询，系统调用此方法：
到数据库搜索匹配的数据，输出到前端控件快捷列表上 | | getQFilter | 获取插件给基础资料字段设置的F7列表过滤条件，只取第一个条件 | | getQFilters | 获取插件给基础资料字段设置的F7列表过滤条件；
与设计器配置的过滤条件，分开存储，组合过滤 | | isShowUsed | F7基础资料列表，是否只显示未禁用的资料 | | setDisplayProp | 设置基础资料字段显示的属性名，默认为显示名称属性 | | setItemByIdFromClient | 基础资料模糊查询，用户选择了资料后回车，调用此方法：
把选择的资料填写到数据模型中 | | setItemByNumber | 按编码给基础资料赋值；默认使用内码赋值； | | setQFilter | 插件给基础资料F7列表，设置过滤条件 | | setQFilters | 插件给基础资料F7列表，设置过滤条件，多个条件组合 | ## 5.2 数据模型 ### 5.2.1 字段的属性对象 基础资料字段在主实体模型中，属性对象有两个： **PKFieldProp**：基础资料**主键属性对象**，属性名是基础资料字段标识 + “_id”； * PKFieldProp是抽象基类，需按照主键数据类型，选用合适的主键属性对象 * VarcharProp：字符型主键； * LongProp：长整型主键； * 暂时只支持字符型、长整型两种主键 **BasedataProp**：基础资料**属性对象**，属性名是基础资料字段标识； * 关联基础资料主实体对象RefEntityType，包含了下级属性对象； * 属性值存储引用的基础资料数据包； * 基础资料数据包中，包含了基础资料下级属性值； 如下代码，演示如何获取基础资料字段的两个属性对象（表单插件类节选）： ```java /** 单据头基础资料字段 */ private final static String KEY_BASEDATAFIELD = "basedatafield"; /** * 演示如何取字段的属性对象 */ private void demoFieldProp(){ // 基础资料字段，属性对象有两个： // 1. 存储基础资料内码，PKFieldProp的派生类型LongProp或VarcherProp类型 // 2. 存储基础资料引用数据包，BasedataProp 类型 // 方案一：使用数据模型的方法获取 BasedataProp basedataProp = (BasedataProp)this.getModel().getProperty(KEY_BASEDATAFIELD); PKFieldProp refIdProp = (PKFieldProp)basedataProp.getRefIdProp(); // 方案二：自行到主实体模型中获取 MainEntityType mainType = this.getModel().getDataEntityType(); basedataProp = (BasedataProp)mainType.findProperty(KEY_BASEDATAFIELD); refIdProp = (LongProp) basedataProp.getRefIdProp(); } ``` ### 5.2.2 基础资料主键属性对象（PKFieldProp） * **主键属性对象基类 (PKFieldProp)** PKFieldProp类型，派生自字段属性对象基类FieldProp： ```java package kd.bos.entity.property; public class PKFieldProp extends FieldProp { ``` * **字符型主键属性对象 (VarcharProp)** VarcharProp派生自PKFieldProp，重写了数据类型方法getDbType，返回Types.VARCHAR： ```java package kd.bos.entity.property; public class VarcharProp extends PKFieldProp { ``` * **长整型主键属性对象 (LongProp)** LongProp派生自PKFieldProp，重写了数据类型方法getDbType，返回Types.BIGINT： ```java package kd.bos.entity.property; public class LongProp extends PKFieldProp { ``` ### 5.2.3 基础资料属性对象 (BasedataProp) BasedataProp属性对象，派生自ORM复杂属性对象基类DynamicComplexProperty： ```java package kd.bos.entity.property; public class BasedataProp extends DynamicComplexProperty implements IFieldHandle, IValidatorHanlder,IBasedataField { ``` * **BasedataProp的方法清单** | 方法 | 说明 | | --- | --- | | applyDefaultValue | 表单新建数据包，调用此方法：
解析默认值配置，填写默认值 | | buildCoreFilter | 根据字段过滤条件配置，构建F7列表过滤条件 | | buildCoreFilterByString | 根据字段过滤条件配置，构建F7列表过滤条件 | | createEntityTreeNodes | 构建单据列表设计器，字段树 | | createEntityTreeNodes | 构建单据列表设计器，字段树 | | createFilterField | 构建过滤字段 | | createFilterFields | 构建过滤字段，含引用属性的过滤字段 | | getBaseEntityId | 取引用的基础资料类型 | | getBindingBasedataValue | 构建用于前端控件的字段值；
含编码、名称两种属性值 | | getClientType | 输出引用属性的前端控件类名 | | getCompareGroupID | 输出字段的比较符号组别Id | | getCompareProp | 输出一个属性对象，基于此属性的值，判断字段有没有录入；
基础资料字段，输出主键属性 | | getCompareTypes | 输出字段使用的全部比较符号 | | getComplexType | 输出引用的基础资料主实体，内含下级引用属性 | | getDbType | 输出数据库物理字段类型：
基础资料字段取主键类型 | | getDefaultCompareTypeId | 常用过滤，选择一个值时，采用的比较符号Id | | getDefaultMultiCompareTypeId | 常用过滤，选择多个值时，采用的比较符号Id | | getDefValue | 输出字段设计时默认值；
需要在运行时动态解析 | | getDisplayProp | 基础资料显示的属性名，默认为名称 name | | getDisplayValue | 从传入的基础资料数据包中，取显示的属性值 | | getDispProp | 输出基础资料显示的属性对象 | | getFilterControlType | 输出过滤字段类型；
基础资料字段输出basedata | | getListColumnDesc | 输出单据列格式化对象：
用于在单据列表，格式化字段值 | | getLookupProp | 输出模糊查询属性名 | | getNumberProp | 输出编码属性名 | | getNumbProp | 输出编码属性对象 | | getOrgProp | 输出关联的使用组织字段名 | | getPropertyType | 输出属性值类型：
DynamicObject | | getRefIdProp | 输出关联的主键属性对象 | | getValidators | 输出字段默认的校验器：
用于在保存、提交时验证字段值的合法性 | | getValueComparator | 输出字段录入校验判断匿名类：
默认使用主键的录入校验 | | isDbIgnore | 是否有对应的物理字段 | | isMustInput | 是否必录 | | isSysField | 是否系统自动生成的属性对象 | | setFieldValue | 设置字段值；
在设置值之前，进行必要的类型转换 | | setFieldValueForWebApi | Web API接口设置字段值；
接收的值格式不同，需先进行必要的格式转换 | | setValueFast | 快速设置字段值，同步设置主键属性值；
默认值类型为DynamicObject，不进行转换 | * **父类 DynamicComplexProperty 的方法清单** | 方法 | 说明 | | --- | --- | | getComplexType | 引用的基础资料主实体模型 | | getDynamicComplexPropertyType | 引用的基础资料主实体模型 | | getRefIdPropName | 主键属性名；
据此到父实体对象中，获取主键属性对象 | | getTableGroup | 拆分表 | | loadValue | 向数据包设置本属性值 | | setComplexType | 设置引用的主实体 | | setRefIdPropName | 设置主键属性名 | | setTableGroup | 设置拆分表 | * **祖类 DynamicProperty 的方法清单** | 方法 | 说明 | | --- | --- | | getAlias | 物理字段名
BasedataProp，此属性为null | | getDefaultValue | 字段默认值 | | getDisplayName | 字段的标题，支持多语言 | | getDTValue | 从动态对象中获取本属性值 | | getDTValueFast | 从动态对象中，快速获取属性值 | | getIsReadOnly | 是否只读
BasedataProp，此属性为ture | | getOrdinal | 属性对象在实体模型中的索引
据此从数组中快速获取属性值 | | getParent | 属性对象所在的实体对象 | | getPropertyType | 属性值类型
BasedataProp为DynamicObject | | getReadOnly | 是否只读 | | getValue | 从动态对象中获取本属性值 | | getValueFast | 从动态对象中，快速获取属性值 | | hasDefaultValue | 有没有设置默认值 | | isEmpty | 判断传入的数据包中，有没有填写本属性值 | | resetDTValue | 重置传入的数据包中本属性值 | | setDTValue | 向动态对象设置本属性值 | | setDTValueFast | 向动态对象快速设置本属性值 | | setValue | 向动态对象设置本属性值 | | setValueFast | 向动态对象快速设置本属性值 | * **高祖类 DynamicMetadata 的方法清单** | 方法 | 说明 | | --- | --- | | getName | 属性名称，默认为字段标识 | | isDbIgnore | 是否对应物理字段
BasedataProp，此属性为false | ### 5.2.4 字段值 与基础资料字段的属性对象对应，在表单数据模型中，基础资料字段，存储有两个字段值： * 引用的基础资料数据包：DynamicObject类型，包含了主键、编码、名称等下级属性值； * 基础资料主键：可能为String、Long两种类型； ### 5.2.5 字段值存取方法 如下示例代码，使用了多种方案，给基础资料字段取值、赋值： 方案1：利用表单数据模型存取字段值，在表单插件中，推荐此方案 方案2：利用属性对象，操作单据数据包，给字段赋值，这种方式适用于单据操作插件、单据转换插件等，这些场景，没有表单数据模型，只能自行操作数据包 方案3：直接操作单据数据包，不使用属性对象，不使用数据模型，不推荐：本示例仅为演示数据包中的基础资料字段值存储方式 ```java package kd.bos.plugin.sample.dynamicform.pcform.field.bizcase; import kd.bos.dataentity.entity.DynamicObject; import kd.bos.entity.MainEntityType; import kd.bos.entity.property.BasedataProp; import kd.bos.entity.property.LongProp; import kd.bos.entity.property.PKFieldProp; import kd.bos.form.plugin.AbstractFormPlugin; public class BasedataFieldSample extends AbstractFormPlugin { /** 单据头基础资料字段 */ private final static String KEY_BASEDATAFIELD = "basedatafield"; /** * 演示如何读取、设置字段值； * @param entryRow 单据体行号 * @param subEntryRow 子单据体行号 * @remark * 设置单据体字段，需要在参数中加上行号 */ private void demoFieldValue(int entryRow, int subEntryRow){ // 方案1：利用表单数据模型存取字段值 // 在表单插件中，推荐此方案 DynamicObject refBasedataObj = (DynamicObject) this.getModel().getValue(KEY_BASEDATAFIELD); Long refBasedataId = (Long) refBasedataObj.getPkValue(); this.getModel().setValue(KEY_BASEDATAFIELD, refBasedataId); // 赋值，传入基础资料主键 // 方案2：利用属性对象，操作单据数据包，给字段赋值 // 这种方式适用于单据操作插件、单据转换插件等，这些场景，没有表单数据模型，只能自行操作数据包 MainEntityType mainType = this.getModel().getDataEntityType(); BasedataProp basedataProp = (BasedataProp) mainType.findProperty(KEY_BASEDATAFIELD); DynamicObject billObj = this.getModel().getDataEntity(); // 演示用的字段在单据头上，调用这个方法，只取单据头数据包，够了 refBasedataObj = (DynamicObject)basedataProp.getValue(billObj); refBasedataId = (Long)basedataProp.getRefIdProp().getValue(billObj); basedataProp.setValue(billObj, refBasedataObj); // 赋值；这个方法内部会同步填写主键属性值 // 方案3：直接操作单据数据包，不使用属性对象，不使用数据模型（不推荐） refBasedataObj = billObj.getDynamicObject(KEY_BASEDATAFIELD); refBasedataId = (Long) refBasedataObj.getPkValue(); billObj.set(KEY_BASEDATAFIELD, refBasedataObj); billObj.set(KEY_BASEDATAFIELD + "_id", refBasedataId); // 这种方法赋值，必须同时填写主键值 } } ``` ## 5.3 插件事件 基础资料字段，继承了字段值改变事件，新增了如下插件事件： | 事件 | 触发时机 | | --- | --- | | beforeF7Select | 用户点击基础资料字段的按钮，打开基础资料列表前，触发此事件 | 请参考[beforeF7Select 事件](https://vip.kingdee.com/article/229260407297126144)。