Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge deinem KI-Tool die Capgo Skills mit folgendem Befehl hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze anschließend diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-printer` plugin in my project.

Wenn du ein manuelles Setup bevorziehst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-printer
bunx cap sync

Importieren

import { Printer } from '@capgo/capacitor-printer';

Quickstart

Drucke eine PDF, die bereits auf der Festplatte liegt (empfohlen für große Dateien).

import { Printer } from '@capgo/capacitor-printer';

await Printer.printFile({
  path: 'file:///data/user/0/.../invoice.pdf',
  name: 'Invoice #1042',
});

Beispiel: HTML-Beleg

await Printer.printHtml({
  html: '<h1>Thank you</h1><p>Total: $42.00</p>',
  name: 'Receipt',
});

Beispiel: Vermeidung riesiger Base64-Payloads

printBase64 dekodiert ganze Dateien im Arbeitsspeicher. Bei Assets über ca. 5 MB in eine Temp-Datei schreiben und printFile instead.

Häufige Fehlerquellen

• Memory: Große Base64-Strings können die App auf Geräten mit wenig RAM zum Absturz bringen.
• Web: Der Druck erfolgt über den Browser-Dialog; das Layout unterscheidet sich von nativen Drucksteuerungen.
• Pfade: Unter Android muss ein zugänglicher file:// URI, absoluter Dateisystempfad oder content:// URI übergeben werden. App-relative Pfade werden nicht automatisch aufgelöst.

API Übersicht

printBase64

Zeigt die Druckoberfläche zum Drucken von als Base64-Strings kodierten Dateien an.

Plattformverhalten:

• iOS: Nutzt UIPrintInteractionController mit base64-dekodierten Daten
• Android: Nutzt PrintManager mit base64-dekodierten Daten
• Web: Erstellt einen Blob aus base64-Daten und öffnet den Druckdialog

Performance-Warnung: Große Dateien können beim Dekodieren von base64 aufgrund von Speicherengpässen zu App-Crashes führen. Bei Dateien über 5 MB wird empfohlen, printFile() zu verwenden.

import { Printer } from '@capgo/capacitor-printer';

// Print a base64 encoded PDF
await Printer.printBase64({
  name: 'Invoice #12345',
  data: 'base64-encoded-pdf-data',
  mimeType: 'application/pdf',
});

// Print a base64 encoded image
await Printer.printBase64({
  name: 'Product Photo',
  data: '/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDA...',
  mimeType: 'image/jpeg',
});

printFile

Zeigt die Druckoberfläche zum Drucken von Gerätedateien an.

Plattform-Verhalten:

• iOS: Nutzt UIPrintInteractionController mit File-URL. Unterstützt file://-Pfade oder Pfade relativ zum Documents-Verzeichnis der App.
• Android: Nutzt PrintManager mit File-Pfad. Unterstützt sowohl content://-URIs als auch file://-Pfade.
• Web: Liest Datei und öffnet den Druckdialog

Unterstützte Dateitypen:

• PDF-Dokumente (application/pdf)
• Bilder: JPEG, PNG, GIF, HEIC, HEIF

import { Printer } from '@capgo/capacitor-printer';

// iOS: Print from app documents directory
await Printer.printFile({
  name: 'Contract',
  path: 'file:///var/mobile/Containers/Data/Application/.../Documents/contract.pdf',
});

// Android: Print from content URI
await Printer.printFile({
  name: 'Receipt',
  path: 'content://com.android.providers.downloads.documents/document/123',
  mimeType: 'application/pdf',
});

// Android: Print from file path
await Printer.printFile({
  name: 'Photo',
  path: 'file:///storage/emulated/0/Download/photo.jpg',
  mimeType: 'image/jpeg',
});

printHtml

Zeigt die Druckoberfläche zum Drucken von HTML-Dokumenten an.

Plattform-Verhalten:

• iOS: Rendert HTML in der WKWebView und druckt via UIPrintInteractionController
• Android: Rendert HTML in der WebView und druckt via PrintManager
• Web: Erstellt ein iframe mit HTML-Inhalt und öffnet den Druckdialog

HTML-Anforderungen:

• Sollte ein vollständiges HTML-Dokument mit korrekter Struktur sein
• Kann Inline-CSS oder Style-Tags enthalten
• Externe Ressourcen (Bilder, Stylesheets) sollten absolute URLs nutzen
• Druckspezifisches CSS kann hinzugefügt werden mit

import { Printer } from '@capgo/capacitor-printer';

// Simple HTML document
await Printer.printHtml({
name: 'Sales Report',
html: '<html><body><h1>Q4 Sales Report</h1><p>Revenue: $125,000</p></body></html>',
});

// HTML with print-specific CSS
await Printer.printHtml({
name: 'Styled Invoice',
html: `
<html>
<head>
<style>

printPdf

Zeigt die Druckoberfläche zum Drucken von PDF-Dokumenten an.

Plattform-Verhalten:

• iOS: Nutzt UIPrintInteractionController mit PDF-Dateipfad
• Android: Nutzt PrintManager mit PdfDocument
• Web: Erstellt Object URL und öffnet den Druckdialog

Anforderungen an den Dateipfad:

• iOS: Muss ein file://-Pfad oder relativ zum Documents-Verzeichnis der App sein
• Android: Unterstützt content://-URIs (aus Downloads, Media Store) oder file://-Pfade
• Web: Muss ein zugreifbarer Dateipfad sein

import { Printer } from '@capgo/capacitor-printer';

// Print PDF from app storage
await Printer.printPdf({
  name: 'Annual Report 2024',
  path: 'file:///var/mobile/Containers/Data/Application/.../Documents/report.pdf',
});

// Print PDF from Android downloads
await Printer.printPdf({
  name: 'Downloaded Document',
  path: 'content://com.android.providers.downloads.documents/document/123',
});

printWebView

Zeigt das Druck-UI an, um WebView-Inhalte zu drucken.

Druckt den aktuellen Inhalt, der in der WebView deiner App angezeigt wird.

Plattform-Verhalten:

• iOS: Nutzt UIPrintInteractionController mit WKWebView’s view printable
• Android: Nutzt WebView.createPrintDocumentAdapter() mit PrintManager
• Web: Löst window.print() für die aktuelle Seite aus

Print-Styling: Unterstützt CSS Print-Media-Queries zur Anpassung. Die aktuellen Styles der Web View werden angewendet, einschließlich aller

import { Printer } from '@capgo/capacitor-printer';

// Print current web view with default name
await Printer.printWebView();

// Print with custom job name
await Printer.printWebView({
name: 'Dashboard Screenshot',
});

// Use with print-specific CSS in your HTML
// Add this to your app's CSS:
//

Typ-Referenz

PrintBase64Options

Optionen zum Drucken von base64-kodierten Daten.

export interface PrintBase64Options extends PrintOptions {
  /**
   * Valid base64 encoded string representing the file content.
   *
   * The base64 string should NOT include the data URL prefix (e.g., "data:application/pdf;base64,").
   * Only provide the raw base64 encoded content.
   *
   * **Performance Considerations:**
   * - Base64 encoding increases data size by approximately 33%
   * - Large files (>5MB) may cause memory issues when decoding
   * - Consider using printFile() for large documents
   *
   * **Platform Notes:**
   * - **iOS**: Decoded to NSData and passed to UIPrintInteractionController
   * - **Android**: Decoded to byte array and written to temporary file
   * - **Web**: Converted to Blob for printing
   *
   * @since 7.0.0
   * @example 'base64-encoded-pdf-data'
   */
  data: string;

  /**
   * MIME type of the base64 encoded data.
   *
   * **Supported types:**
   * - `application/pdf` - PDF documents
   * - `image/jpeg` - JPEG images
   * - `image/.png` - PNG images
   * - `image/.gif` - GIF images (iOS/Android only)
   * - `image/heic` - HEIC images (iOS only)
   * - `image/heif` - HEIF images (iOS only)
   *
   * **Platform Support:**
   * - All platforms support PDF, JPEG, and PNG
   * - GIF support varies by platform
   * - HEIC/HEIF are iOS-specific formats
   *
   * @since 7.0.0
   * @example 'application/pdf'
   * @example 'image/jpeg'
   */
  mimeType: string;
}

PrintFileOptions

Optionen zum Drucken von Dateien aus dem Gerätespeicher.

export interface PrintFileOptions extends PrintOptions {
  /**
   * Path to the file to print.
   *
   * **iOS Path Formats:**
   * - `file://` URL: Full file URL path
   * - Relative path: Path relative to app's documents directory
   * - Must be within app's accessible directories (documents, temporary, cache)
   *
   * **Android Path Formats:**
   * - `content://` URI: Content provider URI (recommended for external files)
   * - `file://` path: Direct file system path
   * - Must have read permission for the file
   *
   * **Common Use Cases:**
   * - App documents: Files saved in app's document directory
   * - Downloads: Files from system downloads folder (use content:// on Android)
   * - Temporary files: Files in app's temporary/cache directory
   * - Shared storage: Files from external storage (Android, requires permissions)
   *
   * @since 7.0.0
   * @platform ios Supports file:// paths and relative paths
   * @platform android Supports content:// URIs and file:// paths
   * @example 'content://com.android.providers.downloads.documents/document/123'
   * @example 'file:///var/mobile/Containers/Data/Application/.../Documents/document.pdf'
   * @example 'file:///storage/emulated/0/Download/receipt.pdf'
   */
  path: string;

  /**
   * MIME type of the file.
   *
   * **Platform Behavior:**
   * - **Android**: REQUIRED for content:// URIs. Helps the system determine how to handle the file.
   *                Optional for file:// paths (auto-detected from extension).
   * - **iOS**: Ignored. File type is auto-detected from file extension.
   * - **Web**: Optional. Auto-detected if not provided.
   *
   * **Common MIME Types:**
   * - `application/pdf` - PDF documents
   * - `image/jpeg` - JPEG images
   * - `image/.png` - PNG images
   * - `image/.gif` - GIF images
   *
   * @since 7.0.0
   * @default Undefined (auto-detected from file extension)
   * @platform android Used for content:// URIs and file type detection
   * @platform ios Ignored (auto-detected)
   * @example 'application/pdf'
   * @example 'image/jpeg'
   */
  mimeType?: string;
}

PrintHtmlOptions

Optionen zum Drucken von HTML-Inhalten.

export interface PrintHtmlOptions extends PrintOptions {
  /**
   * HTML content to print.
   *
   * **Content Requirements:**
   * - Should be a complete HTML document with `<html>`, `<head>`, and `<body>` tags
   * - Can include inline CSS styles or `<style>` tags
   * - External resources (images, fonts) should use absolute URLs
   * - JavaScript is not executed during print rendering
   *
   * **Print Optimization Tips:**
   * - Use `@media print` CSS rules for print-specific styling
   * - Control page breaks with `page-break-before`, `page-break-after`, `page-break-inside`
   * - Hide UI elements using `.no-print { display: none; }` class
   * - Adjust font sizes for readability (12pt is standard for print)
   * - Use print-friendly colors (avoid dark backgrounds)
   *
   * **Platform Rendering:**
   * - **iOS**: Rendered in WKWebView before printing
   * - **Android**: Rendered in WebView before printing
   * - **Web**: Rendered in hidden iframe before printing
   *
   * **Character Encoding:**
   * - UTF-8 is recommended and default
   * - Include charset in HTML: `<meta charset="UTF-8">`
   *
   * @since 7.0.0
   * @example '<html><body><h1>Hello World</h1><p>This is a test document.</p></body></html>'
   * @example
   * ```typescript
   * const htmlWithStyles = `
   *   <html>
   *     <head>
   *       <meta charset="UTF-8">
   *       <style>
   *         @media print {
   *           body { font-family: Arial, sans-serif; font-size: 12pt; }
   *           .no-print { display: none; }
   *           h1 { color: #333; page-break-before: always; }
   *         }
   *       </style>
   *     </head>
   *     <body>
   *       <h1>Invoice #12345</h1>
   *       <p>Amount: $299.99</p>
   *     </body>
   *   </html>
   * `;
   * ```
   */
  html: string;
}

PrintPdfOptions

Optionen zum Drucken von PDF-Dokumenten.

export interface PrintPdfOptions extends PrintOptions {
  /**
   * Path to the PDF document.
   *
   * **iOS Path Formats:**
   * - `file://` URL: Full file URL path to PDF document
   * - Relative path: Path relative to app's documents directory
   * - Must be within app's accessible directories (documents, temporary, cache)
   * - PDF must be valid and not password-protected
   *
   * **Android Path Formats:**
   * - `content://` URI: Content provider URI (recommended for external PDFs)
   * - `file://` path: Direct file system path to PDF
   * - Must have read permission for the file
   * - Supports both single-page and multi-page PDFs
   *
   * **Web Path Formats:**
   * - Relative or absolute path accessible from web context
   * - Must be a valid PDF file
   *
   * **Validation:**
   * - File must exist at the specified path
   * - File must be a valid PDF (checked by magic number/header)
   * - File must be readable by the app
   *
   * **Common Sources:**
   * - App documents: PDFs saved in app's document directory
   * - Downloads: PDFs from system downloads (use content:// on Android)
   * - Generated PDFs: Temporary PDFs created by the app
   * - Network downloads: PDFs downloaded and saved locally
   *
   * @since 7.0.0
   * @platform ios Supports file:// paths and relative paths
   * @platform android Supports content:// URIs and file:// paths
   * @platform web Supports accessible file paths
   * @example 'content://com.android.providers.downloads.documents/document/123'
   * @example 'file:///var/mobile/Containers/Data/Application/.../Documents/document.pdf'
   * @example 'file:///storage/emulated/0/Download/report.pdf'
   * @example 'Documents/invoice-2024.pdf'
   */
  path: string;
}

PrintOptions

Basis-Optionen für alle Druckvorgänge.

export interface PrintOptions {
  /**
   * Name of the print job.
   *
   * **Usage:**
   * - Displayed in the system print queue
   * - Shown in print history/logs
   * - May appear in printer status displays
   * - Used as default filename for "Save as PDF" option
   *
   * **Platform Behavior:**
   * - **iOS**: Shown in print preview header and activity view
   * - **Android**: Displayed in print job notification and print queue
   * - **Web**: Used as document title in print dialog
   *
   * **Best Practices:**
   * - Use descriptive names (e.g., "Invoice #12345", "Q4 Report")
   * - Keep under 50 characters for better display
   * - Avoid special characters that may cause issues in filenames
   * - Include relevant identifiers (order numbers, dates, etc.)
   *
   * **Examples:**
   * - "Invoice #12345"
   * - "Sales Report - 2024 Q4"
   * - "Customer Receipt - John Doe"
   * - "Product Photo - SKU-ABC123"
   *
   * @since 7.0.0
   * @default 'Document'
   * @platform ios Shown in print preview and activity view
   * @platform android Shown in print queue and notifications
   * @platform web Used as document title in print dialog
   * @example 'Invoice #12345'
   * @example 'Annual Report 2024'
   * @example 'Receipt - Order #789'
   */
  name?: string;
}

Source of Truth

Diese Seite wird aus dem Plugin- src/definitions.ts. Führe den Sync erneut aus, wenn sich der öffentliche API upstream ändert.

Weiter mit Getting Started

Wenn Sie ... verwenden Erste Schritte Um Dashboard- und API-Operationen zu planen, verbinde es mit Verwendung von @capgo/capacitor-printer für die native Funktion in Verwendung von @capgo/capacitor-printer, API Übersicht für Details zur Implementierung in der Übersicht zu API, Einführung für das Implementierungsdetail in der Einleitung, API Schlüssel für die Implementierungsdetails in den API Keys und Geräte für die Implementierungsdetails bei Devices.