EscPosInstruct

创建一组可以发送到任何支持ESC/POS的收据打印机的命令。

使用

此软件包与浏览器和Node兼容。它提供了可在浏览器中直接使用的捆绑版本，也可以用作您自己的捆绑程序的输入。当然，Node中也有ES6模块和CommonJS版本可供使用。

您可以将“esc-pos-instruct.js”文件导入“EscPosInstruct”。

import EscPosInstruct from 'esc-pos-instruct.js';

let encoder = new EscPosInstruct();

let result = encoder
    .initialize()
    .text('The quick brown fox jumps over the lazy dog')
    .newline()
    .qrcode('https://nielsleenheer.com')
    .encode();

Options

创建“EscPosInstruct”对象时，可以指定许多选项来帮助库生成收据。

宽度

要设置纸张的宽度，可以使用“width”属性。这是一个选项，因为如果到达纸张边缘，文本会自动换行到新行，但如果要使用换行，则需要指定此选项。

let encoder = new EscPosInstruct({
    width:    42
});

如果使用57毫米宽的纸张，根据打印机的分辨率，可以水平打印最多32或35个字符。

如果您使用80毫米宽的纸张，根据打印机的分辨率，它可以水平打印最多42或48个字符。

自动换行

如果希望文本在纸张边缘自动换行，可以启用“换行”。如果使用此选项，还必须使用“width”属性指定纸张宽度。

let encoder = new EscPosInstruct({
    width:      48,
    wordWrap:   true
});

Commands

您可以重用实例化的“EscPosInstruct”类为同一台打印机生成多个命令或命令集。它会记住代码页之类的设置，所以在以后使用时不必指定。这确实取决于以前的命令实际上是发送到打印机的。

所有命令都可以链接，但“encoder（）”除外，它将以Uint8Array的形式返回结果，该数组包含需要发送到打印机的所有字节。

以下命令可用：

初始化

正确初始化打印机，这意味着启用了文本模式，并将代码页等设置设置为默认设置。

let result = encoder
    .initialize()
    .encode()

打印机支持

对特定代码页的支持不仅取决于此库，更重要的是打印机了解它。对代码页的支撑取决于制造商和型号。有些人只支持少数人，有些人支持大多数人。可能没有支持所有这些功能的打印机。

在选择代码页之前，请查看打印机的技术手册中支持哪些代码页。如果您的打印机不支持您需要的代码页，则说明您运气不好，此库所做的一切都无法帮助您解决此问题。

文本

打印字符串文本。如果文本比打印机的线宽长，当文本达到最大宽度时，它将自动换行到下一行。这意味着它可以直接包裹在一个单词的中间。

let result = encoder
    .text('The quick brown fox jumps over the lazy dog')
    .encode()

一个可选参数启用换行。若要启用此功能，请指定线条的最大长度。

let result = encoder
    .text('The quick brown fox jumps over the lazy dog', 20)
    .encode()

换行

移到下一行的开头。

let result = encoder
    .newline()
    .encode()

线

打印一行文本。这类似于“text”命令，只是它会自动添加一个“newline”指令。

let result = encoder
    .line('The is the first line')
    .line('And this is the second')
    .encode()

这将等于：

let result = encoder
    .text('The is the first line')
    .newline()
    .text('And this is the second')
    .newline()
    .encode()

一个可选参数启用换行。若要启用此功能，请指定线条的最大长度。

let result = encoder
    .line('The quick brown fox jumps over the lazy dog', 20)
    .encode()

下划线

将文本样式更改为下划线。

let result = encoder
    .text('This is ')
    .underline()
    .text('underlined')
    .underline()
    .encode()

它将尝试记住文本样式的当前状态。但是，您也可以提供一个附加参数来强制打开和关闭文本样式。

let result = encoder
    .text('This is ')
    .underline(true)
    .text('bold')
    .underline(false)
    .encode()

加粗

将文本样式更改为粗体。

let result = encoder
    .text('This is ')
    .bold()
    .text('bold')
    .bold()
    .encode()

它将尝试记住文本样式的当前状态。但是，您也可以提供一个附加参数来强制打开和关闭文本样式。

let result = encoder
    .text('This is ')
    .bold(true)
    .text('bold')
    .bold(false)
    .encode()

斜体

将文本样式更改为斜体。

let result = encoder
    .text('This is ')
    .italic()
    .text('italic')
    .italic()
    .encode()

它将尝试记住文本样式的当前状态。但是，您也可以提供一个附加参数来强制打开和关闭文本样式。

let result = encoder
    .text('This is ')
    .italic(true)
    .text('italic')
    .italic(false)
    .encode()

注意：大多数收据打印机不支持这种文本样式。

倒转

将样式更改为黑色背景上的白色文本。

let result = encoder
    .text('This is ')
    .invert()
    .text('white text on black')
    .invert()
    .encode()

它将尝试记住文本样式的当前状态。但是，您也可以提供一个附加参数来强制打开和关闭文本样式。

let result = encoder
    .text('This is ')
    .invert(true)
    .text('white text on black')
    .invert(false)
    .encode()

水平对齐

更改文本的对齐方式。可以使用参数指定路线，该参数可以是“左”、“中”或“右”。

let result = encoder
    .align('right')
    .line('This line is aligned to the right')
    .align('center')
    .line('This line is centered')
    .align('left')
    .line('This line is aligned to the left')
    .encode()

大小

更改文本大小。您可以使用参数指定大小，该参数可以是“small”或“normal”。

let result = encoder
    .size('small')
    .line('A line of small text')
    .size('normal')
    .line('A line of normal text')
    .encode()

宽度

更改文本宽度。您可以使用参数指定宽度，该参数可以是1到8之间的数字。

let result = encoder
    .width(2)
    .line('A line of text twice as wide')
    .width(3)
    .line('A line of text three times as wide')
    .width(1)
    .line('A line of text with normal width')
    .encode()

并非所有打印机都支持所有宽度，为了安全起见，最好最多不要超过4倍。

高度

更改文本高度。您可以使用参数指定高度，该参数可以是1到8之间的数字。

let result = encoder
    .height(2)
    .line('A line of text twice as high')
    .height(3)
    .line('A line of text three times as high')
    .height(1)
    .line('A line of text with normal height')
    .encode()

并非所有打印机都支持所有高度，为了安全起见，最好最多不要超过4倍。

此外，您还可以将此命令与宽度命令结合使用，使文本变大。例如：

let result = encoder
    .width(2)
    .height(2)
    .line('This text is twice as large as normal text')
    .width(1)
    .height(1)
    .encode()

表格

插入一个包含多列的表。每个单元格的内容可以是字符串，也可以是回调函数。

let result = encoder
    .table(
        [
            { width: 36, marginRight: 2, align: 'left' },
            { width: 10, align: 'right' }
        ], 
        [
            [ 'Item 1', '€ 10,00' ],
            [ 'Item 2', '15,00' ],
            [ 'Item 3', '9,95' ],
            [ 'Item 4', '4,75' ],
            [ 'Item 5', '211,05' ],
            [ '', '='.repeat(10) ],
            [ 'Total', (encoder) => encoder.bold().text('€ 250,75').bold() ],
        ]
    )	
    .encode()

table函数采用两个参数。

第一个参数是列定义的数组。每列可以具有以下属性：

• width：确定列的宽度。
• marginLeft和marginRight：在列的左侧和右侧设置边距。
• align：设置列中文本的水平对齐方式，可以是left或right。
• verticalAlign：设置列中文本的垂直对齐方式，可以是top或bottom。

第二个参数包含数据，是一个包含每一行的数组。可以有任意多行。

每一行都是一个数组，每个单元格都有一个值。每行中的单元格数应等于您之前定义的列数。

[
    /* Row one, with two columns */
    [ 'Cell one', 'Cell two' ],

    /* Row two, with two columns */
    [ 'Cell three', 'Cell four' ]
]

该值可以是字符串，也可以是回调函数。、

如果您想在单元格中设置文本样式，可以使用回调函数。被调用函数的第一个参数包含编码器对象，您可以使用它来链接其他命令。

[
    /* Row one, with two columns */
    [ 
        'Cell one',
        (encoder) => encoder.bold().text('Cell two').bold()
    ],
]

盒

插入带边框的框。

第一个参数是一个具有附加配置选项的对象。

-style：边框的样式，可以是single或double。 -width：框的宽度，默认为纸张的宽度。 -marginLeft：左边框和左边缘之间的空格。 -marginRight：右边框和右边缘之间的空格。 -paddingLeft：内容和框左边框之间的空格。 -paddingRight：内容和框右边框之间的空格。 -align：框中文本的对齐方式，可以是left或right。

第二个参数是框的内容，它可以是字符串，也可以是回调函数。

例如：

let result = encoder
    .box(
        { width: 30, align: 'right', style: 'double', marginLeft: 10 }, 
        'The quick brown fox jumps over the lazy dog
    )
    .encode()

规则

插入水平标尺。

第一个参数是一个具有其他样式选项的对象：

• style：行的样式，single或double。
• width：线条的宽度，默认为纸张的宽度。

例如：

let result = encoder
    .rule({ style: 'double' })  
    .encode()

条形码

打印某个符号的条形码。第一个参数是作为字符串的条形码的值，第二个参数是符号，最后是条形码的高度。

可以使用以下符号体系：“upca”、“ean13”、“ean 8”、“code39”、“itf”、“codabar”、“code93”、“code 128”、“gs1-128”、“gs1数据库omni”、“已截断的gs1数据库”、“受限制的gs1数据库”、“扩展的gs1数库”和“code128 auto”。

此库支持符号体系并不意味着打印机将真正支持它。如果不支持符号体系，条形码将不会打印，或者将打印原始数据，具体取决于打印机的型号和制造商

通常，如果没有提供校验和，打印机会自动计算校验和。如果数据中提供了一个，它将不会检查校验和。如果您自己提供校验和，但没有正确计算，则说明行为没有定义。它可能会使用正确的校验和来计算，或者打印无效的条形码。

例如，使用数据中提供的校验和：

let result = encoder
    .barcode('3130630574613', 'ean13', 60)
    .encode()

Or without a checksum:

let result = encoder
    .barcode('313063057461', 'ean13', 60)
    .encode()

上面的两个例子都应该导致打印出相同的条形码。

此外，根据符号体系的不同，必须以不同的方式处理数据：

| Symbology | Length | Characters | |-|-|-| | upca | 11 - 12 | 0 - 9 | | ean8 | 7 - 8 | 0 - 9 | | ean13 | 12 - 13 | 0 - 9 | | code39 | >= 1 | 0 - 9, A - Z, space, or $ % * + - . / | | itf | >= 2 (even) | 0 - 9 | | codabar | >= 2 | 0 - 9, A - D, a - d, or $ + − . / : | | code93 | 1 - 255 | ASCII character (0 - 127) | | code128 | 1 - 253 | ASCII character (32 - 127) |

代码128符号体系指定了三个不同的代码集，它们包含不同的字符。例如：CODE A包含ASCII控制字符、特殊字符、数字和大写字母。代码B包含特殊字符、数字、大写字母和小写字母。CODEC打印与字母的ASCII值相对应的2位数字。

默认情况下，代码128使用代码B。可以使用不同的代码集，方法是使用代码集选择器字符{后跟字符集的大写字母。

例如，使用默认的CODE B设置：

let result = encoder
    .barcode('CODE128 test', 'code128', 60)
    .encode()

相当于手动选择CODE B:

let result = encoder
    .barcode('{B' + 'CODE128 test', 'code128', 60)
    .encode()

CODE C只支持数字，但必须将其编码为字符串：

let result = encoder
    .barcode('{C' + '2Uc#', 'code128', 60)
    .encode()

如果您在ASCII表中查找字符的值，您将看到2=50、U=85、c=99和#=35。

打印的条形码为50859935。

所有其他符号体系都需要Espon ESC/POS打印机语言规范中规定的更复杂的编码。要使用这些其他符号，您需要自己对这些条形码进行编码。

二维码

打印二维码。第一个参数是二维码的数据。

let result = encoder
    .qrcode('https://nielsleenheer.com')
    .encode()

qrcode函数接受以下附加参数：

• 型号 -型号1可以是1，型号2可以是2。
• size -一个介于1和8之间的数字，用于确定二维码的大小。
• errorlevel -可以是l、m、q或h的字符串。

例如：

let result = encoder
    .qrcode('https://nielsleenheer.com', 1, 8, 'h')
    .encode()

图片

打印图像。图像被自动转换为黑白，并且可以选择性地使用不同的算法进行抖动。

第一个参数是图像本身。当在浏览器中运行时，它可以是任何可以绘制到画布上的元素，如img、svg、画布和视频元素。在Node上时，它可以是“Canvas”包提供的Canvas。

第二个参数是纸质收据上图像的宽度（以像素为单位）。它必须是8的倍数。

第三个参数是纸质收据上图像的高度（以像素为单位）。它必须是8的倍数。

第四个参数是抖动算法，用于将彩色和灰度图像转换为黑白图像。支持以下算法：threshold、bayer、floydsteinberg、atkinson。如果没有提供，它将默认为一个简单的阈值。

第五个参数是阈值和拜耳抖动算法将使用的阈值。它被其他算法忽略。它被设置为默认值128。

let img = new Image();
img.src = 'https://...';

img.onload = function() {
    let result = encoder
        .image(img, 320, 320, 'atkinson')
        .encode()
}

列或光栅图像模式

根据打印机的新情况，您可能希望使用“列”模式或“光栅”模式。默认值为“column”。主要区别在于图像的编码方式。一些较新的打印机不支持“光栅”模式的图像，而一些较旧的打印机则不支持“列”模式图像。这可能取决于打印机型号您应该使用的模式。

要选择“光栅”模式，您需要为 EscPosInstruct 类的构造函数提供一个选项对象，该对象的属性 imageMode 设置为 raster。

let encoder = new EscPosInstruct({ 
    imageMode: 'raster' 
});

注意：在EscPosInstruct 1.x中，“光栅”图像模式是默认模式。这在EscPosInstruct 2.0中发生了变化，因为“列”图像模式将在未来更加兼容

剪纸

剪纸。可选地，可以指定一个参数，该参数可以是“部分”或“完全”。如果未指定，将使用完全切割。

let result = encoder
    .cut('partial')
    .encode()

注意：并非所有型号的打印机都支持切纸。即使他们这样做了，他们也可能不支持这两种类型的削减

脉冲

向外部设备发送脉冲，如蜂鸣器或现金抽屉。

let result = encoder
    .pulse()
    .encode()

第一个参数是要发送脉冲的设备。这可以是0或1，具体取决于设备的连接方式。此参数是可选的，默认情况下将发送到设备0。

第二个参数是脉冲激活的时间（以毫秒为单位），默认值为100毫秒。

第三个参数是脉冲发送后的延迟时间（以毫秒为单位），默认值为500毫秒。

let result = encoder
    .pulse(0, 100, 500)
    .encode()

原始命令

添加原始打印机命令，以防您想要发送此库本机不支持的命令。例如，下面的命令是打开汉字字符模式。

let result = encoder
    .raw([ 0x1c, 0x2e ])
    .encode()