用户定义属性组与用户定义属性开发使用指南

用户定义属性组与用户定义属性开发使用指南版本维护人维护时间相关文档备注V60陈伟2009-07-07V6公共服务V60陈伟2009-11-12界面显示自定义项的方法变更V60陈伟2010-4-6为解决同一界面多个模板需要多次远程调用来实现用户定义属性显示问题、及一个界面需要显示多个实体的用户定义属性问题，提出container与preparator分离的设计方案，container负责远程杳询所有用户定义属性引用，界面可以配置多个preparator来显示用户定义属性V60陈伟2010-4-7自定义档案为参照时，需要按组织过滤1术语1.1用户定义属性即以前版本的自定义项。它的具体含义是指业务对象中预留若干字段，这些字段的数据类型是在系统运行期由用户定义的。在V6版本中，对字段可定义的数据类型进行了扩充：它可以是基本类型，如字符串、整数、数值（小数）、布尔、日期等；也可以引用系统预置档案、枚举或用户自定义档案。1.2用户定义属性组用户定义属性的集合升级用户定义属性组，即以前版本的自定义项对象。一个用户定义属性组有自己的编码、名称及包含用户定义属性的数量。抽象出用户定义属性组的目的，是为了允许多个业务对象引用同一组用户定义属性，以保证多个业务对象中的用户定义属性一一对应。如在采购流程中，希望采购单、入库单的自定义项一一对应，可以定义一个公共的“采购流程用户定义属性组”。用户定义属性组引用将一个业务对象关联到一个用户定义属性组，以表明这个业务对象的自定义字段的数据类型是由用户定义属性组中包含的用户定义属性所定义的，这时称业务对象与用户定义属性组间的关联关系为用户定义属性组引用。2设计概要2.1简单类图■PBillListPanelWrapperBillCardPanelWrappoemChangeListenerIUseBillCardPanelDefaultUserdefitemChan+用户定义属性组引用UserDefItemTools#initCardPanel()+getBillCardPanel():#initListPane()+getBillListPanel():BillListPaitemQryService丄istenerUserDefltemListTools+updateHeadItemByDef()+updateHeadItemByUserdefruleCode+updateHeadItemByUserdefruleName()+updateHeadMetaDataItemByDef()+updateBodyItemByDef()+updateBodyItemByUserdefruleCode)+updateBodyItemByUserdefruleName+updateBodyMetaDataItemByDef()()+updateHeadItemByDef()+updateHeadItemByUserdefruleCode+updateHeadItemByUserdefruleName()+updateHeadMetaDataItemByDef()+updateBodyItemByDef()+updateBodyItemByUserdefruleCode「■PBillListPanelWrapperBillCardPanelWrappoemChangeListenerIUseBillCardPanelDefaultUserdefitemChan+用户定义属性组引用UserDefItemTools#initCardPanel()+getBillCardPanel():#initListPane()+getBillListPanel():BillListPaitemQryService丄istenerUserDefltemListTools+updateHeadItemByDef()+updateHeadItemByUserdefruleCode+updateHeadItemByUserdefruleName()+updateHeadMetaDataItemByDef()+updateBodyItemByDef()+updateBodyItemByUserdefruleCode)+updateBodyItemByUserdefruleName+updateBodyMetaDataItemByDef()()+updateHeadItemByDef()+updateHeadItemByUserdefruleCode+updateHeadItemByUserdefruleName()+updateHeadMetaDataItemByDef()+updateBodyItemByDef()+updateBodyItemByUserdefruleCode「)+updateBodyItemByUserdefruleName+updateBodyMetaDataItemByDef()UserdefruleVO+用户定义属性组UserdefltemVO+用户定义属性:()图1用户定义属性类图3使用说明及API3.1元数据建模时设置自定义属性元数据建模时，如果该实体需要预留用户定义的属性，需要将该字段的数据类型设置为自定义项”，如图2所示属性I操作I业势接口属性映射「鬓照增加删，除'下移上移置顶置底名称 I扩展标签显示名称I类型样式类字段名称def6def6自SINGLE自def6def7自定萸项7SINGLE自靈琐def7def8自定僉项8SINGLEdef9自定购gSINGLEBLOB▲己fgdeflO自定辔项IQSINGLECLOB?fiodefll自罡SINGLEmflldefl2自定聂顼12SINGLE▼EflZdefl3自定烫项13SINGLE曰疋乂丄贝deflldefl4自定殖h斗SINGLE自定脚defl4白左:油佈CTMCI匚白帯卷侃图2元数据建模时指定字段数据类型为自定义项3.2创建用户定义属性组在“开发平台/开发配置工具”结点下有一个“用户定义属性组”结点，可在此结点创建和维护用户定义属性组，如图3所示。|St訳|首页"□开发平台我的币种我的人员日开发配置工具04系统管理工具功能注册集成平台工具田J模板管理BJ单据管理业务插件注册|用•户定义Jj性齟参数複板丘箜置自定义档案定义测试服务测试参照图3用户定义属性组结点打开结点后，左侧树显示的是现有的用户定义属性组。可以通过左侧树上方的按钮创建和维护用户定义属性组所在的模块，如图4所示。修改规则编码规则名称日afdsdasdasdasdasd引用规则的实体规则变更校验类名E模块tlCUSt客商基本信息酝custsale客商销售信息己material物料基本信息已materialsale物料销售信息修改规则编码规则名称日afdsdasdasdasdasd引用规则的实体规则变更校验类名E模块tlCUSt客商基本信息酝custsale客商销售信息己material物料基本信息已materialsale物料销售信息supplierclass供应商分类模块編码*|模块名称*| Start新増］首页用尸定义雇性蛆用户定义属性组用户定文雇性組关联用户定义雇性组删除刷新创建维护模块£保存|「取消图4创建维护用户定义属性组所在模块通过结点上方可创建和维护用户定义属性，如图5所示。图5创建维护用户定义属性组完成上述功能后，开发人员需要将生成的模块信息和用户定义属性组数据导入到基准库中，模块信息和用户定义属性组的数据记录在bd_userdefrule表中。创建用户定义属性组引用创建好用户定义属性组后，需要指定对该属性组的引用。在用户定义属性组结点中，选中一个用户定义属性组后，可在界面右下方的表体中为该属性组指定引用，如图创建好用户定义属性组后，需要指定对该属性组的引用。在用户定义属性组结点中，选中一个用户定义属性组后，可在界面右下方的表体中为该属性组指定引用，如图6所示。图6为用户定义属性组设置引用引用用户定义属性组的实体，是通过参照选择的，参照的范围是所有元数据实体。但需要注意的是，最终选择的引用实体必须有数据类型为“自定义项”的属性，并且“自定义项”属性的数量必须与前述用户定义属性组设定的用户定义属性数量相等。如图6所示，用户定义属性组“客商销售信息”设定的用户定义属性数量是30，则在为该属性组设置引用实体时，所中的实体“custsaleinfo”中必须有30个数据类型为“自定义项”的属性，否则系统不允许保存。开发人员可以在设置用户定义属性组引用时，为该引用设置变更校验类的类名，该字段不是必输的，如图7所示。该校验类应该实现nc.itf.bd.userdefrule.IUserdefitemChangeListener接口，当用户定义属性组中包含的用户定义属性发生变化时，会调用所有引用实体注册的校验类的校验方法(userdefitemChanged(UserdefitemVO,UserdefitemVO))。如果开发人员在指定引用实体时未指定变更校验类名，则在相应用户定义属性发生变化时按默认的校验规则进行校验。默认的校验规则如下：当某个用户定义属性变更时，如引用实体中的对应字段在数据库中的值不全部为空，则会抛出异常、不允许保存用户定义属性变更。规则编码custsale规则名称客商销售信息规则编码custsale规则名称客商销售信息用户定义雇性数量关联用户定义犀性组両用规则的实体规则变更校验类名1custsaleinfonc.impl.uap.bd.CustsalelnfoDefCheck1图7在引用实体时指定变更校验类的类名完成上述功能后，开发人员需要将生成的用户定义属性组引用数据导入到基准库中，用户定义属性组引用的数据记录在bd_userdefruleref表中。用户定义属性设置用户定义属性可以在全局设置，也可以在集团设置，分别对应“用户定义属性-全局”和“用户定义属性-集团”两个结点，如图8所示。

start苜页| 品企业連模平台田匚I田匚I田」i■+\:+:+JL田養数设詈R俊共信息

出急员信息地址信息客户信息供应帝信息检料信息财务会计信息结算信息业务信息项目信息目定义项用户定殳厘性-全局用户定义属性篠团H自定交档案定交自定殳裆案錐护-全局自定史档案维护-集团自定或档実维护空司数据导2资产信息任务中心流程平台編玛规则图8用户定义属性结点同一个用户定义属性，在全局设置后，在各集团均可见，并且各集团均不能修改；在任一集团设置后，在全局结点也不能修改，但全局结点中该属性设置仍为空。可以为用户定义属性设置显示名称、数据类型、输入长度和精度。数据类型是通过参照选择的，选择的范围是所有扩展标签带“DOC”标签的元数据实体或枚举，如图9所示。仅当数据类型是字符串、整数、数值时，可以设置输入长度；仅当数据类型为数值时，可以指定精度。

图9为用户定义属性设置数据类型3.5用户定义属性的界面显示当完成3.1.1、3.1.2、3.1.3步骤的设置后，希望在引用用户定义属性组的业务实体的界面中显示用户定义属性，这时需要开发人员在业务实体界面的初始化过程中，利用用户定义属性的显示工具对界面进行设置。3.5.1UI工厂中的处理方法在UI工厂的界面开发中，IControllerBase接口中有两个方法getHeadZYXKey()和getBodyZYXKey(),这两个方法允许用户分别指定表头关联的用户定义属性组名称和表体关联的用户定义属性组名称。只要用户在IControllerBase的实现类中指定了表头和/或表体的用户定义属性组名称,系统会自动查询相关用户定义属性组在当前登录集团的设置情况,并按前缀名“def”和“vdef”分别重置表头和表体的用户定义属性的显示设置。因此，如果业务对象的UI界面是UI工厂实现的、并且其中用户定义属性字段的前缀为“def”或“vdef”，则可以通过在IControllerBase实现类中指定用户定义属性组名称的方法，实现用户定义属性的界面展现。UI工厂中用户定义属性的界面展现代码样例如下：publicclassSaleOrederControllerimplementsICardController{©OverridepublicStringgetBodyZYXKey(){return"供应链-销售订单-表体"；}©OverridepublicintgetBusinessActionType(){returnIBusinessActionType.PLATFORM;}@OverridepublicStringgetChildPkField(){return"pk_saleorder_item";}@OverridepublicStringgetHeadZYXKey(){return"供应链-销售订单-表头"；}}3.5.2UI工厂II中的处理方法在UI工厂II中，主要的IEditor如BatchBillTable、BillForm、BillCardPanelForm都聚合了IBillData或IBillListData用于处理用户定义属性的展现。UI工厂II中，由于界面结构比较复杂，这里分以下几个场景分别描述用户定义属性展现的处理方法。（1） 简单界面简单界面，即单据模板的一个区域（表头或表体）仅展现一个用户定义属性组的用户定义属性（即不支持同一表头/表体展现两个不同用户定义属性组中的用户定义属性），并且该界面不支持动态扩展机制。为使简单界面展现用户定义属性，需要在界面的XML配置文件中显式的注射工具类UserdefitemBillDataPreparator或UserdefitemBillListDataPreparator,并为这两个工具类注射必要的属性，其中UserdefitemBillDataPreparator用于卡片界面（BillCardPanel）的用户定义属性展现、UserdefitemBillListDataPreparator用于列表界面（BillListPanel）的用户定义属性展现。如果当前界面的单据模板是由元数据生成的、并且仅主实体需要处理用户定义属性，则仅需为上述preparator设置context构造子参数即可（注意，context应包含正确的组织信息）。配置样例如下：<beanid="areaeditor"class="nc.ui.bd.cust.areaclass.view.AreaClassEditor"init-method="initUI"><property<property<property<beanname="model"ref="appmodel"></property>name="nodekey"><value>areaelass</value></property>name="userdefitemPreparator">class="nc.ui.uif2.editor.UserdefitemBillDataPreparator"><construetor-arg><refbean="eontext"/></eonstruetor-arg></bean></property></bean>如果当前界面的单据模板不是元数据生成的、或者要同时展现表头及表体的用户定义属性，则除需要为上述preparator设置context构造子参数外，还需要为其设置用户定义属性组的编码或名称、以及用户定义属性字段的前缀；如果需要在表体展现用户定义属性，还需要指定表体所在页签的页签编码。配置样例如下：<beanname="userdefitemPreparator"class="nc.ui.uif2.editor.UserdefitemBillDataPreparator"><construetor-arg><refbean="eontext"/></eonstruetor-arg><propertyname="headUserdefitemPrefix"value="zxy"/><propertyname="headUserdefruleName"value="人员档案"/><propertyname="bodyTabCodes"><list><value>psnjobs</value><value>psnfund</value></list></property><propertyname="bodyUserdefitemPrefixs"><list><value>def</value><value>vdef</value></list></property><propertyname="bodyUserdefruleNames"><list><value>人员任职信息</value><value>人员备用金</value></list></property></bean><!--卡控件--><beanid="billFormEditor"elass="ne.ui.bd.psn.psndoe.view.PsndoeEditor"init-method="initUI"><propertyname="userdefitemPreparator"ref="userdefitemPreparator"/></bean>（2） 需要同时展现多个实体的用户定义属性的界面场景1已经可以支持多数应用场景，但存在以下两点弊端：不支持同一表头/表体展现两个不同用户定义属性组中的用户定义属性如果需要展现多个用户定义属性组的用户定义属性，则需要多次远程调用来查询用户定义属性的引用情况。为了解决上述问题，场景2米用了UserDefItemContainer与UserdefitemContainerPreparator/UserdefitemContainerListPreparator配合

使用的方式在界面展现用户定义属性。UserDefItemContainer负责远程查询界面所需的所有用户定义属性组中用户定义属性的引用情况，UserdefitemContainerPreparator/UserdefitemContainerListPreparator从UserDefltemContainer中读取用户定义属性的引用情况，并做相应处理。首先需要为UserDefItemContainer注射环境变量context、和查询参数歹U表params。params是结构化参数，用于查询用户定义属性组，中需为每个参数指定用户定义属性组编码（rulecode）或实体元数据全名（mdfullname，即卩namespace.entityname）中的一个即可。这里不再支持按用户定义属性组名称查找用户定义属性组。之后，需要为每个iEditor配置相应的UserdefitemContainerPreparator或每个preparator必须指定对应的UserDefItemContainer每个preparator必须指定对应的UserDefItemContainer，另外还需要指定一个格式化参数列表，每个参数对应一个用户定义中参数的相应UserdefitemContainerListPreparator。属性组的展现，其中rulecode和mdfullname与UserDefItemContainer属性含义相同，并且前后要保持一致，以便preparator能根据参数从UserDefItemContainer读取用户定义属性的引用情况（如contain中参数指定的是rulecode,J则在之后的preparator中也应扌旨定rulecode，且值应相同）。一■个preparator可以有一组参数，因此可以展现多个用户定义属性组中的用户定义属性。配置样例如下：<beanid="userdefitemContainer"class="nc.ui.uif2.userdefitem.UserDefltemContainer"><propertyname="context"ref="context"/><propertyname="params"><list><beanclass="nc.ui.uif2.userdefitem.QueryParam"><propertyname="mdfullname"value="md1.entity1"/></bean><beanclass="nc.ui.uif2.userdefitem.QueryParam"><propertyname="rulecode"value="rulecode1"/></bean><beanclass="nc.ui.uif2.userdefitem.QueryParam"><propertyname="mdfullname"value="md2.entity2"/></bean><beanclass="nc.ui.uif2.userdefitem.QueryParam"><propertyname="rulecode"value="rulecode2"/></bean></list></property></bean><beanid="headEditor"class="nc.ui.uif2.editor.BillForm"init-method="initUI"><propertyname="userdefitemListPreparator"><beanid="userdefitemListPreparator"class="nc.ui.uif2.editor.UserdefitemContainerPreparator"><propertyname="container"ref="userdefitemContainer"/><propertyname="params"><list><beanclass="nc.ui.uif2.editor.UserdefQueryParam"><propertyname="mdfullname"value="md1.entity1"/><propertyname="pos"value="0"/><propertyname="prefix"value="def"/></bean><beanclass="nc.ui.uif2.editor.UserdefQueryParam"><propertyname="rulecode"value="rulecode1"/><propertyname="pos"value="0"/><propertyname="prefix"value="vdef"/></bean><beanclass="nc.ui.uif2.editor.UserdefQueryParam"><propertyname="mdfullname"value="md2.entity2"/><propertyname="pos"value="1"/><propertyname="prefix"value="zyx"/></bean><beanclass="nc.ui.uif2.editor.UserdefQueryParam"><propertyname="rulecode"value="rulecode2"/><propertyname="pos"value="1"/><propertyname="prefix"value="userdef"/></bean></list></property></bean></property></bean>（3） 支持动态扩展机制的界面上述两种方法均可实现动态扩展界面的用户定义属性展现,但方法一需要在扩展点和扩展页签分另U配置UserdefitemBillDataPreparator或UserdefitemBillListDataPreparator，这样会造成多次远程调用，因此在此场景下，建议使用场景2的方法，但这时需要在扩展页签中引用preprocessor,以便为UserDefltemContainer动态注射查询参数。扩展页签在preprocessor的初始化方法会在srpingbeans实例化之前调用，因此可以在UserDefltemContainer进行远程查询前动态收集所有页签用户定义属性的查询条件。配置样例如下：扩展点配置信息:<beanid="userdefitemContainer"class="nc.ui.uif2.userdefitem.UserDefltemContainer"><propertyname="context"ref="context"/><propertyname="params"><list><beanid="customerUserdefitemParam"class="nc.ui.uif2.userdefitem.QueryParam"><propertyname<propertyname="value="uap.customer"</bean></list></property></bean><beanid="baseinfoEditor"class="nc.ui.bd.cust.baseinfo.editor.CustBaseInfoEditor"init-method="initUI"><propertyname="userdefitemPreparator"><beanclass="nc.ui.uif2.editor.UserdefitemContainerPreparator"><propertyname="container"ref="userdefitemContainer"/><propertyname="params"><list><beanname="cardUserdefitemQueryParam"class="nc.ui.uif2.editor.UserdefQueryParam"><propertyname="mdfullname"value="uap.customer"/><propertyname="pos"value="0"/><propertyname="prefix"value="def"/></bean></list></property></bean></property></bean>扩展页签配置信息：<beanid="userdefitemFinancePreprocessor"class="nc.ui.uif2.editor.UserdefitemUIPreprocessor"init-method="init">

<propertyname="container"ref="userdefitemContainer"/><propertyname="params"><list><beanclass="nc.ui.uif2.userdefitem.QueryParam"><propertyname="mdclassname"value="uap.custfinance"/></bean></list></property></bean><beanid="custFinanceEditor"class="nc.ui.bd.cust.finance.view.CustFinanceEditor"init-method="initUI"><propertyname="userdefitemPreparator"><beanclass="nc.ui.uif2.editor.UserdefitemContainerPreparator"><propertyname="container"ref="userdefitemContainer"/><propertyname="params"><list><beanclass="nc.ui.uif2.editor.UserdefQueryParam"><propertyname="mdfullname"value="uap.custfinance"/><propertyname="pos"value="0"/><propertyname="prefix"value="def"/></bean></list></property></bean></property></bean>其中，扩展页签中的UserdefitemUIPreprocessor指定了对应的扩展点中的userdefitemContainer,并且指定了自己的查询参数。在扩展点的userdefitemContainer执行查询前，UserdefitemUIPreprocessor会将本页签配置的查询参数注射到扩展点userdefitemContainer的参数列表params中，以便扩展点的userdefitemContainer能一次查询所有页签的用户定义属性引用情况。（4） 以上方法的比较就上述三个场景进行比较，实现用户定义属性显示通过可通过配置UserdefitemBillDataPreparator/UserdefitemBillListDataPreparator，或通过配置UserDefItemContainer配合UserdefitemContainerPreparator/UserdefitemContainerListPreparator实现。大多数情况（即除去单据模板同一区域显示多个用户定义属性组的用户定义属性的场景)下，两种方式都能实现。前者简单但可能需要多次远程查询，后台配置麻烦但能够一次查询界面所需的所有用户定义属性引用情况。因此建议使rnI—:-fv.用后者。3.5.3其他情况的处理方法如果以上两种场景都无法满足界面开发的需要，则需要开发人员自己调用工具类来设置用户定义属性的界面显示了。列表界面和卡片界面分别提供nc.ui.bill.tools.UserDefItemListTools和nc.ui.bill.tools.UserDefItemTools两个工具类，这两个工具类分别提供了根据用户定义属性组编码、用户定义属性级名称、引用用户定义属性组的实体ID等信息初始化单据模板的方法，具体API如下(仅以UserDefItemTools为例)：/***根据表体业务实体的元数据ID,更新表体用户定义属性字段的展现属性•*适用于已知引用用户定义属性组的业务实体的元数据ID的场景.@paramdata业务实体的单据模板数据@parambeanlD表体的业务实体元数据ID@paramtabcode表体编码@paramprefix表体用户定义属性字段的前缀@parampk_org当前组织主键*/publicstaticvoidupdateBodyItemByDef(BillDatadata,StringbeanID,Stringtabcode,Stringprefix,Stringpk_org);/***根据表体实体关联的用户定义属性组编码，更新表体用户定义属性字段的展现属性•*适用于仅知道关联的用户定义属性组编码的场景•@paramuserdefruleCode表体实体关联的用户定义属性组编码@paramdata业务实体的单据模板数据@paramtabcode表体编码@paramprefix表体用户定义属性字段的前缀@parampk_org当前组织主键*/publicstaticvoidupdateBodyItemByUserdefruleCode(StringuserdefruleCode,BillDatadata,Stringtabcode,Stringprefix,Stringpk_org);/***根据表体实体关联的用户定义属性组名称，更新表体用户定义属性字段的展现属性•*适用于仅知道关联的用户定义属性组名称的场景•@paramuserdefruleName表体实体关联的用户定义属性组名称@paramdata业务实体的单据模板数据@paramtabcode表体编码@paramprefix表体用户定义属性字段的前缀@parampk_org当前组织主键*/publicstaticvoidupdateBodyItemByUserdefruleName(StringuserdefruleName,BillDatadata,Stringtabcode,Stringprefix,Stringpk_org);/***根据单据模板中表体实体的元数据,更新表头用户定义属性的元数据属性.*适用于业务实体的单据模板由元数据生成的场景，这时单据模板本身记录了表体业*务实体的元数据ID.*@paramdata业务实体的单据模板数据*@paramtabcode表体编码*@paramprefix表体用户定义属性字段的前缀*@parampk_org当前组织主键*/publicstaticvoidupdateBodyMetaDataItemByDef(BillDatadata,Stringtabcode,Stringprefix,Stringpk_org);/***用户表头关联的用户定义属性组编码,更新表头用户定义属性组的展现属性.*适用于仅知道关联的用户定义属性组编码的场景.*@paramuserdefrule