使用 @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 |
Deletes a file at the given absolute path on the device. Use this to quickly clean up temporary images created with storeToFile。在 Web 端不支持此操作并会抛出错误。 |
getSafeAreaInsets |
获取设备的 Safe Area Insets。返回感知方向的刘海/摄像头挖孔区域偏移量及当前方向。竖屏模式下：返回顶部偏移量（刘海在顶部）。横屏模式下：返回左侧偏移量（刘海移至侧边）。这专门针对现代手机普遍存在的挖孔区域（刘海、挖孔屏等）。 |
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.”中的原生能力