jatoolsPrinter8.2最新使用手册.doc

jatoolsPrinter 使用手册（更新日期：2012-11-13）简介安装快速入门最简单的打印预览打印前设置打印参数保留打印时的打印参数第一次打印用当前配置，后续打印用最后一次打印配置批量打印文档多个文档共存在同一web页面中，区别打印不显示文档，直接指定url打印打印隐藏对象仅在预览时可见，不输出到打印机的套打底图打印时样式类的自动插入(实现不打印表格线等)样式文件(*.css)的显式导入 打印结束后提交数据为什么要使用回调方法打印后关闭窗口可视化设计套打 视频演示 打印内容相对位置的事后调整及保存 视频演示调整后的套打位置信息保存到服务端连续打印的套打偏移校正 使用自动分页表格自动分页，表头每页可见页内多表自动分页含合并单元格的表格自动分页 表格的横向自动分页 大单元格分页自动缩放打印指定缩放比例打印零边距打印预览时提示生成监视打印任务状态手动双面打印模式自动双面打印模式打印份数控制打印指定页 监听打印页数事件显示页面设置对话框后打印选择打印机进行打印选择打印机,纸张类型,边距进行打印纵横打印(有些页纵向打印，有些横打) Excel导出 打印非 HTML 文档(*.doc,*.xls,*.ppt,*.pdf)附件方式打印非 HTML 文档(*.doc,*.xls,*.ppt,*.pdf)打印TIFF文件 设置图文并茂的页脚页眉个性化的页脚页眉(首页不打印页脚页眉)一次打印中的页号分组指定显示的起始页号取本地MAC地址取CPU序列号用控件设置IE打印背景使用插件，使jatoolsPrinter 支持 firefox、chrome、safari 支持繁体中文、英文、日文等界面附录：API 参考手册简介:jatoolsPrinter 是一款实现网页套打的专门工具。作为web应用开发者，我们经常会遇到在浏览器中打印报表、票据的需求，浏览器本身 提供的打印功能一般不能满足这些需求，如精确分页，套打等。jatoolsPrinter正是为了解决这些需求而专门研发的。使用jatoolsPrinter可以最大限度地实现对web页面的打印控制，比如，输出到哪个打印机，什么纸张类型，是否打印附件等。设置图文并茂的页眉、页脚，自动分页或程序分页。你也可以利用jatoolsPrinter随心所欲地定制出自己的打印设置界面，更好地满足项目需求。jatoolsPrinter不同于报表工具，它只解决web客户端的html页面的打印问题，至于这些页面如何生成，格式怎样需要你自己做后端的开发（使用jsp,asp,或php等） ，因此，你可以有很大的自由度来定制格式。jatoolsPrinter也没有可视化的票据或报表设计工具，而一般报表工具都有可视化的报表设计器。jatoolsPrinter只需要在web服务器的一个目录中，放置一个控件文件即算配置完成，而报表工具一般在服务端需要配置报表服务引擎。jatoolsPrinter是本公司报表产品杰表的一个组件，2006年起单独发展成品。如果你需要可视化的套打设计工具、各种格式(Excel,pdf)导出、表格无折断分页等更为强大的功能，建议你采用本公司的报表产品，杰表.2008。安装:服务端：可以是任何操作系统，任何web服务器，比如iis、tomcat、weblogic、websphere等。客户端：windows操作系统（除win95/98外），Internet Explorer5.5及以上版本。1. 服务端 先来看一个示例网页 test.htm . .如果你访问该网页的地址是: /print/test.htm 则你必须将 jatoolsPrinter.cab放在 /print/jatoolsPrinter.cab 可以访问到的地方。总之，jatoolsPrinter.cab位置，需要根据当前网页路径与codebase属性，来确定。请体会以下示例： 例一、 网页地址： /print/test.htm codebase属性： xyz/jatoolsPrinter.cab#version=5,7,0,0 jatoolsPrinter.cab地址： /print/xyz/jatoolsPrinter.cab 例二、 网页地址： /print/test.jsp codebase属性： /jatoolsPrinter.cab#version=5,7,0,0 jatoolsPrinter.cab地址： /jatoolsPrinter.cab 2. 浏览器端 当你访问使用打印控件的网页时，浏览器将从服务器上下载控件，自动安装到ie中。 当然，如果你的IE安全设置过高，也可能不能自动安装，这时，你需要改变IE的安全设置，或进行离线安装。如果你需要离线安装，可以向我们申请离线安装包。 IE安全设置方法如下：IE 浏览器-工具- internet 选项-安全-自定义级别，设置下载未签名的 ActiveX为启用状态。如下图所示：注：jatoolsPrinter 4.0以后的版本，都经过微软认证的签名，因此，多数情况下无须设置IE安全属性。快速入门我们先来设计一个web页面，如下所示： 我的第一个打印文档 发票1 金额:80 发票2 金额:100 在这个文档中，有两个div对象，假设每个div中包括一张要打印的发票，现在要求是把这两张发票打印出来，而且，一张发票占据一页，如果你使用ie自带的打印菜单来打印，有可能只打印一页，有可能打印超过两页，有可能发票打印到一半时就分页，总之，如何分页取决于打印纸张的大小，及发票的大小，你不能控制页数及分页位置。那么，jatoolsPrinter是如何处理这样的需求的呢？首先，我们在页面中插入这个控件，如下所示。 我的第一个打印文档 发票1 金额:80 发票2 金额:100 其次，调用控件的 print 方法实现打印，如下所示： function doPrint() myDoc = documents:document; / 要打印的div 对象在本文档中，控件将从本文档中的 id 为 page1 的div对象，作为首页打印 / id 为 page2 的作为第二页打印 ; jatoolsPrinter.print(myDoc,false); / 直接打印，不弹出打印机设置对话框 由上可见，你打印若干 div对象时，需要告诉控件，这些div们所属的文档对象(html的document对象)，另外，这些div对象的id，也需要按 page+序号 的规则命名，序号从1开始计，也就是说，id为page1的div对象，总是作为首页打印。这些设置使用一个javascript对象来描述，也就是上面的myDoc对象，下面是完整的html代码： 我的第一个打印文档 function doPrint() myDoc = documents:document, / 要打印的div 对象在本文档中，控件将从本文档中的 id 为 page1 的div对象，作为首页打印 / id 为 page2 的作为第二页打印 copyrights:杰创软件拥有版权 / 版权声明,必须 ; jatoolsPrinter.print(myDoc,false); / 直接打印，不弹出打印机设置对话框 发票1 金额:80 发票1 金额:100 运行示例最后，有几点需要说明： 1. 控件在打印指定div对象时，如果纸张太小不够打印时，超出部分将被截掉(clip)。如果你不想被截掉，你可以使用自动分页功能，参照自动分页打印，如果是一个大表格，想分析打印，参照表格分析打印功能。 。 2. 被指定的div中的内容，可以是html任何可见对象，图片，flash，或文本等等。 3. 控件打印时，边距可设，不设则取打印机默认值。 4. div的id必须连续，如果你的div，存在 page1、page2、page4，而不存在page3，则控件只打印前两页，page4不会被打印。 5. div对象在页面中的位置，可以是随意的，比如，page1显示在page2后面，也是合法的。 6. 指定的div会被打印，没被指定的html元素将不会被打印，比如，本示例中的打印按钮，不会被打印。 7. copyrights属性是版权信息，必须写。 8. 一个div打印成一页，这种分页方法称之为预分页方式，或称为套打分页方式。除此之外，控件也支持自动分页方式，即可以将一个内容较多的网页，由控件自动按纸张大小来分页，方法是使用 autoBreakPage 属性，具体参照下文。 9. 控件打印时，将不会打印ie默认的页脚页眉(ie通常在上面显示网页的网址，网页标题等)，多数情况下是不必要的，当然，如果你确实需要页脚页眉，你也可以自己定义，具体方法参照下文。最简单的打印预览 下面是一个最简单的打印，打印按默认设置进行。运行此示例/打印文档对象 var myDoc = documents: document, / 打印页面(div)们在本文档中 copyrights : 杰创软件拥有版权 / 版权声明必须 ; . jatoolsPrinter.print(myDoc,false); 打印前设置打印参数 你可以打印前设置打印参数，如设置输出的打印机，打印方向，纸张大小。 运行此示例/打印文档对象 var myDoc = settings: / 如果想使用默认打印机,不需要设置 / printer: 联想激打, / 指定纸张的高宽以十分之一毫米为单位,本设置实际是指定为a4大小 paperWidth : 2100, paperHeight : 2970, / 指定打打印方向为横向, 1/2 = 纵向/横向 orientation : 2 , documents: document, / 打印页面(div)们在本文档中 copyrights : 杰创软件拥有版权 / 版权声明必须 ; 保留打印时的打印参数 可以保留打印时的打印参数，待下一次打印同一文档时自动配置打印参数 。运行此示例/打印文档对象 var myDoc = /待保留的打印设置id,打印后将被保存在注册表中, /下一次启动相同值的settingsID,打印文档时, /控件将用保留的参数,自动设置打印机 settingsID:mysettings1, documents: document, copyrights : 杰创软件拥有版权 ; 为什么需要保存设置功能?保存设置功能，通常用在以下两种情况：（1）一个套打系统，由于各客户端打印机不同，或者进纸盒的位置不同，或者其他原因，可能引起打印出来的票据位置发生偏移，用户希望能根据自己打印机的状况，自行调整边距以纠正位置，但不希望每次打印前，都进行一次手工调整。（2）一个客户端配置了多台打印机，分别用于打印不同类型的文档，用户不希望每次打印一个文档前，选择一次打印机；对于第一种情况，你可以这样解决：1. 页面中设置两个按钮，一个直接打印，一个打印预览；2. 当客户发现位置有偏移时，可以点击打印预览按钮，调整左、上边距，并打印这个页面；3. 如果发现位置还不理想，则重复第2步，如果正确，则下一次打印这个票据时，只需点击直接打印即可保证位置正确。对于第二种多种打印机的情况，你可以这样解决：1. 页面中设置两个按钮，一个直接打印，一个打印预览；2. 第一次打印时，可以点击打印预览按钮，选择你想要的打印机进行打印；3. 则下一次打印这个票据时，只需点击直接打印即可保证输出到正确的打印机。提一点建议：因为打印预览按钮不常用，最好不要跟直接打印按钮并排放在一起，以避免干扰。保存设置参数的工作原理是怎样的?控件是如何保留设置参数的，有些用户感觉困惑，下面介绍一下保留与加载打印参数的工作原理。保存设置参数原理：1. 客户打印一个文档到打印机后；2. 控件触发打印完成事件；3. 控件响应打印完成事件，查询本次打印是否有myDoc.settingsID属性，如果有，则保存本次打印的配置参数到注册表(如果注册表中存在该id设置，则替换以前设置)。所以，保存打印参数的前提是：已经输出到打印机，并且设置了myDoc.settingsID。 有些用户，只在控件的预览窗口中设置了边距等，而不实际打印，这样，控件是不会保留你的设置的。加载打印参数原理：1. 客户在预览或打印前，控件查询是否有 myDoc.settingsID属性；2. 如果有myDoc.settingsID属性，控件尝试从注册表中读入该id相关的配置参数，如果存在，则用该配置参数来设置打印机（即忽略myDoc.settings里的设置），转第4步；3. 根据用户的myDoc.settings里的设置，设置打印参数；4. 根据设置，启动打印或打印预览。第一次打印用当前配置，后续打印用最后一次打印配置 运行此示例/打印文档对象 var myDoc = settings: / 当前设置 / printer: 联想激打, paperWidth : 2100, paperHeight : 2970, orientation : 2 , /第一次打印时，注册表中没有mysettings2的打印参数 /所以使用上面指定的参数 /打印后，控件自动将最后一次打印设置保存 /后续打印时将用注册表中的设置，来自动配置打印机 /上述的settings将被忽略 settingsID : mysettings2, documents: document, copyrights : 杰创软件拥有版权 ; 批量打印文档 运行此示例注意，批量打印时，而且打印文档数超过一个，只能进行无提示的直接打印操作。 /打印文档对象 var myDoc = /批量打印时，需要用数组来指定打印文档 /文档页可以在一个document对象中，也可以在url指定的一个文档中 documents: new Array( document, / 打印页面(div)们在正显示在本文档中 attache1.htm, / 打印页面(div)们在一个url指定的文档中 attache2.htm) copyrights : 杰创软件拥有版权 / 版权声明必须 ; 多个文档共存在同一web页面中，区别打印 运行此示例/打印文档对象 var myDoc = documents: document, / 在同一页面中,有多个可打印文档,他们可以用 / pagePrefix 属性来区别 / pagePrefix属性 +page+页序号 构成可打印div的id, / 如前缀为 report1 ,则找到以 report1page1为id的 / div作为文档首页 / 该属性,默认值为空 pagePrefix: whichreport.value, / 本例中,可能是 report1或report2 copyrights : 杰创软件拥有版权 ; 不显示文档，直接指定url打印 运行此示例/打印文档对象 var myDoc = /文档页可以在url指定的一个文档中,用数组指定打印文档 documents: new Array(basic.htm), copyrights : 杰创软件拥有版权 / 版权声明必须 ; 打印隐藏对象你可以使用属性 classesReplacedWhenPrint ，将一个对象在显示时定义为不可见，在打印或打印预览时，定义为可见，这通过预定一个css类实现。如下所示。运行此示例 . .only_for_print display:none. . /左面是两个隐藏的页 div id=page1 class=only_for_print . div id=page2 class=only_for_print . . 打印印文档对象 var myDoc = . / 打印时,only_for_print取值为显示 classesReplacedWhenPrint: new Array(.only_for_printdisplay:block), . ; 仅在预览时可见，不输出到打印机的套打底图 通过特殊的样式类 screen-only ，配合enableScreenOnlyClass 属性，你可以控制所有可视化元素要求其仅在预览时可见，如下图示。运行此示例/打印文档对象 var myDoc = enableScreenOnlyClass:true / 为了使screen-only起作用，必须设置 enableScreenOnlyClass为true 经此设置,引用screen-only样式类的对象，只在显示或预览时可见，打印时不可见. ; . 本层中的内容只在打印预览时可见 . 打印时样式类的自动插入(实现不打印表格线等)运行此示例假设有这样的需求，套打票据是一个表格，且表格线已经印在上面。但你不想将票据底图按上一节所说，设置在打印页面上，而是输出打印页面时，也同时设置表格线，仅在打印时，让控件自动隐去表格线。如何做到？方法是利用打印样式类自动插入功能，该功能在控件打印时，会自动在页面的父对象中，插入一个jatools-printing样式类，类似这样：.有了这个自动插入的样式类，以上不打印表格线的需求，就可以很方便实现了，方法如下：1. 如果你有一个表格，如下所示： .2. 为使打印页面在显示和打印预览时，显示表格线，需要加上边框样式，类似这样: #sample td border:solid 1px solid 3. 为使打印时表格线不可见，增加以下粗线部分，即可： #sample td border:solid 1px black .jatools-printing #sample tdborder:none; 原理是，当控件打印时，sample表格有一个带样式类 .jatools-printing 的祖先对象，因此，上一行有表格线的样式会被下一行没表格线的样式所覆盖，也就是打印时，不显示表格线了。实际上，也许你已经体会到，通过本功用可以精细控制打印对象在预览时和打印时的不同样式，不仅仅是本例中的对表格线的控制。 #sample td border:solid 1px black .jatools-printing #sample tdborder:none;.样式文件(*.css)的显式导入有些应用，往往需要引入庞大的css文件，尤其是一些使用开发框架开发的应用，比如 Oracle的ADF。如果这样大的css放到内存中，让打印控件来解析，必须会影响到控件的打印效率，因此，我们这里推荐用户用显式的css引入方法，可减轻控件对css的解析负担，从而大大提高控件的打印速度。要使用显式的css文件导入功能，只需要设置 importedStyle 属性即可，如:运行此示例function doPrint() myDoc = . documents: document, importedStyle:a.css, / 可同时引入多个css,可以是相对路径，也可以是绝对路径 ; jatoolsPrinter.print(myDoc,false); . 打印结束后提交数据 下面一个示例，意图是在打印成功后，将打印数据提交到服务器保存。运行此示例function doPrint() myDoc = . documents: document, ; myDoc.done=function(err) if(!err) myform.submit(); / 提交表单 else alert(err); jatoolsPrinter.print(myDoc,false); / 直接打印，不弹出打印机设置对话框 . 你可以在打印结束时，让控件自动调用一个脚本方法，回调方法必须通过打印对象的done属性来指定。在打印结束后，你可以通过该方法的err参数，来判断打印是否成功，err为空，则打印成功，非空在打印失败，err表示错误信息。为什么要使用回调方法 不使用回调方法，按下面的代码运行可以吗？回答是不可以！ 下面的代码错误。 function doPrint() myDoc = . documents: document, ; jatoolsPrinter.print(myDoc,false); / 直接打印，不弹出打印机设置对话框 myform.submit(); / 极端错误 . 因为不管三七二十一，就提交了表单，提交后，当前窗口的document就会被新的文档替换，而打印控件对原文档还没有打印完，这时就会经常出现如下错误信息。 打印后关闭窗口 在回调方法(done)中调用window.close()即可；参照演示 运行此示例可视化设计套打 在web套打程序的开发中，最烦琐的事情是打印内容与票据要保持一致，不能移位。在以前的版本中，如果用户想设计套打模板，必须通过网页设计工具做好网页，然后，放到杰表控件中来打印，如果发现打印内容的位置有偏差，再在网页设计工具中调整，然后再放到控件中，如此反复多次，效 率极低。现在有了可视化设计功能，可以使用户在控件中，就能调整位置，不仅如此，由于控件中指定位置，是在真实的、可视化的打印环境中，使用户不必考虑边距的问题，做到完全的所见即所得，可大大提升套打设计的效率。更多内容.打印内容相对位置的事后调整及保存 在web套打程序的开发过程中，你可能会发现，即使是同一套打网页，在不同的打印机中，打印出来的相对位置，也有差别，有的打印机打印出来的内容凑得紧些，有的则离得开些，这种偏差不能通过设置打印机边距的方式进行调整。借助杰表打印控件的可视化设计功能，使用户可以根据自己的打印机状况，自行调整打印内容的位置，并保存到注册表，下次打印时，自动根据自设的位置进行打印。 这种微调，不会影响到其他打印机，这对有大量前台打印，并有不同类型打印机打印同一种票据的场合，非常实用。更多内容.连续打印的套打偏移校正 因连续打印导致套打上下偏移的问题，是套打程序设计中的常见问题，如图所示： 第一张（正常） 第五十张 (向下偏移 1.2cm)导致偏移的原因是什么呢? 一种原因，是打印纸张高度设置得不对，只要根据误差，调整纸张高度就行了。另一种原因，是打印机走纸不够精准，少打几页还看不出有啥问题，但连续打印后，因为误差累积起来，打印到10几张时，就很明显了，如果打印到100多张，上千张，必然谬之毫厘，差之千里了。一般地，在打印多页后，如果出现向下偏移的情况，说明纸张高度设置过大了，调小一点即可，如果出现向上偏移的情况，说明纸张高度过小，调大一点即可。但这里有个坏消息，比如，进过测试，发现如果纸张高度设置为 200.1mm向下偏移，如果设成200.0mm向上偏移，很简单，设成它们俩的中间值:200.05mm试试。遗憾的是，windows不接受这个值，因为windows能接受的纸张高度，其精度只能达到0.1mm，即使你设置了这个中间值，打印机可能仍然以两值中的一个进行打印，也就是说，你设了这个中间值，打印仍然会存在偏移！碰到这种情况，我们做程序的也只能建议用户，换一台精度高一点的打印机，或者建议一次不要打印太多。好消息是，本控件针对这个棘手的问题，提出了更有建设性的方法，那就是，在连续的票据打印过程中，插入若干校正页的办法来进行偏移纠正，此方法可图示如下：控件启动一个打印任务，当打印完几张正常高度的票据后，打印一张用来纠偏的、特别高度的票据（以下称之为校正页），这样可以降低对打印机走纸精度的要求，也达到了纠偏的目的，此方法简单粗暴，直接有效，：）下面介绍如何设置一个可插入校正页的打印任务：1. 先测量出，票据的实际高度，比如120mm(宽)*100mm(高);2. 按所得票据大小，设置自定义纸张，如下所示：var myDoc= settings: paperWidth:1200, / 以1/10毫米为单位 paperHeight:1000 , settingsID:mydoc1 / 必须设置一个唯一id号 . 3. 当发现有连续偏移时，只要调用控件的 setupNormalOffset()方法，设置相应的校正参数即可，如下所示：jatoolsPrinter. setupNormalOffset(mydoc1); / 唯一参数，标识对哪一个打印任务进行校正设定。此方法将使控件弹出如下对话框：你打印了多少张：表示你用来测试的页数，测试页数越多，误差越大，校正效果越好。共偏移了多少毫米（向上偏移为负）：表示你经过上一参数连续打印后，第一页与最后一页的偏移距离，以毫米为单位，当向下偏移时，设置为正，反之为负，也可以设置一个小数位。每隔几张插入一个校正页：表示校正页的插入频度。此参数建议在515之间为好。清除：可能换了好的打印机，不需要校正了，那就采用此按钮，清除校正设置。确定：设置完了，保存。取消：即不保存，也不清除，退出。如果你设置了校正参数，按确定以后，控件将在本地注册表中保存这些参数，当下一次myDoc.settingsID为 ”mydoc1” 的打印任务启动时，控件将按这些参数自动插入校正页。 另外，你需要 注意：1. 因为校正参数是按settingsID来保存的，所以不会干扰到其他打印任务。2. 因为校正参数是保存在用户的本地注册表中，所以某一个用户的校正设置，不会影响到其他用户的。下面是打印与校正设置的部分代码：运行此示例function doPrint() var myDoc = settings: paperWidth:1200, paperHeight:1000 , settingsID:mydoc1, documents: document, copyrights : 杰创软件拥有版权 jatoolsPrinter.print(myDoc,false); / 直接打印function function doNormalOffset() jatoolsPrinter.setupNormalOffset(mydoc1); / 设置校正参数.行文至此，这个方案还是有点不够完美，因为，代码中出现两个按钮，一个是打印，一个是偏移校正，这个偏移校正按钮，对于大多数不存在偏移问题的用户来说，可能永远用不上，即使有少数用户存在偏移问题，也只需要设置一次，就可以了。这个按钮有点多余，我们来改造一下上面的代码，如下：运行此示例function doPrint() if(window.event.shiftKey) jatoolsPrinter.setupNormalOffset(mydoc1); / 设置校正参数 else var myDoc = settings: paperWidth:1200, paperHeight:1000 , settingsID:mydoc1, documents: document, / 打印页面(div)们在本文档中 copyrights : 杰创软件拥有版权 / 版权声明必须 ; jatoolsPrinter.print(myDoc,false); / 直接打印 .上述代码，删除了用于校正的按钮，但doPrint代码里，加入了是否按下shift键的判断，如果用户在按下打印按钮的同时，也按了shift，则调用控件的校正设定方法，否则，就以正常打印处理。 这样，作为程序开发人员，只需要当用户发现有连续偏移时，才告诉他使用这个方法，来校正偏差。调整后的套打位置信息保存到服务端运行此示例 下载此示例代码上一功能打印内容相对位置的事后调整及保存只将位置微调后的信息保存到本地注册表，所以某个用户的位置微调不会影响到其他用户，而本功能可以使调整后的位置信息保存到服务端，因此 某个用户的位置微调将影响到所有其他客户。 这在需要由专人负责调整套打位置的场合，非常有用。实现此功能的原理，是监听用户微调后的确定按钮事件，你可以在此事件代码中，得到用户的最新位置信息，再通过ajax传递到后台保存，用户在下一次请求打印页面时，在页面的中加入该位置信息。下面以jsp语言为例说明本功能，如下所示，加入监听事件只需要设置 myDoc.dragDesigner.ok 为一个函数即可，当用户点击确定时，控件将调用这个方法，并传入两个参数，sid和styles. sid就是你设置的 settingsID属性. styles是一个javascript对象，形式如f1:top:200;left:200, f2:top:100;left:300，本例是将此对象转换成css字符串后，ajax到后台.remotelayout.htm / 保存到服务端的位置信息，成为style的一部分，从而影响到后面的html元素.f1left:533;top:422.f2left:124;top:146.function doPrint() myDoc = settings: paperWidth: 2500, paperHeight: 1800, orientation: 2 , documents: document, dragDesigner: viewSource: false, ok: function (sid,styles) /在拖放设计完毕后点击确定按钮会调用此函数，获取到sid和style的信息 /* styles=f1:top:200;left:200, f2:t