Text2 Barcode – Web Print API (Docs & Samples)

Introduction

Imprime desde la web a impresoras térmicas usando t2bprinter.js.

La API de Text2 Barcode permite listar impresoras, detectar la predeterminada, filtrar por nombre y enviar comandos de impresión (ZPL, ESC/POS, TSPL). También puede convertir imágenes/PDF a formatos de impresión.

Idea clave: Tu web/app carga la librería t2bprinter.js en el navegador. Esta se encarga de encontrar y enviar datos a la impresora (USB/Bluetooth/Driver/Red) a través del conector compatible.

Prerequisites

Una impresora soportada (p. ej., Zebra GK420d/GK420t, Bixolon SRP-330II, etc.).
Acceso a la librería: https://labeldictate.com/text2barcode/lib/t2bprinter.js.
Tener instalado Text2 Barcode.

Quick Start

Incluye la librería y llama a los métodos:

<script src="https://labeldictate.com/text2barcode/lib/t2bprinter.js"></script>

Probar rápido: Abre API Test para verificar que tu navegador detecta impresoras: labeldictate.com/text2barcode/test

Configuración del objeto

T2bPrinter expone propiedades de configuración que puedes sobreescribir antes de llamar a cualquier método. Todas tienen valores por defecto funcionales.

// Habilitar logs de depuración en consola
T2bPrinter.enableDebug = true;

Descripción de propiedades

enableDebug (boolean, default: false)
Cuando es true, la librería imprime en console.debug / console.warn detalles de cada solicitud HTTP (URL, opciones y errores de reconexión). Útil durante el desarrollo para diagnosticar problemas de conectividad.
defaultPort (number, default: 9100)
Puerto utilizado cuando useSecureConnection es false o cuando la conexión segura falla y la librería reintenta con HTTP plano.
securePort (number, default: 9101)
Puerto utilizado cuando useSecureConnection es true. Las solicitudes se realizan sobre HTTPS hacia 127.0.0.1.
useSecureConnection (boolean, default: true)
Controla si las peticiones se realizan sobre HTTPS (securePort) o HTTP (defaultPort). La librería tiene un mecanismo de fallback automático: si la petición segura falla, reintenta automáticamente con HTTP en el puerto no seguro y actualiza esta propiedad a false para las siguientes llamadas.
Fallback automático: No necesitas configurar esto manualmente en la mayoría de casos. La librería detecta qué puerto responde y lo recuerda durante la sesión.

Tipos de datos

La mayoría de los métodos de T2bPrinter devuelven objetos de tipo Printer.

type Printer = {
  "uid": string;
  "name": string;
  "manufacturer": string;
  "connection": "driver" | "bluetooth" | "network" | "ttb";
  "deviceType": string;
  "version": number;
};

Descripción de campos

uid: Identificador único del dispositivo.
Ej: nombre de la impresora, dirección IP, dirección MAC de Bluetooth o ID de plantilla de Text2Barcode.
name: Nombre asignado a la impresora.
manufacturer: Nombre del fabricante del dispositivo.
connection: Tipo de conexión. Valores posibles:
- driver: Controlador específico (Windows/macOS).
- bluetooth: Conexión Bluetooth (Android/iOS).
- network: Conexión de red (IP/host).
- ttb: Conexión a través de Text2Barcode.
Sistemas operativos:
Android/iOS: bluetooth, network, ttb.
Windows/macOS: driver, network, ttb.
deviceType: Categoría del dispositivo (normalmente printer).
version: Versión de la API en uso.

Core API

isAvailable()boolean

Verifica si el servidor de Text2 Barcode está en ejecución y accesible desde el navegador.

No recibe parámetros. Realiza una petición GET / al servidor local. Devuelve true si el servidor responde correctamente, o false si no está disponible — nunca lanza una excepción.

Ideal para: comprobar antes de cualquier operación si Text2 Barcode está instalado y corriendo, y mostrar un mensaje amigable al usuario en caso contrario. A diferencia del resto de métodos, este nunca rechaza la promesa; el error queda capturado internamente y se transforma en false.

const running = await T2bPrinter.isAvailable();
if (running) {
  console.log("Text2 Barcode está disponible ✓");
} else {
  console.warn("Text2 Barcode no está disponible. ¿Está instalado y en ejecución?");
}

true // Servidor disponible:
flase // Servidor no disponible o no instalado:

Probar isAvailable() Test

Ejecuta T2bPrinter.isAvailable() y muestra si el servidor de Text2 Barcode responde en este equipo. No requiere ningún parámetro. Nunca lanza error: devuelve true o false.

available()Printer[]

Lista todas las impresoras disponibles en el dispositivo.

No recibe parámetros. Devuelve un objeto con la clave printer que contiene un array de objetos Printer.

const available = await T2bPrinter.available();
for (const printer of (available.printer || [])) {
  console.debug("printer", JSON.stringify(printer, null, 2));
}

{
  "printer":[
    {
      "uid":"ZDesigner GK420t Plus (ZPL)",
      "name":"ZDesigner GK420t Plus (ZPL)",
      "manufacturer":"Zebra Technologies",
      "connection":"driver",
      "deviceType":"printer",
      "version":4
    },
    { ... }
  ]
}

Probar available() Test

Ejecuta T2bPrinter.available() y muestra la lista completa de impresoras detectadas en este dispositivo. No requiere ningún parámetro.

default()Printer

Obtiene la impresora predeterminada del dispositivo.

No recibe parámetros. Devuelve un único objeto Printer correspondiente a la impresora marcada como predeterminada en el sistema operativo.

const printer = await T2bPrinter.default();
console.debug("defaultPrinter:", JSON.stringify(printer, null, 2));

{
  "uid":"ZDesigner GK420t Plus (ZPL)",
  "name":"ZDesigner GK420t Plus (ZPL)",
  "manufacturer":"Zebra Technologies",
  "connection":"driver",
  "deviceType":"printer",
  "version":4
}

Probar default() Test

Ejecuta T2bPrinter.default() y retorna el objeto Printer de la impresora predeterminada del sistema. No requiere ningún parámetro.

filter(predicate)Printer[]

Devuelve todas las impresoras que cumplen un criterio (predicado).

predicate (Function) — Función que recibe un objeto Printer y debe retornar true para incluirlo en el resultado.

const printers = await T2bPrinter.filter(it => it.name.includes("ZPL"));
console.debug("printers:", JSON.stringify(printers, null, 2));

[
  {
    "uid":"ZDesigner GK420t Plus (ZPL)",
    "name":"ZDesigner GK420t Plus (ZPL)",
    "manufacturer":"Zebra Technologies",
    "connection":"driver",
    "deviceType":"printer",
    "version":4
  },
  { ... }
]

Probar filter(predicate) Test

Filtra las impresoras disponibles según el texto ingresado. Se busca coincidencia parcial (case-insensitive) en el campo name de cada Printer.

Texto a buscar en name

Se aplicará: it.name.toLowerCase().includes(texto)

find(predicate)Printer

Devuelve la primera impresora que cumple un criterio.

predicate (Function) — Función que recibe un objeto Printer y debe retornar true para seleccionarlo. Si ninguna impresora cumple el criterio, retorna null.

const printer = await T2bPrinter.find(it => it.name === "Zebra GK420d");
// o por uid: await T2bPrinter.find(it => it.uid === "ZDesigner GK420t Plus (ZPL)");
console.debug("printer:", JSON.stringify(printer, null, 2));

{
  "uid":"ZDesigner GK420t Plus (ZPL)",
  "name":"ZDesigner GK420t Plus (ZPL)",
  "manufacturer":"Zebra Technologies",
  "connection":"driver",
  "deviceType":"printer",
  "version":4
}

Probar find(predicate) Test

Busca la primera impresora que coincida. Elige el campo y el valor para construir el predicado.

Campo

Operador

Valor

Predicado generado: it.name === "…"

write(printer, data)Result

Envía datos en texto plano (ZPL, ESC/POS, TSPL) directamente a una impresora. Internamente serializa el payload como Content-Type: text/plain con la estructura { device, data }.

printer (Printer — requerido) — Objeto Printer obtenido con find(), default(), filter(), etc. Debe incluir al menos uid, name y connection.
data (string — requerido) — Contenido del trabajo de impresión en texto plano:
- ZPL: bloque entre ^XA y ^XZ.
- ESC/POS: bloque XML entre <EscPos> y </EscPos>.
- TSPL: comandos TSPL de impresoras TSC.

Payload enviado al servidor: { "device": <Printer>, "data": "<string>" } — la propiedad device identifica la impresora y data contiene los comandos a imprimir.

const result = await T2bPrinter.write(printer, `
^XA
^PW609
^LL403
^PON
^CI28
^FO38,30^GB545,349,5^FS
^FO85,60^A0N,33,33^FH^FDZPL PRINT TEST - 3"^FS
^BY2,2,44^FO90,280^BCN,,Y,N
^FD123456789012^FS
^FO465,20^BQN,2,4
^FH\\^FDLA,123456789012^FS
^PQ1,0,1,Y
^XZ
`);
console.debug("write", JSON.stringify(result, null, 2));

{
  "result": true,
  "message": "messages"
}

Probar write(printer, data) Test

Selecciona una impresora disponible y edita el contenido a enviar. El panel carga automáticamente las impresoras del dispositivo al abrirse.

Impresora

Contenido (ZPL / ESC/POS / TSPL)

writeAsBlob(printer, blob)Result

Envía datos binarios directamente a la impresora sin conversión de texto. Internamente construye un FormData con dos campos: json (metadatos del dispositivo) y blob (los datos binarios).

printer (Printer — requerido) — Objeto Printer destino. Se serializa como JSON en el campo json del FormData.
blob (Blob — requerido) — Datos binarios a enviar. Útil cuando el contenido ya está pre-compilado (p. ej., bytes ESC/POS generados programáticamente o archivos ZPL cargados desde disco). El type recomendado es "application/octet-stream".

FormData enviado al servidor:
json → JSON.stringify({ "device": <Printer> })
blob → contenido binario del Blob

const zpl = '^XA^FO50,50^A0N,50,50^FDHello^FS^XZ';
const blob = new Blob([zpl], { type: "application/octet-stream" });
const result = await T2bPrinter.writeAsBlob(printer, blob);
console.debug("writeAsBlob", JSON.stringify(result, null, 2));

{
  "result": true,
  "message": "messages"
}

Probar writeAsBlob(printer, blob) Test

Escribe el contenido del campo de texto como un Blob de tipo application/octet-stream y lo envía a la impresora seleccionada.

Impresora

Archivo a enviar (ZPL / TSPL / BIN / etc.)

Se enviará el archivo tal cual (File → Blob) con MIME fijo: application/octet-stream.

convert(resource, payload)Result

Convierte una imagen o PDF a ZPL/ESC-POS/TSPL y, opcionalmente, imprime o almacena el resultado. Internamente construye un FormData con los campos json (opciones) y blob (el archivo fuente).

resource (Blob | File — requerido) — Archivo fuente. Puede ser un File de un <input type="file"> o cualquier Blob. Se adjunta como campo blob en el FormData.
payload (Object — requerido) — Objeto con la configuración de la conversión. Se serializa como JSON en el campo json del FormData:
- options (Object):
  - action ("print" | "store" | "return") — Acción tras convertir:
    • "print": convierte e imprime directamente (requiere device).
    • "return": devuelve el resultado en base64 sin imprimir.
    • "store": almacena el resultado en el servidor (usa storageName para nombrar el archivo).
  - storageName (string, opcional) — Nombre del archivo a guardar en el servidor cuando action es "store".
  - fromFormat ("png" | "jpg" | "pdf") — Formato del archivo fuente (resource).
  - toFormat ("zpl" | "esc-pos" | "tspl") — Formato destino de la conversión.
  - resize ({ width?: number, height?: number }, opcional) — Redimensiona la imagen antes de convertir. Puedes especificar solo width o solo height; el otro lado se calcula proporcionalmente.
  - dithering (string, opcional) — Algoritmo de dithering para la conversión a blanco/negro. Valores:
    - "FloydSteinbergDithering" — Difusión de error Floyd-Steinberg (recomendado para fotografías).
    - "AtkinsonDithering" — Algoritmo Atkinson, genera patrones más compactos.
    - "NoDithering" — Sin dithering, umbral simple.
- device (Printer, requerido si action es "print") — Objeto Printer destino.

FormData enviado al servidor:
json → JSON.stringify(payload)
blob → contenido del archivo resource

const fileInput = document.querySelector('#file');
const resource = fileInput.files[0]; // File / Blob

const payload = {
  options: {
    action: "print",                      // "print" | "return" | "store"
    storageName: "mi-etiqueta.zpl",       // solo si action === "store"
    fromFormat: "png",                    // "png" | "jpg" | "pdf"
    toFormat: "zpl",                      // "zpl" | "esc-pos" | "tspl"
    resize: { width: 600 },              // redimensionar antes de convertir
    dithering: "FloydSteinbergDithering" // "FloydSteinbergDithering" | "AtkinsonDithering" | "NoDithering"
  },
  device: {                               // requerido si action === "print"
    uid: "ZDesigner GK420t Plus (ZPL)",
    name: "ZDesigner GK420t Plus (ZPL)",
    manufacturer: "Zebra Technologies",
    connection: "driver",
    deviceType: "printer",
    version: 4
  }
};

const result = await T2bPrinter.convert(resource, payload);
console.debug("converted", JSON.stringify(result, null, 2));

{
  "data": "base64-encoded ZPL or format",
  "width": 600,
  "height": 400,
  "filename": "converted.zpl"
}

Probar convert(resource, payload) Test

Selecciona un archivo imagen o PDF y configura las opciones de conversión. Si action es "print", también debes elegir la impresora destino.

Archivo (PNG, JPG o PDF)

fromFormat

toFormat

action

resize.width (px)

resize.height (px, opcional)

dithering

Recipes (Samples)

Imprimir muestra ZPL

Ejemplo mínimo para imprimir una etiqueta ZPL buscando por name:


<!DOCTYPE html>
<html>
  <head>
    <script src="https://labeldictate.com/text2barcode/lib/t2bprinter.js"></script>
    <script>
      const printLabel = async () => {
        const printerName = "Zebra GK420d";
        const labelContent = `
^XA
^PW609
^LL403
^PON
^CI28
^FO85,60^A0N,33,33^FH^FDZPL PRINT TEST - 3"^FS
^BY2,2,44^FO90,280^BCN,,Y,N
^FD123456789012^FS
^FO465,20^BQN,2,4
^FH\\^FDLA,123456789012^FS
^PQ1,0,1,Y
^XZ
`;
        try {
          const printer = await T2bPrinter.find(it => it.name === printerName);
          if (printer) {
            const res = await T2bPrinter.write(printer, labelContent);
            alert(JSON.stringify(res, null, 2));
          } else {
            alert(\`Printer "${printerName}" not found.\`);
          }
        } catch (err) {
          alert(err);
        }
      };
      window.onload = printLabel;
    </script>
  </head>
  <body></body>
</html>

Imprimir muestra ESC/POS

Ejemplo mínimo para imprimir en ESC/POS:


<!DOCTYPE html>
<html>
  <head>
    <script src="https://labeldictate.com/text2barcode/lib/t2bprinter.js"></script>
    <script>
      const printLabel = async () => {
        const printerName = "Bixolon SRP-330II";
        const labelContent = `
<EscPos>
  <Init/>
  <QrCode justification="right">QR Test Text</QrCode>
  <Feed lines="1"/>
  <BarCode>1234567890</BarCode>
  <Feed lines="1"/>
  <Text fontWidth="3" fontHeight="3">Large Text</Text>
  <Text fontWidth="2" fontHeight="2">Medium Text</Text>
  <Text fontWidth="1" fontHeight="1">Small Text</Text>
  <Feed lines="1"/>
  <Text justification="left">Left</Text>
  <Text justification="center">Center</Text>
  <Text justification="right">Right</Text>
  <Feed lines="1"/>
  <Text underline="one-dot-thick">Underline</Text>
  <Text bold="true">Bold</Text>
  <Text inverse="true">Inverted</Text>
  <Feed lines="3" />
  <Cut mode="full" />
</EscPos>
`;
        try {
          const printer = await T2bPrinter.find(it => it.name === printerName);
          if (printer) {
            const res = await T2bPrinter.write(printer, labelContent);
            alert(JSON.stringify(res, null, 2));
          } else {
            alert(\`Printer "${printerName}" not found.\`);
          }
        } catch (err) {
          alert(err);
        }
      };
      window.onload = printLabel;
    </script>
  </head>
  <body></body>
</html>

Solución de problemas

No aparecen impresoras: Revisa permisos del navegador/OS, usa HTTPS, valida el conector y prueba en API Test.
Nombre no coincide: Usa available() para listar y copia el name real o filtra por uid.
Caracteres especiales: Asegura ^CI28 en ZPL o las banderas correctas en ESC/POS para charset/UTF-8.
Rendimiento/colas: Evita mandar múltiples trabajos simultáneos; espera la promesa de write.

API Test