目录一、导入模板设置............................................................................................................................21.菜单路径....................................................................................................................................22.字段解读....................................................................................................................................23.模板字段设置............................................................................................................................4二、前端接入实现说明....................................................................................................................41.快速接入....................................................................................................................................42.自定义按钮................................................................................................................................53.自定义打开导入任务界面........................................................................................................54.常见问题解决............................................................................................................................5三、业务实现类开发说明.................................................................................................................61.接口说明....................................................................................................................................62.抽象类说明................................................................................................................................93.默认实现类................................................................................................................................94.常用类说明..............................................................................................................................11导入功能开发接入简要指南一、导入模板设置1.菜单路径管理员登录->开发平台->导入模板配置。2.字段解读模板名称：指模板显示名称、模板下载的文件名称。模板状态：拥有“启用”与“禁用”两个选项，其中启用是指模板可以被使用；禁用是指模板不能被用来上传导入数据，并且在模板列表界面不与展示。描述：模板说明文字，按需添加。业务实现类：指定使用此模板进行导入上传的数据文件进行处理导入的Java实现类；非必填项，若未指定，则采用系统默认实现类；实现类的开发细则见后文。导入类型：通过复选框的形式可以指定当前导入功能可以支持的导入类型，显示名称为模板中显示的选项名称，说明文字指对当前选项的补充性说明。UIPK：导入功能使用界面的uipk，必填项，不可为空。按钮名称：导入功能使用界面用来触发导入的按钮名称，此按钮名称是按钮英文命名，可以通过浏览器在界面右键审查元素查看名称，也可以通过视图查看界面查看。如下图所示：图：通过浏览器查看按钮名称图：通过视图查看按钮名称互斥条件：指定当前导入功能的数据互斥类型，支持四个选项：实体、主键字段、绑定功能、不互斥。实体指进行导入任务时，当前所有正在导入的任务其导入模板包含了相同实体，则当前任务排队等待其执行完毕；主键字段指使用使用相同绑定功能的导入模板进行导入时，读取每一行中按导入模板中设置的主键字段数据，此行数据有其他导入任务正在执行处理，则跳过此行；绑定功能是指取出当前导入任务使用的导入模板的绑定功能，若在系统中检测到有相同的绑定功能模板正在执行导入，则当前导入任务进行互斥排队等待；不互斥指执行此模板的导入任务时，直接开始执行，不进行数据互斥判断。绑定功能：自动填写，由UIPK和按钮名称按一定规则组合，代表着一个导入功能。是否预置：此模板是否为系统预置模板，预置模板不允许修改。是否数据源模板类型：指导入字段来源是否为结构配置，若选择是，则是采用相应结构配置作为导入字段；选择否，则是采用实体对象作为导入字段来源。数据源编码：当是否数据源模板类型选择“是”时，将必需填写对应的数据源编码。实体路径：填写要导入的实体全路径，点击后方的按钮可以增加多个关联实体。第一个实体是主实体，下方实体是一对一关联实体，并且下方每个实体是主实体的一个属性且属性的名称为实体的短名称。例如：主实体为：com.kingdee.shr.A，关联实体为com.kingdee.shr.B，则A实体有一个其类型为B实体的属性b。除此之外的关联关系需要导入，需要自行实现导入的业务实现类。实现类的开发细则见后文。3.模板字段设置导入字段设置：当完成输入实体路径或者数据源编码时，点击“刷新”按钮，将会加载出可以选择的导入字段信息。点击候选字段中的相应字段，将其添加至导入模板字段中。字段名称：不可修改，在实现业务实现类时使用；显示名称：导入模板中表头显示名称；是否主键：在进行新增或者修改数据时，判断数据是否存在的依据；是否必录：当前字段在导入时是否可以为空；最大宽度：以14号中文字体为单位设置导入模板中列的宽度；示例：将在导入模板中展示的示例。增加自定义字段：若想处理实体或者结构配置中没有的字段，可以通过点击自定义字段进行增加，必须输入相应的每一个字段中的值。若有自定义字段，则必须通过业务实现类自行处理。实现类的开发细则见后文。二、前端接入实现说明1.快速接入创建列表视图，新增导入按钮。在模板设置当中设置相应的UIPK、按钮名称的值，配置好模板，在相应列表上点击“导入”将弹出导入任务界面。2.自定义按钮当期望导入按钮名称不为import时，可以使用相应的按钮事件中调用相应的方法打开导入任务界面。在列表界面list.js中拥有简单与复杂两个方法。方法doImportData拥有三个参数依次为(btnName,customParam,callback)；具体为模板配置中的按钮名称，不允许为空；自定义附加参数，可以为空，参数类型为json数据对象；导入完成执行的回调函数，可以为空，回调函数的参数有处理完成的数据列表、上传的自定义参数，若回调函数不为空，则数据导入将默认不写入至数据库，若要写入数据库需自行在业务实现类中处理。此方法中包含导入任务界面关闭后自动刷新当前界面的代码。方法startImportData拥有四个参数依次为(btnName,customParam,clsCallback,callback)，其中clsCallback是指导入任务界面关闭时回调处理函数，回调参数有是否有执行完成导入任务；其它参数含义与doImportData一致。3.自定义打开导入任务界面若需要在任意界面(不局限于列表视图界面)中添加导入功能，需要调用shr中的方法doImportExcel，示例如下：shr.doImportExcel({btnName:btnName,uipk:uipk,serviceId:serviceId,customParam:customParam,clsCallback:clsCallback},callback);参数拥有两个，第一个为JSON数据对象格式，其中属性btnName必填，指需要使用的模板中填写的按钮名称；uipk必填，指导入模板中填写的uipk，serviceId非必填，用作权限验证。其它参数与自定义按钮中提到一致。4.常见问题解决模板加载不出来。检查模板是否已启用，查看传进的参数btnName和uipk是否与模板配置一致。点击模板下载无反映或一闪而过。检查是否被浏览器拦截或已禁止弹出框。三、业务实现类开发说明导入任务执行概览图如下：导入任务执行过程消息处理如下：当需要处理一些特殊的导入处理逻辑时，需要自行实现相应的java接口，在里面处理自己的逻辑。系统导入代码结构如下：1.接口说明接口com.kingdee.shr.base.syssetting.app.io.fileImport.IBaseImportService为顶级接口，里面定义了导入的基本处理方法和模板下载时扩展模板功能方法。1.1初始化导入服务程序初始化导入服务程序导入任务开始前的初始化，参数有上下文、导入任务、任务监控者，可以做一些初始化准备工作，保存一些后续需要用到的数据变量等。1.2模板下载时的初始化服务模板下载时的初始化服务1.3是否为批量导入是否为批量导入若有些导入任务，需要保持一致性，即一条数据失败，其它的全部失败，在此种场景下，需要使用批量导入，此接口需返回true值。并且需要自主实现批量导入的具体逻辑。1.4单行数据导入单行数据导入导入框架将循环遍历的对每一行数据调用此方法进行数据导入，若数据导入失败，则将错误信息包含在ImportException异常对象中，并抛出此异常；此方法执行完成，则一行数据导入处理完成。1.5批量数据导入批量数据导入此接口参数为导入数据迭代器，若需要此实现此接口，则导入进度控制需要自行控制，调用导入任务监控者monitor相应方法。monitor在导入任务初化方法中通过参数已传入。1.6获取数据唯一标识获取数据唯一标识若模板中的互斥条件选择了主键字段，则需要实现此接口，返回代表此行数据标识字段串，系统中正在处理的数据与此重复则此行数据暂不进行处理。1.7任务执行完成执行任务任务执行完成调用1.8前端界面在处理完成后获取的回调数据前端回调获取数据1.9模板动态添加列动态添加列1.10模板默认填充值模板默认填充值1.11模板添加可选值模板添加可选值1.12模板设置批注信息模板列头部设置批注说明信息1.13模板生成完成后执行内容模板生成完成后回调2.抽象类说明抽象类com.kingdee.shr.base.syssetting.app.io.fileImport.AbstractBaseImportService为继承自导入接口的一个抽象实现类。此抽象类中默认实现了接口中的方法，并且额外提供了许多工具方法并且提供许多功能扩展方法。3.默认实现类实现类com.kingdee.shr.base.syssetting.app.io.fileImport.BaseImportService为系统导入默认实现类，它继承至抽象类AbstractBaseImportService。它已经可以完成简单基本导入任务，若模板设置中若业务实现类为空，则系统会默认选择使用此类处理导入数据。若需要自行处理导入数据或扩展导入功能，推荐继承此类，复写相应方法。3.1验证扩展验证入口为BaseImportService类中的verifyRow方法，里面分为系统验证verifyRowSystem与业务验证verifyRowBiz。前者是验证数据类型，长度等基本信息，后者验证数据合法性。若验证需要自行处理，一般复写业务验证方法。将验证错误信息导入验证方法3.2自定义导入处理逻辑导入的入口方法为BaseImportService类中的importRow,系统默认中有四个子方法，分别对应模板配置中的四种导入类型的不同导入处理入口。数据导入入口在导入数据时，若有特殊的处理逻辑，则复写相应的方法即可实现。3.3其它说明在自行实现验证与导入时，可能需要获取一些数据，在继承了BaseImportService类时，在它的父类提供了若干方法可以直接调用。获取当前使用的导入模板信息：getTemplateInfo():SHRFileTemplateInfo；获取模板中填写的实体名称：getEntityFullNames():String[];获取当前登录用户上下文：getContext():Context;获取当前用户权限项Id：getPermItemId():String;获取用户算定义参数：getCustomParams():Map;获取全部列信息：getColumnMap():Map;获取列信息的迭代器：getColumnIterator():Iterator;用户是否设置出错中止：isStopOnError():Boolean;用户是否设置前端回调处理：hasCallback():Boolean;获取导入类型：getImportTypeEnum():SHRImportTypeEnum;是否为数据源模板导入：isDataSource():boolean;获取数据行迭代器：getRowIterator():Iterator;获取从指定行开始的行迭代器：getRowIterator(intstartIndex):Iterator;获取导入监控器：getMonitor():ImportTaskMonitor;4.常用类说明4.1BaseRowInfo行数据结构类名com.kingdee.shr.base.syssetting.app.io.fileImport.BaseRowInfo为导入数据行的数据封装类，每一行数据封装成一个实例。里面提供一些方法，用于获取相应数据。获取指定列输入的值，总共有四个方法，分别是根据属性名称和列序号获取表格中输入的值与转换过后的值。其中转换过后的值需要调用了验证方法verifyRowSystem后才会有值。publicStringgetValueOfStringByIndex(intcolumnIndex)；publicStringgetValueOfString(StringpropName);publicStringgetValueOfObjectByIndex(intcolumnIndex);publicStringgetValueOfObject(StringpropName);4.2BaseColumnInfo列信息类名com.kingdee.shr.base.syssetting.app.io.fileImport.BaseColumnInfo为导入列封装信息，常用方法有获取列所在表格模板中的序号，获取列的属性名称。publicintgetColumnIndex();publicStringgetPropName();4.3ImportTaskMonitor导入监控器类名com.kingdee.shr.base.syssetting.app.io.fileImport.ImportTaskMonitor为导入监控器类，当进行批量导入时，需要自行使用监控器进行进度控制与导入错误日志写入，所使用的方法一般为：
