Getting Started

インストールステップとこのプラグインのフルマークダウンガイドまでの全てのステップを含むセットアップ用質問をコピーする。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/camera-preview`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/camera-preview/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

インストール

bun add @capgo/camera-preview
bunx cap sync

インポート

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

API オーバービュー

`start`

カメラのプレビューを開始します。

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

await CameraPreview.start({} as CameraPreviewOptions);

`stop`

カメラのプレビューを停止します。

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

await CameraPreview.stop();

`capture`

カメラから写真を撮ります。

もし storeToFile __CAPGO_KEEP_0__ true __CAPGO_KEEP_0__が value __CAPGO_KEEP_0__のとき、プレビューを開始したときに設定された__CAPGO_KEEP_0__が絶対ファイルパスであるデバイスのファイルパスに代わってbase64文字列として返されます。__CAPGO_KEEP_0__からbase64文字列を取得するにはgetBase64FromFilePathを使用してください。

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

await CameraPreview.capture({} as CameraPreviewPictureOptions);

`captureSample`

__CAPGO_KEEP_1__

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

await CameraPreview.captureSample({} as CameraSampleOptions);

`getSupportedFlashModes`

__CAPGO_KEEP_4__

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

await CameraPreview.getSupportedFlashModes();

`setAspectRatio`

__CAPGO_KEEP_7__

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

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

`getAspectRatio`

__CAPGO_KEEP_10__

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

await CameraPreview.getAspectRatio();

`setGridMode`

カメラプレビューOverlayのグリッドモードを設定します。

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

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

`getGridMode`

カメラプレビューOverlayの現在のグリッドモードを取得します。

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

await CameraPreview.getGridMode();

`checkPermissions`

カメラ（およびオプションでマイク）許可の現在の状態を確認します。システムダイアログを提示せずに。

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

await CameraPreview.checkPermissions();

`requestPermissions`

カメラ（オプションでマイク）許可を要求します。許可が既に付与されたり拒否されたりしている場合は、現在の状態を返します。ダイアログを提示せずに。許可が拒否されている場合、trueの場合、プラットフォーム固有のアラートを提示してユーザーをアプリ設定に案内します。 showSettingsAlert セクション「requestPermissions」

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

await CameraPreview.requestPermissions();

`getHorizontalFov`

__CAPGO_KEEP_2__

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

await CameraPreview.getHorizontalFov();

`getSupportedPictureSizes`

__CAPGO_KEEP_4__

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

await CameraPreview.getSupportedPictureSizes();

`setFlashMode`

__CAPGO_KEEP_0__

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

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

`flip`

__CAPGO_KEEP_7__

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

await CameraPreview.flip();

`setOpacity`

__CAPGO_KEEP_2__

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

await CameraPreview.setOpacity({} as CameraOpacityOptions);

`stopRecordVideo`

__CAPGO_KEEP_4__

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

await CameraPreview.stopRecordVideo();

`startRecordVideo`

__CAPGO_KEEP_0__

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

await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

`isRunning`

__CAPGO_KEEP_7__

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

await CameraPreview.isRunning();

`getAvailableDevices`

__CAPGO_KEEP_2__

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

await CameraPreview.getAvailableDevices();

`getZoom`

__CAPGO_KEEP_2__、最小値/最大値および現在のレンズ情報を含む

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

await CameraPreview.getZoom();

`getZoomButtonValues`

__CAPGO_KEEP_2__、ズームボタンの値を取得します。iOS/Android: 超広角が利用可能な場合に0.5を含み、広角が利用可能な場合に1と2を含み、望遠レンズが利用可能な場合に3を含みます。Web: 不対応

__CAPGO_KEEP_0__']}
iOS/Android: 0.5が超広角が利用可能な場合、1と2が広角が利用可能な場合、3が望遠レンズが利用可能な場合に含まれます。Web: 不対応です。

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

await CameraPreview.getZoomButtonValues();

`setZoom`

カメラのズームレベルを設定します。

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

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

`getFlashMode`

現在のフラッシュモードを取得します。

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

await CameraPreview.getFlashMode();

`setDeviceId`

指定されたIDのカメラに切り替えます。 deviceId.

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

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

`getDeviceId`

現在使用されているカメラデバイスのIDを取得します。 Androidの場合、物理レンズのリクエストが論理カメラにフォールバックした場合、このIDは論理カメラのIDになります。

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

await CameraPreview.getDeviceId();

`getPreviewSize`

現在のプレビューサイズと位置を取得します。

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

await CameraPreview.getPreviewSize();

`setPreviewSize`

プレビューサイズと位置を設定します。

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

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

`setFocus`

プレビュー内で特定のポイントにカメラの焦点を設定します。

注意: プラグインは、タップで焦点を合わせるジェスチャーハンドラーをネイティブに追加しません。HTML/JS (例:Overlay UI) でタップを処理し、ここに正規化された座標を渡してください。

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

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

`deleteFile`

デバイス上の絶対パスで指定されたファイルを削除します。このメソッドを使用して、プレビューで作成された一時的な画像を迅速に削除できます。 storeToFile. ウェブではサポートされていません。

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

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

`getSafeAreaInsets`

端末の安全なエリアのインセットを取得します。端末の向きに応じたノッチ/カメラカットアウトのインセットと現在の向きを返します。ポートレートモードの場合：上部のインセット（上部のノッチ）を返します。ランドスケープモードの場合：左側のインセット（ノッチが側面に移動）を返します。この機能は、すべてのモダン端末が持つカットアウトエリア（ノッチ、パンチホールなど）を特定的にターゲットしています。

Android: dp (論理ピクセル) で返される値。 iOS: ステータスバーを除いた物理ピクセルで返される値（純粋なノッチ/カットアウトサイズのみ）。

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

await CameraPreview.getSafeAreaInsets();

`getOrientation`

端末の現在の向きをクロスプラットフォーム形式で取得します。

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

await CameraPreview.getOrientation();

`getExposureModes`

現在のアクティブカメラでサポートされている露光モードを返します。モードには ‘locked’、 ‘auto’、 ‘continuous’、 ‘custom’ が含まれます。

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

await CameraPreview.getExposureModes();

`getExposureMode`

現在の露出モードを取得します。

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

await CameraPreview.getExposureMode();

`setExposureMode`

露出モードを設定します。

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

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

`getExposureCompensationRange`

露出補償（EVバイアス）サポート範囲を取得します。

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

await CameraPreview.getExposureCompensationRange();

`getExposureCompensation`

現在の露出補償（EVバイアス）を取得します。

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

await CameraPreview.getExposureCompensation();

`setExposureCompensation`

EV補償値 (EVバイアス) を設定します。値は範囲内に圧縮されます。

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

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

タイプリファレンス

`CameraPreviewOptions`

カメラプレビューを開始するための構成オプションを定義します。

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`

写真を撮るためのオプションを定義します。

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`

EXIFデータを画像から抽出したものを表します。

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

`CameraSampleOptions`

サンプルフレームをキャプチャするためのカメラプレビューのオプションを定義します。

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

`CameraPreviewFlashMode`

カメラの利用可能なフラッシュモードです。 ‘torch’ は連続光モードです。

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`

特定の方向に向いたカメラのサポートされたピクチャサイズを表します。

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

`CameraOpacityOptions`

コピーをクリップボード

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

`CameraDevice`

レンズに関する情報を表します。

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`

現在のアクティブなレンズの詳細情報を表します。

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

真実の源

このページはプラグインの src/definitions.tsAPIがアップストリームで変更された場合に再度同期を実行してください。

「Getting Started」から続けてください。

「Getting Started」を使用して、ネイティブのメディアとインターフェイスの動作を計画している場合、 「@__CAPGO_KEEP_0__/camera-preview」を接続してください。 「Getting Started」を使用しています。 Using @capgo/camera-preview capgo/カメラプレビューのネイティブ機能を使用するために capgo/capacitor-ライブアクティビティを使用する capgo/capacitor-ライブアクティビティのネイティブ機能を使用するために capgo/capacitor-ライブアクティビティ capgo/capacitor-ライブアクティビティの実装詳細 capgo/capacitor-ビデオプレーヤーを使用する capgo/capacitor-ビデオプレーヤーのネイティブ機能を使用するために capgo/capacitor-ビデオプレーヤー capgo/capacitor-ビデオプレーヤーの実装詳細

Getting Started

インストール

インポート

API オーバービュー

start

stop

capture

captureSample

getSupportedFlashModes

setAspectRatio

getAspectRatio

setGridMode

getGridMode

checkPermissions

requestPermissions

getHorizontalFov

getSupportedPictureSizes

setFlashMode

flip

setOpacity

stopRecordVideo

startRecordVideo

isRunning

getAvailableDevices

getZoom

getZoomButtonValues

setZoom

getFlashMode

setDeviceId

getDeviceId

getPreviewSize

setPreviewSize

setFocus

deleteFile

getSafeAreaInsets

getOrientation

getExposureModes

getExposureMode

setExposureMode

getExposureCompensationRange

getExposureCompensation

setExposureCompensation

タイプ リファレンス

CameraPreviewOptions

CameraPreviewPictureOptions

ExifData

CameraSampleOptions

CameraPreviewFlashMode

GridMode

PermissionRequestOptions

CameraPermissionStatus

SupportedPictureSizes

CameraOpacityOptions

CameraDevice

LensInfo

真実の源

「Getting Started」から続けてください。

`start`

`stop`

`capture`

`captureSample`

`getSupportedFlashModes`

`setAspectRatio`

`getAspectRatio`

`setGridMode`

`getGridMode`

`checkPermissions`

`requestPermissions`

`getHorizontalFov`

`getSupportedPictureSizes`

`setFlashMode`

`flip`

`setOpacity`

`stopRecordVideo`

`startRecordVideo`

`isRunning`

`getAvailableDevices`

`getZoom`

`getZoomButtonValues`

`setZoom`

`getFlashMode`

`setDeviceId`

`getDeviceId`

`getPreviewSize`

`setPreviewSize`

`setFocus`

`deleteFile`

`getSafeAreaInsets`

`getOrientation`

`getExposureModes`

`getExposureMode`

`setExposureMode`

`getExposureCompensationRange`

`getExposureCompensation`

`setExposureCompensation`

タイプリファレンス

`CameraPreviewOptions`

`CameraPreviewPictureOptions`

`ExifData`

`CameraSampleOptions`

`CameraPreviewFlashMode`

`GridMode`

`PermissionRequestOptions`

`CameraPermissionStatus`

`SupportedPictureSizes`

`CameraOpacityOptions`

`CameraDevice`

`LensInfo`