Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

bun add @capgo/capacitor-printer
bunx cap sync

Importar

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

Inicio rápido

Imprime un PDF que ya esté en el disco (recomendado para archivos grandes).

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

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

Ejemplo: recibo en HTML

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

Ejemplo: evita payloads base64 enormes

printBase64 decodifica archivos completos en memoria. Para assets de más de 5 MB, escribe en un archivo temporal y llama printFile en su lugar.

Errores comunes

• Memoria: las cadenas base64 muy grandes pueden bloquear la app en dispositivos con poca RAM.
• Web: la impresión usa el diálogo del navegador; el diseño varía respecto a los controladores nativos.
• Rutas: en Android, pasa un objeto accesible file:// URI, ruta absoluta del sistema de archivos o content:// URI. Las rutas relativas a la app no se resuelven automáticamente.

Resumen de API

printBase64

Muestra la interfaz de impresión para imprimir archivos codificados como cadenas base64.

Comportamiento por plataforma:

• iOS: Usa UIPrintInteractionController con datos decodificados en base64
• Android: Usa PrintManager con datos decodificados en base64
• Web: Crea un blob desde datos base64 y abre el diálogo de impresión

Advertencia de rendimiento: Los archivos grandes pueden causar cierres de la app por falta de memoria al decodificar base64. Para archivos de más de 5MB, se recomienda usar printFile().

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

Presents the printing UI to print device files.

Comportamiento por plataforma:

• iOS: Usa UIPrintInteractionController con una URL de archivo. Admite rutas file:// o rutas relativas al directorio de documentos de la app.
• Android: Usa PrintManager con la ruta del archivo. Admite tanto URIs content:// como rutas file://.
• Web: Lee el archivo y abre el diálogo de impresión

Tipos de archivo compatibles:

• Documentos PDF (application/pdf)
• Imágenes: 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

Muestra la interfaz de impresión para imprimir documentos HTML.

Comportamiento por plataforma:

• iOS: Renderiza HTML en WKWebView y luego imprime con UIPrintInteractionController
• Android: Renderiza HTML en WebView y luego imprime con PrintManager
• Web: Crea un iframe con contenido HTML y activa el diálogo de impresión

Requisitos de HTML:

• Debe ser un documento HTML completo con estructura correcta
• Puede incluir estilos CSS inline o etiquetas style
• Los recursos externos (imágenes, hojas de estilo) deben usar URLs absolutas
• Se puede añadir CSS específico para impresión usando

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

- Muestra la interfaz de impresión para imprimir documentos PDF.

Comportamiento por plataforma:

• iOS: Usa UIPrintInteractionController con la URL del archivo PDF
• Android: Usa PrintManager con PdfDocument
• WebCrea una URL de objeto y abre el diálogo de impresión

Requisitos de la ruta del archivo:

• iOSDebe ser una ruta file:// o relativa al directorio de documentos de la app
• Android: Soporta URIs content:// (de descargas, media store) o rutas file://
• Web: Debe ser una ruta de archivo accesible

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

Muestra la interfaz de impresión para imprimir contenido de la WebView.

Imprime el contenido actual mostrado en la web view de tu app.

Comportamiento por plataforma:

• iOS: Usa UIPrintInteractionController con la vista imprimible de WKWebView
• Android: Usa WebView.createPrintDocumentAdapter() con PrintManager
• Web: Ejecuta window.print() para la página actual

Estilos de impresión: Soporta CSS print media queries para personalización. Se aplicarán los estilos actuales de la web view, incluyendo cualquier

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

Referencia de tipos

PrintBase64Options

Opciones para imprimir datos codificados en 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

Options for printing files from device storage.

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

Opciones para imprimir contenido 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

Opciones para imprimir documentos 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

Opciones base para todas las operaciones de impresión.

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

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar las operaciones del dashboard y de API, conéctalo con Usando @capgo/capacitor-printer para la capacidad nativa al usar @capgo/capacitor-printer, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para los detalles de implementación en las claves de API, y Dispositivos para el detalle de implementación en Devices.