Inizia a utilizzare

Installazione

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo competenze al tuo strumento AI utilizzando il seguente comando:

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

Poi utilizza il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

bun add @capgo/camera-preview
bunx cap sync

Importa

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

API Panoramica

start

Avvia la preview della fotocamera.

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

await CameraPreview.start({} as CameraPreviewOptions);

stop

Ferma la preview della fotocamera.

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

await CameraPreview.stop();

capture

Cattura un'immagine dalla fotocamera.

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

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

await CameraPreview.capture({} as CameraPreviewPictureOptions);

captureSample

Copia nella clipboard

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

await CameraPreview.captureSample({} as CameraSampleOptions);

getSupportedFlashModes

Copia nella clipboard

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

await CameraPreview.getSupportedFlashModes();

setAspectRatio

Imposta il rapporto d'aspetto della preview della camera.

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

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

getAspectRatio

Ottiene il rapporto d'aspetto corrente della preview della camera.

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

await CameraPreview.getAspectRatio();

setGridMode

Imposta il modo della griglia della sovrapposizione della preview della camera.

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

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

getGridMode

Ottiene il modo della griglia corrente della sovrapposizione della preview della camera.

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 autorizzazioni per la camera (e la microfono facoltativa). 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, viene presentato un avviso specifico per piattaforma che guida l'utente alle 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 camere.

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

Alternare tra le telecamere 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 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 zoom attuale, compreso minimo/maximo e informazioni sulla lente corrente.

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-largangolare; 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 di flash corrente.

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

await CameraPreview.getFlashMode();

setDeviceId

Switcha la camera attiva a quella con lo specificato deviceId.

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

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

getDeviceId

Ottiene l'ID del dispositivo della camera che è attualmente vincolato. Su Android, se una richiesta di lente fisica cade su una camera logica, questo restituisce l'ID della camera logica vincolata.

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

await CameraPreview.getDeviceId();

getPreviewSize

Ottiene la dimensione e la posizione della preview corrente.

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

await CameraPreview.getPreviewSize();

setPreviewSize

Imposta la dimensione e la posizione della preview.

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 per il focus nativo. Gestisci i tocchi nel tuo HTML/JS (ad esempio, sull'interfaccia utente sovrapposta), quindi passa le coordinate normalizzate qui.

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

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

deleteFile

Cancella un file in un percorso assoluto sul dispositivo. Usa questo per pulire velocemente le immagini temporanee create con . Non è supportato su web e lancerà un errore. storeToFileCopia negli appunti

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

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

getSafeAreaInsets

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

Copia negli appunti

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

await CameraPreview.getSafeAreaInsets();

getOrientation

Restituisce 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 attuale.

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

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 (bias EV). Il valore sarà limitato al range.

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

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

Sezione intitolata “Tipo di Riferimento”

CameraPreviewOptions

Definisce le opzioni di configurazione per avviare la 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 camera. '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 camera che si trova 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 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;
}

Punto di Riferimento

Questa pagina è generata dal plugin's src/definitions.ts. Riavvia la sincronizzazione quando le informazioni pubbliche API cambiano in modo upstream.

Continua da Inizia a utilizzare

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