Inizia

Installa

bun add @capgo/camera-preview
bunx cap sync

Importa

import { CameraPreview } from '@capgo/camera-preview';

API Panoramica

start

Avvia la preview della camera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.start({} as CameraPreviewOptions);

stop

Ferma la preview della camera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.stop();

capture

Cattura una foto dalla fotocamera.

Se storeToFile era stato impostato true al momento di avviare la preview, il valore restituito value sarà una percorso di file assoluto sul dispositivo al posto di una stringa base64. Utilizza getBase64FromFilePath per ottenere la stringa base64 dal percorso di file.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.capture({} as CameraPreviewPictureOptions);

captureSample

Cattura un singolo frame dal flusso di anteprima della fotocamera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.captureSample({} as CameraSampleOptions);

getSupportedFlashModes

Ottiene i modi flash supportati dalla fotocamera attiva.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getSupportedFlashModes();

setAspectRatio

Imposta il rapporto di aspetto della anteprima della camera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setAspectRatio({} as { aspectRatio: '4:3' | '16:9'; x?: number; y?: number });

getAspectRatio

Ottiene l'attuale rapporto di aspetto della anteprima della camera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getAspectRatio();

setGridMode

Imposta il modo della griglia della anteprima della camera sovrapposta.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setGridMode({} as { gridMode: GridMode });

getGridMode

Ottiene l'attuale modo della griglia della anteprima della camera sovrapposta.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getGridMode();

checkPermissions

Verifica lo stato di autorizzazione attuale della camera (e della microfono facoltativa) senza sollecitare il dialogo del sistema.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.checkPermissions();

requestPermissions

Richiede le autorizzazioni per la camera (e per il microfono facoltativo). Se le autorizzazioni sono già state concesse o negate, lo stato attuale viene restituito senza sollecitare il sistema. Quando showSettingsAlert è vero e le autorizzazioni sono negate, asulta un avviso specifico per piattaforma che guida l'utente verso le impostazioni dell'applicazione.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.requestPermissions();

getHorizontalFov

Ottiene il campo orizzontale di visione per la camera attiva. Nota: Questo può essere un'ipotesi su alcuni dispositivi.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getHorizontalFov();

getSupportedPictureSizes

Ottiene le dimensioni delle immagini supportate per tutte le fotocamere.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getSupportedPictureSizes();

setFlashMode

Imposta il modo flash per la fotocamera attiva.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setFlashMode({} as { flashMode: CameraPreviewFlashMode | string });

flip

Alternare tra le fotocamere anteriore e posteriore.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.flip();

setOpacity

Imposta la trasparenza della anteprima della fotocamera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setOpacity({} as CameraOpacityOptions);

stopRecordVideo

Interrompe la registrazione video in corso.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.stopRecordVideo();

startRecordVideo

Inizia a registrare un video.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

isRunning

Controlla se la preview della camera è attualmente in esecuzione.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.isRunning();

getAvailableDevices

Ottiene tutti i dispositivi di camera disponibili.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getAvailableDevices();

getZoom

Ottiene lo stato di ingrandimento corrente, compreso minimo/maximo e informazioni sulla lente.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getZoom();

getZoomButtonValues

Restituisce i valori dei pulsanti di ingrandimento per la rapida selezione.

• iOS/Android: include 0,5 se disponibile ultra-larghezza; 1 e 2 se disponibile larghezza; 3 se disponibile teleobiettivo
• Web: non supportato

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getZoomButtonValues();

setZoom

Imposta il livello di ingrandimento della camera.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setZoom({} as { level: number; ramp?: boolean; autoFocus?: boolean });

getFlashMode

Ottiene il modo flash corrente.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getFlashMode();

setDeviceId

Sostituisce la camera attiva con quella specificata con l'ID deviceId.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setDeviceId({} as { deviceId: string });

getDeviceId

Ottiene l'ID del dispositivo di camera attualmente associato. Su Android, se una richiesta di lente fisica si trasforma in una lente logica, questo restituisce l'ID della lente logica associata.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getDeviceId();

getPreviewSize

Ottiene la dimensione e la posizione della anteprima attuale.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getPreviewSize();

setPreviewSize

Imposta la dimensione e la posizione della anteprima.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setPreviewSize({} as { x?: number; y?: number; width: number; height: number });

setFocus

Imposta il focus della camera su un punto specifico nella anteprima.

Nota: Il plugin non attacca alcun gestore di tocco nativo per la messa a fuoco. Gestisci i tocchi nel tuo HTML/JS (ad esempio, sull'interfaccia utente sovrapposta), poi passa le coordinate normalizzate qui.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setFocus({} as { x: number; y: number });

deleteFile

Elimina un file in un percorso assoluto sul dispositivo.\nUsa questo per pulire velocemente immagini temporanee create con storeToFile.\nIn rete, questo non è supportato e lancerà un errore.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.deleteFile({} as { path: string });

getSafeAreaInsets

Ottiene gli insetti di area sicura per i dispositivi. Restituisce l'insetto di orientamento consapevole della notch/camera e l'orientamento corrente. In modalità ritratto: restituisce l'insetto superiore (notch in alto). In modalità orizzontale: restituisce l'insetto sinistro (notch spostato sul lato). Ciò si concentra sull'area del foro (notch, foro, ecc.) che tutti i telefoni moderni hanno.

Android: Valori restituiti in dp (pixel logici). iOS: Valori restituiti in pixel fisici, escludendo la barra dello stato (solo dimensioni di notch/cutout pura).

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getSafeAreaInsets();

getOrientation

Ottenere l'orientamento attuale del dispositivo in un formato cross-platform.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getOrientation();

getExposureModes

Restituisce i modi di esposizione supportati dalla camera attiva. I modi possono includere: ‘bloccato’, ‘auto’, ‘continuo’, ‘personalizzato’.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getExposureModes();

getExposureMode

Restituisce il modo di esposizione corrente.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getExposureMode();

setExposureMode

Imposta il modo di esposizione.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setExposureMode({} as { mode: ExposureMode });

getExposureCompensationRange

Restituisce il range di compensazione di esposizione (EV bias) supportato.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getExposureCompensationRange();

getExposureCompensation

Restituisce la compensazione di esposizione corrente (EV bias).

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.getExposureCompensation();

setExposureCompensation

Imposta la compensazione di esposizione (EV bias). Il valore verrà limitato al range.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.setExposureCompensation({} as { value: number });

Sezione intitolata “Riferimento di tipo”

CameraPreviewOptions

Definisce le opzioni di configurazione per l'avvio dell'anteprima della camera.

export interface CameraPreviewOptions {
  /**
   * The parent element to attach the video preview to.
   * @platform web
   */
  parent?: string;
  /**
   * A CSS class name to add to the preview element.
   * @platform web
   */
  className?: string;
  /**
   * The width of the preview in pixels. Defaults to the screen width.
   * @platform android, ios, web
   */
  width?: number;
  /**
   * The height of the preview in pixels. Defaults to the screen height.
   * @platform android, ios, web
   */
  height?: number;
  /**
   * The horizontal origin of the preview, in pixels.
   * @platform android, ios
   */
  x?: number;
  /**
   * The vertical origin of the preview, in pixels.
   * @platform android, ios
   */
  y?: number;
  /**
   * The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.
   * Cannot be set if width or height is provided, otherwise the call will be rejected.
   * Use setPreviewSize to adjust size after starting.
   *
   * @since 2.0.0
   */
  aspectRatio?: '4:3' | '16:9';
  /**
   * Controls how the camera preview fills the available space.
   * - 'contain': Fits the entire preview within the space, may show letterboxing (default).
   * - 'cover': Fills the entire space, may crop edges of the preview.
   * @default "contain"
   * @platform android, ios, web
   */
  aspectMode?: 'cover' | 'contain';
  /**
   * The grid overlay to display on the camera preview.
   * @default "none"
   * @since 2.1.0
   */
  gridMode?: GridMode;
  /**
   * Adjusts the y-position to account for safe areas (e.g., notches).
   * @platform ios
   * @default false
   */
  includeSafeAreaInsets?: boolean;
  /**
   * If true, places the preview behind the webview.
   * @platform android
   * @default true
   */
  toBack?: boolean;
  /**
   * Bottom padding for the preview, in pixels.
   * @platform android, ios
   */
  paddingBottom?: number;
  /**
   * Whether to rotate the preview when the device orientation changes.
   * @platform ios
   * @default true
   */
  rotateWhenOrientationChanged?: boolean;
  /**
   * The camera to use.
   * @default "rear"
   */
  position?: CameraPosition | string;
  /**
   * If true, saves the captured image to a file and returns the file path.
   * If false, returns a base64 encoded string.
   * @default false
   */
  storeToFile?: boolean;
  /**
   * If true, prevents the plugin from rotating the image based on EXIF data.
   * @platform android
   * @default false
   */
  disableExifHeaderStripping?: boolean;
  /**
   * If true, disables the audio stream, preventing audio permission requests.
   * @default true
   */
  disableAudio?: boolean;
  /**
   * If true, locks the device orientation while the camera is active.
   * @platform android
   * @default false
   */
  lockAndroidOrientation?: boolean;
  /**
   * If true, allows the camera preview's opacity to be changed.
   * @platform android, web
   * @default false
   */
  enableOpacity?: boolean;

  /**
   * If true, disables the visual focus indicator when tapping to focus.
   * @platform android, ios
   * @default false
   */
  disableFocusIndicator?: boolean;
  /**
   * The `deviceId` of the camera to use. If provided, `position` is ignored.
   * @platform ios
   */
  deviceId?: string;
  /**
   * On Android, attempts to bind a physical camera directly when `deviceId` refers to a physical lens.
   * Disabled by default because OEM support is inconsistent; when false, Android keeps the current logical-camera fallback behavior.
   * @default false
   * @platform android
   */
  enablePhysicalDeviceSelection?: boolean;
  /**
   * The initial zoom level when starting the camera preview.
   * If the requested zoom level is not available, the native plugin will reject.
   * @default 1.0
   * @platform android, ios
   * @since 2.2.0
   */
  initialZoomLevel?: number;
  /**
   * The vertical positioning of the camera preview.
   * @default "center"
   * @platform android, ios, web
   * @since 2.3.0
   */
  positioning?: CameraPositioning;
  /**
   * If true, enables video capture capabilities when the camera starts.
   * @default false
   * @platform android
   * @since 7.11.0
   */
  enableVideoMode?: boolean;
  /**
   * If true, forces the camera to start/restart even if it's already running or busy.
   * This will kill the current camera session and start a new one, ignoring all state checks.
   * @default false
   * @platform android, ios, web
   */
  force?: boolean;
  /**
   * Sets the quality of video for recording.
   * Options: 'low', 'medium', 'high'
   * @note On Android requires 'enableVideoMode' to be true
   * @note Will affect the entire preview stream for iOS
   * @platform ios, android
   * @default "high"
   */
  videoQuality?: 'low' | 'medium' | 'high';
}

CameraPreviewPictureOptions

Definisce le opzioni per la captura di una foto.

export interface CameraPreviewPictureOptions {
  /**
   * The maximum height of the picture in pixels. The image will be resized to fit within this height while maintaining aspect ratio.
   * If not specified the captured image will match the preview's visible area.
   */
  height?: number;
  /**
   * The maximum width of the picture in pixels. The image will be resized to fit within this width while maintaining aspect ratio.
   * If not specified the captured image will match the preview's visible area.
   */
  width?: number;
  /**
   * The quality of the captured image, from 0 to 100.
   * Does not apply to `.png` format.
   * @default 85
   */
  quality?: number;
  /**
   * The format of the captured image.
   * @default "jpeg"
   */
  format?: PictureFormat;
  /**
   * If true, the captured image will be saved to the user's gallery.
   * @default false
   * @since 7.5.0
   */
  saveToGallery?: boolean;
  /**
   * If true, the plugin will attempt to add GPS location data to the image's EXIF metadata.
   * This may prompt the user for location permissions.
   * @default false
   * @since 7.6.0
   */
  withExifLocation?: boolean;
  /**
   * If true, the plugin will embed a timestamp in the top-right corner of the image.
   * @default false
   * @since 7.17.0
   */
  embedTimestamp?: boolean;
  /**
   * If true, the plugin will embed the current location in the top-right corner of the image.
   * Requires `withExifLocation` to be enabled.
   * @default false
   * @since 7.18.0
   */
  embedLocation?: boolean;
  /**
   * Sets the priority for photo quality vs. capture speed.
   * - "speed": Prioritizes faster capture times, may reduce image quality.
   * - "balanced": Aims for a balance between quality and speed.
   * - "quality": Prioritizes image quality, may reduce capture speed.
   * See https://developer.apple.com/documentation/avfoundation/avcapturephotosettings/photoqualityprioritization for details.
   *
   * @since 7.21.0
   * @platform ios
   * @default "speed"
   */
  photoQualityPrioritization?: 'speed' | 'balanced' | 'quality';
}

ExifData

Rappresenta i dati EXIF estratti dall'immagine.

export interface ExifData {
  [key: string]: any;
}

CameraSampleOptions

Definisce le opzioni per la captura di un frame di anteprima dalla camera.

export interface CameraSampleOptions {
  /**
   * The quality of the captured sample, from 0 to 100.
   * @default 85
   */
  quality?: number;
}

CameraPreviewFlashMode

Le modalità flash disponibili per la fotocamera. ‘torch’ è una modalità di luce continua.

export type CameraPreviewFlashMode = 'off' | 'on' | 'auto' | 'torch';

GridMode

export type GridMode = 'none' | '3x3' | '4x4';

PermissionRequestOptions

export interface PermissionRequestOptions {
  disableAudio?: boolean;
  showSettingsAlert?: boolean;
  title?: string;
  message?: string;
  openSettingsButtonTitle?: string;
  cancelButtonTitle?: string;
}

CameraPermissionStatus

export interface CameraPermissionStatus {
  camera: PermissionState;
  microphone?: PermissionState;
}

SupportedPictureSizes

Rappresenta le dimensioni delle immagini supportate per una fotocamera che si affaccia in una certa direzione.

export interface SupportedPictureSizes {
  /** The camera direction ("front" or "rear"). */
  facing: string;
  /** A list of supported picture sizes for this camera. */
  supportedPictureSizes: PictureSize[];
}

CameraOpacityOptions

Definisce le opzioni per impostare l'opacità della preview della camera.

export interface CameraOpacityOptions {
  /**
   * The opacity percentage, from 0.0 (fully transparent) to 1.0 (fully opaque).
   * @default 1.0
   */
  opacity?: number;
}

CameraDevice

Rappresenta una camera fisica sul dispositivo (ad esempio, la camera anteriore).

export interface CameraDevice {
  /** A unique identifier for the camera device. */
  deviceId: string;
  /** A human-readable name for the camera device. */
  label: string;
  /** The physical position of the camera on the device. */
  position: CameraPosition;
  /** A list of all available lenses for this camera device. */
  lenses: CameraLens[];
  /** The overall minimum zoom factor available across all lenses on this device. */
  minZoom: number;
  /** The overall maximum zoom factor available across all lenses on this device. */
  maxZoom: number;
  /** Identifies whether the device is a logical camera (composed of multiple physical lenses). */
  isLogical: boolean;
}

LensInfo

Rappresenta le informazioni dettagliate della lente attualmente attiva.

export interface LensInfo {
  /** The focal length of the active lens in millimeters. */
  focalLength: number;
  /** The device type of the active lens. */
  deviceType: DeviceType;
  /** The base zoom ratio of the active lens (e.g., 0.5x, 1.0x). */
  baseZoomRatio: number;
  /** The current digital zoom factor applied on top of the base zoom. */
  digitalZoom: number;
}

Fonte di Verità

Questa pagina è generata dal plugin’s src/definitions.ts. Riavvia la sincronizzazione quando il pubblico API cambia in modo upstream.