Getting Started

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten zu Ihrem KI-Tool hinzu, indem Sie die folgende Befehlszeile verwenden:

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

Verwenden Sie dann die folgende Anfrage:

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

Wenn Sie eine manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und die unten angegebenen plattform-spezifischen Anweisungen befolgen:

bun add @capgo/camera-preview
bunx cap sync

Importieren

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

API Übersicht

start

Startet die Kameravorschau.

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

await CameraPreview.start({} as CameraPreviewOptions);

stop

Die Kamera-Vorschau wird gestoppt.

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

await CameraPreview.stop();

capture

Ein Bild von der Kamera aufnimmt.

Wenn storeToFile festgelegt wurde true wenn die Vorschau gestartet wurde, wird das zurückgegebene value eine absolute Dateipfad auf dem Gerät anstatt eine Base64-Zeichenfolge sein. Verwenden Sie getBase64FromFilePath, um die Base64-Zeichenfolge aus dem Dateipfad zu erhalten.

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

await CameraPreview.capture({} as CameraPreviewPictureOptions);

captureSample

Ein einzelnes Frame aus der Kamera-Vorschau-Stream aufnimmt.

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

await CameraPreview.captureSample({} as CameraSampleOptions);

getSupportedFlashModes

Ermittelt die von der aktiven Kamera unterstützten Blitzmodi.

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

await CameraPreview.getSupportedFlashModes();

setAspectRatio

Setzt den Seitenverhältnis der Kamera-Vorschau.

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

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

getAspectRatio

Ermittelt das aktuelle Seitenverhältnis der Kamera-Vorschau.

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

await CameraPreview.getAspectRatio();

setGridMode

Setzt den Rastermodus der Kamera-Vorschau-Überlagerung.

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

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

getGridMode

Ermittelt die aktuelle Grid-Modus der Kamera-Vorschau-Überlagerung.

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

await CameraPreview.getGridMode();

checkPermissions

Überprüft den aktuellen Kamera- (und optionalen Mikrofon-) Berechtigungsstatus ohne das Systemdialog zu öffnen.

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

await CameraPreview.checkPermissions();

requestPermissions

Berechtigungen für die Kamera (und optionalen Mikrofon) anfordern. Wenn die Berechtigungen bereits erteilt oder abgelehnt wurden, wird der aktuelle Status ohne Aufforderung zurückgegeben. Wenn showSettingsAlert wahr ist und die Berechtigungen abgelehnt wurden, wird eine plattform-spezifische Warnung, die den Benutzer zu den App-Einstellungen leitet, angezeigt.

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

await CameraPreview.requestPermissions();

getHorizontalFov

Gets the horizontal field of view für die aktive Kamera. Hinweis: Dies kann eine Schätzung auf einigen Geräten sein.

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

await CameraPreview.getHorizontalFov();

getSupportedPictureSizes

Ermittelt die unterstützten Bildgrößen für alle Kameras.

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

await CameraPreview.getSupportedPictureSizes();

setFlashMode

Setzt die Blitzmodus für die aktive Kamera.

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

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

flip

Schaltet zwischen der Vorder- und Rückkamera um.

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

await CameraPreview.flip();

setOpacity

Setzt die Opazität der Kamera-Vorschau.

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

await CameraPreview.setOpacity({} as CameraOpacityOptions);

stopRecordVideo

Beendet ein laufendes Videoaufnahmeprogramm.

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

await CameraPreview.stopRecordVideo();

startRecordVideo

Beginnt eine Videoaufnahme.

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

await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

isRunning

Überprüft, ob die Kamera-Vorschau derzeit läuft.

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

await CameraPreview.isRunning();

getAvailableDevices

Alle verfügbaren Kamera-Geräte abrufen.

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

await CameraPreview.getAvailableDevices();

getZoom

Gibt den aktuellen Zoom-Zustand, einschließlich Mindest- und Maximalwert sowie aktuelle Objektiv-Informationen, zurück.

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

await CameraPreview.getZoom();

getZoomButtonValues

Gibt die Werte der Zoom-Taste für schnelles Wechseln zurück.

• iOS/Android: enthält 0,5, wenn Ultra-Wide verfügbar ist; 1 und 2, wenn Wide verfügbar ist; 3, wenn Telephoto verfügbar ist
• Web: nicht unterstützt

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

await CameraPreview.getZoomButtonValues();

setZoom

Setzt den Zoom-Level der Kamera.

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

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

getFlashMode

Ermittelt die aktuelle Blitzmodus-Einstellung.

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

await CameraPreview.getFlashMode();

setDeviceId

Schaltet den aktiven Kamera auf die mit der angegebenen deviceId.

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

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

getDeviceId

Ermittelt die ID der Kamera, die derzeit gebunden ist. Bei Android, wenn eine physische-Linsen-Anfrage auf eine logische Kamera zurückfällt, gibt dies die ID der gebundenen logischen Kamera zurück.

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

await CameraPreview.getDeviceId();

getPreviewSize

Ermittelt die aktuelle Vorschau-Größe und -Position.

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

await CameraPreview.getPreviewSize();

setPreviewSize

Setzt die Vorschau-Größe und -Position.

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

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

setFocus

Setzt die Kamera-Belichtung auf einen bestimmten Punkt in der Vorschau.

Hinweis: Das Plugin bindet keine native Berührungszuordnungs-Handler. Behandeln Sie Berührungen in Ihrer HTML/JS (z.B. auf der überlagerten UI), dann übergeben Sie normalisierte Koordinaten hier.

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

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

deleteFile

Löscht ein Datei an der gegebenen absoluten Pfad auf dem Gerät. Verwenden Sie dies, um temporäre Bilder schnell zu löschen, die mit storeToFileZur Zwischenablage kopieren

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

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

getSafeAreaInsets

Ermittelt die sicheren Bereichs-Einstellungen für Geräte. Gibt die orientierungsbewusste Notch/Kamera-Schnittstelle-Einrückung und die aktuelle Orientierung zurück. Bei Portrait-Modus: Gibt die obere Einrückung (Notch oben) zurück. Bei Landschaftsmodus: Gibt die linke Einrückung (Notch an der Seite verschoben) zurück. Dies zielt speziell auf die Schnittstelle-Bereich (Notch, Loch, usw.) ab, die alle modernen Smartphones haben.

Android: Werte in dp (logische Pixel) zurückgegeben. iOS: Werte in physischen Pixel zurückgegeben, ausschließlich Statusleiste (reine Notch-/Schnittstelle-Größe).

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

await CameraPreview.getSafeAreaInsets();

getOrientation

Ermittelt die aktuelle Geräteeinstellung in einer plattformübergreifenden Format.

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

await CameraPreview.getOrientation();

getExposureModes

Gibt die von der aktiven Kamera unterstützten Belichtungsmodi zurück. Modi können beinhalten: ‘gesperrt’, ‘automatisch’, ‘fortlaufend’, ‘benutzerdefiniert’.

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

await CameraPreview.getExposureModes();

getExposureMode

Gibt den aktuellen Belichtungsmodus zurück.

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

await CameraPreview.getExposureMode();

setExposureMode

Setzt die Belichtungsart.

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

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

getExposureCompensationRange

Gibt den Bereich der unterstützten Belichtungsentsprechung (EV-Verschiebung) zurück.

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

await CameraPreview.getExposureCompensationRange();

getExposureCompensation

Gibt die aktuelle Belichtungsentsprechung (EV-Verschiebung) zurück.

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

await CameraPreview.getExposureCompensation();

setExposureCompensation

Setzt die Belichtungsentsprechung (EV-Verschiebung). Der Wert wird auf den Bereich begrenzt.

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

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

Typenverweis

CameraPreviewOptions

Legt die Konfigurationsoptionen für das Starten des Kameravorschau-Bildschirms fest.

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

Legt die Optionen für die Bildaufnahme fest.

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

Stellt EXIF-Daten dar, die aus einem Bild extrahiert wurden.

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

CameraSampleOptions

Definiert die Optionen für die Aufnahme einer Sample-Frames von der Kamera-Vorschau.

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

CameraPreviewFlashMode

Die verfügbaren Blitz-Modi für die Kamera. ‘torch’ ist ein kontinuierlicher Lichtmodus.

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

Darstellt die unterstützten Bildgrößen für eine Kamera, die in eine bestimmte Richtung zeigt.

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

CameraOpacityOptions

Definiert die Optionen zum Festlegen der Transparenz der Kamera-Vorschau.

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

CameraDevice

Darstellt eine physische Kamera auf dem Gerät (z.B. die Vorderkamera).

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

Darstellt die detaillierten Informationen des aktiven Objektivs.

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

Quelle der Wahrheit

Diese Seite wird aus dem Plugin generiert. src/definitions.tsRe-run die Synchronisierung, wenn die öffentliche API upstream geändert wird.

Fortsetzen von Getting Started

Wenn Sie native Medien- und Interfaceverhalten planen, verbinden Sie es mit Mit @__CAPGO_KEEP_0__/camera-preview Für die native Fähigkeit in Mit @__CAPGO_KEEP_0__/camera-preview, Mit @capgo/__CAPGO_KEEP_1__-live-activities for the native capability in Using @capgo/camera-preview, Using @capgo/capacitor-live-activities für die native Fähigkeit in @capgo/capacitor-live-activities, @capgo/capacitor-live-activities für die Implementierungsdetail in @capgo/capacitor-live-activities, Mit @capgo/capacitor-video-player für die native Fähigkeit in Mit @capgo/capacitor-video-player, und @capgo/capacitor-video-player für die Implementierungsdetail in @capgo/capacitor-video-player.