Primeros pasos
Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este 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.
Instalar
Sección titulada “Instalación”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-pluginsLuego 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-printerbunx cap syncImportar
Sección titulada “Importar”import { Printer } from '@capgo/capacitor-printer';Inicio rápido
Sección titulada “Inicio rápido”Imprime un PDF que ya está en disco (preferido para archivos grandes).
import { Printer } from '@capgo/capacitor-printer';
await Printer.printFile({ path: 'file:///data/user/0/.../invoice.pdf', name: 'Invoice #1042',});Ejemplo: recibo HTML
Sección titulada “Ejemplo: recibo HTML”await Printer.printHtml({ html: '<h1>Thank you</h1><p>Total: $42.00</p>', name: 'Receipt',});Ejemplo: evita payloads base64 enormes
Sección titulada “Ejemplo: evitar payloads base64 enormes”printBase64 decodifica archivos completos en memoria. Para assets de más de 5 MB, escribe en un archivo temporal y llama a printFile en su lugar.
Errores comunes
Sección titulada “Errores comunes”- Memoria: large base64 strings can crash the app on low RAM devices.
- Web: la impresión usa el diálogo del navegador; el diseño difiere de los controladores de impresión nativos.
- Rutas: on Android, pass an accessible
file://URI, ruta absoluta del sistema de archivos ocontent://URI. Las rutas relativas a la app no se resuelven automáticamente.
Resumen de API
Sección titulada “Resumen de API”printBase64
Sección titulada “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 a partir de datos base64 y abre el diálogo de impresión
Advertencia de rendimiento: Los archivos grandes pueden provocar el cierre de la app por limitaciones de memoria al decodificar base64. Para archivos mayores de 5 MB, se recomienda usar printFile() en su lugar.
import { Printer } from '@capgo/capacitor-printer';
// Print a base64 encoded PDFawait Printer.printBase64({ name: 'Invoice #12345', data: 'base64-encoded-pdf-data', mimeType: 'application/pdf',});
// Print a base64 encoded imageawait Printer.printBase64({ name: 'Product Photo', data: '/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDA...', mimeType: 'image/jpeg',});printFile
Sección titulada “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 directoryawait Printer.printFile({ name: 'Contract', path: 'file:///var/mobile/Containers/Data/Application/.../Documents/contract.pdf',});
// Android: Print from content URIawait Printer.printFile({ name: 'Receipt', path: 'content://com.android.providers.downloads.documents/document/123', mimeType: 'application/pdf',});
// Android: Print from file pathawait Printer.printFile({ name: 'Photo', path: 'file:///storage/emulated/0/Download/photo.jpg', mimeType: 'image/jpeg',});printHtml
Sección titulada “printHtml”Muestra la interfaz de impresión para imprimir documentos HTML.
Comportamiento por plataforma:
- iOS: Renderiza HTML en WKWebView y luego imprime usando UIPrintInteractionController
- Android: Renderiza HTML en WebView y luego imprime usando PrintManager
- Web: Crea un iframe con contenido HTML y abre el diálogo de impresión
Requisitos de HTML:
- Debe ser un documento HTML completo con una estructura adecuada
- Puede incluir estilos CSS en línea o etiquetas de estilo
- Los recursos externos (imágenes, hojas de estilo) deben usar URLs absolutas
- Se puede agregar CSS específico para impresión usando
import { Printer } from '@capgo/capacitor-printer';
// Simple HTML documentawait Printer.printHtml({name: 'Sales Report',html: '<html><body><h1>Q4 Sales Report</h1><p>Revenue: $125,000</p></body></html>',});
// HTML with print-specific CSSawait Printer.printHtml({name: 'Styled Invoice',html: `<html><head><style>printPdf
Sección titulada “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
- Web: Crea una object URL y abre el diálogo de impresión
Requisitos de la ruta del archivo:
- iOS: Debe ser una ruta file:// o relativa al directorio de documentos de la app
- Android: Admite URIs content:// (de descargas, galería de medios) o rutas file://
- Web: Debe ser una ruta de archivo accesible
import { Printer } from '@capgo/capacitor-printer';
// Print PDF from app storageawait Printer.printPdf({ name: 'Annual Report 2024', path: 'file:///var/mobile/Containers/Data/Application/.../Documents/report.pdf',});
// Print PDF from Android downloadsawait Printer.printPdf({ name: 'Downloaded Document', path: 'content://com.android.providers.downloads.documents/document/123',});printWebView
Sección titulada “printWebView”Muestra la interfaz de impresión para imprimir contenido de la WebView.
Imprime el contenido actual mostrado en el web view de tu app.
Comportamiento por plataforma:
- iOS: Usa UIPrintInteractionController con la vista imprimible de WKWebView
- Android: Usa WebView.createPrintDocumentAdapter() con PrintManager
- Web: Dispara window.print() para la página actual
Estilos de impresión: Admite consultas de medios de impresión CSS para personalización. Se aplicarán los estilos actuales de la web view, incluidos los
import { Printer } from '@capgo/capacitor-printer';
// Print current web view with default nameawait Printer.printWebView();
// Print with custom job nameawait Printer.printWebView({name: 'Dashboard Screenshot',});
// Use with print-specific CSS in your HTML// Add this to your app's CSS://Referencia de tipos
Sección titulada “Referencia de tipos”PrintBase64Options
Sección titulada “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
Sección titulada “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
Sección titulada “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;}Invoice #12345
*Amount: $299.99
* *