★ FEATURED ARTICLE 简介面向K/3 Cloud BOS插件开发初学者的一份入门文档聚焦BOSIDE、套打、万能报表等BOS产品应用知识帮助读者理解动态领域模型、标准接口与服务扩展之间的关系并掌握个性化业务定制的基本路径。压缩包仅含1个docx文件大小约1.9MB便于集中查阅与离线学习。已有216人学习适合刚接触金蝶K/3 Cloud二次开发的技术人员作为起步材料。内容围绕开发环境配置、BOS架构模型与四类插件展开具体涉及团队服务器与客户端配置建议、Visual Studio 2012、Silverlight 5、SQL Server 2008R2或Oracle 11g R2、插件Building路径以及动态表单插件、服务插件、校验规则插件、表单构建插件的用途同时给出公共环境与个人环境搭建要点、SQL Server排序规则与Oracle字符集提示并以新建工程、引用Kingdee.BOS组件、重载BarItemClick、编译注册测试为例说明插件开发步骤便于读者建立从环境准备到实际编码的完整认知。1. 先弄明白一件事插件到底是个什么东西很多人第一次听到“BOS 平台插件开发”第一反应是我连这套系统里的单据都没摸熟就要上手写代码先别急着打退堂鼓。插件这个词听着唬人本质上是给一套已经装好的软件留的“改装接口”。就像买了套成品柜子厂家在背板上预留了螺丝孔和走线槽你想加个抽屉、加条灯带不用把柜子拆了重做对准孔位拧上去就行。BOS 平台的插件就是这些预留孔位它专门为某一套软件做功能扩充可以改菜单、改外观、控制字段的显示和锁定可以在标准业务流程中间插一段自己的判断也能加一个原本不存在的按钮并让这个按钮真的干活。它适合谁适合那些能看懂单据界面、但一遇到“客户要一个标准产品里没有的效果”就卡住的新人零基础也能从跑通一个弹窗开始。2. 为什么值得学标准功能覆盖不到的地方就是插件的位置2.1 一套标准产品喂不饱所有企业同一张采购收料单甲厂的流程是仓库收货后由质检补录检验结果乙厂要求扫一下码就直接过账丙厂还想在保存前弹一句“本批物料超过三批请走特批”。这三家买的是同一套产品用的是同一张单据差别全在“流程和规则”上。产品本身会把常见需求做成开关和配置项界面上勾一勾就能用但配置项总有边界一旦需求拐到边界外就得靠代码介入。插件就是那个“在标准流程上开一扇小门”的东西标准逻辑照常跑跑到你指定的位置时把你的代码叫起来执行一下执行完再还给标准流程继续走。这也是很多做实施、做二开的新人绕不开它的原因。你在项目上遇到的问题八成不是“系统不行”而是“这个细节没地方配”。会写插件的人这时候能当场给出方案不会写的人只能反馈给产品等排期。从职业角度讲插件开发是把“会用系统”变成“能改系统”的那道分水岭而且它不需要你从零造一个系统只需要你在已有的骨架里补几块肉学习曲线比想象中缓。它带来的好处也很实在控制方式更灵活、能实现标准产品里没有的特殊业务流程、能定制菜单和外观、能对已有操作没覆盖到的功能做扩展而且改完能配置、能测试、能快速部署不用推倒重来。2.2 先把插件家族认全四类插件各管一段刚接触的人最容易犯的错是把“插件”当成一个东西。实际上平台按用途把它分成了四类你前期只要能分清楚“我这个需求该找哪一类”就已经省掉一大半返工。插件类型管什么典型场景新手要不要先学动态表单插件在单据、列表等界面上介入业务事件、操作和服务按钮点击弹窗、字段联动、保存前校验要最常用先学这个服务插件提供服务端的编程接口供外部直接调用外部系统调用一段业务逻辑后面再说校验规则插件针对业务规则做校验一批数据的合法性检查用到再看表单构建插件在界面加载时调整控件和元数据按条件动态隐藏页签、改控件属性进阶再看看得出一件事动态表单插件是入口也是日常出现频率最高的一类。它提供了大量事件、操作和服务接口你在界面上能看到的绝大多数“点了之后发生什么”都能从这里切进去。所以入门阶段别贪多把动态表单插件吃透剩下的三类等你真的接到对应需求时再补效率最高。提示判断需求该用哪类插件有个笨办法但很准——先问自己“这段逻辑是在界面上被人的操作触发的还是被外部调用触发的”。前者十有八九是动态表单插件。2.3 动态表单插件里的五个分支以及它们的抽象基类动态表单插件往下还能再分分成单据插件、列表插件、过滤条件插件、账表插件、动态表单插件五类。分这么细是因为界面形态不同能拿到的事件也不同单据界面关心的是“这张单保存了没、分录加行了没”列表界面关心的是“这一行被双击了没、过滤条件变了没”。你继承哪个基类就等于告诉平台“我关心的是哪一类界面”平台也只会把对应的事件推给你。入门阶段真正要记住的抽象基类只有四个抽象基类对应界面AbstractBillPlugIn单据插件业务单据的编辑界面AbstractBasePlugIn基础资料插件基础资料的编辑界面AbstractDynamicFormPlugIn动态表单插件自定义的动态表单AbstractListPlugIn列表插件各种列表界面它们的继承关系是一层层往下走的最上面是动态表单插件的抽象基类单据插件和基础资料插件都继承自它。这意味着你在单据插件里能用到的方法比在动态表单插件里更多因为它多了一层业务语义。第一次写的时候不用纠结继承树画成什么样只要记住“写单据就继承单据基类写列表就继承列表基类”选错了基类事件根本不会来敲你的门这是新手最常见的第一个闷棍。2.4 视图管长相模型管数据再往下走一步会碰到两个绕不开的接口视图接口和模型接口。这两个名字听着抽象其实就是把一张界面拆成两半来看。视图管“长相”。它持有布局元数据也就是你在设计器里拖出来的那些东西控件摆在哪、哪个字段叫什么、菜单项有哪些、页签怎么排。你在插件里写“把某个字段隐藏掉”“把某个菜单项灰掉”“改一下表单标题”动的都是视图。模型管“数据”。它持有业务元数据负责按元数据定义把数据绑上来还持有一个数据对象里面装着单据头和单据体的实际值。你写“把某一行的数量改成 10”“新增一行分录”“取一下当前选中行的物料编码”动的都是模型。分开的好处是同一份数据可以有好几种长相。举个不恰当但好记的比喻数据是同一锅汤视图是盛汤的碗碗可以换汤不用重煮。入门阶段记住一条就够用改界面找视图改数据找模型两个都改的时候先改数据再刷界面顺序反了容易看到旧值。3. 动手前的准备开发环境怎么搭才不返工3.1 机器配置团队服务器和个人机器怎么分工环境这块新手最容易吃的一个亏是“拿自己的笔记本当服务器用”装到一半发现内存不够重装一遍又是一下午。所以在动手之前先把机器角色分清楚公共环境里要有一台数据库服务器、一台 Web 服务器个人环境里装开发工具和产品客户端连到公共环境的管理中心上去。平台本身跑在 Windows 上开发工具也是 Windows 上的 Visual Studio这点绕不过去。配置上按下面的基准值准备低于这个数会明显卡角色CPU内存说明团队数据库服务器4 核 2.0 GHz 以上SQL Server 8 GBOracle 16 GB多人共用的那台别省团队 Web 服务器双核 2.0 GHz 以上推荐 4 GB跑 IIS 和产品服务个人客户端双核 2.0 GHz 以上推荐 4 GB只装开发工具和客户端个人机器兼做数据库双核 2.0 GHz 以上SQL Server 4 GB 以上Oracle 8 GB 以上单人练习够用多人别这么干给新手的建议是如果你只是想跑通第一个例子个人机器兼做数据库完全够一旦要给同事演示或者两个人一起调老老实实按团队服务器的配置来不然你会经历“我这边好好的他那边一直转圈”这种说不清的玄学问题。第一次搭环境的时候我建议直接按最低配置往上加一档内存省下来的时间远比省下来的硬件成本值钱。3.2 软件清单装什么、什么版本配置够了接下来是对版本。版本对不上后面会出现一堆看起来毫无关联的报错比如插件注册成功但界面打不开、页面能开但控件加载不出来。按这张表逐个核对组件版本要求操作系统Windows Server 2008 以上服务端Windows 客户端数据库SQL Server 2008R2 以上标准版、企业版或 Oracle 11g 以上Web 服务器IIS 6.0 以上.NET Framework4.0开发工具Visual Studio 2012浏览器IE 8.0 / 9.032 位和 64 位都支持Firefox 12 及以上32 位 Windows浏览器插件Silverlight 5跟踪工具HttpWatch Pro 6.0 一类用来抓请求这张表里最容易被忽略的是最后一个“跟踪工具”。很多人以为调试就是打断点但这个平台的界面是跑在浏览器里的字段值不对、按钮没反应很多时候问题出在服务端返回的数据上而断点看不到浏览器和服务端之间到底传了什么。装一个抓包工具点一下按钮看看请求和响应比盯着代码猜半小时有用得多。这不是必须项但它决定了你排查问题的速度。另外注意浏览器的组合IE 要配 Silverlight 5Firefox 12 及以上是 32 位 Windows 版本。这一条看着琐碎但它是“页面白屏”这类问题的高发区后面避坑那章还会再提一次。3.3 个人环境和公共环境怎么连上环境装完还有一步是很多人会漏掉的让个人机器知道管理中心在哪。公共环境里那台 Web 服务器要配置成管理中心站点装完之后会有一个访问地址个人环境里装产品时不需要再配置一次管理中心但你得把它指向公共环境那个地址。改法很简单找到产品安装目录下的配置文件通常在这个位置产品安装目录\K3CloudServer\App_Data\Common.config打开它找到managementSiteUrl这一项把值改成公共环境里管理中心的 IP 和端口!-- 把 value 换成本地公共环境的管理中心地址 -- add keymanagementSiteUrl valuehttp://192.168.73.40:8000/ /这里的192.168.73.40和8000只是示例实际填你那边管理中心的地址和端口改完保存重启一下相关服务。改错了会出现什么表现是登录能进、但一打开单据就报找不到管理中心或者插件注册列表是空的。这不是代码问题纯粹是个人环境“不知道去哪找组织”。入门的话建议把这一步当成装机的固定动作装完立刻验证一次别等写了一半代码才发现连接的还是默认地址。3.4 数据库的两个初始化前提数据库这一步装完不等于装对。有两个初始设置必须在建库的时候定好事后改代价很大。第一个是 SQL Server 的排序规则必须是Chinese_PRC_CI_AS。第二个是如果用 Oracle数据库字符集必须是AL32UTF8国家字符集必须是AL16UTF16。为什么强调这个因为排序规则和字符集决定了中文怎么存、怎么比大小。设置不对短期内可能一切正常等到某天出现中文乱码、查询条件里中文字段匹配不上、或者排序结果怪里怪气的时候你会以为是代码写错了查半天最后发现是建库时选错了。这种问题属于典型的“血泪经验”重装数据库的成本远高于第一次就选对。注意这两项在建库时是一次性选择装完再改基本等于重来。装之前把这两串字符抄在手边装的时候逐个对一遍。4. 第一个例子跑通 Hello World 插件4.1 建工程、加引用、写第一个类前面铺垫了那么多现在真正开始写代码。第一个例子不搞复杂业务就做一件事在一张单据上点一个新加的菜单按钮弹出一句 Hello world。目标不是学会业务是走通“建工程、写类、编译、注册、运行”这条完整链路这条链路走通了后面写什么都是往里面填内容。打开 Visual Studio 2012新建一个类库工程工程名可以按业务线起比如MyDev.BOS.Stock.Business.PlugIn。然后添加对平台核心程序集的引用最基础的两个是业务核心和界面核心引用程序集作用业务核心程序集提供业务对象、数据服务等基础能力界面核心程序集提供表单视图、模型、事件参数等类型接着新建一个类命名成ReceiptEdit让它继承单据插件基类using BOS.Core.Bill.PlugIn; // 单据插件抽象基类在这里 using BOS.Core.DynamicForm; // 界面相关的枚举、消息框类型 using BOS.Core.DynamicForm.PlugIn.Args; // 各种事件参数类型 // 继承单据插件基类等于告诉平台我要挂在一张单据的编辑界面上 public class ReceiptEdit : AbstractBillPlugIn { // 具体重载哪个方法下一节写 }这里说明三件事。第一示例里的命名空间去掉了产品前缀实际引用时以你本地安装目录下那批程序集的真实命名空间为准类名和方法名是一致的别照抄前缀。第二AbstractBillPlugIn是关键继承它才有单据相关的事件继承成别的基类你写的方法再多也不会被调用。第三类库工程的目标框架要和产品要求对齐也就是 .NET Framework 4.0框架选高了编译出来平台加载不了。4.2 重载 BarItemClick让按钮弹出一句话类建好了接下来要决定“什么时候执行我的代码”。在单据上点菜单按钮对应的是主菜单单击事件方法名是BarItemClick参数类型是BarItemClickEventArgs。重载它判断按的是哪个按钮然后弹消息public override void BarItemClick(BarItemClickEventArgs e) { // 先让基类把标准逻辑跑完避免影响原有按钮 base.BarItemClick(e); // e.BarItemKey 是设计器里给按钮设置的标识必须一字不差 if (e.BarItemKey HelloWorld) { // this.View 是当前表单的视图对象ShowMessage 用于弹出提示 this.View.ShowMessage(Hello world!, MessageBoxType.Notice); } }几处细节值得逐个说清楚。base.BarItemClick(e)这一行别删标准产品原有的按钮逻辑都在基类里删掉之后你可能会莫名其妙地让别的按钮失灵。e.BarItemKey是按钮的标识不是按钮上显示的中文名字两者可以不一样判断的时候用的是标识写错了就是“点了没反应”的头号原因。this.View是视图对象改界面、弹提示、取控件都从它身上拿。MessageBoxType.Notice决定弹窗的样式是普通提示还是警告按需求换就行。写完之后保存、编译。如果编译报“找不到类型或命名空间”八成是引用没加全如果报“没有适合的重写方法”八成是基类继承错了或者方法名拼错了。这两种错误都很直白照着提示改就行不用慌。4.3 编译输出路径一定要设到 Bin 目录编译这一步有个坑属于新手必踩默认输出路径是工程自己的bin\Debug但平台不会去那里找你的程序集。必须把输出路径改成产品服务端的 Bin 目录一般是产品安装目录下的这一段产品安装目录\K3CloudServer\Bin\改法是在工程属性里找到生成输出路径把上面这个绝对路径填进去。改完重新编译然后去那个目录里确认一下编译出来的 dll 文件是不是真的躺在里面。为什么要多这一步确认因为“编译成功”只代表代码没问题不代表文件到了正确的位置。我见过不止一次代码写得完全正确注册的时候在浏览窗口里怎么找都找不到 dll最后发现输出路径还停在默认值上。更麻烦的是有时候 dll 出去了但你没注意它是最新版本还是上一次的注册的其实是旧文件改了代码却毫无变化能让人怀疑人生。提示养成习惯每次编译完顺手看一眼 Bin 目录里那个 dll 的修改时间是不是刚刚。这个动作三秒钟能省掉半小时的自我怀疑。4.4 在设计器里注册插件并运行dll 到位了最后一步是告诉平台“这张单据要用这个插件”。打开设计器找到单据属性窗口编辑你要挂的那张单据的单据属性进入插件列表界面点注册插件再点浏览选中刚编译出来的那个 dll勾上里面的插件类确定返回再确定并保存单据。保存完就可以运行测试了打开这张单据点你新加的菜单按钮应该能看到弹窗。第一次跑通的时候别急着往下写业务先确认三件事都对了——按钮能点、弹窗能出、内容是你写的。三个都对这条链路就通了。但注册这一步有个风险必须提前说插件列表里可能已经注册了别的插件这些插件在运行时是动态加载的你把它们删掉业务的某些功能就会失效严重的时候会导致业务数据出错。所以进入这个界面之后的第一件事不是点浏览是先把现有列表看一遍心里有数操作时只做“增加”不动“删除”。注意在插件列表里删掉已有插件是最容易造成“上线后业务数据异常”的操作之一。改之前先截图或者记下来只加不删。5. 新手最容易翻车的几个地方排查清单5.1 环境刚装完就打不开界面现象产品装完了登录也能进但一打开单据就转圈或者报错插件列表里空空如也。原因个人环境没有指向公共环境的管理中心配置文件里的地址还是默认值或者写错了 IP、端口。解决打开K3CloudServer\App_Data\Common.config核对managementSiteUrl确保它指向公共环境里那台配置了管理中心站点的服务器改完重启服务再试。这一条在第 3 章提过但它是新手撞得最多的一堵墙值得再强调一次。5.2 页面白屏、控件加载不出来现象界面框架出来了但中间区域一片空白或者某个控件一直显示加载中。原因浏览器和浏览器插件版本不匹配。这个平台的界面依赖 Silverlight 5IE 用的是 8.0 或 9.0 的 32 位、64 位版本Firefox 要 12 及以上且是 32 位 Windows 版本。用新版浏览器或者插件没装好就会出现这种“看起来是代码问题、其实是环境问题”的现象。解决先按版本要求把浏览器和插件对齐再清一次缓存重开。如果还是白屏装个抓包工具看看请求有没有正常返回别一上来就怀疑自己代码写错了。5.3 代码写得没错就是点了没反应现象编译零报错插件也注册上了运行起来点按钮啥也不发生。原因三个高频嫌疑。一是e.BarItemKey和设计器里按钮的标识不一致判断条件永远不成立二是继承的基类选错了比如该继承单据插件却继承了动态表单插件三是编译输出路径没改注册的 dll 是旧的你改的代码根本没生效。解决按顺序排查——先去 Bin 目录确认 dll 修改时间再看设计器里按钮的标识是不是和代码里一模一样最后确认类继承的基类对不对。这个顺序是从“最便宜的动作”到“最贵的动作”能最快定位。5.4 字段值改了界面上还是老样子现象插件里明明设置了值界面上就是不刷新或者刷新了但马上又被冲掉。原因改数据的时机不对或者改完之后没触发界面刷新。数据绑定前后是两个阶段绑定前改的数据会被后续绑定流程覆盖绑定后改的数据需要主动通知界面更新。另外某些阶段设置的值不会进入状态管理表单整体发送到客户端时才生效看起来就像“没改成功”。解决先想清楚你要的效果是“数据本身变了”还是“界面上看到变了”前者在数据层改完刷新界面后者在绑定完成后的事件里改。拿不准的时候在这几个事件里各打一条日志看看到底哪个先触发、哪个后触发执行顺序一清二楚问题基本就自己浮出来了。5.5 数据库装完能用过一阵子开始出怪事现象中文偶尔乱码、中文字段查不出来、排序结果不符合预期。原因建库的时候排序规则和字符集没按规矩设。SQL Server 要求Chinese_PRC_CI_ASOracle 要求字符集AL32UTF8、国家字符集AL16UTF16。解决这事儿没有后悔药只能在建库时设对。已经装错了的话趁数据还少尽早重建越晚成本越高。这也是我在装环境时唯一会反复核对两遍的地方。6. 接下来学什么从会改一个事件到敢接一个需求跑通 Hello World 之后很多人会陷入第二个迷茫期弹窗会弹了然后呢我的建议是别急着去看 API 列表那玩意儿有几百个方法和事件硬看只会更晕。按“事件执行顺序”这条主线走效率高得多。一张表单从打开到关闭插件里的方法是有固定先后顺序的页面初始化、数据包创建、分录行创建、数据包创建完毕、绑定数据前、绑定数据完成、页面关闭前。你把这七个节点记住等于拿到了一张地图以后接到任何需求第一件事就是判断“这个动作该发生在哪个节点”。比如要给字段设默认值就放在绑定数据前要根据类型控制字段显示隐藏就放在绑定数据完成后要在新增分录时自动算一个序号就放在分录行创建之后。位置放错代码再对也不生效。按这个思路我给一个三阶段的练手路径阶段目标练手内容第一阶段摸清事件顺序在几个主要事件里各写一行日志观察打开单据时它们的执行先后画成自己的顺序表第二阶段学会改界面按条件隐藏一个字段、灰掉一个菜单项、改一次表单标题第三阶段学会改数据新增单据时从别处取一个默认值填进来、新增分录行时自动带出序号三个阶段走完你已经能应付大部分“小改动”类需求了。再往后是操作插件和服务插件那是另一个层级的东西等你能独立判断“这个需求是界面逻辑还是业务逻辑”的时候再去碰水到渠成。最后分享一个我自己的习惯。刚开始写插件的时候我总想着“先把业务写完跑不通再查”结果每次卡住都要从头翻代码一查一晚上。后来我改成任何一个新插件先只写一行日志编译、注册、运行确认这行日志真的打印出来了再去写真正的业务。这个动作看着笨但它把“环境对不对、插件挂没挂上、事件来没来”三个问题一次性排掉了剩下的才是纯代码问题。从那以后我每次新建插件都强制走一遍这个空跑流程再也没出现过改了两小时发现插件压根没被调用的情况。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
