시작하기
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-document-scanner`
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/document-scanner/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-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-document-scanner` plugin in my project.수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:
bun add @capgo/capacitor-document-scannerbunx cap sync가져오기
“Import” 섹션import { DocumentScanner } from '@capgo/capacitor-document-scanner';빠른 시작
“빠른 시작” 섹션import { DocumentScanner, ResponseType } from '@capgo/capacitor-document-scanner';
const result = await DocumentScanner.scanDocument({ maxNumDocuments: 1, responseType: ResponseType.ImageFilePath,});
if (result.status === 'success' && result.scannedImages?.length) { await uploadReceipt(result.scannedImages[0]);}예시: 다중 페이지 패킷
“예시: 여러 페이지 패킷” 섹션const result = await DocumentScanner.scanDocument({ maxNumDocuments: 12, letUserAdjustCrop: true, reviewCapturedDocument: true,});네이티브 스캐너를 통해 세션당 최대 24페이지까지 지원됩니다.
예시: 최적화된 Android 정리
“예시: 최적화된 Android 정리 작업” 섹션import { ScannerMode } from '@capgo/capacitor-document-scanner';
await DocumentScanner.scanDocument({ scannerMode: ScannerMode.Full, brightness: 0.1, contrast: 1.2,});scannerMode 및 ML 클린업 옵션은 Android에서만 지원됩니다. 자세한 플러그인 옵션은 scanDocument 에서 확인하세요.
자주 하는 실수
“흔한 실수” 섹션- 웹: 스캐닝은 네이티브 기능만 지원하므로, 대체 수단(파일 피커 또는 수동 사진 촬영)을 계획하세요.
- 사용자 취소:
status가능합니다cancel이미지가 없는 경우, 다른 취소 동작과 동일하게 처리하세요. - 출력 타입: 다음 중 선택하세요.
imageFilePath또는 base64를 통해responseType업로드를 구현하기 전에.
API 개요
“API 개요” 섹션scanDocument
“scanDocument” 섹션기기 카메라를 열고 문서 스캔을 시작합니다.
import { DocumentScanner } from '@capgo/capacitor-document-scanner';
const result = await DocumentScanner.scanDocument();console.log(result);타입 레퍼런스
“타입 참조” 섹션ScanDocumentOptions
“ScanDocumentOptions” 섹션export interface ScanDocumentOptions { /** * Android only: quality of the cropped image from 0 - 100 (100 is best). * @default 100 */ croppedImageQuality?: number;
/** * Allow the user to adjust the detected crop before saving. * On iOS this forces the native VisionKit preview/editor after each capture using * the private VisionKit navigation hooks needed to keep the scanner flow alive. * On Android this enables ML Kit's crop adjustment flow. * @default true */ letUserAdjustCrop?: boolean;
/** * When enabled, shows the current scanned page before continuing so the user can * review it and explicitly continue or finish the flow. * On iOS this forces the native VisionKit preview/editor between captures. * On Android this switches to a one-page-at-a-time flow between ML Kit sessions. * The review/editor screen is still shown automatically when the scan limit is reached. * @default false */ reviewCapturedDocument?: boolean;
/** * Maximum number of documents to scan. * On iOS: VisionKit caps scans at 24 pages (system limit), and the hacked native flow * can still stop earlier when you pass a smaller limit. * On Android: customizable limit; defaults to 20 for performance (clamped 1-24). * Set to 1 for single-scan mode where the scanner stops after one document. * @default 20 on Android, 24 on iOS */ maxNumDocuments?: number;
/** * Format to return scanned images in (file paths or base64 strings). * @default ResponseType.ImageFilePath */ responseType?: ResponseType;
/** * Brightness adjustment applied to scanned images. * Range: -255 to 255 (0 = no change, positive = brighter, negative = darker) * Useful for compensating low-light scans. * @default 0 */ brightness?: number;
/** * Contrast adjustment applied to scanned images. * Range: 0.0 to 10.0 (1.0 = no change, >1 = more contrast, <1 = less contrast) * Helps improve text clarity in poorly lit scans. * @default 1.0 */ contrast?: number;
/** * Android only: scanner mode that controls ML Kit features and filters. * - 'base': Basic scan with crop/rotate, no filters or ML cleaning * - 'base_with_filter': Adds grayscale and auto-enhancement filters * - 'full': All features including ML-based image cleaning (erases stains, fingers, etc.) * @default ScannerMode.Full */ scannerMode?: ScannerMode;}ScanDocumentResponse
“ScanDocumentResponse” 섹션export interface ScanDocumentResponse { /** * Scanned images in the requested response format. */ scannedImages?: string[];
/** * Indicates whether the scan completed or was cancelled. */ status?: ScanDocumentResponseStatus;
/** * Get the native Capacitor plugin version * * @returns {Promise<{ id: string }>} an Promise with version for this device * @throws An error if the something went wrong */ getPluginVersion(): Promise<{ version: string }>;}ResponseType
“ResponseType” 섹션export enum ResponseType { /** * Return scanned images as base64-encoded strings. */ Base64 = 'base64',
/** * Return scanned images as file paths on disk. */ ImageFilePath = 'imageFilePath',}ScannerMode
“ScannerMode” 섹션export enum ScannerMode { /** * Basic document scanning with crop and rotate features only. * No filters or ML-based enhancements. */ Base = 'base',
/** * Basic features plus automatic filters (grayscale, auto-enhancement). */ BaseWithFilter = 'base_with_filter',
/** * Full feature set including ML-based image cleaning. * Automatically removes stains, fingers, and other artifacts. */ Full = 'full',}ScanDocumentResponseStatus
“ScanDocumentResponseStatus” 섹션export enum ScanDocumentResponseStatus { /** * The scan completed successfully. */ Success = 'success',
/** * The user cancelled the scan flow. */ Cancel = 'cancel',}Source of Truth
“Source Of Truth” 섹션이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.
시작하기 다음 단계
“Getting Started에서 계속하기” 섹션사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-document-scanner 사용하기 @capgo/capacitor-document-scanner를 사용하여 Native Build 기능을 구현하려면, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.