Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

bun add @capgo/camera-preview
bunx cap sync

Importer

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

Démarrage rapide

Lancez un aperçu de la caméra arrière derrière votre UI, capturez une photo, puis arrêtez-le pour libérer la caméra.

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

await CameraPreview.start({
  position: 'rear',
  parent: 'cameraPreview',
  toBack: true,
});

const { value } = await CameraPreview.capture({ quality: 90 });
console.log('Photo base64', value);

await CameraPreview.stop();

Montez un élément plein écran avec id="cameraPreview" dans votre HTML, et rendez l'arrière-plan de la route ou de l'app transparent pour que l'aperçu natif derrière la WebView soit visible (par exemple ion-content { --background: transparent; } sur les routes Ionic).

Exemple : overlay de code-barres

await CameraPreview.start({ position: 'rear', toBack: true });

await CameraPreview.startBarcodeScanner({
  formats: ['qr_code', 'code_128'],
  detectionInterval: 400,
});

let handled = false;
const barcodeListener = await CameraPreview.addListener('barcodeScanned', async (event) => {
  if (handled) return;
  const code = event.barcodes[0]?.value;
  if (!code) return;
  handled = true;
  await CameraPreview.stopBarcodeScanner();
  await handleScan(code);
});

// When leaving the screen:
await barcodeListener.remove();

Exemple : basculer la caméra et le flash

await CameraPreview.flip();
await CameraPreview.setFlashMode({ flashMode: 'torch' });

Erreurs courantes

• Autorisations: demandez l'accès à la caméra (et au micro si vous enregistrez une vidéo) avant start.
• Cycle de vie: appelez stop() lors du changement de route, l'écran suivant peut échouer à ouvrir la caméra.
• Le Web: vérifiez les API prises en charge dans le README du plugin avant de vous fier à l'aperçu dans les navigateurs mobiles.

Aperçu de API

start

Lance l'aperçu de la caméra.

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

const result = await CameraPreview.start({ parent: 'parent' });
console.log(result);

stop

Arrête l'aperçu de la caméra.

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

await CameraPreview.stop();

capture

Capture une photo avec la caméra.

Si storeToFile est défini sur true au lancement de la preview, le value sera un chemin de fichier absolu sur l'appareil au lieu d'une chaîne base64. Utilisez getBase64FromFilePath pour obtenir la chaîne base64 à partir du chemin de fichier.

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

const result = await CameraPreview.capture({ height: 1920 });
console.log(result);

captureSample

Capture une seule image du flux de la preview caméra.

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

const result = await CameraPreview.captureSample({
  quality: 85,
  mirrorFrontCamera: false,
});
console.log(result);

getSupportedFlashModes

Récupère les modes de flash supportés par la caméra active.

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

const result = await CameraPreview.getSupportedFlashModes();
console.log(result);

setAspectRatio

Définit le rapport d'aspect de l'aperçu caméra.

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

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

getAspectRatio

Récupère le rapport d'aspect actuel de l'aperçu caméra.

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

const result = await CameraPreview.getAspectRatio();
console.log(result);

setGridMode

Définit le mode de grille de l'overlay de l'aperçu caméra.

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

await CameraPreview.setGridMode({ gridMode: 'none' });

getGridMode

Récupère le mode de grille actuel de l'overlay de l'aperçu caméra.

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

const result = await CameraPreview.getGridMode();
console.log(result);

checkPermissions

Vérifie l'état actuel des permissions de la caméra (et optionnellement du micro) sans afficher la boîte de dialogue système.

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

const result = await CameraPreview.checkPermissions();
// The result holds sensitive values: use it without logging it.

requestPermissions

Demande les permissions de la caméra (et optionnellement du micro). Si les permissions sont déjà accordées ou refusées, l'état actuel est renvoyé sans solliciter l'utilisateur. Si showSettingsAlert est vrai et que les permissions sont refusées, unne alerte spécifique à la plateforme guidera l'utilisateur vers les paramètres de l'appareil.

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

const result = await CameraPreview.requestPermissions();
// The result holds sensitive values: use it without logging it.

getHorizontalFov

Récupère le champ de vision horizontal de la caméra active. Note : Cela peut être une estimation sur certains appareils.

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

const result = await CameraPreview.getHorizontalFov();
console.log(result);

getSupportedPictureSizes

Récupère les tailles d'image prises en charge pour toutes les caméras.

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

const result = await CameraPreview.getSupportedPictureSizes();
console.log(result);

setFlashMode

Définit le mode flash de la caméra active.

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

await CameraPreview.setFlashMode({ flashMode: 'off' });

flip

Bascule entre la caméra avant et la caméra arrière.

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

await CameraPreview.flip();

setOpacity

Définit l'opacité de l'aperçu de la caméra.

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

await CameraPreview.setOpacity({ opacity: 1.0 });

stopRecordVideo

Arrête l'enregistrement vidéo en cours.

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

const result = await CameraPreview.stopRecordVideo();
console.log(result);

startRecordVideo

Lance l'enregistrement d'une vidéo.

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

await CameraPreview.startRecordVideo({ parent: 'parent' });

isRunning

Vérifie si l'aperçu de la caméra est actif.

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

const result = await CameraPreview.isRunning();
console.log(result);

getAvailableDevices

Récupère tous les appareils photo disponibles.

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

const result = await CameraPreview.getAvailableDevices();
console.log(result);

getZoom

Récupère l'état actuel du zoom, incluant le min/max et les infos sur l'objectif actuel.

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

const result = await CameraPreview.getZoom();
console.log(result);

getZoomButtonValues

Renvoie les valeurs du bouton de zoom pour un changement rapide.

• iOS/Android : inclut 0,5 si l'ultra grand-angle est disponible ; 1 et 2 si le grand-angle est disponible ; 3 si le téléobjectif est disponible
• Web : non supporté

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

const result = await CameraPreview.getZoomButtonValues();
console.log(result);

setZoom

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

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

await CameraPreview.setZoom({ level: 1 });

getFlashMode

Récupère le mode flash actuel.

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

const result = await CameraPreview.getFlashMode();
console.log(result);

setDeviceId

Bascule la caméra active vers celle dont l'ID est spécifié deviceId.

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

await CameraPreview.setDeviceId({ deviceId: 'device-id-123' });

getDeviceId

Récupère l'ID de la caméra actuellement liée. Sur Android, si une requête sur un objectif physique retombe sur une caméra logique, la méthode renvoie l'ID de la caméra logique liée.

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

const result = await CameraPreview.getDeviceId();
console.log(result);

getPreviewSize

Récupère la taille et la position actuelles de l'aperçu.

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

const result = await CameraPreview.getPreviewSize();
console.log(result);

setPreviewSize

Définit la taille et la position de l'aperçu.

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

const result = await CameraPreview.setPreviewSize({
  width: 1080,
  height: 1920,
});
console.log(result);

setFocus

Définit la mise au point de la caméra sur un point précis de l'aperçu.

Note : le plugin n'ajoute aucun gestionnaire de geste natif de tap-to-focus. Gérez les taps dans votre HTML/JS (par exemple sur l'UI en superposition), puis transmettez les coordonnées normalisées ici.

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

await CameraPreview.setFocus({
  x: 1,
  y: 1,
});

deleteFile

Supprime un fichier au chemin absolu indiqué sur l'appareil. Utilisez ceci pour nettoyer rapidement les images temporaires créées avec storeToFile. Sur le web, ce n'est pas pris en charge et une erreur sera levée.

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

const result = await CameraPreview.deleteFile({ path: 'path/to/file' });
console.log(result);

getSafeAreaInsets

Récupère les insets de safe area des appareils. Retourne l'inset de l'encoche/découpe caméra selon l'orientation, ainsi que l'orientation actuelle. En mode portrait : retourne l'inset du haut (encoche en haut). En mode paysage : retourne l'inset de gauche (encoche sur le côté). Cible spécifiquement la zone de découpe (encoche, punch hole, etc.) présente sur tous les téléphones modernes.

Android : valeurs retournées en dp (pixels logiques). iOS : valeurs retournées en pixels physiques, barre d'état exclue (uniquement la taille de l'encoche/découpe).

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

const result = await CameraPreview.getSafeAreaInsets();
console.log(result);

getOrientation

Récupère l'orientation actuelle de l'appareil dans un format multiplateforme.

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

const result = await CameraPreview.getOrientation();
console.log(result);

getExposureModes

Retourne les modes d'exposition pris en charge par la caméra active. Les modes peuvent inclure : « locked », « auto », « continuous », « custom ».

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

const result = await CameraPreview.getExposureModes();
console.log(result);

getExposureMode

Retourne le mode d'exposition actuel.

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

const result = await CameraPreview.getExposureMode();
console.log(result);

setExposureMode

Définit le mode d'exposition.

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

await CameraPreview.setExposureMode({ mode: 'AUTO' });

getExposureCompensationRange

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

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

const result = await CameraPreview.getExposureCompensationRange();
console.log(result);

getExposureCompensation

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

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

const result = await CameraPreview.getExposureCompensation();
console.log(result);

setExposureCompensation

Définit la compensation d'exposition (biais EV). La valeur sera limitée à la plage autorisée.

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

await CameraPreview.setExposureCompensation({ value: 1 });

Référence de type

CameraPreviewOptions

Définit les options de configuration pour démarrer l'aperçu 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 photo.

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 une image échantillon de l'aperçu 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 flash disponibles 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 d'image prises en charge pour une caméra orientée dans une direction donnée.

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 régler l'opacité de l'aperçu 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 l'appareil (ex: la caméra 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

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 de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/camera-preview pour la capacité native dans l'utilisation de @capgo/camera-preview, Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la capacité native dans Utiliser @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.