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

KINGDEE
K/3 BOS 开发指导手册
BOS扩展服务说明手册

金蝶软件（中国）有限公司 研发中心 K/3 BOS系统开发部
BOS扩展业务服务说明手册
ã 金蝶软件（中国）有限公司
研发中心 K/3 BOS系统开发部
RaymondYao 2006.02.12

1 扩展业务服务（扩展Action）
1.1 名词解释
扩展业务服务：独立、通用的业务处理函数，其参数、返回数据独立于单据、基础资料；为了把业务处理函数和特定的单据绑定，必须在函数的配置界面进行参数配置。因此，一个完整的扩展业务服务包括参数配置组件和解析运行组件；扩展业务服务实现的功能等同于BOS原有的Action函数，只是允许用户自行扩展。
后文中扩展业务服务又称为扩展Action；
1.2 简介
K/3 BOS 除了内置的一些业务服务函数（Action）外，还支持用户开发自有的Action：用户可以将自有的业务逻辑封装在这种Action中，并在需要的时候配置到单据的字段（加载更新事件、值更新事件、保存规则）事件、操作事件和单据事件中，以实现自定义的过程。
K/3 BOS目前支持的Action，按照运行领域可以分为：
² 客户端Action：包含适用于单据的Action和序时簿的Action
² 中间层Action
按照触发条件可以分为：
² 字段相关的Action
² 操作相关的Action
² 单据事件相关的Action
同时还有一种特殊的Action：简单业务Action。
1.2.1 字段相关的Action
字段相关的Action，是指当单据字段的值发生改变时会触发的Action。
字段相关的Action包含了所有BOS内置的Action，如：TakeBaseData、Calculate、UnitExchange、LockByItemTrack、SetDecimal、SetEquation、ShowHideField、LockField、Vertify、LockUsed、LockMenu、VerifyUniquely、TrigAction，关于这些Action的使用，请参考相关手册。
字段相关的Action，需要在字段的加载更新事件、值更新事件、保存规则中进行定义。
目前，字段相关的Action，都是客户端单据运行的Action。
1.2.2 操作相关的Action
操作相关的Action，是指当BOS单据的指定操作被用户触发后会执行的Action。
操作相关的Action，需要在BOS单据的操作管理中定义。
目前操作相关的Action，又包含：
² 单据操作前置Action：在插件BOSBarClick事件发生之后触发
² 单据操作Action：在单据操作前置Action之后、BOS内置处理过程（如果有的话）之前触发
² 单据操作后置Action：在BOS内置处理过程（如果有的话）完成之后触发
² 序时簿操作前置Action：在插件BOSBarClick事件发生之后触发
² 序时簿操作Action：在序时簿操作前置Action之后、BOS内置处理过程（如果有的话）之前触发
² 序时簿操作后置Action：在BOS内置处理过程（如果有的话）完成之后触发
操作相关的Action，可以在客户端运行，也可以在中间层运行。
1.2.3 单据事件相关的Action
单据事件相关Action，是指BOS单据在执行某些特定事件时触发的Action。
单据事件相关的Action，需要在BOS单据的 保存前事件、保存后事件、删除前事件、删除后事件 属性中定义。
目前包含：
² 单据保存前：在插件的BeforeSave事件后发生
² 单据保存后：在插件的AfterSave事件后发生
² 单据删除前：在插件的BeforeDel事件后发生
² 单据删除后：在插件的AfterDel事件后发生
操作相关的Action，目前都是在中间层运行。
1.2.4 简单业务Action
所谓简单业务Action，是指符合BOS简单业务规则定义的扩展Action。
这种Action，可能是字段相关的，也可能是操作相关的Action；可以在客户端运行，也可以在中间层运行。
这种Action和其他扩展Action的区别在于：Action的定义界面是由BOS提供的。
1.3 扩展Action的基本属性
所有的扩展Action，应该具有以下属性：
1.3.1 运行时组件
所有的扩展Action，都需要有一个运行时组件，在实现特定接口后完成Action的具体操作过程。
这个组件是一个标准的Active Dll组件。
1.3.2 配置时组件
如果扩展Action希望在用户配置时，由用户设定一些选项，并完成定义公式的校验，就需要提供定义时组件。
这个组件是一个标准的ActiveX Control组件。
对于简单业务Action，不需要提供这样的组件，但必须按照指定的参数编写公式，这样，配置界面将由BOS按照公式提供。
1.3.3 接口
所有的扩展Action，都必须实现下列接口：
定义组件接口：
函数/属性
类型
详细说明
Action
属性
可读/写，String类型，用来设置/返回用户配置的Action表达式
m_dctTableInfo
属性
只写，KFO.Dictionary类型。接受单据字段模板包
m_Field
属性
只写，KFO.Dictionary类型。接受Action对应的当前字段模板
m_vctClassTypeEntry
属性
只写，KFO.Vector类型。接受单据分录模板包
m_dctClassType
属性
只写，KFO.Dictionary类型。接受单据属性数据包
GetAction
函数
String类型，返回用户设置的Action表达式
Initial
方法
提供接口给调用者，由其触发配置界面初始化
FormulaCheck
函数
Boolean，检查最终用户设置的表达式是否合法，合法则返回真，BOS会接受用户的设置；不合法则应该返回假，BOS不会接受用户的设置
下面是代码模版：
Private m_sAction As String

Public Property Get Action() As String
Action = m_sAction
End Property

Public Property Let Action(ByVal New_Action As String)
m_sAction = New_Action
End Property

Public Property Set m_dctTableInfo(ByRef New_TableInfo As Object)

End Property

Public Property Set m_Field(ByRef New_Field As Object)

End Property

Public Property Set m_vctClassTypeEntry(ByRef New_vctClassTypeEntry As Object)

End Property

Public Property Set m_dctClassType(ByRef New_dctClassType As Object)

End Property

Public Function GetAction() As String

End Function

Public Sub Initial()
'在这里添加Action界面的初始化代码
End Sub

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

Public Sub SetInterface(ByRef objInterface As Object)
'设置/传入插件代理组件
On Error GoTo Catch

If Not (objInterface Is Nothing) Then
Select Case VBA.UCase$(TypeName(objInterface))
Case "BILLEVENT"
Set m_objBillInterface = objInterface
Case "BASECLASSEVENT"
Set m_objBaseInterface = objInterface
Case "LISTEVENTS"
Set m_objListInterface = objInterface
Case Else
End Select
End If
Catch:
End Sub

Public Property Set DataSrv(ByRef New_DataSrv As Object)

End Property

Public Function TransAction( _
ByRef strAction As String, _
ByRef strDescription As String, _
Optional ByVal strLanguage As String = "CHS", _
Optional ByVal blnTransToDesc As Boolean = True) As Long
'翻译Action
End Function

Public Function DoAction(ByVal strFunction As String, _
ByVal dctParamenters As KFO.Dictionary, _
ByRef dctActionReturn As KFO.Dictionary) As Long
'执行Action
On Error GoTo Catch
Dim lRet As Long
Exit Function
Catch:
lRet = Err.Number
dctActionReturn("ErrorDescription") = Err.Description
DoAction = lRet
End Function
运行组件接口（中间层适用Action）：
函数/属性
类型
详细说明
DoAction
函数
解析、执行Action的入口函数
下面是代码模版：
中间层扩展Action模版
Private m_dctPara As KFO.Dictionary
Private m_dctReturn As KFO.Dictionary

Public Function DoAction(ByVal strFunction As String, _
Byval cn As ADODB.Connection, _
ByVal dctParamenters As KFO.Dictionary, _
ByRef dctActionReturn As KFO.Dictionary) As Long
'执行Action
On Error GoTo Catch
Dim lRet As Long

Exit Function
Catch:
lRet = Err.Number
dctActionReturn("ErrorDescription") = Err.Description
DoAction = lRet
End Function
1.3.4 配置时组件的Licenses
如果扩展Action定义时组件，采用了一些具有Licenses许可要求的控件，则当用户运行时，会出现下面的情况：

如果出现这种情况，需要在组件（控件）的初始化过程中添加Licenses许可。具体方法参考如下：
Private Sub UserControl_Initialize()
Licenses.Add ProgId, LicenseKey
End Sub

1.4 扩展Action的注册
创建的Action如果需要在BOS中起到预期的作用，必须向BOS进行注册，即向表格ICClassAction中添加数据。该表关键字段描述：
字段名
类型
长度
为空
详细说明
FID
int
4
No
编码，唯一，自定义的Action请指定大于100000的编码，避免和BOS内置的FID冲突
FName
varchar
20
No
名称，系统通过FName和具体的Action关联，必须唯一，且无歧义
FDesc
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的组件名，如果为扩展Action，必须填写
需要注意的是，一个扩展Action，只能支持1个运行组件和1个定义组件。
1.5 FType的意义
ICClassAction表中的FType字段，表示了这个Action所具有的属性。其含义参考下面的值：
值
含义
说明
-1
无效的Action

0
有效的Action

1
客户端的Action

2
中间层的Action

4
有配置界面的Action

8
加载更新的Action

16
值更新的Action

32
保存更新的Action

64
连续触发的Action

128
有返回值的Action

256
操作类的Action

512
系统内置Action
系统内置Action 不允许修改
1024
扩展Action

2048
简单业务Action

4096
字段相关的Action
只能是客户端的Action
8192
事件相关的Action
只能是中间层的Action
需要注意的是：一个Action可以具有多个属性。
举例：
Action：TakeBaseData FType = 0 + 1 + 4 + 8 + 16
1.6 Action的执行控制
在BOS中，允许对同一个字段或操作，同时定义多个Action。这是，我们称之为字段或操作具有“Action序列”。
Action序列中的每个Action，按照定义时的先后次序依次执行。通过扩展Action接口中的dctActionReturn参数，我们可以控制Action的运行。
dctActionReturn参数包含以下内容：
序号
dctActionReturn值域
值
说明
1
CancelSeries
布尔值。默认为False
表示是否需要取消整个Action序列的执行。如果是一组中间层Action，则会产生事务回滚；如果是客户端Action，则后续Action将不会被执行
2
ErrorDescription
字符串。默认为空。
错误描述。如果Action执行中出现错误，则此值域包含错误描述。
3
ActionSeriesSharePool
KFO.Dictionary
Action之间共享变量的存储缓冲区
4
ActionSeriesSharePoolDef
KFO.Dictionary
Action之间共享变量的存储缓冲区变量定义
5
Consts
KFO.Dictionary
常量定义和值
6
其它

Action的交换交换数据空间。
我们也可以通过在这个数据包中增加传递不同的值，来达到Action间的数据传递。
注意：请不要在Action中将这个数据包上述的几个值域清除，或将整个数据包清空。否则会产生运行时错误。
2 客户端字段相关扩展Action
制作客户端字段相关的扩展Action，DoAction接口的dctParamenters参数包包含以下内容：
值域
说明
FieldAction
当前Action Name
FieldActionExpressions
当前Action的定义表达式
FieldActionType
当前Action的类型
Paramenters
当前Action的参数
Trigger
是否连续执行
SeriesTotal
Action序列的Action总数
ActionSeriesSource
Action序列的触发来源
ActionSeriesType
Action序列的类型
ClassType

ClassTypeEntry

TableInfo

Data

BOSFieldTpl
引发Action的字段的模版数据包
BOSFieldValue
引发Action的字段的值数据包
ItemObj
核算项目对象
3 客户端操作相关扩展Action
制作客户端操作相关的扩展Action，DoAction接口的dctParamenters参数包包含以下内容：
值域
说明
OperationAction
当前Action Name
OperationActionExpressions
当前Action的定义表达式
OperationActionType
当前Action的类型
Paramenters
当前Action的参数
Trigger
是否连续执行
SeriesTotal
Action序列的Action总数
ActionSeriesSource
Action序列的触发来源
ActionSeriesType
Action序列的类型
ClassType

ClassTypeEntry

TableInfo

Data

OperationObject
引发Action的操作对象数据包
4 中间层扩展Action
制作中间层的扩展Action，DoAction接口的dctParamenters参数包包含以下内容：
值域
说明
MiddleAction
当前Action Name
MiddleActionExpressions
当前Action的定义表达式
MiddleActionType
当前Action的类型
Paramenters
当前Action的参数
SeriesTotal
Action序列的Action总数
ActionSeriesSource
Action序列的触发来源
ActionSeriesType
Action序列的类型
ClassType

ClassTypeEntry

TableInfo

Data

OperationObject
如果Action序列是操作相关的，则包含此值域，否则不包含。引发Action的操作对象数据包
BOSFieldTpl
如果Action序列是字段相关的，则包含此值域，否则不包含。引发Action的字段的模版数据包
BOSFieldValue
如果Action序列是字段相关的，则包含此值域，否则不包含。引发Action的字段的值数据包
ItemObj
如果Action序列是字段相关的，则包含此值域，否则不包含。核算项目对象
5 单据事件相关Action
5.1 保存前、保存后事件
DoAction接口的dctParamenters参数包包含以下内容：
值域
说明
MiddleAction
当前Action Name
SeriesTotal
Action序列的Action总数
ActionSeriesSource
Action序列的触发来源
ActionSeriesType
Action序列的类型
ActionKey
FBeforeSaveAction 或 FAfterSaveAction
ClassType

ClassTypeEntry

TableInfo

Data

5.2 删除前、删除后事件
DoAction接口的dctParamenters参数包包含以下内容：
值域
说明
MiddleAction
当前Action Name
SeriesTotal
Action序列的Action总数
ActionSeriesSource
Action序列的触发来源
ActionSeriesType
Action序列的类型
ActionKey
FBeforeDeleteAction或 FAfterDeleteAction
ClassTypeID
单据模版号
InterID
单据内码
ClassType

ClassTypeEntry

TableInfo

Data