Iniziare

Copiare un prompt di impostazione con i passaggi di installazione e la guida markdown completa per questo plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-printer`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/printer/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Installare

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo abilità al tuo strumento AI utilizzando il seguente comando:

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

Usa poi il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche del tuo platform qui sotto:

bun add @capgo/capacitor-printer
bunx cap sync

Importa

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

Panoramica di API

`printBase64`

Presenta l'interfaccia di stampa per stampare file codificati come stringhe base64.

Comportamento della piattaforma:

iOS: Utilizza UIPrintInteractionController con dati base64 decodificati
Android: Utilizza PrintManager con dati base64 decodificati
Web: Crea un blob dai dati base64 e apre la finestra di dialogo di stampa

Avvertenza sulle prestazioni: Il caricamento di file grandi può portare a crash del'applicazione a causa delle limitazioni di memoria durante la decodifica base64. Per file più grandi di 5MB, si consiglia di utilizzare stampaFile() al posto di questa funzione.

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`

Presenta l'interfaccia di stampa per stampare i file del dispositivo.

Comportamento della piattaforma:

iOS: Utilizza UIPrintInteractionController con l'URL del file. Supporta percorsi file:// o percorsi relativi alla cartella dei documenti dell'app.
Android: Utilizza PrintManager con il percorso del file. Supporta sia URIs content:// che percorsi file://.
Web: Legge il file e apre il dialogo di stampa

Tipi di file supportati:

Documenti PDF (application/pdf)
Immagini: 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`

Visualizza l'interfaccia di stampa per stampare documenti HTML.

Comportamento della piattaforma:

iOSRende l'HTML in WKWebView, poi stampa utilizzando UIPrintInteractionController
AndroidRende l'HTML in WebView, poi stampa utilizzando PrintManager
WebCreati un iframe con contenuto HTML e attiva il dialogo di stampa

Requisiti per l'HTML:

Deve essere un documento HTML completo con struttura corretta
Può includere stili CSS inline o tag di stile
Le risorse esterne (immagini, fogli di stile) dovrebbero utilizzare URL assoluti
Si possono aggiungere CSS specifici per la stampa utilizzando

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`

Presenta l'interfaccia di stampa per stampare documenti PDF.

Comportamento della piattaforma:

iOS: Utilizza UIPrintInteractionController con URL del file PDF
Android: Utilizza PrintManager con PdfDocument
WebCrea un URL di oggetto e apre il dialogo di stampa

Requisiti del percorso del file:

iOSDeve essere un percorso file:// o relativo alla directory dei documenti dell'app
AndroidSupporta le URI di contenuto (da download, archivio dei media) o percorsi file://
WebDeve essere un percorso di file accessibile

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`

Presenta l'interfaccia di stampa per stampare il contenuto della vista web.

Stampa il contenuto attualmente visualizzato nella tua app di visualizzazione web.

Comportamento della piattaforma:

iOS: Utilizza UIPrintInteractionController con la vista di WKWebView stampabile
Android: Utilizza WebView.createPrintDocumentAdapter() con PrintManager
Web: Attiva window.print() per la pagina corrente

Stili di stampa: Sostiene le query di media stampa CSS per la personalizzazione. Le stili attuali della vista web verranno applicati, compresi qualsiasi

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:
//

Riferimento di tipo

`PrintBase64Options`

Opzioni per la stampa dei dati codificati in base64.

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`

Opzioni per la stampa dei file dallo storage del dispositivo.

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`

Opzioni per la stampa del contenuto HTML.

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`

Opzioni per la stampa dei documenti PDF.

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`

Opzioni base per tutte le operazioni di stampa.

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;
}

Fonte di verità

Questa pagina è generata dal plugin. src/definitions.ts. Riavvia la sincronizzazione quando le pubbliche API cambiano upstream.

Continua da Inizia a utilizzare

Se stai utilizzando Inizia a utilizzare per pianificare il dashboard e le API operazioni, connettilo con Utilizza @capgo/capacitor-stampa per la capacità nativa in Utilizza @capgo/capacitor-stampa API Panoramica per la dettagliata implementazione in API Panoramica Introduzione per la dettagliata implementazione in Introduzione API Chiavi per la dettagliata implementazione in API Chiavi, e Dispositivi per la dettagliata implementazione in Dispositivi.