跳过内容
Capgo - 实时更新 Capacitor 应用程序 Capgo

相机预览 __CAPGO_KEEP_0__ 仓库

GitHub

安装

标题为“安装”

您可以使用我们的 AI 助手来安装插件。将 Capgo 技能添加到您的 AI 工具中，使用以下命令：

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

然后使用以下提示：

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

如果您更喜欢手动设置，请运行以下命令安装插件，并按照以下平台特定的说明进行操作：

终端窗口
bun add @capgo/camera-preview
bunx cap sync

导入

标题为“导入”的部分
import { CameraPreview } from '@capgo/camera-preview';

API概述

标题为“API概述”的部分

start

标题为“start”的部分

启动相机预览。

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


await CameraPreview.start({} as CameraPreviewOptions);

stop

Section titled “stop”

停止预览

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


await CameraPreview.stop();

capture

Section titled “capture”

拍摄照片

If storeToFile was set to true when starting the preview, the returned value will be an absolute file path on the device instead of a base64 string. Use getBase64FromFilePath to get the base64 string from the file path.

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


await CameraPreview.capture({} as CameraPreviewPictureOptions);

captureSample

Section titled “captureSample”

捕获单帧

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


await CameraPreview.captureSample({} as CameraSampleOptions);

getSupportedFlashModes

标题："getSupportedFlashModes"

获取当前激活相机支持的闪光模式。

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


await CameraPreview.getSupportedFlashModes();

setAspectRatio

标题："setAspectRatio"

设置相机预览的分辨率比例。

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


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

getAspectRatio

标题："getAspectRatio"

获取相机预览当前的分辨率比例。

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


await CameraPreview.getAspectRatio();

setGridMode

标题："setGridMode"

设置相机预览覆盖层的网格模式。

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


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

getGridMode

标题：获取网格模式

获取相机预览覆盖层的当前网格模式。

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


await CameraPreview.getGridMode();

checkPermissions

标题：检查权限

检查当前相机（可选微型话筒）权限状态，不会弹出系统对话框。

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


await CameraPreview.checkPermissions();

requestPermissions

标题：请求权限

请求相机（可选微型话筒）权限。如果权限已经被授予或拒绝，当前状态会返回而不会弹出对话框。当 showSettingsAlert is true 且权限被拒绝时，会弹出一个平台特定的提示，指导用户到应用设置。

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


await CameraPreview.requestPermissions();

getHorizontalFov

标题：获取水平视野

获取当前激活相机的水平视野。 注意：在某些设备上，这可能是一个估计值。

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


await CameraPreview.getHorizontalFov();

getSupportedPictureSizes

标题：getSupportedPictureSizes

获取所有相机支持的图片尺寸。

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


await CameraPreview.getSupportedPictureSizes();

setFlashMode

标题：setFlashMode

设置当前激活相机的闪光模式。

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


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

flip

标题：flip

切换前置和后置摄像头。

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


await CameraPreview.flip();

setOpacity

标题：setOpacity

设置摄像头预览的不透明度。

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


await CameraPreview.setOpacity({} as CameraOpacityOptions);

stopRecordVideo

标题：停止录制视频

停止正在进行的视频录制。

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


await CameraPreview.stopRecordVideo();

startRecordVideo

标题：开始录制视频

开始录制视频。

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


await CameraPreview.startRecordVideo({} as CameraPreviewOptions);

isRunning

标题：是否正在运行

检查摄像头预览是否正在运行。

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


await CameraPreview.isRunning();

getAvailableDevices

标题：获取可用设备

获取所有可用的摄像头设备。

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


await CameraPreview.getAvailableDevices();

getZoom

标题：getZoom

获取当前的缩放状态，包括最小值/最大值和当前镜头信息。

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


await CameraPreview.getZoom();

getZoomButtonValues

标题：getZoomButtonValues

快速切换缩放按钮值。

  • iOS/Android：包含超广角可用时的 0.5；宽广角可用时的 1 和 2；望远镜可用时的 3
  • Web：不支持
import { CameraPreview } from '@capgo/camera-preview';


await CameraPreview.getZoomButtonValues();

setZoom

标题：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

获取当前绑定的摄像头设备ID。 在Android上，如果物理镜头请求 fallback 到逻辑摄像头，这将返回绑定的逻辑摄像头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（例如，覆盖的UI）中处理触摸，然后将标准化坐标传递到此处。

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


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

deleteFile

标题：删除文件

删除设备上的给定绝对路径上的文件。 使用此功能快速清理使用 storeToFile创建的临时图像。 在Web上，这项功能不受支持并将抛出异常。

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


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

getSafeAreaInsets

Section titled “getSafeAreaInsets”

获取安全区域边距

获取安全区域边距的值。 返回根据方向的凹槽/摄像头切口内边距和当前方向。 在竖屏模式下：返回顶部内边距（顶部凹槽）。 在横屏模式下：返回左侧内边距（凹槽移动到侧面）。 这特别针对所有现代手机都有的切口区域（凹槽，孔洞等）。

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


await CameraPreview.getSafeAreaInsets();

getOrientation

复制到剪贴板

Section titled “getOrientation”

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


await CameraPreview.getOrientation();

getExposureModes

复制到剪贴板

Section titled “getExposureModes”

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


await CameraPreview.getExposureModes();

getExposureMode

复制到剪贴板

Section titled “getExposureMode”

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


await CameraPreview.getExposureMode();

setExposureMode

《setExposureMode》

设置曝光模式。

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


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

getExposureCompensationRange

《getExposureCompensationRange》

获取支持的曝光补偿范围（EV偏差）。

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


await CameraPreview.getExposureCompensationRange();

getExposureCompensation

《getExposureCompensation》

获取当前曝光补偿（EV偏差）。

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


await CameraPreview.getExposureCompensation();

setExposureCompensation

《setExposureCompensation》

设置曝光补偿（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数据部分

从图像中提取的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

[Section titled “SupportedPictureSizes”]

[Represents the supported picture sizes for a camera facing a certain direction.]

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

CameraOpacityOptions

[Section titled “CameraOpacityOptions”]

[Defines the options for setting the camera preview’s opacity.]

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

CameraDevice

[Section titled “CameraDevice”]

[Represents a physical camera on the device (e.g., the front-facing camera).]

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

[Section titled “LensInfo”]

[Represents the detailed information of the currently active lens.]

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 Of Truth

Section titled “Source Of Truth”

本页面由插件生成 src/definitions.ts当公共API上游发生变化时，请重新同步。

从开始

Section titled “Keep going from Getting Started”

如果您正在使用 开始 来规划原生媒体和界面行为，连接它与 使用@capgo/camera-preview 为在使用@capgo/camera-preview中native能力的 使用@capgo/capacitor-live-activities 为native能力在使用@capgo/capacitor-live-activities中, @capgo/capacitor-live-activities 为实现细节在@capgo/capacitor-live-activities中, 使用@capgo/capacitor-video-player 为native能力在使用@capgo/capacitor-video-player, @capgo/capacitor-video-player 为实现细节在@capgo/capacitor-video-player中,