在 EKP 系统中，“关联机制”是实现跨业务对象关联、文档互相关联的重要基础能力。本文将从实际项目落地角度，完整介绍关联机制的接入步骤、关键代码以及常见注意事项，帮助你一次性跑通整个流程。

一、关联机制简介

关联机制用于在主业务对象（如文档、流程、知识对象）之间建立逻辑关联关系，支持在编辑页、阅读页中统一维护和展示关联内容。

典型应用场景包括：

• 文档与文档之间的关联

• 文档与流程实例的关联

• 知识对象与其他业务对象的关联

二、整体接入流程概览

接入关联机制需要同时改动8 个层面：

1. Model 层

2. Form 层

3. Edit JSP 页面

4. View JSP 页面

5. design.xml

6. 数据字典（data-dict）

7. Action 层

8. 注意事项与坑点

下面逐一展开。

三、修改 Model（核心）

1️⃣ 实现接口

在需要支持关联机制的Model 类中，实现接口：

com.landray.kmss.sys.relation.interfaces.ISysRelationMainModel

2️⃣ 增加关联属性

/** * 关联域模型信息 */ private SysRelationMain sysRelationMain = null; public SysRelationMain getSysRelationMain() { return sysRelationMain; } public void setSysRelationMain(SysRelationMain sysRelationMain) { this.sysRelationMain = sysRelationMain; } /** * 关联分表字段 */ protected String relationSeparate = null; public String getRelationSeparate() { return relationSeparate; } public void setRelationSeparate(String relationSeparate) { this.relationSeparate = relationSeparate; }

📌说明

• SysRelationMain：关联主对象

• relationSeparate：用于分表或业务隔离场景

四、修改 Form

在对应的Form 类中，实现接口：

com.landray.kmss.sys.relation.interfaces.ISysRelationMainForm

并添加：

/** * 关联机制 */ private SysRelationMainForm sysRelationMainForm = new SysRelationMainForm(); public SysRelationMainForm getSysRelationMainForm() { return sysRelationMainForm; }

📌作用
用于在页面层承载、回传关联数据。

五、修改 Edit 页面（JSP）

在编辑页面中插入关联机制编辑区：

<tr LKS_LabelName="<bean:message bundle='sys-relation' key='sysRelationMain.tab.label' />"> <c:set var="mainModelForm" value="${kmDocKnowledgeForm}" scope="request"/> <c:set var="currModelName" value="com.landray.kmss.km.doc.model.KmDocKnowledge" scope="request"/> <td> <%@ include file="/sys/relation/include/sysRelationMain_edit.jsp"%> </td> </tr>

参数说明

六、修改 View 页面（JSP）

阅读页配置方式与 Edit 页面类似，仅替换 include 文件：

<%@ include file="/sys/relation/include/sysRelationMain_view.jsp"%>

📌注意

• 模板的 view 页面不要加关联 view

• 模板只需要 edit 页面即可

七、修改 design.xml

在对应模块的design.xml中增加relation节点：

<relation modelName="com.landray.kmss.km.doc.model.KmDocKnowledge" messageKey="km-doc:kmDoc.tree.title"/>

⚠️重要顺序要求

relation节点必须放在 flowDef 之前，否则系统会提示格式错误。

八、修改数据字典（data-dict）

在模块的data-dict/*.xml中，为允许被关联的字段增加：

canRelation="true"

示例：

<simpleProperty name="docSubject" messageKey="sys-doc:sysDocBaseInfo.docSubject" canSearch="true" canRelation="true" type="String" column="doc_subject" length="200" />

📌 表示该字段可作为关联条件字段。

九、修改 Action（关键）

在创建文档时，需要初始化模板关联信息。

1️⃣ 重载 createNewForm()

getDispatchCoreService().initFormSetting( mainForm, null, moduleModel, null, new RequestContext(request) );

参数说明

📌 若不初始化，将导致模板关联信息丢失。

十、注意事项（非常重要）

✔ 关联信息会随Model ↔ Form 转换自动维护
✔ Service 层会统一处理新增、更新、删除
✔ 外键字段若要支持搜索，displayProperty 必须配置
✔ 模板 view 页面不要加载关联 view

十一、总结

关联机制本质上是一套横跨 Model / Form / 页面 / XML / Action 的系统能力，只要严格按步骤接入，整体运行非常稳定。

建议做法：

• 封装一个可复用的关联接入 Checklist

• 新模块统一按本文步骤接入

• 模板与实例页面严格区分