★ FEATURED ARTICLE 简介面向K/3 Cloud BOS插件开发初学者的一份docx入门文档围绕BOS产品应用汇总场景帮助读者理解插件开发在个性化与非标准化业务中的作用并建立从环境配置到插件分类、架构模型的整体认识。压缩包仅含1个docx文件大小约1.9MB内容集中便于按章节查阅。文档覆盖团队服务器、数据库服务器、Web服务器和客户端的环境要求梳理动态表单插件、服务插件、校验规则插件、表单构建插件四类插件的用途并说明Visual Studio、Silverlight、SQL Server或Oracle等工具与公共环境、个人环境的搭建要点。文中还给出插件开发步骤与HelloWorld示例便于把概念落到操作。已有216人学习适合需要快速了解BOS插件开发基础概念、厘清开发准备事项与后续动手方向的初学者作为入门参考。1. 先弄明白一件事K/3 Cloud 插件开发到底在做什么很多人第一次进到 K/3 Cloud 的后台看到单据、字段、菜单、按钮全都排得整整齐齐第一反应是这还有啥可开发的这恰恰是 K/3 Cloud 插件开发要回答的问题。产品把一套标准流程做出来给你用但你所在的公司总有那么几条规矩是标准流程里没有的——比如收料单要按供应商等级多卡一道、某张单据的某个字段要按组织自动填默认值。你不可能去改产品源码只能在产品预留的“扩展点”上挂一段自己写的 C# 逻辑这段逻辑就是插件。所以入门阶段你不用懂整个系统的底层只要搞清楚三件事插件挂在哪个动作上、什么时候被调用、在里面能拿到什么。2. 为什么值得学标准产品和真实业务之间永远差一截2.1 差的那一截就是插件的生存空间过去做企业软件追求的是大规模、标准化、高效率一套流程卖给一百家公司大家都照着用。但企业越做越细对人的关注、对个性的释放被推到了很前面的位置企业和市场之间开始建立一种“你有你的特殊要求我按你的要求来”的关系。落到具体的单据上就是同样是采购收料A 公司要求超收超过 5% 就拦下来B 公司要求超过 3% 就提醒但放行C 公司压根不管超收只管批次号必须录。这三条规矩都不在产品标准功能里产品也不会为了某一家去改主干逻辑因为一改就可能影响其他所有客户。于是平台留了一条路把表单的外观和业务逻辑拆成“元数据”在可视化设计器里配出来配不到的部分用插件补。平台用动态领域模型把业务抽象成标准接口和标准服务插件负责在标准之外做扩展。这句话听着玄翻译过来就是单据的骨架是配置出来的血肉是你写进去的。这也是为什么这类岗位在实际项目里很吃香——实施顾问搞不定的个性化需求最后都会落到能写插件的人手上。我要提前说一句这不是让你从零造一个系统而是让你在已经跑起来的系统上做“加法”。门槛比你想的低但有一个前提你得知道往哪儿加。2.2 四类插件先认清你以后最常写哪一种平台按用途把插件分成四类新手最容易犯的错是一上来就想全学结果每类都只停留在“见过”。先把这张表看一遍心里有个优先级。插件类型管什么通俗理解新手优先级动态表单插件单据、基础资料上的各种事件、操作、服务介入站在界面上用户点一下你就能插手最先学用得最多服务插件提供服务端编程接口供外部直接调用不在界面上别人来敲门时你应答第二学校验规则插件针对业务规则做校验保存前把不合格的数据挡回去用到再学表单构建插件动态调整界面控件和元数据界面还没画出来之前先动手脚暂时了解即可动态表单插件之所以最常用是因为绝大部分需求都发生在“用户打开单据、点了个按钮、改了某个字段、保存之前”这些瞬间而这些瞬间平台都留了事件接口。你后面写的第一个 Hello World 就属于这一类。服务插件和校验规则插件不是不重要而是它们的典型场景更偏后端和规则化等你把动态表单的事件顺序摸熟了再回头看它们会轻松很多。表单构建插件则是给界面做“元数据级别”的调整属于进阶内容新手期知道它存在就够了不用急着上手。2.3 学会之后你手上具体多了哪几样本事第一你能做更灵活的控制方式和客户化定制别人只能劝客户“这个功能标准产品不支持”你能说“我看一下能不能挂个插件”。第二你能处理标准产品里特殊的业务流程比如某张单据在特定组织下要走另一套审批路径。第三你能做个性化的菜单和外观定制把不该让某类用户看到的按钮藏掉把该显眼的字段标出来。第四你能增加自定义菜单并响应它的操作也能对已有操作和服务没覆盖到的功能做扩展。这四件事听起来抽象落地之后其实都很具体菜单可见性、字段锁定、默认值、分录自动带号、操作前后加一段判断。它们的共同点是——快。改一行代码编译一下注册上去刷新页面就能看到效果不用等发版。这种“快速开发、快速实施、快速应用”的节奏是插件开发最让人上头的地方也是新手最容易建立信心的地方。2.4 拿到一个需求先问自己三个问题这是我这几年带人时反复强调的动作你别急着打开 Visual Studio先把这三个问题回答完这个需求发生在什么时刻是打开单据时、点按钮时、改字段时还是保存前把时刻定位准了事件方法基本就定了。这个需求改的是“界面”还是“数据”藏按钮、改标题、设只读属于界面赋默认值、算金额、写分录属于数据。两类操作调用的接口不在一个地方。这个需求能不能用配置解决平台在设计器里提供了实体服务规则这类配置能力能配出来的优先配配不出来再写代码。第三个问题最容易被跳过。新手常见的心态是“我会写代码了什么都想写”结果做了一堆本该配置的东西后期维护的人接手时一脸懵。血泪经验是能用配置表达的规则别写进代码里因为配置是业务顾问能看懂、能自己改的代码只有你能改。3. 动手之前先把环境搭好Windows 机器上的最小可用配置3.1 三层环境数据库、Web 服务、你自己的开发机整个环境可以拆成三块。数据库服务器负责存数据Web 服务器负责跑产品服务、对外提供访问入口你的开发机负责写代码和调试。三块可以是三台机器也可以挤在一台机器上——新手自己练手一台性能还行的 Windows 机器全装上完全够用只是会慢一点。平台本身跑在 Windows 上开发工具也是基于 Windows 的 Visual Studio这一条没有选择余地别指望在别的系统上折腾。先按文档给的基准对一下你手上的机器角色CPU内存团队数据库服务器4 核2.0 GHz 以上SQL Server 8 GB / Oracle 16 GB客户端双核2.0 GHz 以上推荐 4 GB个人开发机客户端 数据库同机双核2.0 GHz 以上SQL Server 4 GB 以上 / Oracle 8 GB 以上软件环境这一层也要对一下。数据库服务器用 SQL Server 2008R2 以上标准版或企业版都行或者 Oracle 11g 以上操作系统 Windows Server 2008 以上Web 服务器需要 IIS 6.0 以上、.NET Framework 4.0操作系统同样是 Windows Server 2008 以上。客户端这边文档给的基准是 IE 8.0 / 9.032 位和 64 位都支持配 Silverlight 5或者 Firefox 12 及以上的 32 位 Windows 版本。提示上面这些是文档写作时的基准线不是唯一解。你手上如果已经是更新的版本按同样的思路对照着装就行重点看两件事——数据库版本够不够、浏览器能不能跑起 Silverlight 插件。真正卡人的往往不是版本号而是浏览器插件没装或者被禁用了。3.2 公共环境和个人环境分工不要搞混环境分两种这个区分对新手特别重要搞混了会浪费一整天。公共环境是“大家共用的那一套”通常配一台数据库服务器装好 SQL Server再配一台 Web 服务器装产品、配成管理中心站点。管理中心你可以理解成整个系统的“总调度台”所有业务站点都认它。个人环境是“你自己写代码的那台机器”装 Visual Studio装产品但不需要再配管理中心。装完之后产品默认会去找一个管理中心地址你得把它改成公共环境里那台的地址否则你本地这套跑起来是孤立的登录进去什么都对不上。改的地方在安装目录下的配置文件里路径是K3Cloud\K3CloudServer\App_Data\Common.config用文本编辑器打开找managementSiteUrl这一项!-- 开发机连到公共环境的管理中心地址换成你们自己那台的 IP 和端口 -- add keymanagementSiteUrl valuehttp://192.168.73.40:8000/ /这里的 value 就是管理中心站点的访问地址IP 和端口按你们实际环境填末尾那个斜杠别丢。改完保存重启一下站点再登录本地这套环境能正常进到业务界面、能看到公共环境里的数据说明通了。这一步翻车的概率不低最常见的表现是本地环境能打开登录页但登录后一直转圈或者报错。八成就是这个地址没改、或者改了没重启、或者公共环境那台机器的端口被防火墙挡了。遇到先别怀疑代码你这时候一行代码都还没写呢。3.3 建库时就要定死的两个参数后期改代价很大这一条我一定要单独拎出来讲因为它是典型的“装的时候两分钟改的时候两天”。用 SQL Server 的时候排序规则要选Chinese_PRC_CI_AS。用 Oracle 的时候数据库字符集必须是AL32UTF8国家字符集必须是AL16UTF16。这两组参数在建库那一刻就写进库里了后面你发现选错不是改个配置能解决的通常要重建库、重导数据。新手容易觉得这是 DBA 的事跟我写代码的没关系。关系大了——排序规则不对中文排序和查询会出各种诡异问题你查半天以为是代码逻辑写错了实际上是库在底层就不认。我见过有人为了一个中文排序问题排查了两天最后发现是装库时随手点了默认值。3.4 工具清单和那个必须记住的编译输出路径工具上Visual Studio 2012 是文档给的基准另外会用到 IE 的 Silverlight 5 插件、SQL Server 2008R2 或 Oracle 11G R2还有一个跟踪工具 HttpWatchPro 6.0用来抓客户端和服务端之间的请求调界面问题时很好用。然后是最关键的一条插件的编译输出路径必须指向K3Cloud\K3CloudServer\Bin\。你写的插件最终是一个 dll产品运行时去这个目录里找它。路径没设或者设错代码写得再漂亮系统也看不见你。这个路径建议你在新建工程的第一时间就去属性里设好别等编译完再回头找。4. 第一个插件从 Hello World 到能弹窗的菜单4.1 新建工程把地基打对打开 Visual Studio新建一个类库工程名字按团队规范来比如MyDev.K3.SCM.Stock.Business.PlugIn。名字长一点没关系工程命名把业务领域带上是好习惯以后插件多了你一眼能认出来它属于哪个模块。建好之后添加两个引用组件Kingdee.BOS和Kingdee.BOS.Core。这两个是平台的核心程序集插件的基类、事件参数、界面接口都在里面。然后在工程里新建一个类命名为ReceiptEdit让它继承Kingdee.BOS.Core.Bill.PlugIn.AbstractBillPlugIn。继承这一下你的类就从“普通 C# 类”变成了“平台认识的单据插件”平台在加载单据的时候会主动来找你。4.2 先分析业务再动手写点菜单该重载哪个方法我们的目标是在采购收料单上点一个叫 HelloWorld 的菜单弹出一句 Hello world!。拆一下这个需求。发生在什么时刻用户点击菜单的那一刻。改界面还是改数据都不是是弹一个提示框。那对应哪个接口菜单点击对应的是BarItemClick方法。这个判断过程只有三秒钟但它决定了你后面写的代码对不对——新手常犯的错是先写代码再想需求写到一半发现方法选错了全部推倒。4.3 把代码写出来就这几行确定方法之后先补上 usingusing Kingdee.BOS.Core.Bill.PlugIn; // 单据插件基类 using Kingdee.BOS.Core.DynamicForm; // 消息框类型等基础定义 using Kingdee.BOS.Core.DynamicForm.PlugIn.Args; // 各事件的参数类型然后重载方法namespace MyDev.K3.SCM.Stock.Business.PlugIn { // 继承单据插件基类后续会把它注册到采购收料单上 public class ReceiptEdit : AbstractBillPlugIn { public override void BarItemClick(BarItemClickEventArgs e) { base.BarItemClick(e); // 先让基类走完默认逻辑别急着 return // e.BarItemKey 是菜单项的标识必须和设计器里配的完全一致 if (e.BarItemKey HelloWorld) { // 在界面上弹出提示框Notice 表示普通提示 this.View.ShowMessage(Hello world!, MessageBoxType.Notice); } } } }挨个说清楚。BarItemClick是主菜单单击事件的处理入口只要用户点了工具栏或菜单上的按钮这个方法就会被调用一次。e.BarItemKey是菜单项的字符串标识注意它比的是“标识”不是“显示名称”界面上显示“你好世界”也行标识必须写 HelloWorld。this.View是当前表单的视图对象弹窗、取控件、改标题都从它出发。ShowMessage负责把文字弹到界面上第二个参数MessageBoxType.Notice决定提示框的类型纯提示用 Notice。保存然后编译。4.4 设好输出路径再编译别让 dll 掉在自己家编译前回到工程属性把输出路径指到K3Cloud\K3CloudServer\Bin\。这一步做完再点生成你的插件程序集就直接落到产品能读到的位置了。如果你忘了设编译会成功dll 会躺在工程目录的 bin 文件夹里你会觉得一切正常然后到界面上怎么点都没反应。这是新手翻车率最高的一步没有之一。4.5 在设计器里注册插件这一步最容易出事打开平台的设计器找到单据属性窗口编辑“采购收料单-_Bill”这个单据的属性进到插件列表界面点注册插件。这里有个必须知道的注意点注意插件列表里可能已经注册了其他插件这些插件在系统运行时会动态加载。不要因为“看着多余”就随手删掉删错一个可能导致业务数据出错而且这种错误往往不是当场报是过一阵子才暴露。接着点浏览选中你刚编译出来的组件勾上插件类一路确定最后保存单据。顺序上先确定、再返回、最后保存中间任何一步跳过注册都不算生效。保存这一步尤其容易被忽略——很多人以为点完确定就完事了结果注册信息没落库。4.6 运行测试先确认菜单存在再确认弹窗出现刷新界面打开采购收料单。如果菜单栏上还没有 HelloWorld 这个菜单项先去设计器里把菜单配上插件是挂在菜单事件上的菜单不存在自然触发不了。菜单出来之后点一下。弹窗出现第一个插件就通了。没弹窗的话按这个顺序查编译输出路径对不对、注册后有没有保存单据、菜单标识和代码里比对的字符串是否完全一致、最后再清一次缓存重进。这四步查完九成问题都能定位。剩下那一成通常是环境本身的问题不是代码的问题——这种时候别死磕代码先确认你注册的那个单据和你打开的那个单据是不是同一个业务对象。5. 新手最容易踩的 5 个坑排查清单5.1 坑一编译全绿界面上毫无反应现象代码编译通过注册也显示成功了点菜单就是没动静连个报错都没有。原因大部分情况是编译输出路径没指向Bin目录系统加载的还是旧版本或者根本找不到你的 dll。另一种可能是注册完没保存单据注册信息没写进去。还有一种是同名的旧插件还在列表里两边抢同一个事件。解决先去Bin目录里看一眼你的 dll 修改时间是不是刚才不是就回去改输出路径重新编译再看单据属性里的插件列表确认你勾的那个类名和文件都在最后把旧的同名插件取消勾选。这三步做完再刷新页面。养成“改完代码先看 dll 时间戳”的习惯能省掉一半的无效排查。5.2 坑二改完代码界面行为还是老的现象逻辑改了、重新编译了、注册也没动界面跑起来还是老行为像是代码根本没更新。原因产品运行时会缓存已加载的程序集你换了 dll 但进程里还是旧的。另一种情况是你本地环境和公共环境各有一份 dll你编译到本地实际访问的是另一台。解决重启对应站点再清一次浏览器缓存重进。同时确认你登录的环境地址和你编译输出指向的那台机器是同一台这一点在团队协作里特别容易搞错我见过有人对着测试环境改了半天编译全打到开发机上去了。5.3 坑三中文排序和查询莫名其妙不对现象数据查出来顺序不对或者中文检索结果缺东西代码逻辑怎么看都没问题。原因建库时排序规则或字符集选错了。SQL Server 要求Chinese_PRC_CI_ASOracle 要求AL32UTF8配AL16UTF16这两个是在建库那一刻写死的。解决这个没有后悔药改配置解决不了得重建库、重导数据。所以新手自己练手时装库那一步宁可停下来核对三遍。团队环境里装完立刻执行一次带中文的排序查询验证一下比事后排查划算得多。5.4 坑四在创建数据的事件里设了值界面上没生效现象在AfterCreateNewData里调了SetValue界面上那个字段还是空的。原因这类创建数据包的事件属于“数据包还没交给界面”的阶段在这个阶段设的值是整个数据包一起发到客户端的不经过状态管理器。有些场景下界面刷新会覆盖掉你设的值看起来就像没生效。解决先确认你设的字段 Key 写对了Key 错一个字就是静默失败不报错。再确认事件选得对——AfterCreateNewData只在新增时触发打开已有单据不会走。如果需要跟界面状态联动把赋值挪到AfterBindData里试。判断依据很简单这个值是“数据初始化”还是“界面呈现”选事件跟着这个判断走。5.5 坑五随手删了设计器里的老插件业务悄悄出错现象清理插件列表把看着不认识的插件取消勾选了测试时功能正常过几天业务反馈数据不对。原因列表里那些插件是系统运行时动态加载的有些承担着你看不见的校验或赋值逻辑。删掉之后不一定立刻报错但某条数据链路断了。解决只加不删。确实要停用某个插件先在测试环境单独验证确认没有其他业务依赖它再做变更并记录。这条是纯粹的踩坑换来的经验新手最容易在“整理环境”的时候犯因为那时候你还不清楚每个插件在干什么。6. 接下来学什么把事件顺序刻进脑子里第一个例子跑通之后很多人会急着去学更复杂的控件操作我建议先停一停把动态表单的加载顺序背下来。因为后面你写的每一个插件本质上都是“在某个时刻插入自己的一段逻辑”时刻搞不清代码就一定写偏。6.1 这张顺序表值得你抄一遍打开一张单据时事件的触发顺序大致是这样顺序事件触发时机适合干什么1OnInitialize页面初始化初始化控件数据源、批量修改界面的下拉列表2CreateNewData动态表单数据包创建仅新增时触发从其他服务取数据填充新单据3AfterCreateNewEntryRow每新增一条分录都会触发给新分录的行字段赋初始值4AfterCreateNewData数据包创建完成后仅新增时触发按当前组织等参数设置字段默认值5BeforeBindData数据绑定到界面前绑定前调整控件状态、按类型加分录行6AfterBindData绑定数据及控件状态后加载和刷新都会调用控制字段可见性、锁定、菜单启用状态7BeforeClosed页面准备关闭前收尾、提示未保存模型层还有几个常用的AfterCreateModelData在模型数据包创建完毕后触发只在新增时走BeforeUpdateValue在字段值更新前触发适合做输入拦截DataChanged在字段值改变后触发。这几个不用背顺序知道什么时候该找它们就行。背这张表的意义在于你以后拿到需求第一反应不再是“我该写哪个方法”而是“这事发生在第几步”。同一个赋值需求放AfterCreateNewData和放AfterBindData效果完全不同前者进数据包后者影响界面呈现选错了就是那种“代码没错但现象不对”的玄学问题。6.2 视图和模型两条线别搅在一起再往后走你必须分清IDynamicFormView和IDynamicFormModel这两个接口。视图管外观菜单、控件样式、标题、字段显示隐藏。模型管数据新增、删除、复制、定位分录行、设值。两边各有一个BusinessInfo表示业务对象的逻辑元数据也就是你在设计器里配的那些信息的运行时版本。实际写的时候界面操作从this.View出发数据操作从this.Model出发。新手常见的错是用视图去改数据、用模型去改样式跑起来不报错但没效果然后开始怀疑人生。分不清的时候问自己一句我改的是用户看到的东西还是系统存下来的东西。6.3 我给新手的四周路线阶段目标怎么算过关第 1 周环境搭通Hello World 弹窗能出来不看文档能独立装一遍并注册成功第 2 周把加载顺序表默写出来每个事件各写一个小例子给一个需求能说出该挂哪个事件第 3 周视图和模型各练三个操作藏菜单、设只读、给分录赋值能不看示例写出完整插件第 4 周挑一个真实的小需求从分析到注册跑完整流程需求方验收通过顺序不要跳。我见过太多人第一周就想学服务插件和表单构建插件结果基础事件一問就卡壳。最后说个我自己的教训。早期我带新人总觉得把文档丢过去、把例子跑通就算入门了后来发现真正拉开差距的不是会不会写那段 Hello World而是有没有养成“先定位时刻、再选事件、最后才写代码”的习惯。从那以后我每次带人第一件事都是让对方把加载顺序表手抄一遍贴在显示器边上抄完再动键盘。这个动作看着笨但它能挡掉后面八成的无效排查。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
