使用 @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.”中的原生能力