Iniziare

Installazione

bun add @capgo/camera-preview
bunx cap sync

Importazione

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 camera.

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 del file.

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

await CameraPreview.capture({} as CameraPreviewPictureOptions);

captureSample

Cattura una singola immagine 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 l'aspetto della anteprima della fotocamera.

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

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

getAspectRatio

Ottiene l'aspetto corrente della anteprima della fotocamera.

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

await CameraPreview.getAspectRatio();

setGridMode

Imposta la modalità della rete della vista di anteprima della fotocamera.

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

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

getGridMode

Ottiene la modalità attuale della rete della vista di anteprima della fotocamera.

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

await CameraPreview.getGridMode();

checkPermissions

Verifica lo stato dei permessi della fotocamera (e facoltativamente del microfono) senza sollecitare la finestra di dialogo del sistema.

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

await CameraPreview.checkPermissions();

requestPermissions

Richiede i permessi della fotocamera (e facoltativamente del microfono). Se i permessi sono già stati concessi o negati, lo stato attuale viene restituito senza sollecitare. Quando showSettingsAlert è vero e i permessi sono negati, a finestra di dialogo guidata dall'applicazione per la configurazione dell'utente sarà presentata.

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'indicazione approssimativa su alcuni dispositivi.

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

await CameraPreview.getHorizontalFov();

getSupportedPictureSizes

Ottiene le dimensioni delle immagini supportate per tutte le telecamere.

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

await CameraPreview.getSupportedPictureSizes();

setFlashMode

Imposta il modo flash per la camera attiva.

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

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

flip

Toglie tra la telecamera anteriore e posteriore.

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

await CameraPreview.flip();

setOpacity

Imposta la trasparenza della anteprima della camera.

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 la registrazione di un video.

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

await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

isRunning

Verifica se l'anteprima 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 zoom corrente, compreso minimo/maximo e informazioni sulla lente attuale.

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

await CameraPreview.getZoom();

getZoomButtonValues

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

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

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

await CameraPreview.getZoomButtonValues();

setZoom

Imposta il livello di zoom 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. 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 rivolge a una logica, questo restituisce l'ID della logica camera associata.

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

await CameraPreview.getDeviceId();

getPreviewSize

Ottiene la dimensione e la posizione correnti della anteprima.

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 tap-to-focus nativo. Gestisci i tocchi nella tua HTML/JS (ad esempio, sull'interfaccia utente sovrapposta), quindi passa coordinate normalizzate qui.

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

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

deleteFile

Cancella un file all'indirizzo assoluto specificato sul dispositivo. Usa questo per pulire velocemente immagini temporanee create con storeToFile. In rete, questo non è supportato e lancerà un'eccezione.

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

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

getSafeAreaInsets

Ottenere gli insetti di area sicura per dispositivi. Restituisce l'insetto di notch/camera tagliato 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). Questo si concentra specificamente sull'area di taglio (notch, foro, ecc.) che tutti i telefoni moderni hanno.

Android: I valori restituiti in dp (pixel logici). iOS: I valori restituiti in pixel fisici, escluso il barra dello stato (solo dimensione pura notch/cutout).

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

await CameraPreview.getSafeAreaInsets();

getOrientation

Ottenere l'orientamento corrente 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 (bias EV) supportato.

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

await CameraPreview.getExposureCompensationRange();

getExposureCompensation

Restituisce la compensazione di esposizione corrente (bias EV).

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

await CameraPreview.getExposureCompensation();

setExposureCompensation

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

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

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

Riferimento di tipo

CameraPreviewOptions

Definisce le opzioni di configurazione per l'avvio della preview della fotocamera.

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 cattura 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 da un'immagine.

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

CameraSampleOptions

Definisce le opzioni per la cattura di un frame di prova dalla preview della fotocamera.

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

CameraPreviewFlashMode

I modi di flash disponibili per la fotocamera. ‘torch’ è un modo 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 certa direzione della fotocamera.

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 fotocamera.

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

CameraDevice

Rappresenta una fotocamera fisica sul dispositivo (ad esempio, la fotocamera frontale).

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.tsRiepilogare la sincronizzazione quando le informazioni pubbliche API cambiano in modo upstream.

Continua da Iniziare

Se stai utilizzando Iniziare per pianificare il comportamento dei media e dell'interfaccia nativi, connettilo con Utilizza @capgo/camera-preview For la capacità nativa in Utilizzare @capgo/camera-preview, Utilizzare @capgo/capacitor-live-attività For la capacità nativa in Utilizzare @capgo/capacitor-live-attività, @capgo/capacitor-live-attività For il dettaglio di implementazione in @capgo/capacitor-live-attività, Utilizzare @capgo/capacitor-video-player For la capacità nativa in Utilizzare @capgo/capacitor-video-player, e @capgo/capacitor-video-player For il dettaglio di implementazione in @capgo/capacitor-video-player.