スタートガイド
インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。
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.
インストール
「インストール」セクションAIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いの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-printerbunx 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レシート
「例:HTMLレシート」というセクションawait Printer.printHtml({ html: '<h1>Thank you</h1><p>Total: $42.00</p>', name: 'Receipt',});例:巨大なbase64ペイロードを避ける
「例:巨大なbase64ペイロードを避ける」というセクションprintBase64 ファイル全体をメモリ内でデコードします。約5 MBを超えるアセットの場合は、一時ファイルに書き込んでから呼び出してください printFile こちらを読んでください。
よくある落とし穴
「よくある落とし穴」セクション- メモリ:大規模な base64 文字列は、低 RAM デバイスでアプリをクラッシュさせる可能性があります。
- Web:印刷にはブラウザのダイアログを使用するため、ネイティブの印刷コントローラーとはレイアウトが異なります。
- パス:Android では、アクセス可能な
file://URI、絶対ファイルシステムパス、またはcontent://URI を渡してください。アプリ相対パスは自動的に解決されません。
API の概要
「API 概要」セクションprintBase64
「printBase64」セクションbase64 文字列としてエンコードされたファイルを印刷するための印刷 UI を表示します。
プラットフォーム別の動作:
- iOSと: base64デコード済みデータをUIPrintInteractionControllerで使用します
- Androidでは: base64デコード済みデータをPrintManagerで使用します
- Web: base64データからblobを作成し、印刷ダイアログを開きます
パフォーマンス警告: base64のデコード時はメモリ制約により、大きなファイルでアプリがクラッシュする可能性があります。 5MBを超えるファイルでは、代わりにprintFile()の使用を推奨します。
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
「printFile」セクションデバイス内のファイルを印刷するための印刷UIを表示します。
プラットフォーム別の動作:
- iOSと: file URL を使用して UIPrintInteractionController を呼び出します。file:// パスまたはアプリのドキュメントディレクトリからの相対パスをサポートします。
- Androidでは: file path を使用して PrintManager を呼び出します。content:// URI と file:// パスの両方をサポートします。
- Web: ファイルを読み取り、印刷ダイアログを開きます
サポートされるファイル形式:
- PDF ドキュメント (application/pdf)
- 画像: 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
「printHtml」セクションHTMLドキュメントを印刷するための印刷UIを表示します。
プラットフォーム別の動作:
- iOSとWKWebViewでHTMLをレンダリングし、UIPrintInteractionControllerを使用して印刷します
- AndroidではWebViewでHTMLをレンダリングし、PrintManagerを使用して印刷します
- WebHTMLコンテンツを含むiframeを作成し、印刷ダイアログをトリガーします
HTML要件:
- 適切な構造を持つ完全なHTMLドキュメントである必要があります
- インラインCSSスタイルやstyleタグを含めることができます
- 外部リソース(画像、スタイルシート)には絶対URLを使用してください
- 印刷専用のCSSは以下を使用して追加できます
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
セクション「printPdf」PDFドキュメントを印刷するための印刷UIを表示します。
プラットフォーム別の動作:
- iOSと: PDFファイルのURLでUIPrintInteractionControllerを使用
- Androidでは: PdfDocumentでPrintManagerを使用
- Web: オブジェクトURLを作成して印刷ダイアログを開く
ファイルパスの要件:
- iOSと: file:// パス、またはアプリの Documents ディレクトリからの相対パスである必要があります
- Androidでは: content:// URI(ダウンロードやメディアストアから)または file:// パスをサポートしています
- Web: アクセス可能なファイルパスである必要があります
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
セクション「printWebView」WebView のコンテンツを印刷する UI を表示します。
アプリの WebView に表示されている現在のコンテンツを印刷します。
プラットフォーム別の動作:
- iOSと: UIPrintInteractionController と WKWebView の view printable を使用します
- Androidでは: WebView.createPrintDocumentAdapter() と PrintManager を使用します
- Web: 現在のページで window.print() をトリガーします
印刷スタイル: カスタマイズのために CSS の印刷メディアクエリをサポートします。Webビューの現在のスタイル(...を含む)が適用されます。
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://型リファレンス
「型リファレンス」セクションPrintBase64Options
「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
「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
「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;}Invoice #12345
*Amount: $299.99
* *