客开培训文档单据列表.docx

U8单据列表控件开发
培训部门：U8平台及公共开发部 U8版本号：V11.1
讲师： 李亮 定稿时间：2023-11-11

0.变更记录
变更阶段
时间
变更因素
变更类型
内容
提出人

1. 单据列表介绍
1.1 单据列表发展历程
单据列表发展经历了如下几个重大里程碑：
1、U8V8.72
1）单据列表控件引用的UFSpGrid.ocx 因代码超过VB工程“容量”，同时避免打破兼容性，更换为UFSpGrid2.ocx。
2）同时单据列表支持的编辑功能，具体如下：
单据列表对合并显示功能的支持：
要使单据列表支持合并显示的功能，重要要对栏目设立功能的进行设立，
单据列表对参照输入的支持
1、增长对事件BrowUser,FillList的支持，其用法与SuperGrid中的用法相同
2、要使单据列表具有参照输入的功能，须在栏目设立中进行如下设立：
a.AA_ColumnDic及AA_ColumnSet两个视图
b.BrowUserType，假如为NULL或为0，则单据列表状态保持原样，其它类型同SuperGrid中的类型定义，其定义如下：
'列参照类型
Enum BrowType
BrowNull = 0
UserBrowButton
DblBrowButton
DateBrowButton
BrowCom
End Enum
其值按１递增。
增长对超字段选择范围的支持，也就条件的字节数可以超过8k限制
增长对UAP结构下分页组件的调用方式,用法如下：
其大体调用方式与CS方式下的调用没有太大区别，与CS不同的地方在于要UAP的调用方式要声明一个算法变量，以支持UIP调用后结果集的导入，具体用法详见示例工程的Form2代码
增长对枚举类型的支持
在U8VouchList中增长分页的功能，用法如下：
1、请按原有使用VouchList的方式使用单据列表
2、将分页的按钮放在所使用的窗体中
3、在数据库中执行脚本，创建分页引擎的存储过程SPPagediv
2、U8V11.0
单据列表整合了翻页和快捷过滤功能，同时增强了交互和易用性。如：着色、布局等20多个功能，具体参考 《新单据列表迁移指导说明.doc》
1.2 单据列表达例代码及常用功能说明
具体代码示例工程参见：《列表测试工程》
1. 扩展：
Private WithEvents m_pagediv As Pagediv '分页引擎，配合实现单据列表自身的翻页功能。
Call objU8Tbl.InitExternalButton(strCardNum, m_Login)
Call Me.UFToolbar1.SetFormInfo(VchLst, Me) ‘单据列表及控件与toolbar绑定，以便后续二次开发功能拓展。
2. 属性：
VchLst.SumStyle = vlGridSum '合计方式
'合计方式枚举
Public Enum SumStyleEum
vlSumNone = 0 '没有合计
vlRecordsum = 1 '记录集合计
vlGridSum = 2 'Grid合计
vlRecordAndGridsum = 3 '记录集和Grid合计
End Enum
VchLst.ReadOnly = Not CBool(1)
VchLst.LoginObj = m_Login
VchLst.FltState = False
VchLst.ShiftUpDown = True ‘是否支持shift+上下箭头连续选择行
VchLst.HiddenRefreshView = False
VchLst.FillMode = FillOverwrite '填充模式
'填充模式枚举
Public Enum FillModeEnum
FillAppend = 0 '追加填充
FillOverwrite = 1 '覆盖填充
End Enum
VchLst.Title=“列表的标题”
VouchList.TextMatrix(row,col)=“单元格值”
VouchList.LocateState ‘定位状态 True：定位False：取消定位
VouchList.TopRow ‘纵向滚动后最顶上的当前行号
3. 方法：
Call VchLst.InitFlt(m_Login, clsVoucherLst.objFilter, "", "", "", strErrorRes) ‘初始化过滤对象
VchLst.InitHead oColSet.getColInfo() ‘初始化表头 sHeadXml表头格式信息
VchLst.SetPrintOtherInfo sXML ‘设立打印其它信息-表尾
Set domOption = VchLst.GetListDom(False) ‘取得列表相应dom对象 bSelect true-返回选中行dom对象 false-返回整个列表dom对象
sXML = Me.VchLst.GetColumnWidthXML() ‘获取被调整列宽或列序的栏目串
VchLst .SetFormatString "fdtrate", "0.000000" 、VchLst.DoFormat ‘设立格式化信息
VchLst.ClearDataSource ‘解除数据邦定
VchLst.SetVchLstRst vltable.DataRecordset ‘设立表体记录集
VchLst.RecordCount = vltable.DataCount ‘设立列表所有数据集记录数
VchLst.SetSumRst rstSum ‘合计记录集
Call VchLst.BindPagediv(m_pagediv) ‘分页引擎邦定
VchLst.AdJustGridWidth ‘作废
VchLst.ProtectUnload() ‘数据合法性检查。当前对象状态安全检查，可在执行某些上层功能时调用。如增长/删除功能、窗口Form_QueryUnload事件等地方
Private Sub ButtonClick(strButtonKey As String)
If VchLst.ReadOnly = False Then
If VchLst.ProtectUnload() <> 2 Then
Exit Sub
End If
End If
Call VchLst.ShowVoucherDesign(strPrintCardnum, ipvtidStr, "SA") ‘打印模板设计界面
VchLst.AddItem "", VchLst.rows ‘增长项目
VchLst.ShowBatchModify ‘调用这个方法显示批量修改窗口
//VchLst.AllSelect
//VchLst.AllNone
lngMainCol = VchLst.GridColIndex(strMainKey) ‘根据关键字来获取所在列的索引
VchLst.Find ‘查找:在定位状态下，查找下一个
VchLst.InitPrintSetup strPrnXml ‘初始化打印设立
VouchList.VchLstPreview ` '预览
VchLst.GetGridBody().XXX ‘引用UFSpGrid2.ocx，用于直接操作UFSpGrid2控件
VchLst.GetGridBody().GetGridBody().XXX ‘引用vsflexgrid.ocx，用于直接操作vsflexgrid控件
VouchList.Locate '定位
Set domLine = VouchList.GetBodyLine(iRow) ‘根据行索引取得表体行dom对象
4. 事件：
Private Sub VchLst_AfterColumnsDisplayRule() '着色后事件
Private Sub VchLst_BatchModify(sItemXML As String) '批改窗口弹出前，对传入批改窗口的xml进行再构造，比如设立参照类型等
Private Sub VchLst_BrowUser(RetValue As Variant, row As Long, Col As Long) ‘单元格编辑参照事件
Private Sub VchLst_CellValueChanged(ByVal row As Integer, ByVal Col As Integer, NewValue As Variant, OldValue As Variant, KeepFocus As Boolean) ‘单元格内容变化检查事件
Private Sub VchLst_DblClick() ‘双击
Private Sub VchLst_FillList(ByVal r As Long, ByVal c As Long, pCom As Object) ‘单元格编辑下拉事件
Private Sub VchLst_MouseUp(ByVal Button As Integer, ByVal Shift As Integer, ByVal X As Single, ByVal Y As Single)
Private Sub VchLst_PrintSettingChanged(ByVal varLocalSettings As Variant, ByVal varModuleSettings As Variant) ‘打印信息改变时触发
Private Sub VchLst_RowColChange() ‘单据列表支持切换行功能
Private Sub VchLst_SelectClick2(ByVal Selected As Boolean, ByVal row As Long) ‘SelectClick和SelectClick2使用一个就可以了，并且SelectClick2要逐渐替代SelectClick
Private Sub VchLst_CopySelect(bAuther As Boolean) ‘增长copy to cliborad的功能 ，返回权限。
Private Sub VouchList_BeforeSendCommand(cmdType As U8VouchList.UFCommandType, pageSize As Long, pageCurrent As Long) ‘列表翻页事件
2. 列表控件原有功能说明
2.1 特性
列表控件的安装位置：\U8SOFT\ufcomsql\U8VouchList.ocx
列表控件重要用于初报表外的表格样式的展示，涉及单据列表、生单列表、个别档案列表等等。
列表控件重要和栏目控件配合使用，也可以单独使用。
列表控件具有编辑能力，支持文本、数字、下拉框、参照等输入方式。

下面介绍列表控件的属性、方法、事件。
2.2 属性
BottomRow属性
说明：
获取当前显示区域最后一行的索引。只读属性。
语法： 
VouchList1. BottomRow
参数说明： 无
返回值：
当前显示区域最后一行的索引
ColPoint属性
说明：
获取与设立某列的小数位数。
语法： 
VouchList1. ColPoint (cFld) = [value as long]
参数说明： 
VouchList1：控件名称 
cFld：列的字段名
Value：小数位数
EditLocked属性
说明：
获取或设立控件是否被编辑锁定，锁定后将不能编辑。
语法： 
VouchList1. EditLocked () = [value as Boolean]
参数说明： 
VouchList1：控件名称 
Value：true—锁定，不能编辑，false—不锁定，可编辑。
FrozenCols属性
说明：
获取或设立列表控件冻结列的个数。
语法： 
VouchList1. FrozenCols () = [value as Long]
参数说明： 
VouchList1：控件名称 
Value：冻结列的个数
IsSumSelectedRows属性
说明：
获取和设立是否只对选中行进行合计。
语法： 
VouchList1. IsSumSelectedRows () = [value as Boolean]
参数说明： 
VouchList1：控件名称。
Value：true--只对打上“Y”的行进行合计；false—对所有行进行合计。
LeftCol属性
说明：
获取和设立当前显示区域最左侧列的索引。
语法： 
VouchList1. LeftCol = [value as Long]
参数说明： 
Value：当前显示区域最左侧列的索引
LoginObj属性
说明：
获取和设立登录对象，在批改时需要登录对象。
假如使用批量替换必须设立该属性，并且在调用ShowBatchModify之前必须设立好，假如不使用批量替换，可以不设立。
语法： 
VouchList1. LoginObj = [value as Object]
参数说明： 
Value：当前U8的登录对象
ReadOnly属性
说明：
获取和设立控件是否只读。
语法： 
VouchList1. ReadOnly = [value as Boolean]
参数说明： 
Value：true—只读 false—可编辑
RightCol属性
说明：
获取当前显示区域最右侧列的索引。只读属性。
语法： 
VouchList1. RightCol
参数说明： 
无
ShiftUpDown属性
说明：
获取和设立是否支持shift+上下箭头连续选择行。
语法： 
VouchList1. ShiftUpDown= [value as Boolean]
参数说明： 
VouchList1：当前控件对象。
Value：true—支持 false—不支持。
ShowSelCol属性
说明：
获取和设立是否显示选择列。
语法： 
VouchList1. ShowSelCol= [value as Boolean]
参数说明： 
VouchList1：当前控件对象。
Value：true—显示选择列 false—不显示选择列。
SortASC属性
说明：

获取和设立当前排序是升序还是降序。
语法： 
VouchList1. SortASC= [value as Boolean]
参数说明： 
VouchList1：当前控件对象。
Value：true表达升序 false表达降序。
SortCol属性
说明：
获取当前排序列的列号，假如返回值为-1表达没有排序列（还没有使用过排序）。
语法： 
VouchList1. SortCol
参数说明： 
VouchList1：当前控件对象。
SumRows属性
说明：
获取和设立合计（小计）行的行数。
有些合计行是业务组加进去的，不是用的SumStyle属性，这种情况解决选择行时就会把这样的行选中。增长这个属性后，业务组代码就可以更改合计行的行数，从而在选择行时排除这些行。
注意：合计行必须是在末尾
语法： 
VouchList1. SumRows= [value as Long]
参数说明： 
VouchList1：当前控件对象。
Value：有多少个合计行。
SumStyle属性
说明：
假如需要连续使用addline增长行，将会频繁地调用GridAutoSum（addline内调用）导致效率下降。
解决办法：程序员在连续调用addline之前，把sumstyle设立为sumnone，调用addline结束后，再赋回本来的合计方式。示例代码如下：
dim OldSumStyle As SumStyleEum
OldSumStyle = Vouchlist.SumStyle
VouchList.SumStyle = SumStyleEum.vlSumNone
........
VouchList.SumStyle = OldSumStyle
语法： 
VouchList1. SumStyle= [value as SumStyleEum]
参数说明： 
VouchList1：当前控件对象。
Value：
Public Enum SumStyleEum
vlSumNone = 0 '没有合计
vlRecordsum = 1 '记录集合计
vlGridSum = 2 'Grid合计
vlRecordAndGridsum = 3 '记录集和Grid合计
End Enum
TextMatrixName属性
说明：
返回表体中某一单元格的值，假如是枚举值，则返回枚举名称
语法： 
VouchList1.TextMatrixName(row as long,col as long)
参数说明： 
VouchList1：控件名称 
Row：行索引 
Col：列索引
TopRow属性
说明：
获取和设立当前显示区域最顶端行的索引。
语法： 
VouchList1. TopRow = [value as Long]
参数说明： 
Value：当前显示区域最顶端行的索引
2.3 方法
AddLine方法
说明：
根据传入dom对象新增长一行，内部要调用AddItem方法。
语法： 
Function AddLine(ByVal row As Long, ByVal oDom As DOMDocument) As Boolean
参数说明： 
Row： 插入行索引，在该行后插入新增行
oDom： 行dom对象 
返回值：成功返回true，失败返回false。
AddSumLine方法
说明：
根据传入dom对象新增长一行合计行.
语法： 
    Public Function AddSumLine(ByVal row As Long, ByVal oDom As DOMDocument) As Boolean
参数说明： 
Row：插入行索引，在该行后插入新增行
oDom：行dom对象 
返回值：
成功返回true，失败返回false。
CalcSum方法
说明：
重新计算合计行的数值。
语法： 
    Public Sub CalcSum()
参数说明：
无
返回值：
无
DisableTextMatrix方法
说明：
设立单元格是否可用，不可用后，既不能手工输入，也不能通过textmatrix赋值。
语法： 
    Public Sub DisableTextMatrix(ByVal bDisable As Boolean, ByVal sIndex As String, ByVal row As Long)
参数说明： 
bDisable： true-disable false-enable
sIndex： 列索引(字符串)
row： 行索引(数值) 
返回值：
无
GetBodyLine方法
说明：
根据行索引取得表体行dom对象。
语法： 
    Public Function GetBodyLine(ByVal row As Long) As DOMDocument
参数说明： 
row： 行索引数值) 
返回值：
行dom对象，其中包含行中的数据。
GetColIndex方法
说明：
根据列的字段名称取列的顺序号。
语法： 
    Public Function GetColIndex(ByVal ColName As String) As Long
参数说明： 
ColName： 列的字段名称 
返回值：
列的顺序号。
GetColName方法
说明：
根据列的顺序号取列的字段名称。
语法： 
    Public Function GetColName(ByVal ColIndex As Long) As String
参数说明： 
ColName： 列的顺序号
返回值：
列的字段名称 。
GetGridBody方法
说明：
获取列表控件封装的SuperGrid控件。
语法： 
    Public Function GetGridBody() As Object
参数说明：
无
返回值：
SuperGrid控件对象。 
GetHeadLine方法
说明：
取得标题行的dom对象。
语法： 
    Public Function GetHeadLine() As DOMDocument
参数说明：
无
返回值：
标题行的dom对象。
GetListDom方法
说明：
取得列表数据的dom对象。
语法： 
    Public Function GetListDom(ByVal bSelect As Boolean) As DOMDocument
参数说明： 
bSelect：true-返回选中行dom对象 false-返回整个列表dom对象
返回值：
列表数据的dom对象 。
HideCaption方法
说明：
隐藏列表的标题，如销售订单列表的标题“销售订单列表”。
语法 
    Public Sub HideCaption()
参数说明：
无
返回值：
无
Locate方法
说明：
弹出定位窗口，根据输入的条件定位。
语法： 
    Public Sub Locate(ByVal LocState As Boolean)
参数说明： 
LocState：true-定位 false-取消定位
返回值：
无。
ProtectUnload方法
说明：
当前对象状态安全检查，可在执行某些上层功能时调用。如增长/删除功能、窗口Form_QueryUnload事件等地方
语法 
    Public Function ProtectUnload() As OpType
参数说明： 
无
返回值：
Enum OpType
dbCandel = 0—取消操作
dbRetry---------重试操作
dbsuccess-------操作成功
End Enum
ReadOnlyTextMatrix方法
说明：
设立单元格是否只读，只读单元格不能手工输入，但是可以通过textmatrix赋值。
语法： 
    Public Sub ReadOnlyTextMatrix(ByVal bReadOnly As Boolean, ByVal sIndex As String, ByVal row As Long)
参数说明： 
bReadOnly： true-只读 false—可编辑
sIndex： 列索引(字符串)
row： 行索引(数值) 
返回值：
无
RemoveItem方法
说明：
删除一行。
语法： 
    Public Sub RemoveItem(ByVal Index As Variant)
参数说明： 
Index： 行索引(数值) 
返回值：

无
SetCellFocus方法
说明：
光标移至单元格（Row,Col）。
语法： 
    Public Function SetCellFocus(ByVal row As Long, ByVal col As Long)
参数说明： 
row： 行索引(数值) 
col： 列索引(数值) 
返回值：
无
SetListDom方法
说明：
将dom对象内的数据刷新到列表界面上，dom对象是一个recordset转换的对象。
语法： 
    Public Function SetListDom(ByVal oDom As DOMDocument) As Boolean
参数说明： 
oDom：存放数据的dom对象
返回值：
执行成功返回true，否则返回false。
ShowBatchModify方法
说明：
显示批量修改窗口，要支持批量修改功能，必须调用此方法。
语法： 
    Public Sub ShowBatchModify()
参数说明： 
无
返回值：
无
UpdateLine方法
说明：
根据传入dom对象数据更新一行。
语法： 
    Public Function UpdateLine(ByVal row As Long, ByVal oDom As DOMDocument) As Boolean
参数说明： 
Row：行索引
oDOM：dom对象
返回值：
更新成功返回true，否则返回false。
2.4 事件
AfterSort事件
触发时机： 
排序之后触发此事件
功能：  
解决列排序后的事件 
声明： 
Public Event AfterSort(ByVal col As Long, ByVal bAsc As Boolean)
参数说明：
bAsc：true－升序 false－降序
col：排序的列号
BatchModify事件
触发时机： 
批改窗口弹出前触发此事件
功能：  
批改窗口弹出前，对传入批改窗口的xml进行再构造，比如设立参照类型等。
声明： 
Public Event BatchModify(ByRef sItemXML As String)
参数说明：
sItemXML：出给批改出口的xml字符串。
BeforeEdit事件
触发时机： 
单元格进入编辑状态前触发此事件
功能：  
进入编辑之前的事件，可以在这里做一些编辑前的设立和判断，假如Cancel返回true，则不进入编辑。
声明： 
Public Event BeforeEdit(ByRef Cancel As Boolean)
参数说明：
Cancel：假如Cancel返回true，则不进入编辑。
BeforeSort2事件
触发时机： 
将要排序之前触发此事件
功能：  
解决列排序前的个性化需求
声明： 
Public Event BeforeSort2(ByRef bSort As Boolean, ByVal col As Long, ByVal bAsc As Boolean)
参数说明：
bSort：是否继续排序，假如为false，则将不执行排序操作，也将不触发BeforeSort和AfterSort事件。
bAsc：true－将要执行的是升序 false－将要执行的是降序
col：排序的列号
BeforeSort事件
此事件已废弃，由BeforSort2代替。
Click事件
触发时机： 
鼠标在控件上点击时触发
功能：  
解决鼠标单击事件
声明： 
Public Event Click()
参数说明：
无
DblClick事件
触发时机： 
鼠标在控件上双击时触发
功能：  
解决鼠标双击事件
声明： 
Public Event DblClick()
参数说明：
无
IsAllowBatchModify事件
触发时机： 
批改窗口关闭后，执行批改过程中触发。
功能：  
是否允许批改事件，在进行批改前判断单元格是否可修改，假如bCanModify返回为false，则对此单元格不执行批改。
声明： 
Event IsAllowBatchModify(ByRef bCanModify As Boolean, ByVal row As Long, ByVal colkey As String)
参数说明：
bCanModify：false－不执行批改 true－执行批改
row行索引
colkey：列字段名
KeyDown事件
触发时机： 
键盘按键按下时触发
功能：  
解决键盘按键按下事件
声明： 
Public Event KeyDown(ByVal KeyCode As Integer, ByVal Shift As Integer)
参数说明：
KeyCode：按下的按键
Shift：同时按下的其他功能键
KeyPress事件
触发时机： 
键盘按键按下时触发
功能：  
解决键盘按键按下事件
声明： 
Public Event KeyPress(ByVal KeyAscii As Integer)
参数说明：
KeyAscii：按下的按键
KeyUp事件
触发时机： 
键盘按键按下后又松开是触发
功能：  
解决键盘按键松开抬起时的事件
声明： 
Public Event KeyUp(ByVal KeyCode As Integer, ByVal Shift As Integer)
参数说明：
KeyCode：按下的按键
Shift：同时按下的其他功能键
SelectClick2事件
触发时机： 
当选中/取消选（打上“Y”/去掉“Y”）中一行时触发此事件。
代替SelectClick事件。

功能：  
解决行选中/取消选中时的个性化操作。
声明： 
Public Event SelectClick2(ByVal Selected As Boolean, ByVal row As Long)
参数说明：
Selected:当前所点击的选择列的状态，假如已选择，也就是被打上“Y”，则此值为True，否则为False
Row：当前选中/取消选中的行索引。

其他的属性、方法、事件

列表控件其他的属性、方法、事件请参考：（html格式文献，双击图标可打开）
2.5 Supergrid表格控件
SuperGrid控件的安装位置：\U8SOFT\ufcomsql\UFSPGrid.ocx
属性
方法
AddItem方法
说明：
在列表表体中增长一行
语法： 
     VouchList1.AddItem(Item As String, [Index As Long])
参数说明： 
Item：待插入行的String表达，用vbTag或Chr(0)分隔开的字符串 
Index：待插入的行在列表中所在的位置，假如这个参数忽略，将在列表的表体最末行加入 
返回值：
无 
Clear方法
说明：
清空Grid的数据。
语法： 
     VouchList1.AddItem(Item As String, [Index As Long])
参数说明： 
Item：待插入行的String表达，用vbTag或Chr(0)分隔开的字符串 
Index：待插入的行在列表中所在的位置，假如这个参数忽略，将在列表的表体最末行加入 
返回值：
无
事件
BeforeEdit事件
触发时机： 
单元格进入编辑状态前触发此事件
功能：  
进入编辑之前的事件，可以在这里做一些编辑前的设立和判断，假如Cancel返回true，则不进入编辑。
声明： 
Event BeforeEdit(Cancel As Boolean, sReturnText As String)
参数说明：
Cancel：假如Cancel返回true，则不进入编辑
sReturnText：可以通过这个参数返回单元格的值
其他的属性、方法、事件
Supergrid表格控件的属性、方法、事件请参考：（html格式文献，双击图标可打开）

3. 栏目控件相关
3.1 特性
栏目控件是用来设立编辑栏目的位置、标题、宽度等信息的控件，开发者可以运用此控件返回的SQL语句动态拼写SQL语句。
3.2 显示栏目
Dim colset as New U8ColumnSet.clsSet
Cnnstr=”Data数据库连接串”
Call colset.init(cnnstr,用户名)
Call colset.setColMode(Key值，1) ‘第二个参数为1返回显示列，为2返回默认列，为0返回所有列
Colset.setcol

3.3 得到返回值
² GetSqlString 返回SQL语句的Select部分。
² GetSqlSumString 返回SQL语句的汇总部分（需要将ShowSumType设立为True才有效）。
² GetOrderString、GetOrderStringEx返回SQL语句的Order by部分。
² GetSQLGr