跳转至正文

相机预览 Capacitor 插件

以叠加层形式显示实时摄像头画面,支持自定义控件和拍摄功能

安装

bun add @capgo/camera-preview bunx cap sync
npm、pnpm 或 yarn
  • npm install @capgo/camera-preview
  • pnpm add @capgo/camera-preview
  • yarn add @capgo/camera-preview

指南

如何在 Capacitor 中使用 Camera Preview

在设备上测试

下载 Capgo App,然后扫描二维码 code。

Camera Preview 插件预览二维码 code

使用 @capgo/camera-preview

CameraPreview 插件的主界面。

安装

bun add @capgo/camera-preview
bunx cap sync

bunx cap sync 将插件的原生 code 复制到你的原生项目中。每次升级插件后都要重新运行。

导入

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

API 概览

方法 描述
start 启动相机预览。
stop 停止相机预览。
capture 使用相机拍摄照片。
captureSample 从相机预览流中截取单帧。
startBarcodeScanner 在当前相机预览上启动条码扫描。
stopBarcodeScanner 停止条码扫描,但保持相机预览运行。
getSupportedFlashModes 获取当前相机支持的闪光灯模式。
setAspectRatio 设置相机预览的宽高比。
getAspectRatio 获取相机预览当前的宽高比。
setGridMode 设置相机预览叠加层的网格模式。
getGridMode 获取相机预览叠加层当前的网格模式。
checkPermissions 在不弹出系统对话框的情况下,检查当前摄像头(以及可选的麦克风)权限状态。
requestPermissions 请求相机(及可选的麦克风)权限。如果权限已被授予或拒绝,则直接返回当前状态,不会弹出提示。当 showSettingsAlert 为 true 且权限被拒绝时,会显示平台特定的弹窗,引导用户前往应用设置。
getHorizontalFov 获取当前摄像头的水平视场角(FoV)。注意:在某些设备上,此值可能为估算值。
getSupportedPictureSizes 获取所有相机支持的照片尺寸。
setFlashMode 设置当前活动相机的闪光灯模式。
flip 切换前置和后置摄像头。
setOpacity 设置相机预览的透明度。
stopRecordVideo 停止正在进行的视频录制。
startRecordVideo 开始录制视频。
setVideoQuality 设置当前摄像头会话的视频录制质量。
getVideoQuality 获取当前的视频录制质量。
getSupportedVideoQualities 返回当前摄像头支持的画质。
setVideoCodec 设置录制时使用的视频编码。
getVideoCodec 获取当前录制使用的视频编码。
getSupportedVideoCodecs 返回当前摄像头支持的视频编码。
isVideoStabilizationSupported 检查当前摄像头是否支持视频防抖。
getSupportedVideoStabilizationModes 返回当前摄像头支持的防抖模式。
getVideoStabilizationMode 获取当前的视频防抖模式。
setVideoStabilizationMode 设置录制时的视频防抖模式。录制过程中无法更改。您也可以传入 videoStabilizationMode 中的 startRecordVideo() 选项来指定自定义密钥。
isRunning 检查相机预览当前是否正在运行。
getAvailableDevices 获取所有可用的相机设备。
getZoom 获取当前的缩放状态,包括最小/最大倍数及当前镜头信息。
getZoomButtonValues 返回用于快速切换的变焦按钮值。- iOS/Android:如果支持超广角,则包含 0.5;如果支持广角,则包含 1 和 2;如果支持长焦,则包含 3 - Web:不支持。
setZoom 设置相机的变焦级别。
getFlashMode 获取当前闪光灯模式。
setDeviceId 将当前相机切换为具有指定 deviceId.
getDeviceId 获取当前绑定的相机设备 ID。在 Android 上,如果物理镜头请求回退到逻辑相机,则返回绑定的逻辑相机 ID。
getPreviewSize 获取当前预览的大小和位置。
setPreviewSize 设置预览的大小和位置。
setFocus 将相机对焦点设置到预览画面中的指定位置。
deleteFile 删除设备上给定绝对路径的文件。使用此方法可快速清理通过 storeToFile创建的临时图像。在 Web 上不支持此操作,并会抛出异常。
getSafeAreaInsets 获取设备的安全区域内边距。返回感知方向的刘海/摄像头挖孔内边距以及当前方向。在竖屏模式下:返回顶部内边距(刘海在顶部)。在横屏模式下:返回左侧内边距(刘海移至侧面)。这专门针对所有现代手机都存在的挖孔区域(刘海、打孔等)。
getOrientation 以跨平台格式获取当前设备方向。
getExposureModes 返回当前活动摄像头支持的曝光模式。模式可能包括:'locked'、'auto'、'continuous'、'custom'。
getExposureMode 返回当前的曝光模式。
setExposureMode 设置曝光模式。
getExposureCompensationRange 返回支持的曝光补偿 (EV bias) 范围。
getExposureCompensation 返回当前的曝光补偿 (EV bias)。
setExposureCompensation 设置曝光补偿 (EV bias)。数值将被限制在有效范围内。
getWhiteBalanceModes 返回当前活动摄像头支持的白平衡模式。模式可能包括:'AUTO'、'LOCK'、'CONTINUOUS'。 CUSTOM 在实现手动增益支持之前不会列出。
getWhiteBalanceMode 返回当前的白平衡模式。
setWhiteBalanceMode 设置白平衡模式。 CONTINUOUS 保持自动白平衡运行(推荐;可避免画面偏暖/偏黄), LOCK 锁定当前增益, AUTO 执行一次性调整。 CUSTOM 保留该值,在实现手动增益支持之前会被拒绝。
getSupportedVideoFrameRates 列出当前格式下活动摄像头支持的帧率。支持的值取决于所选摄像头、镜头和视频质量。
getVideoFrameRate 返回活动摄像头的已配置帧率。在 Android 上,低光或高温环境下实际录制帧率仍可能波动。
setVideoFrameRate 设置活动摄像头会话的目标帧率。建议传入 frameRate 改为 startRecordVideo() 开始录制时。不支持的值会被拒绝并返回明确错误。

示例

start()

启动相机预览。

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

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

stop()

停止相机预览。

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

await CameraPreview.stop();

capture()

使用相机拍摄照片。

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

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

captureSample()

从相机预览流中截取单帧。

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

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

startBarcodeScanner()

在当前相机预览上启动条码扫描。

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

await CameraPreview.startBarcodeScanner();

stopBarcodeScanner()

停止条码扫描,但保持相机预览运行。

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

await CameraPreview.stopBarcodeScanner();

上表列出了 56 个核心方法。监听器、版本辅助函数以及每个方法的完整契约,详见 GitHub 仓库.

监听事件

addListener 会返回一个句柄。调用 handle.remove() 在屏幕卸载时,或者调用 CameraPreview.removeAllListeners() 以清除所有监听器。

完整参考文档

继续阅读“使用 @capgo/camera-preview”

如果你正在使用 使用 @capgo/camera-preview 来规划原生媒体和界面行为,并将其与 @capgo/camera-preview 有关 @capgo/camera-preview 中的实现细节, 快速入门 有关“入门指南”中的实现细节, 使用 @capgo/capacitor-live-activities 用于使用 @capgo/capacitor-live-activities 时的原生能力, @capgo/capacitor-live-activities 关于 @capgo/capacitor-live-activities 中的实现细节,以及 使用 @capgo/capacitor-video-player 有关“使用 @capgo/capacitor-video-player.”中的原生能力

常见问题

Camera Preview 插件常见问题

如何在 Capacitor 应用中安装 Camera Preview 插件?

运行 "bun add @capgo/camera-preview"(或 "npm install @capgo/camera-preview"),然后运行 "bunx cap sync",以便 iOS 和 Android 项目获取原生 code。在您的应用 code 中从 "@capgo/camera-preview" 导入它。

@capgo/camera-preview 支持 React、Vue 和 Angular 吗?

是的。Camera Preview 是一个 Capacitor 包,因此它适用于任何在 Capacitor 内运行的 Web 框架,包括 Ionic、React、Vue、Angular、Svelte 和纯 JavaScript。

@capgo/camera-preview 支持哪个版本的 Capacitor?

Capgo 插件遵循 Capacitor 的主版本号:请使用与 Capacitor 主版本号一致的插件主版本(例如插件 v8 对应 Capacitor 8)。GitHub README 中的兼容性表列出了仍在维护的版本。

@capgo/camera-preview 是免费且开源的吗?

是的。code 源代码公开在 GitHub 上,地址为 https://github.com/Cap-go/capacitor-camera-preview/,并且可以从 npm 免费安装该包。欢迎提交 Bug 报告和 Pull Request。

我可以更新使用 Camera Preview 的 code 而无需经过 App Store 审核吗?

安装或升级插件会改动原生 code,因此需要重新做一次商店构建。之后,调用该插件的 JavaScript、HTML 和 CSS 改动就能通过 Capgo live updates 立即发布。

无需等待应用审核,即可发布 Camera Preview 更新

只要插件已包含在你的商店版本中,Capgo live updates 就能在几分钟内把 JavaScript、HTML 和 CSS 的改动推送给用户。

开始使用 Capgo