Tarayıcıdan ESC/POS Yazdırma: Bir Geliştirici Kılavuzu

Tarayıcı Yazdırma Sorunu

Bir web uygulamasından hiç fiş yazdırmayı denediyseniz, acıyı bilirsiniz: window.print() bir yazdırma iletişim kutusu açar, sayfayı PDF olarak işler ve otomatik kesme veya özel kağıt genişliği gibi ESC/POS komutları için sıfır desteğe sahiptir.

Termal fiş yazıcıları için bu, anlaşmayı bozan bir durumdur. İhtiyacınız olanlar:

  • Sessiz yazdırma — iletişim kutusu yok, kullanıcı etkileşimi yok
  • ESC/POS komutları — otomatik kesme, kalın metin, hizalama, barkodlar için
  • Güvenilir kodlama — yazıcınız için doğru kod sayfasına UTF-8
  • Çapraz platform desteği — Mac, Windows, Linux

Çözüm, yerel bir WebSocket köprüsüdür — kullanıcının bilgisayarında çalışan, web uygulamanızdan yazdırma işlerini kabul eden ve yazıcıya ham ESC/POS komutları gönderen küçük bir arka plan uygulamasıdır.

WebSocket Köprüsü Nasıl Çalışır?

Web Uygulamanız → WebSocket (ws://localhost:8765) → Yazdırma Aracısı → Termal Yazıcı

Akış basittir:

  1. Web uygulamanız ws://localhost:8765 adresine bir WebSocket bağlantısı açar
  2. Fişi açıklayan bir JSON yükü gönderirsiniz
  3. Yazdırma Aracısı bunu ESC/POS'a dönüştürür ve yazıcıya gönderir
  4. Yazıcı sessizce yazdırır — iletişim kutusu yok, sürücü etkileşimi yok

MenuForma Yazdırma Aracısı bu köprüyü uygular. Ücretsiz, açık kaynaklıdır ve Mac, Windows ve Linux'ta çalışır.

API Referansı

Bağlantı

const ws = new WebSocket('ws://localhost:8765');

ws.onopen = () => {
  console.log('Yazdırma Aracısı bağlandı');
};

ws.onerror = () => {
  console.log('Yazdırma Aracısı çalışmıyor');
};

Aracı Durumunu Kontrol Et

Aracının çalıştığını doğrulamak için bir ping gönderin:

ws.send(JSON.stringify({ type: 'ping' }));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'pong') {
    console.log('Aracı sürümü:', data.version);
  }
};

Fiş Yazdır

const receipt = {
  type: 'print',
  printer: 'auto',   // veya '192.168.1.100' gibi belirli bir IP
  data: {
    storeName: 'Restoranım',
    storeAddress: 'Ana Cadde 123',
    orderNumber: '#1042',
    tableNumber: 'Masa 5',
    items: [
      { name: 'Margherita Pizza', qty: 1, price: 14.90 },
      { name: 'Maden Suyu', qty: 2, price: 3.50 },
    ],
    subtotal: 21.90,
    tax: 1.97,
    total: 23.87,
    paymentMethod: 'Kart',
    footer: 'Bizimle yemek yediğiniz için teşekkür ederiz!',
  }
};

ws.send(JSON.stringify(receipt));

React Entegrasyon Örneği

import { useEffect, useRef, useCallback, useState } from 'react';

function usePrintAgent() {
  const wsRef = useRef(null);
  const [connected, setConnected] = useState(false);

  useEffect(() => {
    const connect = () => {
      const ws = new WebSocket('ws://localhost:8765');
      ws.onopen = () => setConnected(true);
      ws.onclose = () => {
        setConnected(false);
        setTimeout(connect, 3000); // tekrar dene
      };
      wsRef.current = ws;
    };
    connect();
    return () => wsRef.current?.close();
  }, []);

const print = useCallback((receiptData) => { if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) { throw new Error('Print Agent not connected'); } wsRef.current.send(JSON.stringify({ type: 'print', data: receiptData })); }, []);

return { connected, print }; }


---

## Shopify Entegrasyonu

Shopify mağazaları için, bir Sipariş webhook'undan veya bir tarayıcı uzantısından yazdırmayı tetikleyebilirsiniz:

```javascript
// Shopify mağazanızda veya yönetici uzantınızda
async function printShopifyOrder(order) {
  const ws = new WebSocket('ws://localhost:8765');
  
  ws.onopen = () => {
    ws.send(JSON.stringify({
      type: 'print',
      data: {
        storeName: order.shop_name,
        orderNumber: order.name,
        items: order.line_items.map(item => ({
          name: item.title,
          qty: item.quantity,
          price: parseFloat(item.price),
        })),
        total: parseFloat(order.total_price),
        paymentMethod: order.payment_gateway,
      }
    }));
  };
}

Yazıcı Yapılandırması

Yazdırma yükündeki "printer" alanı şunları kabul eder:

Değer Açıklama
"auto" Print Agent ayarlarında yapılandırılan yazıcıyı kullanın
"192.168.1.100" IP ile doğrudan bir ağ yazıcısına bağlanın
"USB" İlk algılanan USB yazıcıyı kullanın

Hata Yönetimi

ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  
  if (response.type === 'print_success') {
    console.log('Printed successfully');
  } else if (response.type === 'print_error') {
    console.error('Print failed:', response.error);
    // Yedek UI göster veya tekrar dene
  }
};

Print Agent'ın Yüklü Olup Olmadığını Algılama

Kullanıcı arayüzünüzde yazdırma işlevselliğini göstermeden önce, aracının çalışıp çalışmadığını kontrol edin:

async function isPrintAgentAvailable() {
  return new Promise((resolve) => {
    const ws = new WebSocket('ws://localhost:8765');
    const timeout = setTimeout(() => {
      ws.close();
      resolve(false);
    }, 1000);
    ws.onopen = () => {
      clearTimeout(timeout);
      ws.close();
      resolve(true);
    };
    ws.onerror = () => {
      clearTimeout(timeout);
      resolve(false);
    };
  });
}

// Kullanım
const agentAvailable = await isPrintAgentAvailable();
if (!agentAvailable) {
  // İndirme istemini göster
  window.open('/print-agent', '_blank');
}

Print Agent'ı İndir

MenuForma Print Agent Mac, Windows ve Linux için ücretsizdir. USB, ağ ve Bluetooth termal yazıcıları destekler ve bu kılavuzda açıklanan tüm WebSocket API'sini uygular.

Tam API belgeleri ve açık kaynak kodu için Print Agent sayfasını ziyaret edin.

Related Articles

MenuForma Products