开发指南

【能加加】网页打印插件是一款面向网页浏览器的Web打印代理软件,支持跨平台(Windows/Linux/MacOS)、适配各种浏览器。插件提供了精简灵活的API,浏览器与代理软件的交互均通过Javascript API完成。

1. 引入Javascript API

【能加加】网页打印插件的Javascript API非常小,只有不到7K。我们提供了CDN地址,可以直接引用CDN,也可以转存到项目引用。

CDN地址可以从下载中心获得。

引用Javascript API只需在<head>…</head>节点加入如下代码:

<head>
……
<script type="text/javascript" src="https://www.nengjj.com/webdev/nengjj.min.js"></script>
……
</head>

2. 获取能加加插件实例

2.1 获取默认配置的实例

引入Javascript API文件后,可以在页面任意位置获取能加加插件实例。

注意:在一个页面中,只能获取一次实例。
var instance = nengjj.getInstance();

2.2 获取定制参数的实例

也可传入定制参数,参数为Json格式:

var instance = nengjj.getInstance({
    host: "192.168.1.6", // 插件运行的主机地址
});

目前仅支持指定host属性。

3. 检测能加加插件运行

3.1 获取插件的版本信息

可通过尝试读取插件信息,检测插件是否已启动运行:

instance.getInfo(
    function(res){
        console.log(res);
    },
    function(st, text){
        console.log(st + ":" + text);
        if(st == 0) {
            alert("插件未启动!");
        } else {
            alert(text);
        }
    }
);

成功则返回:

{
    appVer: "1.2", // 插件版本
    os: "win", // 插件运行的平台
    printVer: "1.1" // 打印模块版本
    ...
}

4. License设置与查询

4.1 License 查询

可以使用readLicense(onsuccess, onerror)接口读取License信息。

instance.readLicense(
    function(res){
        console.log(res);
    },
    function(st, text){
        console.log(st + ":" + text);
        if(st == 0) {
            alert("插件未启动!");
        } else {
            alert(text);
        }
    }
);

注意:可通过插件的软件界面查看License详细信息,右键点击系统托盘中的能加加插件图标,弹出菜单,选择:设置 > 授权信息,查看授权信息,在此界面也可设置License。

4.2 License设置

可以使用installLicense(license, onsuccess, onerror)接口更新License信息,试用版许可证(license)可通过此链接免费获取。

instance.installLicense(
    license, // 申请试用授权或购买正式授权
    function(res) { // 调用成功回调函数
        console.log(res);
    },
    function(status, text) { // 调用出错回调函数
        console.error(status + ":" + text);
    }
);

5. 打印内容

安装好正确的License后,即可调用Javascript API进行打印。

5.1 请求打印

打印请求接口,主要有下面几种:

function print(doc, onsuccess, onerror); // 直接打印
function printConfig(doc, onsuccess, onerror);  // 弹出打印设置对话框,点击"打印"按钮打印
function printPreview(doc, onsuccess, onerror); // 显示打印预览窗口,点击"打印"按钮打印

下面的示例使用print接口的地方,都可以替换为printConfigprintPreview接口,以获得相应效果。
这些函数都返回docId,可用于后续监听事件。

最简单的打印请求

// 调用实例中print模块的print接口
instance.print.print({
	name:"测试",
	content: "<div style='color: red; font-weight:bold;'>Hello</div>",
}, 
function(result){
    console.log(result);
});
	

下面是更多示例:

指定打印机

instance.print.print({
	name:"测试",
	content:"HTML内容",
	printer:"Microsoft Print to PDF",
},
function(result){
    console.log(result);
});
	
	

设定页边距

instance.print.print({
    name:"测试",
    content:"HTML内容",
    option: {
        marginTop: 3, //毫米
        marginBottom: 3, //毫米
        marginLeft: 3, //毫米
        marginRight: 3 //毫米
    }
}, 
function(result){
    console.log(result);
});
	
注意: 打印机边距设定有一个最小值,例如有的打印机是2.96mm,不同打印机可能不同,小于这个值的设置将无效或无法打印。

打印多份

要打印多份文档,可以传入copyCount配置:

instance.print.print({
    name:"测试",
    content:"HTML内容",
    option: {
        copyCount: 3
    }
}, 
function(result){
    console.log(result);
});
	

设置纸张

instance.print.print({
    name:"测试",
    content:"HTML内容",
    option: {
        paperWidth: 210, //纸张宽度,单位mm
        paperHeight: 297 //纸张高度,单位mm
    }
}, 
function(result){
    console.log(result);
});
	

如果设置的纸张尺寸与标准纸张尺寸很接近,会自动转换为标准纸张尺寸。在设置纸张尺寸前,可使用listPrinterPaper函数,获取打印机支持的纸张规格。

注意:listPrinterPaper获取的纸张尺寸单位是0.01毫米,设置纸张时的paperWidth/paperHeight单位是毫米,必须做一下转换。

获取打印机支持的纸张规格:

instance.print.listPrinterPaper(
    "Microsoft Print to PDF", // 打印机名称
    function(result) { // 调用成功回调函数
        console.log(result);
    },
    function(status, text) { // 调用出错回调函数
        console.error(status + ":" + text);
    }
);

输出:

[
    {
        name: "A4",         // 纸张名称, String类型
        width: 21000,       // 纸张宽度, 单位0.01毫米, Integer类型
        height: 29700,      // 纸张高度, 单位0.01毫米, Integer类型
    },
    {
        name: "A5",         // 纸张名称, String类型
        width: 14800,       // 纸张宽度, 单位0.01毫米, Integer类型
        height: 21000,      // 纸张高度, 单位0.01毫米, Integer类型
    }
    ...
]

更多选项

详情参见API手册。

instance.print.print({
	name:”任务”,
	content:HTML内容”,
	config:{
		color: "no", //黑白打印, yes/no,默认彩色
		duplex: "duplex_none", // 单面打印
		orientation: "portrait", //纵向打印
        pageRange: "1-2", // 页码范围
	}
}, 
function(result){
    console.log(result);
});
	

打印URL

instance.print.print({
	name: "打印URL",
	type: "url",
	content: "https://www.some-url.com"
}, 
function(result){
    console.log(result);
});
	

具体参数参考API手册。

5.2 接收打印完成事件

打印请求接口都是异步的,发出请求后,函数马上返回,打印结果会以事件的方式发回来。

事件例子:

{
    type: "nengjj_event_print",  // 事件类型总是 nengjj_event_print
    detail: { // 事件详情
        docId: "2vm3b95n", // 唯一标志一次打印请求
        state: "PRINT_INIT", // 事件状态
        ...
    }
    ...
}

在发出打印请求后,如需监听打印相关事件(如打印完成事件),可注册事件监听函数:

window.currentDocId = instance.print.print({
	name:"测试",
	content: "<div style='color: red; font-weight:bold;'>Hello</div>",
}, 
function(result){
    console.log(result);
});

document.addEventListener(
    "nengjj_event_print", // 事件类型总是 nengjj_event_print
    function(e) {
        console.log(e);

        if(e.detail.docId == window.currentDocId) {
            switch(e.detail.state)
            {
                case "PRINT_INIT":
                // ...
                break;

                case "PRINT_DONE":
                // ...
                break;

            }
        }

    }
);

事件参数详情,请参考API手册。

6. 打印机管理

获取默认打印机名称

instance.print.getDefaultPrinter(function(res){
    console.log(res);
});

输出:

HP DeskJet 5820 series (网络)

接口详情请参考API手册。

获取全部打印机名称

instance.print.listPrinter(function(res){
    console.log(res);
});

输出:

[
    "Microsoft XPS Document Writer", 
    "Microsoft Print to PDF", 
    "HP DeskJet 5820 series (网络)", 
    "Foxit Reader PDF Printer", 
    "Fax"
]

接口详情请参考API手册。

获取打印机支持的纸张

var printerName = "HP DeskJet 5820 series (网络)";
instance.print.listPrinterPaper(printerName, function(result){
    console.log(result);
});

输出:

[
    {name: "信纸", height: 27940, width: 21590},
    {name: "法律专用纸", height: 35560, width: 21590},
    {name: "Statement", height: 21590,  width: 13970},
    {name: "Executive", height: 26670, width: 18410},
    {name: "A4", height: 29700, width: 21000},
    {name: "A5", height: 21000, width: 14800},
    // ...
]

接口详情请参考API手册。

获取打印机状态

var printerName = "HP DeskJet 5820 series (网络)";
instance.print.getPrinterState(printerName, function(result){
    console.log(result);
});

输出:

idle

接口详情请参考API手册。

获取打印机作业

instance.print.getPrinterJob(printerName, function(result){
    console.log(result);
});

接口详情请参考API手册。