zplCore Designer
der einbettbare Etiketten-Editor.

01Überblick

Der Designer besteht aus zwei Teilen, die immer zusammen laufen: der Editor-Oberfläche (statische Dateien, eine Angular-App ohne externe Aufrufe) und einer zustandslosen Render-API in .NET, die Vorschauen rendert, für die Arbeitsfläche die gedruckte Geometrie jedes Elements misst und Bilder und SVGs umwandelt. Beides liefert eine ASP.NET-Core-Bibliothek; der Container ist diese Bibliothek mit einem minimalen Host.

Was enthalten ist

• Arbeitsfläche mit allen Elementtypen: Text, Barcode (1D/2D, GS1, gestaltete Codes), Rechteck, Linie, Kreis/Ellipse, Bild, Druckerspeicher-Grafik, SVG-Icon, ZPL-Element, Tabelle, RFID.
• Eigenschaften-Panel, Elementliste, Gruppen, mehrere Seiten, Raster, Lineale, Fang, Zoom, Rückgängig/Wiederholen, Zwischenablage, Tastaturkürzel.
• Datenbindung mit JSON-Datensätzen (aus Ihrer Anwendung oder im Editor bearbeitet), Vorschau je Datensatz, Ausblenden je Datensatz, Ausdrücke und Zahlenformate.
• Vorschauen: ZPL, PDF, PNG, SVG; ZPL-Analyser und -Linter; GS1-Assistent, RFID-Felder, Bild → ZPL, SVG → ZPL, Icon-Bibliothek.
• 10 Oberflächensprachen (en, de, zh, ja, es, fr, pt, it, ar, hi), Hell und Dunkel, mm / Zoll / Dots, 203 / 300 / 600 dpi.

Was bewusst nicht enthalten ist

• Drucken jeder Art – Ihre Anwendung sendet das ZPL (zum Beispiel mit dem zplCore-SDK).
• Speichern, Konten, Versionen oder Teams – Ihre Anwendung bekommt das JSON und speichert es.
• Datenquellen-Konnektoren – Daten kommen als JSON-Datensätze aus Ihrer Anwendung.
• Ein KI-Copilot und das alte zplCloud-Designformat { label, fields } (vorher umwandeln).

02Schnellstart: NuGet (ASP.NET Core)

dotnet add package ZplCore.Designer

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication(/* your scheme */);
builder.Services.AddAuthorization();
builder.Services.AddZplCoreDesigner(o =>
{
    o.Fonts.AddDirectory("fonts");                  // optional: your TTF/OTF printer fonts (E:NAME.TTF)
    o.PrinterGraphics.AddDirectory("graphics");     // optional: your printer-memory graphics (E:NAME.GRF)
    o.Limits.MaxRecordsPerRequest = 500;
});

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapZplCoreDesigner("/designer")
   .RequireAuthorization("label-editors");          // your auth – the designer brings none of its own
app.Run();

Der Editor liegt nun unter /designer/, die API unter /designer/api/…, das OpenAPI-Dokument unter /designer/api/openapi/zplcore-designer.json und eine Statusantwort unter /designer/healthz. MapZplCoreDesigner liefert einen Convention-Builder: .RequireAuthorization(…) schützt Oberfläche und API, .Api und .Ui sprechen je einen Teil an (zum Beispiel öffentliche Oberfläche mit geschützter API).

03Schnellstart: Docker

docker run -d -p 8080:8080 --read-only --tmpfs /tmp \
  -e ZPLCORE_DESIGNER__AUTH__MODE=apikey \
  -e ZPLCORE_DESIGNER__AUTH__APIKEYS__0=<Schlüssel mit mindestens 16 Zeichen> \
  -e ZPLCORE_DESIGNER__ALLOWEDORIGINS__0=https://app.example.com \
  -v ./fonts:/fonts:ro -v ./graphics:/graphics:ro \
  zplcore/designer

Der Editor liegt unter http://localhost:8080/designer/. Das Image ist distroless (Azure Linux), läuft als Benutzer app ohne Root-Rechte auf Port 8080 und funktioniert mit schreibgeschütztem Root-Dateisystem und beschreibbarem /tmp; es wird für linux/amd64 und linux/arm64 gebaut. Der Container wird über den Abschnitt Designer als Umgebungsvariablen ZPLCORE_DESIGNER__… konfiguriert (doppelter Unterstrich = Verschachtelung, __0 = erster Listeneintrag); jede Option aus Abschnitt 09 lässt sich so setzen, zum Beispiel ZPLCORE_DESIGNER__LIMITS__MAXRECORDSPERREQUEST=200.

Eingebundene Ordner (alle optional, nur lesend genügt): /fonts Druckerspeicher-Schriften, /graphics Druckerspeicher-Grafiken, /templates Design-Vorlagen (*.json), /icons eigene SVG-Icons, /svg-fonts SVG-Schriften und Glyphen-Sets, /graphic-fonts für Grafiktext freigegebene Schriften (ZPLCORE_DESIGNER__FOLDERS__* für andere Pfade). Liveness /healthz, Readiness /readyz (rendert ein kleines Etikett). Die API braucht Schlüssel oder Token; die statische Oberfläche und {prefix}/healthz bleiben öffentlich.

Kubernetes: das Helm-Chart deploy/helm/zplcore-designer (API-Schlüssel nur aus einem vorhandenen Secret, ohne Root, schreibgeschütztes Root-Dateisystem, Probes, optional HPA und Network Policy):

kubectl create secret generic designer-api-keys --from-literal=key1=<key>
helm install designer deploy/helm/zplcore-designer \
  --set auth.apiKey.existingSecret=designer-api-keys \
  --set designer.allowedOrigins[0]=https://app.example.com

04Einbetten mit JavaScript (iframe)

Jeder Designer-Host liefert das SDK unter {baseUrl}/sdk/zplcore-designer.js aus (ohne Abhängigkeiten, ohne CDN); mit einem Bundler nehmen Sie das npm-Paket @zplcore/designer. Das SDK legt ein iframe auf den Editor an und spricht mit ihm über postMessage; das iframe trennt Stile und Skripte vollständig von Ihrer Seite.

<div id="editor" style="height: 720px"></div>
<script src="https://labels.example.com/designer/sdk/zplcore-designer.js"></script>   <!-- global ZplCoreDesigner -->
<script type="module">
  const editor = await ZplCoreDesigner.mount('#editor', {
    baseUrl: 'https://labels.example.com/designer/',
    design,                                   // design document { label, editor, records } or only the label JSON
    data: [{ name: 'Anna', ean: '9506000134352' }],
    locale: 'de', theme: 'auto', unit: 'mm',
    requestHeaders: { 'X-Api-Key': key },     // container with API key; travels by postMessage, never in a URL
    onChange: (doc) => save(doc)              // user edits only, debounced, incl. records
  });
  const zpl = await editor.getZpl();          // the same ZPL the server prints
</script>

// with a bundler
import { mount } from '@zplcore/designer';
const editor = await mount('#editor', { baseUrl: '/designer/' });

Läuft der Editor auf einem anderen Ursprung als Ihre Anwendung, tragen Sie Ihren Ursprung in AllowedOrigins des Designer-Hosts ein; ursprungsübergreifend laden Sie das klassische Skript (das ES-Modul von einem anderen Ursprung bräuchte CORS). Fertige Hüllen für React 19, Vue 3 und Angular liegen in examples/ des SDK. Alle Optionen, Methoden und Ereignisse: Abschnitt 11.

05Einbetten als Web Component

<script src="/designer/sdk/zplcore-designer.js"></script>   <!-- defines <zplcore-designer> -->
<zplcore-designer base-url="/designer/" locale="de" theme="auto" unit="mm"
                  features="-gs1,-rfid" style="display: block; height: 720px"></zplcore-designer>
<script type="module">
  const el = document.querySelector('zplcore-designer');
  el.design = doc;                  // or the attribute design='{"label":…}'
  el.data = rows;
  el.addEventListener('zplcore-change', (e) => save(e.detail.design));
  const zpl = await el.getZpl();
</script>

Mit einem Bundler: import '@zplcore/designer/element'. Das Element ist eine schlanke Hülle um das iframe-SDK (Shadow DOM, das iframe ist der Part frame): Attribute base-url, design, locale, theme, unit, tab, features, read-only, autosave, allowed-origins, timeout, title; Properties design, data, requestHeaders; Ereignisse (bubbling, composed) zplcore-ready, zplcore-change, zplcore-selection-change, zplcore-validation, zplcore-error; alle SDK-Methoden am Element. Es funktioniert in jedem Framework, das Custom Elements rendert.

06Blazor

dotnet add package ZplCore.Designer.Blazor

<ZplCoreDesigner @ref="editor" @bind-Design="design" Data="rows" BaseUrl="/designer"
                 Locale="de" Theme="DesignerTheme.Auto" ReadOnly="false" Height="720px"
                 OnChange="OnChange" OnSelectionChange="OnSelection" />

@code {
    ZplCoreDesigner? editor;
    JsonObject? design;                  // DesignDocument { schemaVersion, label, editor, records }
    List<object> rows = [new Dictionary<string, object?> { ["name"] = "Anna", ["ean"] = "9506000134352" }];

    async Task Export()
    {
        string zpl = await editor!.GetZplAsync();
        byte[] pdf = await editor.GetPdfAsync();
    }
}

// same host (Blazor Server or a hosted WebAssembly app)
builder.Services.AddZplCoreDesigner();
app.MapZplCoreDesigner("/designer").RequireAuthorization();   // your auth

Die Komponente hüllt das JavaScript-SDK für Blazor Server und WebAssembly ein (interaktive Render-Modi; beim Prerendering passiert nichts). Den Editor liefert ein ZplCore.Designer-Host in derselben Anwendung oder der Container: BaseUrl="https://labels.example.com/designer", Ihre Anwendung in ZPLCORE_DESIGNER__ALLOWEDORIGINS__0 eintragen und den Schlüssel mit RequestHeaders übergeben. Designs, ZPL und PDFs kommen als Byte-Streams zurück, die SignalR-Nachrichtengrenze von Blazor Server greift daher nicht.

Methoden: GetDesignAsync, SetDesignAsync, SetDataAsync, GetZplAsync, GetPdfAsync, GetPngAsync, GetSelectionAsync, ValidateAsync, UndoAsync, RedoAsync, SetLocaleAsync, SetThemeAsync, SetRequestHeadersAsync.

07WPF / WinForms mit WebView2

Eine Desktop-Anwendung startet den Designer im eigenen Prozess (NuGet ZplCore.Designer, Kestrel auf einem zufälligen 127.0.0.1-Port) und zeigt ihn in WebView2. Eine kleine Bridge-Seite bindet den Editor mit dem JavaScript-SDK ein und reicht Befehle und Ereignisse zwischen C# (CoreWebView2.PostWebMessageAsString / WebMessageReceived) und dem Editor weiter. Die API antwortet nur auf Anfragen mit einem zufälligen Token des Prozesses, andere Programme auf dem Rechner können den Port also nicht nutzen; nichts verlässt den Rechner.

// samples/DesignerWpf: host on a random loopback port, API only with a per-process token
var host = await LocalDesignerHost.StartAsync(Path.Combine(AppContext.BaseDirectory, "bridge"));
await Web.EnsureCoreWebView2Async();
var core = Web.CoreWebView2;
var bridge = new DesignerBridge(json => { core.PostWebMessageAsString(json); return Task.CompletedTask; });
core.WebMessageReceived += (_, e) => bridge.OnMessage(e.TryGetWebMessageAsString());
core.Navigate(host.BridgePageUrl);                 // the bridge page mounts the editor with the JS SDK
await bridge.InitAsync(host.DesignerUrl, design, data, "de", headers: host.Headers);

string zpl = await bridge.GetZplAsync();
JsonObject? doc = await bridge.GetDesignAsync();

Das Beispiel samples/DesignerWpf (gemeinsame Teile in samples/designer-embed: Bridge-Seite, DesignerBridge, LocalDesignerHost, Datensatz-Import aus JSON oder CSV) öffnet und speichert Designs, lädt Datensätze, exportiert ZPL und PDF und bietet Rückgängig/Wiederholen und die Sprachwahl. Es braucht die WebView2-Laufzeit.

08.NET MAUI

Eine HybridWebView zeigt dieselbe Bridge-Seite; Befehle und Ereignisse laufen über DesignerBridge. Unter Windows läuft der Designer-Host in der App (LocalDesignerHost); unter Android, iOS und Mac Catalyst nutzt die App einen Designer-Host oder den Container in Ihrem Netz – dort den Ursprung der Seite erlauben:

ZPLCORE_DESIGNER__ALLOWEDORIGINS__0=https://0.0.0.1   # Android
ZPLCORE_DESIGNER__ALLOWEDORIGINS__1=app://0.0.0.1     # iOS / Mac Catalyst

Das Beispiel samples/DesignerMaui braucht die MAUI-Workloads (dotnet workload install maui-windows maui-android) und gehört nicht zur Solution. Die Arbeitsfläche ist für Maus und Stift ausgelegt; auf Touch-Geräten funktioniert der Editor mit Einschränkungen.

09Optionen und Konfiguration

AddZplCoreDesigner(o => …) konfiguriert ZplCoreDesignerOptions; der Container bindet dasselbe Objekt aus dem Abschnitt Designer.

Grenzen

Erweiterungspunkte

Schnittstellen, die Sie in der DI registrieren oder in den Optionen übergeben: IFontProvider, IPrinterGraphicsProvider, IIconProvider, ITemplateProvider (Inhalte), IDesignerAuthorization (eine Operation je Anfrage erlauben oder ablehnen), IRenderObserver (Logging, Metriken) und IDesignerLicenseValidator (Lizenzprüfung).

Konfiguration der Editor-Oberfläche

Die Oberfläche liest, spätere Quellen gewinnen: {prefix}/config.json des Servers (Funktionen, Einbettungs-Ursprünge, Branding – keine Geheimnisse) → window.__ZPLCORE_DESIGNER__ einer Host-Seite → den Query-String nur für Anzeigeoptionen (locale, theme, unit, tab, autosave=0, features=-images,-fonts). API-Basis, Request-Header und Ursprünge kommen nie aus der URL. autosave (Standard an) hält einen Entwurf im lokalen Speicher des Browsers unter dem Präfix zplcore.designer.; schalten Sie es ab, wenn Ihre Anwendung das Design speichert.

10Render-API-Referenz

Alle Routen sind relativ zu {prefix}/api (z. B. /designer/api). Anfragen und Antworten sind UTF-8-JSON mit camelCase-Namen; jede Anfrage ist in sich vollständig, nichts wird gespeichert. Antworten tragen X-ZplCore-Designer-Api: 1. Der Editor nutzt diese API; Ihr Backend kann sie direkt aufrufen (mit der Anmeldung des Hosts oder dem API-Schlüssel des Containers).

Design rendern

{
  "document": { "label": { "unit": "Mm", "width": 60, "height": 40, "items": [
    { "type": "text", "name": "name", "x": 3, "y": 3, "dataField": "name", "fontSize": 14 } ] } },
  "records": [ { "name": "Anna" }, { "name": "Ben" } ]
}

document ist ein Design-Dokument (oder { "label": … }); das Label wird streng gelesen (unbekannte Eigenschaften → 400). Die Werte kommen aus records/record, nicht aus document.records. Jedes Bild ist das gerenderte /zpl-Ergebnis: Vorschau = Druck.

curl -X POST https://labels.example.com/designer/api/zpl \
  -H "X-Api-Key: $DESIGNER_API_KEY" -H "Content-Type: application/json" \
  -d @request.json

Helfer für die Arbeitsfläche

Umwandeln und Analysieren

Fehler

{ "error": "The request body is larger than 16,777,216 bytes.", "code": "too_large" }

Serveroptionen für die Oberfläche: GET {prefix}/config.json; Status: GET {prefix}/healthz → { status, version, buildTimeUtc }. Die vollständige OpenAPI-Beschreibung liefert Ihr eigener Host unter {prefix}/api/openapi/zplcore-designer.json.

11JavaScript-API

ZplCoreDesigner.mount(target, options)

Legt den Editor in target an (Element oder Selektor) und liefert ein Editor-Objekt, sobald der Editor antwortet.

Methoden (alle liefern Promises)

Alle Methoden liefern Promises; Fehler lehnen mit ZplCoreDesignerError ab (code: timeout, command_failed, ready_timeout, destroyed, invalid_options …). createDesigner() liefert die Instanz sofort (Befehle warten, bis sie bereit ist).

Das postMessage-Protokoll

Ohne SDK können Sie direkt mit dem iframe sprechen (Protokollversion 2). Host → Editor: { source: 'zplcore-host', type, id, payload }; Editor → Host: { source: 'zplcore', type: 'result', id, payload } und die Ereignisse ready und change (entprellt, { design, records }). Befehle: ping, getDesign, setDesign { design, records? }, setData { records }, getZpl { records? }, getPdf, getPng { record? } (beide { mimeType, base64 }), undo, redo, setLocale { locale }, setTheme { theme }. Der erste gültige Absender legt den Host-Ursprung fest (oder die Allow-List AllowedOrigins); Antworten gehen nur an diesen Ursprung, nie an *. Das SDK nutzt zusätzlich einen Start-Handshake (?embed=sdk: der Editor sendet hello, das SDK antwortet mit init samt Headern, Lesemodus, Design und Datensätzen vor dem ersten API-Aufruf) sowie die Befehle setReadOnly, setRequestHeaders, getSelection, setValidation, validate mit den Ereignissen selectionChange, validation und error. Der Live-Editor dieser Website nutzt genau dieses Protokoll.

12Schema des Design-Dokuments

Ein Design ist ein JSON-Dokument mit fünf Teilen. Pflicht ist nur label; der Editor schreibt nur Werte, die vom Startwert abweichen.

{
  "schemaVersion": 4,
  "label":   { "unit": "Mm", "width": 100, "height": 50, "items": [ … ] },
  "editor":  { "version": 1, "dpi": 203, "items": { "ean": { "locked": true } }, "groups": [] },
  "records": [ { "name": "Anna", "metadata": { "promo": { "isRendered": false } } } ],
  "uiSettings": { "zoom": 120, "tab": "pdf" }
}

Der Teil editor

Kompatibilitätszusage

• Innerhalb einer Schema-Version nur additive Änderungen: neue optionale Eigenschaften, deren Startwert den bisherigen Druck und das bisherige Verhalten erhält.
• Umbenennen, Entfernen, neuer Typ, neue Bedeutung oder neuer Startwert ⇒ neue Version (label.schemaVersion oder editor.version) mit Migrationsschritt; jede Version liest alle älteren.
• Unbekannte Eigenschaften in editor bleiben erhalten und werden zurückgeschrieben, damit ein älterer Host ein neueres Design nie beschädigt. An API-Grenzen wird das Label streng gelesen.

13Sicherheit und Betrieb

• Keine eigene Benutzerverwaltung. NuGet: Ihre Anmeldung und Richtlinien. Container: apikey, jwt (OIDC) oder ausdrücklich none.
• Einbettung: frame-ancestors und CORS aus AllowedOrigins; postMessage-Antworten gehen nur an den festgelegten Host-Ursprung.
• Eingaben: Größengrenzen je Anfrage, Render-Plätze mit Warteschlange und Zeitlimit, optionale Anfragegrenze je IP; SVGs werden bereinigt (keine Skripte, keine externen Verweise), der Server ruft nie URLs ab, ZPL-Elemente werden nur gerendert.
• Keine Speicherung, keine Telemetrie: Der Server behält zwischen Anfragen nichts (nur Zwischenspeicher gemessener Geometrie); kein Nach-Hause-Telefonieren, kein CDN – die Oberfläche lädt jede Datei von Ihrem Host.
• Skalierung: zustandslos, also beliebig viele Instanzen ohne Sticky Sessions. Native Abhängigkeiten (SkiaSharp, HarfBuzz, PDFium, ZXing) unterstützen Linux x64/arm64 (glibc), Windows und macOS.
• Überwachung: Status {prefix}/healthz (Container zusätzlich /healthz, /readyz), Metriken im Meter ZplCore.Designer (zplcore.designer.requests, zplcore.designer.duration, zplcore.designer.records), OpenTelemetry-Export (OTEL_EXPORTER_OTLP_ENDPOINT) und strukturierte JSON-Logs im Container.
• Container: distroless-Basis (Azure Linux), Benutzer app ohne Root, schreibgeschütztes Root-Dateisystem mit beschreibbarem /tmp; Helm-Chart mit entzogenen Capabilities, seccomp und optionaler Network Policy.
• Datenschutz: Designs und Datensätze bleiben in Ihrer Anwendung; der Entwurf des Editors liegt nur im Browser des Benutzers und lässt sich abschalten (autosave=0).

14Lizenz

Der zplCore Designer gehört zur kommerziellen Produktfamilie von zplCore.com. Lizenzmodell und Preise sind noch nicht veröffentlicht; sprechen Sie uns an für eine Testversion oder ein Angebot. Den Live-Editor dieser Website können Sie mit Demo-Grenzen kostenlos ausprobieren.