Mulai Menggunakan

Instalasi

Kamu bisa menggunakan Setup Bantuan AI untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI kamu menggunakan perintah berikut:

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

Lalu gunakan prompt berikut:

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

Jika kamu lebih suka Setup Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

bun add @capgo/camera-preview
bunx cap sync

Impor

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

API Ringkasan

start

Mengaktifkan kamera untuk menampilkan preview.

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

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

stop

Menghentikan kamera preview.

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

await CameraPreview.stop();

capture

Mengambil gambar dari kamera.

Jika storeToFile ditetapkan true ketika memulai pratinjau, nilai yang dikembalikan value akan menjadi jalur file absolut pada perangkat daripada string base64. Gunakan getBase64FromFilePath untuk mendapatkan string base64 dari jalur file.

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

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

captureSample

Mengambil frame tunggal dari aliran pratinjau kamera.

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

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

getSupportedFlashModes

Mendapatkan mode kilasan yang didukung oleh kamera aktif.

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

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

setAspectRatio

Setel rasio aspek kamera preview.

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

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

getAspectRatio

Dapatkan rasio aspek kamera preview saat ini.

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

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

setGridMode

Setel mode grid kamera preview overlay.

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

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

getGridMode

Dapatkan mode grid kamera preview overlay saat ini.

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

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

checkPermissions

Memeriksa status izin kamera (dan mikrofon opsional) saat ini tanpa meminta dialog sistem.

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

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

requestPermissions

Mengajukan izin kamera (dan mikrofon opsional). Jika izin sudah diberikan atau ditolak, status saat ini akan dikembalikan tanpa meminta. Ketika showSettingsAlert Jika nilai __CAPGO_KEEP_0__ adalah benar dan izin di tolak, maka akan ditampilkan peringatan platform khusus yang mengarah pengguna ke pengaturan aplikasi.

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

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

getHorizontalFov

Mengambil sudut pandang horizontal untuk kamera aktif. Catatan: Ini bisa menjadi perkiraan pada beberapa perangkat.

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

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

getSupportedPictureSizes

Mengambil ukuran gambar yang didukung untuk semua kamera.

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

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

setFlashMode

Mengatur mode kilas balik untuk kamera aktif.

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

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

flip

Mengganti antara kamera depan dan belakang.

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

await CameraPreview.flip();

setOpacity

Mengatur kejelasan kamera preview.

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

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

stopRecordVideo

Stops an ongoing video recording.

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

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

startRecordVideo

Mengawali rekaman video.

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

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

isRunning

Memeriksa apakah preview kamera sedang berjalan.

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

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

getAvailableDevices

Mengambil semua perangkat kamera yang tersedia.

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

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

getZoom

Mengambil informasi pengaturan lensa saat ini, termasuk batas minimum dan maksimum.

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

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

getZoomButtonValues

Mengembalikan nilai tombol zoom untuk perubahan cepat.

• IOS/Android: termasuk 0,5 jika ultra-lebar tersedia; 1 dan 2 jika lebar tersedia; 3 jika telefoto tersedia
• Web: tidak didukung

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

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

setZoom

Mengatur tingkat zoom kamera.

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

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

getFlashMode

Mengembalikan mode kilat saat ini.

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

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

setDeviceId

Ganti kamera aktif ke kamera yang ditentukan deviceId.

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

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

getDeviceId

Mendapatkan ID perangkat kamera yang sedang terikat. Pada Android, jika permintaan lensa fisik jatuh kembali ke kamera logis, ini akan mengembalikan ID kamera logis yang terikat.

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

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

getPreviewSize

Mendapatkan ukuran dan posisi preview saat ini.

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

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

setPreviewSize

Mengatur ukuran dan posisi preview.

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

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

setFocus

Menetapkan fokus kamera ke titik tertentu dalam pratinjau.

Merk: Plugin ini tidak menambahkan penggunaan gestur sentuh native untuk fokus. Tangani sentuhan di HTML/JS Anda (misalnya, di antara UI yang menutupi), lalu kirimkan koordinat yang dinormalisasi ke sini.

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

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

deleteFile

Menghapus sebuah file di jalur absolut pada perangkat ini. Gunakan ini untuk membersihkan cepat gambar sementara yang dibuat dengan storeToFileTidak di dukung di web dan akan menyebabkan kesalahan.

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

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

getSafeAreaInsets

Gets the safe area insets for devices. Returns the orientation-aware notch/camera cutout inset and the current orientation. In portrait mode: returns top inset (notch at top). In landscape mode: returns left inset (notch moved to side). This specifically targets the cutout area (notch, punch hole, etc.) that all modern phones have.

Android: Nilai yang dikembalikan dalam dp (pixel logis). iOS: Nilai yang dikembalikan dalam pixel fisik, mengingkari status bar (hanya ukuran notch/cutout murni).

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

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

getOrientation

Memperoleh orientasi perangkat saat ini dalam format lintas platform.

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

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

getExposureModes

Mengembalikan mode eksposisi yang didukung oleh kamera aktif. Mode dapat mencakup: ‘terkunci’, ‘otomatis’, ‘terus menerus’, ‘custom’.

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

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

getExposureMode

Mengembalikan mode eksposisi saat ini.

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

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

setExposureMode

Mengatur mode eksposisi.

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

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

getExposureCompensationRange

Kembali nilai kompensasi eksposur (EV bias) yang didukung.

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

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

getExposureCompensation

Mengembalikan nilai kompensasi eksposur (EV bias) saat ini.

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

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

setExposureCompensation

Mengatur nilai kompensasi eksposur (EV bias). Nilai akan dikompresi ke rentang.

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

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

Referensi Tipe

CameraPreviewOptions

Menggambarkan opsi pengaturan untuk memulai preview kamera.

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

Mengatur opsi untuk mengambil gambar.

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

Menggambarkan data EXIF yang diekstrak dari gambar.

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

CameraSampleOptions

Mengatur opsi untuk mengambil frame sampel dari preview kamera.

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

CameraPreviewFlashMode

Mode kilat yang tersedia untuk kamera. ‘torch’ adalah mode cahaya terus-menerus.

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

Mewakili ukuran gambar yang didukung untuk kamera yang menghadap ke arah tertentu.

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

CameraOpacityOptions

Mengatur opsi untuk mengatur kejelasan kamera preview.

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

CameraDevice

Mewakili kamera fisik pada perangkat (misalnya kamera depan).

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

Mewakili informasi rinci tentang lensa aktif saat ini.

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

Sumber Kebenaran

Halaman ini dihasilkan dari plugin’s src/definitions.ts. Ulangi sinkronisasi ketika API publik berubah di atas.

Teruskan dari Getting Started

Jika Anda menggunakan Mulai Menggunakan untuk merencanakan perilaku media dan antarmuka native, hubungkannya dengan Menggunakan @capgo/camera-preview untuk kemampuan native di Menggunakan @capgo/camera-preview, Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-aktivitas-langsung untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kemampuan native di Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-player video untuk detail implementasi di @capgo/capacitor-player video.