HTC组件API手册.doc

/用户名称：神州数码（中国）有限公司密级： HTC组件API手册文档编号：文档名称：编 写：编写日期：审 核：审核日期：批 准：批准日期：修订状况章节编号章节名称修订内容简述修订人修订日期修订前版本号批准人4Datawindow属性增加此属性，用于实现dw分页时每页的序号累积王健2006-3-2Datawindow属性支持多表头及表头的合并王健2006-5-3Datawindow方法支持在任意位置插入行赵元凯2006-5-113.18DocEditorX增加word编辑控件，用于在ie内能进行word文档的编辑List属性增加对齐方式属性align赵元凯2006-6-Datawindow列属性增加列对齐方式属性align赵元凯2006-6-2Datawindow列属性增加表头对齐方式属性headeralign赵元凯2006-6-5Datawindow属性增加对列的分组合计汇总的功能王健2006-6-TextArea增加maxLength和minLength两个属性王健2006-6-TextField增加maxLength和minLength两个属性王健2006-6-Tree增加tree分批加载数据的功能王健2006-6-3Datawindow列属性增加input输入法开关ime赵元凯2006-6-3Datawindow列属性增加input大小写控制属性ucase赵元凯2006-6-231. HTC组件综述1.1. 本指南适用范围和人员本手册是为在SmatFrame平台上进行应用开发，前端使用htc方案的开发人员编写的。阅读人员需了解如下的基础知识：1） activex控件2） javascript语言3） xml语言4） j2ee1.2. HTC架构介绍1.2.1. HTC概述HTML组件(HTCsHtml Components)提供一种机制来使用脚本作为动态HTML(DHTML)行为实现组件功能。以.htc扩展名保存，一份HTC是一份包含脚本和一组用于定义组件的HTC特殊元素的HTML文件。HTC组件内可包含属性、方法、事件，也可订阅绑定页面的事件，通过这些机制实现功能的封装。可理解成一个功能独立的javabean或一个activex控件，只是它的封装层次是在页面这一层。Frame提供的前端HTC组件主要是一组前端页面的展示组件和一些前端编程的工具函数。前端展示HTC组件内部以封装activeX控件的形式提供展示功能，包括自定义文本框、树型列表、单选下拉列表，多选下拉列表，数据网格等组件。前端编程工具函数以js文件的形式提供，主要提供loadXml,XmlToHtml,HtmlToXml,checkValid等功能。1.2.2. HTC的组成和调用客户前端WebServer通过XMLHTTP(msxml4.dll)进行前后台消息的请求和响应页面内的js脚本Service.jsHTC组件脚本ActiveX:Ctais_htc.ocxAutoupdt.dllDcbassrv.dll辅助工具脚本:checkValid.jsservicexml.jsHtc的前端由图示的几部分组成，service.js文件是前后端调用的总控模块，负责调用报文的拼装，操作xmlhttp进行报文的发送和接收，并将相应数据返回给调用的页面或js代码。Htc组件主要是对activeX控件的封装，使可直接使用html语言进行定义。Activex控件实现了大多数的界面元素，其中autoupdt.dll和dcbassrv.dll实现了组件的自动下载和一些基本服务支持。辅助工具脚本是一些有用的辅助开发工具，能够减少代码开发量和规范页面的一致性。checkValid用于对整个页面元素（主要是htc的页面元素）进行统一的有效性验证，servicexml用于统一处理数据从html页面的导出，和将xml数据导入到html页面内。所以对于常规的htc前端页面的开发，包含如下步骤：1） 使用htc组件进行页面的定义2） 使用jsp和js脚本进行页面逻辑的开发3） 通过调用service.js内提供的方法访问后台的服务进行数据的提交和交换。2. 脚本工具2.1. htcCommon.js2.1.1. 用途负责维护一些常用的前台路径及全局的调试信息，用户在配置完Frame的htc方案后，可手工修改此文件的变量，完成信息的配置2.1.2. 引用方式2.1.3. 配置变量说明1） var G_DEBUG = false;定义是否在调试状态，如果G_DEBUG = true，则前后台传输的报文会打印到一个对话框上。2） var HOST = http:/localhost:7001;主机路径3） var URL_SERVICE_ENTRY = /WebTest/entry/EntryServlet;后台servlet的入口地址4） var URL_MESSAGE = /WebTest/public/htmComponent/htm/dlg_message.htm;调试信息对话框的地址5） var URL_ALERT = /WebTest/public/htmComponent/htm/dlg_alert.htm;定制了window.alert函数6） var URL_CONFIRM = /WebTest/public/htmComponent/htm/dlg_confirm.htm;定制了window.confirm函数7） var URL_PROMPT = /WebTest/public/htmComponent/htm/dlg_prompt.htm;定制了mpt函数2.2. service.js2.2.1. 用途Service.js是一个核心脚本，负责前后端的通讯，所有服务报文的发送，接收，解析都是通过这个脚本来操作的，另外还提供一些和xml数据操作相关的函数和在调试状态下对报文的查看。2.2.2. 引用方式2.2.3. 函数. createWorkId1 功能描述产生一个随机数，用于和后台的工作区相对应2 语法格式var sid = createWorkId();3 返回值一个随机数字符串4 相关Service doService . doService1 功能描述执行一个具体的后台服务调用，并将结果返回。2 语法格式var xmlResult = service.doService();var xmlResult = service.doService(strCondition);3 参数strCondition：xml格式字符串，对应于后台服务方法调用的传入条件字符串。4 返回值xmlResult：xml格式字符串，后台服务返回的结果。5 举例下面的示例演示了一个完整的服务方法的调用过程var sid=createWorkId();var service = new Service(“com.dc.class.method”, sid);var oArg = service.doService(“%”);if (getCode(service)= 2000) var oDoc = loadXml(oArg);/将数据映射到对应的htc控件内elseshowMessage(getMessage(service), 0);6 相关Service createWorkId getCode. getCode1 功能描述得到调用后台服务的返回代码，约定2000为正常调用的返回代码，其他代码用户可自定义其含义，前后台根据约定的代码进行相应的处理。2 语法格式var sCode = getCode();var sCode = getCode(service);3 参数service：Service对象实例4 返回值字符串格式的返回代码5 备注第一种无参数的调用方式返回当前Service实例对象对应的返回代码；第二种调用返回指定的Service实例对象的返回代码6 相关Service doService getMessage. getMessage1 功能描述得到调用后台服务的返回代码对应的消息说明，当返回代码不为2000时，通常在此处得到详细的异常消息说明。2 语法格式var sMsg = getMessage ();var sMsg = getMessage (service);3 参数service：Service对象实例4 返回值返回的消息说明字符串5 备注第一种无参数的调用方式返回当前Service实例对象对应的消息说明；第二种调用返回指定的Service实例对象的消息说明6 相关Service doService getCode. loadFile1 功能描述装入指定的xml文件，以XmlDocument对象的形式返回2 语法格式var oDoc loadFile(strFile);3 参数strFile：一个本地的xml文件的全路径名4 返回值包含装入的xml文件的XmlDocument对象5 相关loadXml. loadXml1 功能描述将给定的xml字符串进行解析，以XmlDocument对象的形式返回2 语法格式var oDoc loadXml(strXml);3 参数strXml：xml格式的字符串4 返回值XmlDocument对象5 相关loadFile. Service1 功能描述通过new Service对象，建立一个前后台的连接机制，将前台的调用映射到后台的一个服务调用上，在doService()时调用后台的服务，并将结果返回。2 语法格式var service = new Service(serviceName, sid);3 参数1) serviceName：一个后台具体的服务名称字符串2) sid：可选参数，工作区标识号字符串4 返回值Service对象的引用5 举例具体例子可参阅doService()。6 相关doService getCode getMessage. xmlNodeCopy1 功能描述xml节点之间的数据复制。一般用于把doservice()返回的数据，映射到页面的相应的数据岛中。2 语法格式void xmlNodeCopy(oSrc, oTarget, targetNodeName)3 参数1) oSrc：原数据的节点，可是XmlDocument或XmlEmlment对象2) oTarget：一般为页面上的数据岛，也可以是XmlDocument或XmlEmlment对象3) targetNodeName：目标节点名称字符串。必须写出该节点的完整路径，如:ROOT/ITEMS。4 返回值无5 备注1) oSrc和oTarget可具有相同的xml结构，或者oTarget是oSrc的一个子集。2) 当进行节点之间的拷贝时，如果目标数据岛或节点内有数据则清除。2.3. servicexml.js2.3.1. 用途用于将大量xml格式的数据信息和html页面上的元素通过id属性进行绑定和导出,现在支持的绑定元素包括：input，textarea，select，drop2.3.2. 引用方式2.3.3. 函数. xmlTohtml1 功能描述将给定的xml数据绑定到一个form对象内的相应的元素上。2 语法格式xmlTohtml(strXML, form);3 参数1) strXML：xml格式的字符串，记录了需要映射的元素名称和数据2) form：html页面内form表单的id名称4 举例详见演示代码. htmlToxml1 功能描述将html页面上的form对象内的各个元素上的数据提取出来，以xml数据导出。2 语法格式var strXml = htmlToxml(form);3 参数form：html页面内form表单的id名称4 返回值包含form表单全部元素和数据的xml字符串5 举例详见演示代码2.4. checkValid.js2.4.1. 用途对html页面元素进行整体的数据验证,现在支持的绑定元素包括：INPUT,SELECT,TEXTAREA,IFRAME,FRAME:SELECT2.4.2. 引用方式2.4.3. 属性. fill1 功能描述定义html元素是否必填2 语法格式3 取值true：必填项. checkType1 功能描述定义当对html元素进行验证时的验证类型，对元素进行验证的类型包括数字，正则表达式，日期，email，长度范围，2 语法格式3 取值1) number(len,pric)：表示元素是数字类型，数字的总长度为len，小数点后的长度为pric位。2) date：元素是日期格式3) email：元素是email格式4) range(number1,number2)：元素的长度范围在number1和number2之间5) regexp（expression）：一个合法的自定义的整个表达式4 举例1) 下面示例定义一个数字类型的元素，长度返回在10位以内，并且允许小数点后有两位数字2) 下面示例自定义一个正则表达式的验证格式，允许输入09的数字，并且长度范围在1020之间2.4.4. 函数. checkValid1 功能描述根据指定范围-例如某个FORM表单，解析其中的HTML dom对象，验证有效性并返回结果.如果TRUE 则表明验证通过2 语法格式var result =checkValid(form);3 参数form：html的一个form表单对象标识字符串4 返回值Boolean。true表示验证通过，否则不通过。3. HTC组件3.1. TextArea3.1.1. 用途Htc组件的TextArea对html的TextArea进行了少量的扩充，除支持原有input的功能外，扩充了是否必填，数据最小最大长度的限制等。本部分列出的属性和方法只是扩充的功能，原来的功能依然可以使用。当在控件上按下“Enter”键时，会将焦点移动到下一个控件，如果希望在本行输入完后，还行到下一行，需按“ALT+Enter”组合键。3.1.2. 引用和定义1 引用media Allinputbehavior: url(./htc/textarea.htc);2 定义3.1.3. 属性. fill1 功能描述设置文本框填充风格，是否为必填项2 语法格式定义：脚本：var b = input1.fill;3 读写状态R/W4 属性值布尔类型，true：控件为必须输入false：默认值，不为必填项. maxLength1 功能描述设置文本框中输入内容的长度，默认值为0，表示没有最大长度限制2 语法格式定义：脚本：var num = input1.maxLength;3 读写状态R/W. minLength1 功能描述设置文本框中输入内容的最小长度，当输入字符串的长度不足此设置时，当焦点离开时，给出错误提示。2 语法格式定义：3 读写状态R/W4 备注1） 当使用鼠标离开焦点时，不进行最小长度的验证2） 长度以字符串个数作为计数，不以字节数计数3） 当fill=no时，如果文本框为空，则不进行此验证。3.1.4. 方法. checkData1 功能描述检验输入数据的有效性，有效true,无效false,主要检查是否符合minLength的限制2 语法格式var b = textarea. CheckData();3 参数无4 返回值true：验证通过。False：不符合. getValue1 功能描述得到文本框中的输入文本值。2 语法格式var strValue = textarea.getValue();3 参数无4 返回值文本内容字符串。5 备注请不要使用默认的value属性取得内容，会产生冲突。. setValue1 功能描述设置文本框中的文本值。2 语法格式 textarea.setValue(strValue);3 参数strValue：要设置的文本字符串4 返回值无5 备注请不要使用默认的value属性设置内容，会产生冲突。3.2. TextField3.2.1. 用途Htc组件的Input是对html的input的扩充，除支持原有input的功能外，扩充了对不同输入类型的支持，现支持的类型有：日期型、数字型、百分比型、金额型。本部分列出的属性和方法只是扩充的功能，原来的功能依然可以使用。本控件常用于页面上不同类型文本框的输入。3.2.2. 引用和定义3 引用media Allinputbehavior: url(./htc/textfield.htc);4 定义3.2.3. 属性. ctrl1 功能描述用于对控件的显示形式做控制，并且优先级高于disable属性。2 语法格式定义：脚本：var strCtrl = input1.ctrl;3 读写状态R/W4 属性值字符串类型，可是如下三种类型no：默认值，不对控件做任何限制。disable：使控件无效，不可编辑。当设置此属性后disable属性无效。noshow：使控件无效并且显示内容不可见(以*号显示)。当设置此属性后disable属性无效。. disable1 功能描述设置控件是否可编辑2 语法格式定义：脚本：var b = input1.disable;3 读写状态R/W4 属性值布尔类型，true：控件灰色显示，不可编辑false：默认值，控件正常显示，并且可编辑5 备注请不要使用input的html属性：disabled. fill5 功能描述设置文本框填充风格，是否为必填项6 语法格式定义：脚本：var b = input1.fill;7 读写状态R/W8 属性值布尔类型，true：控件为必须输入false：默认值，不为必填项. maxLength4 功能描述设置文本框中输入内容的长度，日期默认8位，数字默认2位小数点,Data类型默认十位。5 语法格式定义：脚本：var num = input1.maxLength;6 读写状态R/W. minLength5 功能描述设置文本框中输入内容的最小长度，当输入字符串的长度不足此设置时，当焦点离开时，给出错误提示。6 语法格式定义：7 读写状态R/W8 备注4） 当使用鼠标离开焦点时，不进行最小长度的验证5） 长度以字符串个数作为计数，不以字节数计数6） 当fill=no时，如果文本框为空，则不进行此验证。. preset1 功能描述设置文本框的显示格式2 语法格式定义：脚本：var strPreset = input1. preset;3 读写状态R4 属性值字符串类型，默认为任意文本类型，共有如下几种形式：NUMBER(x,y)：数字类型，x表示总位数，y表示小数点后位数。DATE：日期类型。PERCENT：百分比类型CURRENCY：金额类型. readOnly1 功能描述设置文本框是否只读，不可编辑，但能够进行拷贝2 语法格式定义：脚本：var b = input1. readOnly;3 读写状态R/W4 属性值布尔类型，true：控件为只读状态false：默认值，可编辑状态. tooltip1 功能描述设置当鼠标移动到文本框上后，显示的提示标题2 语法格式定义：脚本：var str = input1.tooltip;3 读写状态R/W4 属性值字符串类型3.2.4. 方法. checkData5 功能描述检验输入数据的有效性，有效true,无效false6 语法格式var b = input. CheckData();7 参数无8 返回值true：验证通过。False：不符合preset设定的输入. getValue6 功能描述得到文本框中的输入文本值。7 语法格式var strValue = input.getValue();8 参数无9 返回值文本内容字符串。10 备注请不要使用默认的value属性取得内容，会产生冲突。. setValue6 功能描述设置文本框中的文本值。7 语法格式 input.setValue(strValue);8 参数strValue：要设置的文本字符串9 返回值无10 备注请不要使用默认的value属性设置内容，会产生冲突。3.2.5. 事件. OnFocus1 功能描述在获得输入焦点时触发此事件2 参数event.onfocus. OnBlur3 功能描述当失去交点时触发事件4 参数event.onBlur. onchange5 功能描述当文本框内容发生改变-激发6 参数Event.onchange3.3. List3.3.1. 用途列表控件，列表展示多行数据，并且每行可显示多列。3.3.2. 引用和定义1 引用2 定义3.3.3. xml数据格式 Zhangboy Wangboy 3.3.4. 属性. align1. 功能描述指定List的列对齐方式,彼此之间用|隔开。同时作用于该列的列头和数据。2. 语法格式3. 读写状态R4. 属性值字符串类型，有效值为：left, center, right。不设置该属性或设置无效值时默认左对齐。5. 备注设置不包含第一列，即序号列。序号列默认左对齐，不能更改。. checkedRows1 功能描述返回当前check的所有行组成的集合2 语法格式var oLst = List.checkedRows;3 读写状态R4 属性值返回一个List的内部对象类. colsWidth6. 功能描述指定List的列宽度,彼此之间用|隔开。注意指定的是序号列宽度的倍数！7. 语法格式var str = List.colsWidth ;8. 读写状态R9. 属性值字符串类型. label1 功能描述指定List的列标题,彼此之间用|隔开2 语法格式var str = List. label;3 读写状态R4 属性值字符串类型. view1 功能描述指定List的列绑定的数据岛中的节点名称,彼此之间使用|隔开2 语法格式var str = List. view;3 读写状态R4 属性值字符串类型. node1 功能描述当采用静态加载数据时，List绑定的XML数据岛名称2 语法格式3 读写状态R4 属性值对象类型. nodeRequest1 功能描述在网页控件初始化时使用此方法，初始化下拉列表中的数据。 根据传入的查询要求，生成新的sid，查询服务得到结果。根据给出的xml节点路径的说明，将结果数据写入控件中。适用于页面初始化时载入后台字典表中数据。2 语法格式3 读写状态R4 属性值字符串类型，字符串规则如下“服务名称:查询条件:返回的xml节点路径”，中间以”:”进行分割5 举例下面示例定义一个list控件，在页面载入时，会调用role.RoleBndService.init服务，并把服务返回的xml数据的ROOT/ROLE_DATA节点下的内容载入控件。6 备注此属性自己创建sid，并且服务须返回数据。当node属性定义时，此属性无效. selectedIndex1 功能描述当前选中的行索引,如果没有选中返回-1，0-based2 语法格式var num = List.selectedIndex;3 读写状态R4 属性值数字类型3.3.5. 方法. addRow1 功能描述往列表中增加一行数据，增加到列表的尾部2 语法格式list.addRow(strRowData);3 参数strRowData：字符串，要添加的行的内容，每列用”|”分割，,例如AAA|BBB. clear1 功能描述删除所有内容2 语法格式list.clear();. deleteRow1 功能描述删除索引指定行2 语法格式list.deleteRow(rowIndex);3 参数rowIndex：整数，要删除的行索引，0-based. getCellValue1 功能描述获得指定坐标单元格的内容2 语法格式var strCellValue = list.getCellValue(rowIndex,colIndex)3 参数7） rowIndex：整数，行索引，0-based8） colIndex：整数，列索引，0-based4 返回值字符串，坐标对应单元格的文本值. getColCount1 功能描述返回列表中列的总数2 语法格式var iCol = list.getColCount();3 返回值整数. getRowCount1 功能描述返回列表中的总行数2 语法格式var iRow = list.getRowCount ();3 返回值整数. getRowData1 功能描述获得指定行的字符串数据，彼此列之间用|隔开2 语法格式var strRowData getRowData(rowIndex);3 参数rowIndex：整数，行索引，0-based4 返回值字符串，行数据. hasFocus1 功能描述当前控件实例是否获得焦点2 语法格式var b = list.hasFocus();3 返回值true：当前控件具有焦点false：当前控件没有焦点. mapNode1 功能描述动态绑定xml数据到控件上2 语法格式list.mapNode(oDoc);3 参数oDoc：XmlDoument对象，xmlElement对象，或数据岛对象0. rowIsChecked1 功能描述判断指定索引对应的行是否被check2 语法格式var b = list.rowIsChecked(rowIndex);3 参数rowIndex：整数，行索引，0-based4 返回值布尔类型true：行被checkedfalse：行没有被checked1. selectRow1 功能描述选中索引指定的行2 语法格式list.selectRow(rowIndex);3 参数rowIndex：整数，行索引，0-based2. setColor1 功能描述配置组件的颜色显示方案2 语法格式list.setColor(type,color);3 参数1) ype：字符串，设置颜色的位置，是如下类型：DEFAULT_COLOR: 默认的背景色FILL_COLOR：必添列背景色TEXT_CONTENT_COLOR：正文文本颜色2) color：字符串，十六进制或十进制颜色色值4 举例list.setColor(FILL_COLOR,&HF5D8D1);5 备注注意：如为十六进制表示法，数值表示顺序为蓝绿红。和网页上颜色红绿蓝的顺序的设置正好相反。例如网页上颜色值rrggbb，此处应为&Hbbggrr3. setFont1 功能描述配置组件的字体显示方案2 语法格式list.setFont (type, fontname,bold,fontSize);3 参数1) type：字符串，设置字体生效的位置，是如下类型：TEXT：正文文本字体2) fontname：字符串，字体的类型名称3) bold：布尔true：加粗显示字体false：默认值，正常显示4) fontSize：整型，字体尺寸，默认值为124 举例下面例子设置正文字体为隶书，正常12号字显示list.setFont(TEXT,隶书,false);4. setCellValue1 功能描述设置指定单元格的值2 语法格式list.setCellValue(rowIndex,colIndex, val);3 参数1） rowIndex：整数，行索引，0-based2） colIndex：整数，列索引，0-based3） val：字符串，要设置的单元格内容3.3.6. 事件. onrowcheck1 功能描述当某行被check时触发此事件2 参数event. rowIndex：整数，当前被check的行索引，0-based. onrowclick1 功能描述当某行被鼠标单击时触发此事件2 参数event. rowIndex：整数，当前被单击的行索引，0-based. onrowselect3 功能描述当某行被加亮选中时，触发此事件4 参数event. rowIndex：整数，当前被选中的行索引，0-based3.4. Select3.4.1. 用途Select是一个单选下拉列表框控件，除具有基本的下拉列表框的功能外，支持显示字体颜色的自定义，数据岛数据和后台服务请求数据的加载，和后台字典的直接数据绑定，数据的模糊查询等功能。3.4.2. 引用和定义1 引用2 定义3.4.3. xml数据格式 0101卷烟0.6 0102雪茄烟1.6 0103烟丝3 0104烟叶5 3.4.4. 属性. all1 功能描述将内部所有数据，以list对象集合的形式返回。2 语法格式var oList = select.all;3 读写状态R4 属性值List：内部的类对象，可参阅List类说明. ctrl1 功能描述将内部所有数据，以list对象集合的形式返回。2 语法格式var strCtrl = select.ctrl;3 读写状态R/W4 属性值字符串类型，可是如下三种类型no：默认值，不对控件做任何限制。disable：使控件无效，不可编辑。当设置此属性后disable属性无效。noshow：使控件无效并且显示内容不可见(以*号显示)。当设置此属性后disable属性无效。. dictRequest1 功能描述在网页控件初始化时使用此方法，查询字典表数据，将结果写入控件列表内2 语法格式3 读写状态R4 属性值字符串字符串规则如下“数据源:表名称:列名称,”，中间以”:”进行分割，列名称之间以“,”分割。数据源不填使用缺省的数据源，列名称不填则查询出所有列字段。5 举例下面示例在页面定义一个select控件，并且在页面初始化时会调用后台的数据岛服务，查询department表，将表内的全部数据返回绑定到控件上.6 备注此属性自己创建sid，并且服务须返回数据。当node属性定义时，此属性无效. fill1 功能描述设置文本框填充风格，是否是必填字段，必填字段要求文本框内必须输入数据。2 语法格式定义：脚本：var b = select.fill;3 读写状态R/W4 属性值布尔类型，true：控件为必须输入false：默认值，不为必填项. in