目录

安装和使用

二次开发手册

常见问题

PrintSpirit JSAPI 使用指南

打印精灵(PrintSpirit) 提供三种二次开发方式——JS API、动态连接库（DLL）和REST API, 分别适应不同的应用场景, 可助力第三方快速集成标签打印、标签编辑功能、开发专业条码打印软件，详见打印精灵开放平台。本文是 SpiritWeb（基于 JS API）的入门开发指南，详细讲解使用 SpiritWeb 进行条码打印、批量生成条码应用开发的核心步骤与方法。

阅读本文前, 建议先使用SpiritDesigner先设计一个标签, 获得标签编号.

快速学习API，推荐使用互动测试沙箱

应用场景

Spirit JS API 适用于 Web 程序（互联网或内网环境），提供比原生 Web 打印更高质量的输出、更便捷的操作和更精细的控制，适用于各类标签打印需求。

JS API 由SpiritWeb模块提供。使用前需下载安装。标签编辑请参看嵌入"打印精灵"标签编辑器

快速入门

1、系统架构

WEB应用 互联网 局域网 浏览器 websocket 命令/响应 SpiritWeb 打印机

2、引用JS

使用Print Spirit js API，须先引用spirit.js，该JS会自动注入一个全局类：SPIRIT, 可以通过SPIRIT调用js Api。

http方式, spirit会同时在两个端口监听,避免由于端口被其他程序占用的情况.

1<script src="http://127.0.0.1:9011/js/spirit.js"></script>
2<script src="https://127.0.0.1:19011/js/spirit.js"></script>

https方式, 如果开发的程序是https, 应使用https引用spirit.

1<script src="https://127.0.0.1:9443/js/spirit.js"></script>
2<script src="https://127.0.0.1:19443/js/spirit.js"></script>

3、执行打印

打印分为三个步骤：

  1. 利用SPIRIT.open命令获取打印实例p。可以通过SPIRIT判断打印控件是否安装，并提示用户下载。
  2. 通过p.PrintLabel()完成打印。该命令的第一参数为模板ID(如何获取模板ID), 第二个参数为变量列表，实际打印时将替换模板中的对应变量(是么是模板变量?), 第三个参数为模版数据存url缺省为本网站。
  3. 通过p.close(), 关闭打印实例p。

具体代码如下：

1SPIRIT.open(opt, function(p) {
2  p.PrintLabel(labelID, {var1:xxx, var2:xxx, ...});
3  p.close();
4})

为避免过多使用回调函数控件，支持等价的Promise, async/await写法，如：

1const p=await SPIRIT.open(opt);
2p.PrintLabel(labelID, {var1:xxx, var2:xxx, ...});
3p.close();

SPRINT.open的opt参数用于指定打印机参数，包括： 打印机名称，打印机类型, 打印机分辨率参数，字体参数等，可覆盖对应的缺省值。 使用空对象则使用缺省配置。

打印机参数

参数　 内容　 示例 备注
name 打印机名称　　 　　　
type 打印机类型 ZPL/CPCL/WIN
dpi 打印机分辨率(点/英寸) 203 dpi/dpmm二选一
dpmm 打印机分辨率(点／毫米) 8
paper 打印纸名称 系统内置打印纸,
size 纸张大小[w, h] [ 1000, 2000] 表示10mm宽,20厘米高的纸张
width 纸张宽度
height 纸张高度
col 设置每行打印多少个标签 1 缺省=1, auto标识自动根据纸张大小/标签大小计算
row 设置每页打印多少行标签 1 缺省=1, auto标识自动根据纸张大小/标签大小计算
marginTop 上边距 单位0.1mm
marginBottom 下边距 单位0.1mm
marginLeft 左边距 单位0.1mm
marginRight 右边距 单位0.1mm
gapX 多标签拼板时, 标签X方向间隙
gapY 多标签拼板时, 标签Y方向间隙
fill 0:保持大小, 1:缩放以适应纸张 2: 缩放适应纸张并维持宽高比
font 打印机字体 MHEIGB18.TTF 对windows打印机无效
charset 字符集, 目前支持GBK, UTF8 charset=utf8
copies 打印份数, 大于0, 小于20
cache 是否使用模板缓存 false 缺省不使用
imgcache 是否使用图片缓存 true 缺省使用
reset 打印前重置打印队列
master 主从模式时, 设置主服务器IP 参考企业内网场景解决方案

4、一个完整的例子

该例子演示了如何使用共享模版，并在网页上设置模版变量，完成打印的方法。使用的模版(查看)ID为：953745b5-90f3-4852-805d-d11f994d2374， 共定义了name、phone两个模版变量。

使用该例子，你需要有一台打印机（ZPL, CPLC或windows打印机均可），并安装打印控件，如果未安装第一次打印时，会自动提示你下载安装。

 1<!DOCTYPE html>
 2<html>
 3  <head>
 4      <title>打印测试</title>
 5      <!-- 如果主网站是http, 使用下面两行-->
 6      <script src="http://127.0.0.1:9011/js/spirit.js"></script>
 7      <script src="http://127.0.0.1:19011/js/spirit.js"></script>
 8      <!-- 如果主网站是https模式，请使用下面两行 
 9      <!--script src="https://127.0.0.1:9443/js/spirit.js"></script-->
10      <!--script src="https://127.0.0.1:19443/js/spirit.js"></script-->
11  </head>
12  <body>
13  <script type="text/javascript">
14    function do_print() {
15      if (!SPIRIT) {
16        if (!confirm('没有检查到到打印控件，立刻安装？')) return;
17        window.location.href='http://www.printspirit.cn/download/spirit-web-setup.exe';
18      }
19
20      vars= {
21        name:document.getElementById("name").value, 
22        phone:document.getElementById("phone").value
23      };
24      SPIRIT.open({dpi:203, cache:true}, function(p) {
25        p.PrintLabel("953745b5-90f3-4852-805d-d11f994d2374", vars);
26        p.close();
27      })
28    }
29  </script>
30  <p>姓名<input id="name" ></p>
31  <p>电话<input id="phone" ></p>
32  <p><Button onclick="do_print()">点击打印</Button></p>
33  </body>
34</html>

说明 打印精灵同时支持http, https协议。引入print.js的协议应该和你的主网站的协议一致。
为防止本地端口被占用，如果9011（或https端口9443） 端口被占用，打印精灵将尝试打开19011端口（对https为19443端口）。可以同时引入两个端口的print.js,实现端口的自适应。

其他打印模式

除了支持标签模板打印外，控件还支持另外两种打印模式，供高级用户使用。

命令模式

命令模式，可以直接向打印机发送打印命令。

如下面的例子通过Text命令打印"测试文本"4个汉字，更多打印命令详见:JS API手册

1SPIRIT.open(opt, function(p){
2    p.initLabel(80, 210);
3    p.Text(0, 0, "测试文本");
4    p.print();
5    p.close();
6})

原始模式

个打印送原始打印码，可以直接控制底层的打印。比如可以用一台针式打印机作为流水打印。

1SPIRIT.open(opt, function(p){
2  prn=p;
3})
4
5...
6
7p.printRaw(data)
8
9...

留言

登录