在 EKP 系统中，“关联机制”是实现跨业务对象关联、文档互相关联的重要基础能力。本文将从实际项目落地角度，完整介绍关联机制的接入步骤、关键代码以及常见注意事项，帮助你一次性跑通整个流程。
一、关联机制简介
关联机制用于在主业务对象（如文档、流程、知识对象）之间建立逻辑关联关系，支持在编辑页、阅读页中统一维护和展示关联内容。
典型应用场景包括：
文档与文档之间的关联
文档与流程实例的关联
知识对象与其他业务对象的关联
二、整体接入流程概览
接入关联机制需要同时改动8 个层面：
Model 层
Form 层
Edit JSP 页面
View JSP 页面
design.xml
数据字典（data-dict）
Action 层
注意事项与坑点
下面逐一展开。
三、修改 Model（核心）
1️⃣ 实现接口
在需要支持关联机制的Model 类中，实现接口：
com.landray.kmss.sys.relation.interfaces.ISysRelationMainModel2️⃣ 增加关联属性
/** * 关联域模型信息 */ 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>参数说明
| 参数名 | 是否必填 | 说明 |
|---|---|---|
| LKS_LabelName | 是 | 标签名称，如“关联文档” |
| mainModelForm | 是 | 主 Form 对象 |
| currModelName | 可选 | 主 Model 类名（编辑页必须） |
六、修改 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) );参数说明
| 参数 | 说明 |
|---|---|
| mainForm | 主 Form（实现 ISysRelationMainForm） |
| moduleModel | 模板对应的 Model（实现 ISysRelationMainModel） |
📌 若不初始化，将导致模板关联信息丢失。
十、注意事项（非常重要）
✔ 关联信息会随Model ↔ Form 转换自动维护
✔ Service 层会统一处理新增、更新、删除
✔ 外键字段若要支持搜索，displayProperty 必须配置
✔ 模板 view 页面不要加载关联 view
十一、总结
关联机制本质上是一套横跨 Model / Form / 页面 / XML / Action 的系统能力，只要严格按步骤接入，整体运行非常稳定。
建议做法：
封装一个可复用的关联接入 Checklist
新模块统一按本文步骤接入
模板与实例页面严格区分
