시작하기

설치

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

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

그다음 아래 prompt를 사용하세요:

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

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

bun add @capgo/capacitor-document-scanner
bunx cap sync

가져오기

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 정리 튜닝

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 개요

scanDocument

기기 카메라를 실행하여 문서 스캔 프로세스를 시작합니다.

import { DocumentScanner } from '@capgo/capacitor-document-scanner';

const result = await DocumentScanner.scanDocument();
console.log(result);

타입 참조

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

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

export enum ResponseType {
  /**
   * Return scanned images as base64-encoded strings.
   */
  Base64 = 'base64',

  /**
   * Return scanned images as file paths on disk.
   */
  ImageFilePath = 'imageFilePath',
}

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

export enum ScanDocumentResponseStatus {
  /**
   * The scan completed successfully.
   */
  Success = 'success',

  /**
   * The user cancelled the scan flow.
   */
  Cancel = 'cancel',
}

기준 소스

이 페이지는 플러그인의 src/definitions.ts에서 생성되었습니다. public API가 업스트림에서 변경되면 동기화를 다시 실행하세요.

Getting Started에서 계속하기

사용 중인 경우 시작하기 대시보드와 API 운영을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-document-scanner 사용하기 @capgo/capacitor-document-scanner 사용하기의 네이티브 기능을 위해, API 개요 API Overview의 구현 상세 내용은 소개 Introduction의 구현 상세 내용은 API 키 API Keys의 구현 세부 사항은, 디바이스 Devices의 구현 세부 사항은.