BOS扩展业务服务说明手册.doc

1、 KINGDEEK/3 BOS 开 发 指 导 手 册BOS 扩展服务说扩展服务说明手册明手册金 蝶 软 件 （ 中 国 ） 有 限 公 司 研 发 中 心 K/3 BOS 系 统 开 发 部BOS 扩 展 业 务 服 务 说 明 手 册 金 蝶 软 件 （ 中 国 ） 有 限 公 司研 发 中 心 K/3 BOS 系 统 开 发 部RaymondYao 2006.02.1221 扩展业务服务（扩展扩展业务服务（扩展 Action）1.1 名词解释名词解释扩展业务服务：独立、通用的业务处理函数，其参数、返回数据独立于单据、基础资料；为了把业务处理函数和特定的单据绑定，必须在函数的配置界面进行参

2、数配置。因此，一个完整的扩展业务服务包括参数配置组件和解析运行组件；扩展业务服务实现的功能等同于 BOS 原有的 Action 函数，只是允许用户自行扩展。后文中扩展业务服务又称为扩展 Action；1.2 简介简介K/3 BOS 除了内置的一些业务服务函数（Action）外，还支持用户开发自有的Action：用户可以将自有的业务逻辑封装在这种 Action 中，并在需要的时候配置到单据的字段（加载更新事件、值更新事件、保存规则）事件、操作事件和单据事件中，以实现自定义的过程。K/3 BOS 目前支持的 Action，按照运行领域可以分为： 客户端 Action：包含适用于单据的 Action

3、 和序时簿的 Action 中间层 Action按照触发条件可以分为： 字段相关的 Action 操作相关的 Action 单据事件相关的 Action同时还有一种特殊的 Action：简单业务 Action。1.2.1 字段相关的字段相关的 Action字段相关的 Action，是指当单据字段的值发生改变时会触发的 Action。字段相关的 Action 包含了所有 BOS 内置的 Action，如：TakeBaseData、Calculate、UnitExchange、LockByItemTrack、SetDecimal、SetEquation、ShowHideField、LockFiel

4、d、Vertify、LockUsed 、LockMenu、VerifyUniquely 、TrigAction，关于这些 Action 的使用，请参考相关手册。字段相关的 Action，需要在字段的加载更新事件、值更新事件、保存规则中进行定义。3目前，字段相关的 Action，都是客户端单据运行的 Action。1.2.2 操作相关的操作相关的 Action操作相关的 Action，是指当 BOS 单据的指定操作被用户触发后会执行的 Action。操作相关的 Action，需要在 BOS 单据的操作管理中定义。目前操作相关的 Action，又包含： 单据操作前置 Action：在插件 BOSB

5、arClick 事件发生之后触发 单据操作 Action：在单据操作前置 Action 之后、BOS 内置处理过程（如果有的话）之前触发 单据操作后置 Action：在 BOS 内置处理过程（如果有的话）完成之后触发 序时簿操作前置 Action：在插件 BOSBarClick 事件发生之后触发 序时簿操作 Action：在序时簿操作前置 Action 之后、BOS 内置处理过程（如果有的话）之前触发 序时簿操作后置 Action：在 BOS 内置处理过程（如果有的话）完成之后触发操作相关的 Action，可以在客户端运行，也可以在中间层运行。1.2.3 单据事件相关的单据事件相关的 Acti

6、on单据事件相关 Action，是指 BOS 单据在执行某些特定事件时触发的 Action。单据事件相关的 Action，需要在 BOS 单据的 保存前事件 、保存后事件、删除前事件、删除后事件 属性中定义。目前包含： 单据保存前：在插件的 BeforeSave 事件后发生 单据保存后：在插件的 AfterSave 事件后发生 单据删除前：在插件的 BeforeDel 事件后发生 单据删除后：在插件的 AfterDel 事件后发生操作相关的 Action，目前都是在中间层运行。1.2.4 简单业务简单业务 Action所谓简单业务 Action，是指符合 BOS 简单业务规则定义的扩展 Act

7、ion。这种 Action，可能是字段相关的，也可能是操作相关的 Action；可以在客户端运行，也可以在中间层运行。这种 Action 和其他扩展 Action 的区别在于：Action 的定义界面是由 BOS 提供的。41.3 扩展扩展 Action 的基本属性的基本属性所有的扩展 Action，应该具有以下属性：1.3.1 运行时组件运行时组件所有的扩展 Action，都需要有一个运行时组件，在实现特定接口后完成 Action 的具体操作过程。这个组件是一个标准的 Active Dll 组件。1.3.2 配置时组件配置时组件如果扩展 Action 希望在用户配置时，由用户设定一些选项，并

8、完成定义公式的校验，就需要提供定义时组件。这个组件是一个标准的 ActiveX Control 组件。对于简单业务 Action，不需要提供这样的组件，但必须按照指定的参数编写公式，这样，配置界面将由 BOS 按照公式提供。1.3.3 接口接口所有的扩展 Action，都必须实现下列接口：定义组件接口：函数/属性 类型 详细说明Action 属性 可读/写，String 类型，用来设置/ 返回用户配置的 Action 表达式m_dctTableInfo 属性 只写，KFO.Dictionary 类型。接受单据字段模板包m_Field 属性 只写，KFO.Dictionary 类型。接受 Act

9、ion 对应的当前字段模板m_vctClassTypeEntry 属性 只写，KFO.Vector 类型。接受单据分录模板包m_dctClassType 属性 只写，KFO.Dictionary 类型。接受单据属性数据包GetAction 函数 String 类型，返回用户设置的 Action 表达式Initial 方法 提供接口给调用者，由其触发配置界面初始化FormulaCheck 函数 Boolean，检查最终用户设置的表达式是否合法，合法则返回真，BOS会接受用户的设置；不合法则应该返回假，BOS 不会接受用户的设置下面是代码模版：Private m_sAction As String

10、Public Property Get Action() As StringAction = m_sActionEnd PropertyPublic Property Let Action(ByVal New_Action As String)m_sAction = New_ActionEnd Property5Public Property Set m_dctTableInfo(ByRef New_TableInfo As Object)End PropertyPublic Property Set m_Field(ByRef New_Field As Object)End Property

11、Public Property Set m_vctClassTypeEntry(ByRef New_vctClassTypeEntry As Object)End PropertyPublic Property Set m_dctClassType(ByRef New_dctClassType As Object)End PropertyPublic Function GetAction() As StringEnd FunctionPublic Sub Initial()在这里添加 Action 界面的初始化代码End SubPublic Function FormulaCheck() As

12、 Boolean 在这里添加 Action 函数表达式语法检查。如果检查通过，返回 True；否则返回 FalseEnd Function请注意：1、 如果是客户端适用的 Action，其定义时组件和运行时组件，都应该安装在客户端；2、 如果是中间层适用的 Action，其定义时组件仍应该安装在客户端，而运行时组件应安装在中间层；3、 如果同时适用于客户端和中间层的 Action，其定义时组件仍应该安装在客户端，而运行时组件应同时安装在客户端和中间层；运行组件接口（客户端适用 Action）：函数/属性 类型 详细说明SetInterface 方法 接受插件代理组件，单据的模板和数据包都可以从

13、中获取TransAction 函数 翻译 Action 表达式 .暂保留为用DataSrv 属性DoAction 函数 解析、执行 Action 的入口函数下面是代码模版：客户端扩展 Action 模版Private WithEvents m_objBillInterface As K3ClassEvents.BillEvent Private WithEvents m_objBaseInterface As K3ClassEvents.BaseClassEvent Private WithEvents m_objListInterface As K3ClassEvents.ListEvent

14、s Public Sub SetInterface(ByRef objInterface As Object)设置 /传入插件代理组件6On Error GoTo CatchIf Not (objInterface Is Nothing) ThenSelect Case VBA.UCase$(TypeName(objInterface)Case “BILLEVENT“Set m_objBillInterface = objInterfaceCase “BASECLASSEVENT“Set m_objBaseInterface = objInterfaceCase “LISTEVENTS“Set

15、 m_objListInterface = objInterfaceCase ElseEnd SelectEnd IfCatch:End SubPublic Property Set DataSrv(ByRef New_DataSrv As Object)End PropertyPublic Function TransAction( _ByRef strAction As String, _ByRef strDescription As String, _Optional ByVal strLanguage As String = “CHS“, _Optional ByVal blnTran

16、sToDesc As Boolean = True) As Long翻译 ActionEnd FunctionPublic Function DoAction(ByVal strFunction As String, _ByVal dctParamenters As KFO.Dictionary, _ByRef dctActionReturn As KFO.Dictionary) As Long执行 ActionOn Error GoTo CatchDim lRet As LongExit FunctionCatch:lRet = Err.NumberdctActionReturn(“Erro

17、rDescription“) = Err.DescriptionDoAction = lRetEnd Function运行组件接口（中间层适用 Action）：函数/属性 类型 详细说明DoAction 函数 解析、执行 Action 的入口函数下面是代码模版：中间层扩展 Action 模版Private m_dctPara As KFO.DictionaryPrivate m_dctReturn As KFO.DictionaryPublic Function DoAction(ByVal strFunction As String, _Byval cn As ADODB.Connectio

18、n, _ByVal dctParamenters As KFO.Dictionary, _ByRef dctActionReturn As KFO.Dictionary) As Long执行 ActionOn Error GoTo CatchDim lRet As LongExit FunctionCatch:lRet = Err.NumberdctActionReturn(“ErrorDescription“) = Err.Description7DoAction = lRetEnd Function1.3.4 配置时组件的配置时组件的 Licenses如果扩展 Action 定义时组件，采

19、用了一些具有 Licenses 许可要求的控件，则当用户运行时，会出现下面的情况：如果出现这种情况，需要在组件（控件）的初始化过程中添加 Licenses 许可。具体方法参考如下：Private Sub UserControl_Initialize()Licenses.Add ProgId, LicenseKeyEnd Sub1.4 扩展扩展 Action 的注册的注册创建的 Action 如果需要在 BOS 中起到预期的作用，必须向 BOS 进行注册，即向表格ICClassAction 中添加数据。该表关键字段描述：字段名 类型 长度 为空 详细说明FID int 4 No 编码，唯一，自定

20、义的 Action 请指定大于 100000 的编码，避免和 BOS 内置的 FID 冲突FName varchar 20 No 名称，系统通过 FName 和具体的 Action 关联，必须唯一，且无歧义8FDesc varchar 50 No 描述FSyntax varchar 100 No 语法FParameter varchar 7000 No 参数FType smallint 2 No 类型FSetComponent Varchar 64 No 配置 Action 的控件名，可以为 FRunComponent Varchar 64 No 运行 Action 的组件名，如果为扩展 Ac

21、tion，必须填写需要注意的是，一个扩展 Action，只能支持 1 个运行组件和 1 个定义组件。1.5 FType 的意义的意义ICClassAction 表中的 FType 字段，表示了这个 Action 所具有的属性。其含义参考下面的值：值 含义 说明-1 无效的 Action0 有效的 Action1 客户端的 Action2 中间层的 Action4 有配置界面的 Action8 加载更新的 Action16 值更新的 Action32 保存更新的 Action64 连续触发的 Action128 有返回值的 Action256 操作类的 Action512 系统内置 Action

22、 系统内置 Action 不允许修改1024 扩展 Action2048 简单业务 Action4096 字段相关的 Action 只能是客户端的 Action8192 事件相关的 Action 只能是中间层的 Action需要注意的是：一个 Action 可以具有多个属性。举例：Action：TakeBaseData FType = 0 + 1 + 4 + 8 + 161.6 Action 的执行控制的执行控制在 BOS 中，允许对同一个字段或操作，同时定义多个 Action。这是，我们称之为字段或操作具有“Action 序列”。Action 序列中的每个 Action，按照定义时的先后次序

23、依次执行。通过扩展 Action 接口中的 dctActionReturn 参数，我们可以控制 Action 的运行。dctActionReturn 参数包含以下内容：序号 dctActionReturn 值域 值 说明91 CancelSeries 布尔值。默认为 False表示是否需要取消整个 Action 序列的执行。如果是一组中间层 Action，则会产生事务回滚；如果是客户端 Action，则后续 Action 将不会被执行2 ErrorDescription 字符串。默认为空。错误描述。如果 Action 执行中出现错误，则此值域包含错误描述。3 ActionSeriesShare

24、Pool KFO.Dictionary Action 之间共享变量的存储缓冲区4 ActionSeriesSharePoolDef KFO.Dictionary Action 之间共享变量的存储缓冲区变量定义5 Consts KFO.Dictionary 常量定义和值6 其它 Action 的交换交换数据空间。我们也可以通过在这个数据包中增加传递不同的值，来达到 Action 间的数据传递。注意：请不要在 Action 中将这个数据包上述的几个值域清除，或将整个数据包清空。否则会产生运行时错误。2 客户端字段相关扩展客户端字段相关扩展 Action制作客户端字段相关的扩展 Action，DoA

25、ction 接口的 dctParamenters 参数包包含以下内容：值域 说明FieldAction 当前 Action NameFieldActionExpressions 当前 Action 的定义表达式FieldActionType 当前 Action 的类型Paramenters 当前 Action 的参数Trigger 是否连续执行SeriesTotal Action 序列的 Action 总数ActionSeriesSource Action 序列的触发来源ActionSeriesType Action 序列的类型ClassTypeClassTypeEntryTableInfoD

26、ataBOSFieldTpl 引发 Action 的字段的模版数据包BOSFieldValue 引发 Action 的字段的值数据包ItemObj 核算项目对象3 客户端操作相关扩展客户端操作相关扩展 Action制作客户端操作相关的扩展 Action，DoAction 接口的 dctParamenters 参数包包含以下内容：值域 说明OperationAction 当前 Action NameOperationActionExpressions 当前 Action 的定义表达式OperationActionType 当前 Action 的类型Paramenters 当前 Action 的参

27、数Trigger 是否连续执行10SeriesTotal Action 序列的 Action 总数ActionSeriesSource Action 序列的触发来源ActionSeriesType Action 序列的类型ClassTypeClassTypeEntryTableInfoDataOperationObject 引发 Action 的操作对象数据包4 中间层扩展中间层扩展 Action制作中间层的扩展 Action，DoAction 接口的 dctParamenters 参数包包含以下内容：值域 说明MiddleAction 当前 Action NameMiddleActionEx

28、pressions 当前 Action 的定义表达式MiddleActionType 当前 Action 的类型Paramenters 当前 Action 的参数SeriesTotal Action 序列的 Action 总数ActionSeriesSource Action 序列的触发来源ActionSeriesType Action 序列的类型ClassTypeClassTypeEntryTableInfoDataOperationObject 如果 Action 序列是操作相关的，则包含此值域，否则不包含。引发 Action 的操作对象数据包BOSFieldTpl 如果 Action 序

29、列是字段相关的，则包含此值域，否则不包含。引发 Action 的字段的模版数据包BOSFieldValue 如果 Action 序列是字段相关的，则包含此值域，否则不包含。引发 Action 的字段的值数据包ItemObj 如果 Action 序列是字段相关的，则包含此值域，否则不包含。核算项目对象5 单据事件相关单据事件相关 Action5.1 保存前、保存后事件保存前、保存后事件DoAction 接口的 dctParamenters 参数包包含以下内容：值域 说明MiddleAction 当前 Action NameSeriesTotal Action 序列的 Action 总数Actio

30、nSeriesSource Action 序列的触发来源ActionSeriesType Action 序列的类型ActionKey FBeforeSaveAction 或 FAfterSaveActionClassTypeClassTypeEntryTableInfo11Data5.2 删除前、删除后事件删除前、删除后事件DoAction 接口的 dctParamenters 参数包包含以下内容：值域 说明MiddleAction 当前 Action NameSeriesTotal Action 序列的 Action 总数ActionSeriesSource Action 序列的触发来源ActionSeriesType Action 序列的类型ActionKey FBeforeDeleteAction 或 FAfterDeleteActionClassTypeID 单据模版号InterID 单据内码ClassTypeClassTypeEntryTableInfoData