概览
“概览”章节@capgo/camera-preview 渲染一个 原生相机图层 位于 WebView 后方或上方，支持实时预览、静态拍照、闪光灯控制、宽高比及可选的 条码扫描。无需跳转至系统相机应用，即可构建扫码支付、AR 风格叠加层、自定义快门 UX 及视觉工作流。
配合 @capgo/capacitor-uploader 使用，可直接从磁盘路径上传拍摄内容，无需在 JavaScript 中加载完整的 Buffer。
平台支持
标题为“平台支持”的部分| 平台 | 备注 |
|---|---|
| iOS | 支持多摄像头设备、捏合缩放，并通过原生扫描器支持多种条码格式 |
| Android | 支持 CameraX 预览，可配置拍摄分辨率 |
| Web 端 | 支持有限，请查看插件 README 以了解当前 Web 端支持情况 |
核心功能
标题为“核心功能”的章节start- 启动相机预览。stop- 停止相机预览。capture- 使用相机拍摄照片。captureSample- 从相机预览流中截取单帧画面。
公开 API
标题为“公开 API”的章节| 方法 | 描述 |
|---|---|
start | 启动相机预览。 |
stop | 停止相机预览。 |
capture | 使用相机拍摄照片。 |
captureSample | 从相机预览流中截取单帧。 |
getSupportedFlashModes | 获取当前相机支持的闪光灯模式。 |
setAspectRatio | 设置相机预览的宽高比。 |
getAspectRatio | 获取相机预览当前的宽高比。 |
setGridMode | 设置相机预览叠加层的网格模式。 |
getGridMode | 获取相机预览叠加层当前的网格模式。 |
checkPermissions | 在不弹出系统对话框的情况下，检查当前摄像头（以及可选的麦克风）权限状态。 |
requestPermissions | 请求相机（及可选的麦克风）权限。如果权限已被授予或拒绝，则直接返回当前状态，不会弹出提示。当 showSettingsAlert 为 true 且权限被拒绝时，会弹出平台特定的提示框，引导用户前往应用设置。 |
getHorizontalFov | 获取当前活动相机的水平视场角 (FOV)。注意：在某些设备上这可能是一个估算值。 |
getSupportedPictureSizes | 获取所有相机支持的照片尺寸。 |
setFlashMode | 设置当前活动相机的闪光灯模式。 |
flip | 切换前置和后置摄像头。 |
setOpacity | 设置相机预览的透明度。 |
stopRecordVideo | 停止正在进行的视频录制。 |
startRecordVideo | 开始录制视频。 |
isRunning | 检查相机预览当前是否正在运行。 |
getAvailableDevices | 获取所有可用的相机设备。 |
getZoom | 获取当前的缩放状态，包括最小/最大倍数及当前镜头信息。 |
getZoomButtonValues | 返回用于快速切换的缩放按钮值。- iOS/Android：若支持超广角则包含 0.5；若支持广角则包含 1 和 2；若支持长焦则包含 3 - Web：不支持。 |
setZoom | 设置摄像头的缩放倍数。 |
getFlashMode | 获取当前的闪光灯模式。 |
removeAllListeners | 移除所有已注册的监听器。 |
setDeviceId | 将当前激活的摄像头切换至指定的 deviceId. |
getDeviceId | 获取当前绑定的摄像头设备 ID。在 Android 上，如果物理镜头请求回退到逻辑摄像头，则返回绑定的逻辑摄像头 ID。 |
getPreviewSize | 获取当前的预览尺寸和位置。 |
setPreviewSize | 设置预览尺寸和位置。 |
setFocus | 将相机对焦点设置到预览画面中的指定位置。 |
addListener | 添加屏幕尺寸变化事件的监听器。 |
addListener | 添加方向变化事件的监听器。 |
deleteFile | Deletes a file at the given absolute path on the device. Use this to quickly clean up temporary images created with storeToFileWeb 端暂不支持此功能，调用时会报错。 |
getSafeAreaInsets | 获取设备的安全性区域（safe area）内边距。返回与屏幕方向相关的刘海/摄像头挖孔内边距及当前方向。在竖屏模式下：返回顶部内边距（刘海在顶部）。在横屏模式下：返回左侧内边距（刘海移至侧边）。该功能专门针对现代手机普遍存在的挖孔区域（刘海、挖孔屏等）。 |
getOrientation | 以跨平台格式获取当前设备的屏幕方向。 |
getExposureModes | 返回当前活动摄像头支持的曝光模式。模式包括：‘locked’、‘auto’、‘continuous’、‘custom’。 |
getExposureMode | 返回当前的曝光模式。 |
setExposureMode | 设置曝光模式。 |
getExposureCompensationRange | 返回支持的曝光补偿 (EV bias) 范围。 |
getExposureCompensation | 返回当前的曝光补偿 (EV bias)。 |
setExposureCompensation | 设置曝光补偿 (EV bias)。数值将被限制在有效范围内。 |
getPluginVersion | 获取原生 Capacitor 插件版本。 |
参考值
标题为“参考值”的章节使用以下值从 CameraLens.deviceType 或 LensInfo.deviceType 来选择物理摄像头镜头。
设备类型
标题为“设备类型”的部分| 值 | 用户会发现 |
|---|---|
ultraWide | 超广角摄像头镜头。 |
wideAngle | 标准广角摄像头镜头。 |
telephoto | 长焦摄像头镜头。 |
trueDepth | TrueDepth 前置摄像头。 |
dual | 双摄系统。 |
dualWide | 双广角摄像头系统。 |
triple | 三摄系统。 |
单一事实来源
标题为“单一事实来源”的部分此参考文档同步自 src/definitions.ts 中的 capacitor-camera-preview.
继续探索 @capgo/camera-preview
标题为“继续探索 @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 时的原生能力，以及 @capgo/capacitor-video-player 关于 @capgo/capacitor-video-player. 中的实现细节
