Démarrage

Installer

bun add @capgo/camera-preview
bunx cap sync

Importer

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

API Aperçu

start

Démarre la prévisualisation de la caméra.

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

await CameraPreview.start({} as CameraPreviewOptions);

stop

Arrête la prévisualisation de la caméra.

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

await CameraPreview.stop();

capture

Capturer une photo à partir de la caméra.

Si storeToFile était défini sur true When vous lancez la prévisualisation, le résultat sera un chemin de fichier absolu sur le dispositif au lieu d'une chaîne base64. Utilisez getBase64FromFilePath pour obtenir la chaîne base64 à partir du chemin de fichier. value Copier dans le presse-papier

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

await CameraPreview.capture({} as CameraPreviewPictureOptions);

captureSample

Copier dans le presse-papier

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

await CameraPreview.captureSample({} as CameraSampleOptions);

getSupportedFlashModes

Copier dans le presse-papier

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

await CameraPreview.getSupportedFlashModes();

setAspectRatio

Copier dans le presse-papier

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

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

getAspectRatio

Obtient le rapport d'aspect actuel de la prévisualisation de la caméra.

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

await CameraPreview.getAspectRatio();

setGridMode

Configure le mode de grille de la surcouche de prévisualisation de la caméra.

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

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

getGridMode

Obtient le mode de grille actuel de la surcouche de prévisualisation de la caméra.

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

await CameraPreview.getGridMode();

checkPermissions

Vérifie l'état actuel des autorisations de la caméra (et facultativement du microphone) sans afficher le dialogue du système.

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

await CameraPreview.checkPermissions();

requestPermissions

Demande les autorisations de la caméra (et microphone optionnel). Si les autorisations sont déjà accordées ou refusées, le statut actuel est renvoyé sans solliciter. Lorsque showSettingsAlert est vrai et que les autorisations sont refusées, une alerte spécifique à la plateforme guide l'utilisateur vers les paramètres de l'application sera présentée.

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

await CameraPreview.requestPermissions();

getHorizontalFov

Obtient le champ de vision horizontal pour la caméra active. Remarque : Cela peut être une estimation sur certains appareils.

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

await CameraPreview.getHorizontalFov();

getSupportedPictureSizes

Obtient les tailles de pictogrammes supportées pour toutes les caméras.

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

await CameraPreview.getSupportedPictureSizes();

setFlashMode

Mets le mode flash pour la caméra active.

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

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

flip

Alternent entre les caméras avant et arrière.

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

await CameraPreview.flip();

setOpacity

Fixe l'opacité de la prévisualisation de la caméra.

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

await CameraPreview.setOpacity({} as CameraOpacityOptions);

stopRecordVideo

Arrête une enregistrement vidéo en cours.

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

await CameraPreview.stopRecordVideo();

startRecordVideo

Démarre l'enregistrement d'une vidéo.

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

await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

isRunning

Vérifie si la prévisualisation de la caméra est actuellement en cours.

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

await CameraPreview.isRunning();

getAvailableDevices

Récupère tous les appareils de caméra disponibles.

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

await CameraPreview.getAvailableDevices();

getZoom

Récupère l'état de zoom actuel, y compris les valeurs minimale et maximale et les informations sur l'objectif.

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

await CameraPreview.getZoom();

getZoomButtonValues

Renvoie les valeurs des boutons de zoom pour un changement rapide.

• iOS/Android : inclut 0,5 si ultra-large disponible ; 1 et 2 si large disponible ; 3 si téléobjectif disponible
• Web : non pris en charge

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

await CameraPreview.getZoomButtonValues();

setZoom

Définit le niveau de zoom de la caméra.

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

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

getFlashMode

Obtient le mode flash actuel.

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

await CameraPreview.getFlashMode();

setDeviceId

Basculer la caméra active vers celle avec l'identifiant spécifié deviceId.

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

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

getDeviceId

Obtient l'ID du dispositif de caméra actuellement lié. Sur Android, si une demande de lentille physique se répercute sur une caméra logique, cela retourne l'ID de la caméra logique liée.

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

await CameraPreview.getDeviceId();

getPreviewSize

Obtient la taille et la position actuelles de la prévisualisation.

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

await CameraPreview.getPreviewSize();

setPreviewSize

Fixe la taille et la position de la prévisualisation.

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

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

setFocus

Fixe l'axe de la caméra sur un point spécifique de la prévisualisation.

Remarque : Le plugin ne relie aucun gestionnaire de geste de clic sur la focale native. Gérez les clics dans votre HTML/JS (par exemple, sur l'interface utilisateur superposée), puis passez les coordonnées normalisées ici.

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

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

deleteFile

Supprime un fichier à l'emplacement absolu spécifié sur le dispositif. Utilisez cela pour nettoyer rapidement les images temporaires créées avec storeToFile. Sur le web, cela n'est pas pris en charge et lancera une erreur.

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

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

getSafeAreaInsets

Obtient les marges de zone de sécurité pour les appareils. Renvoie les valeurs des notches ou trous d'œil orientées en fonction de l'orientation et l'orientation actuelle. En mode paysage : renvoie l'inset de gauche (notch déplacé du côté). En mode portrait : renvoie l'inset de haut (notch en haut). Cela cible spécifiquement l'aire de coupe (notch, trou d'œil, etc.) que tous les téléphones modernes ont.

Android : Les valeurs renvoyées en dp (pixels logiques). iOS : Les valeurs renvoyées en pixels physiques, en excluant la barre d'état (seulement la taille pure de la notche/coupe).

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

await CameraPreview.getSafeAreaInsets();

getOrientation

Obtient l'orientation actuelle du dispositif sous une forme cross-plateforme.

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

await CameraPreview.getOrientation();

getExposureModes

Renvoie les modes d'exposition pris en charge par la caméra active. Les modes peuvent inclure : ‘bloqué’, ‘automatique’, ‘continu’, ‘personnalisé’.

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

await CameraPreview.getExposureModes();

getExposureMode

Renvoie le mode d'exposition actuel.

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

await CameraPreview.getExposureMode();

setExposureMode

Fixe le mode d'exposition.

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

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

getExposureCompensationRange

Renvoie la plage de compensation d'exposition (EV bias) prise en charge.

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

await CameraPreview.getExposureCompensationRange();

getExposureCompensation

Renvoie la compensation d'exposition actuelle (EV bias).

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

await CameraPreview.getExposureCompensation();

setExposureCompensation

Fixe la compensation d'exposition (EV bias). La valeur sera limitée à la plage.

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

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

Référence de type

CameraPreviewOptions

Définit les options de configuration pour démarrer la prévisualisation de la caméra.

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

Définit les options pour capturer une image.

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

Représente les données EXIF extraites d'une image.

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

CameraSampleOptions

Définit les options pour capturer un échantillon de frame de la prévisualisation de la caméra.

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

CameraPreviewFlashMode

Les modes de la lumière disponible pour la caméra. ‘torch’ est un mode de lumière continue.

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

Représente les tailles de photos prises en fonction d'une certaine direction de la caméra.

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

CameraOpacityOptions

Définit les options pour définir la transparence de la prévisualisation de la caméra.

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

CameraDevice

Représente une caméra physique sur le dispositif (par exemple, la caméra avant).

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

Représente les informations détaillées de l'objectif actuellement actif.

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;
}

Source de Vérité

Cette page est générée à partir du plugin’s src/definitions.tsRexécuter à nouveau la synchronisation lorsque les modifications publiques API changent en amont.

Continuer depuis Getting Started

Si vous utilisez Démarrage pour planifier le comportement des médias et de l'interface native, le connecter avec En utilisant @capgo/camera-preview pour la capacité native dans En utilisant @capgo/camera-preview, En utilisant @capgo/capacitor-live-activities pour la capacité native dans En utilisant @capgo/capacitor-live-activities, @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities, En utilisant @capgo/capacitor-video-player pour la capacité native dans En utilisant @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.