시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-printer
bunx cap sync

가져오기

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

빠른 시작

디스크에 이미 저장된 PDF를 출력하세요 (대용량 파일에 권장).

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

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

예시: HTML 영수증

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

예시: 거대한 base64 페이로드 피하기

printBase64 파일 전체를 메모리에서 디코딩합니다. 약 5 MB 이상의 에셋은 임시 파일로 저장한 뒤 호출하세요. printFile 대신 사용하세요.

자주 하는 실수

• 메모리: 대용량 base64 문자열은 RAM이 부족한 기기에서 앱을 충돌시킬 수 있습니다.
• 웹: 인쇄는 브라우저 다이얼로그를 사용하므로 레이아웃이 네이티브 인쇄 컨트롤러와 다릅니다.
• 경로: Android에서는 접근 가능한 file:// URI, 절대 파일 시스템 경로 또는 content:// URI를 전달해야 합니다. 앱 상대 경로는 자동으로 해석되지 않습니다.

API 개요

printBase64

base64 문자열로 인코딩된 파일을 인쇄하기 위한 인쇄 UI를 제공합니다.

플랫폼별 동작:

• iOS: base64 디코딩된 데이터를 UIPrintInteractionController로 사용
• Android: base64 디코딩된 데이터를 PrintManager로 사용
• 웹: base64 데이터로 blob을 생성하고 인쇄 대화 상자를 엽니다

성능 주의 사항: base64 디코딩 시 메모리 제한으로 인해 대용량 파일은 앱이 크래시될 수 있습니다. 5MB를 초과하는 파일은 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

기기 내 파일을 인쇄하기 위한 인쇄 UI를 표시합니다.

플랫폼별 동작:

• iOS: file URL을 사용하는 UIPrintInteractionController를 활용합니다. file:// 경로 또는 앱의 documents 디렉토리 상대 경로를 지원합니다.
• Android: file path를 사용하는 PrintManager를 활용합니다. content:// URI와 file:// 경로를 모두 지원합니다.
• 웹: 파일을 읽고 인쇄 대화 상자를 엽니다.

지원되는 파일 형식:

• PDF 문서 (application/pdf)
• 이미지: 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

HTML 문서를 인쇄하기 위한 인쇄 UI를 제공합니다.

플랫폼별 동작:

• iOS: WKWebView에서 HTML을 렌더링한 후 UIPrintInteractionController를 사용하여 출력합니다.
• Android: WebView에서 HTML을 렌더링한 후 PrintManager를 사용하여 출력합니다.
• 웹: HTML 콘텐츠가 포함된 iframe을 생성하고 인쇄 대화 상자를 호출합니다.

HTML 요구 사항:

• 올바른 구조를 갖춘 완전한 HTML 문서여야 합니다.
• 인라인 CSS 스타일 또는 style 태그를 포함할 수 있습니다.
• 외부 리소스(이미지, 스타일시트)는 절대 경로 URL을 사용해야 합니다.
• 인쇄 전용 CSS는 다음을 사용하여 추가할 수 있습니다.

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

PDF 문서를 출력하기 위한 인쇄 UI를 제공합니다.

플랫폼별 동작:

• iOS: PDF 파일 URL과 함께 UIPrintInteractionController를 사용합니다.
• Android: PdfDocument와 함께 PrintManager를 사용합니다.
• 웹: object URL을 생성하고 인쇄 대화 상자를 엽니다.

파일 경로 요구 사항:

• iOS: file:// 경로이거나 앱의 documents 디렉토리 기준 상대 경로여야 합니다
• Android: content:// URI(다운로드, 미디어 스토어) 또는 file:// 경로를 지원합니다
• 웹: 접근 가능한 파일 경로여야 합니다

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

웹 뷰 콘텐츠를 인쇄하기 위한 인쇄 UI를 표시합니다.

앱의 웹 뷰에 표시된 현재 콘텐츠를 인쇄합니다.

플랫폼별 동작:

• iOS: WKWebView의 인쇄 가능한 뷰와 함께 UIPrintInteractionController를 사용합니다
• Android: PrintManager와 WebView.createPrintDocumentAdapter()를 사용합니다.
• 웹: 현재 페이지에 대해 window.print()를 실행합니다.

인쇄 스타일링: 커스텀을 위해 CSS print 미디어 쿼리를 지원합니다. 웹 뷰의 현재 스타일이 적용되며, 다음 항목도 포함됩니다.

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

타입 레퍼런스

PrintBase64Options

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

기기 저장소의 파일을 인쇄하기 위한 옵션입니다.

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

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

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

모든 인쇄 작업에 적용되는 기본 옵션입니다.

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

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-printer 사용하기 @capgo/capacitor-printer를 사용하여 Native Build 기능을 구현하려면, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.