Guía
Cómo usar Camera Preview en Capacitor
Usando @capgo/camera-preview
La interfaz principal para el plugin CameraPreview.
Instalar
bun add @capgo/camera-preview
bunx cap sync
bunx cap sync copia el code nativo del plugin en tus proyectos nativos. Ejecútalo de nuevo tras cada actualización del plugin.
Importar
import { CameraPreview } from '@capgo/camera-preview';
API de un vistazo
| Método | Descripción |
|---|---|
start |
Inicia la vista previa de la cámara. |
stop |
Detiene la vista previa de la cámara. |
capture |
Captura una foto con la cámara. |
captureSample |
Captura un frame del stream de la vista previa de la cámara. |
startBarcodeScanner |
Inicia el escaneo de códigos de barras en la vista previa de cámara activa. |
stopBarcodeScanner |
Detiene el escaneo de códigos de barras sin detener la vista previa de la cámara. |
getSupportedFlashModes |
Obtiene los modos de flash compatibles con la cámara activa. |
setAspectRatio |
Set the aspect ratio of the camera preview. |
getAspectRatio |
Obtiene la relación de aspecto actual de la vista previa de la cámara. |
setGridMode |
Sets the grid mode of the camera preview overlay. |
getGridMode |
Obtiene el modo de cuadrícula actual del overlay de la vista previa de la cámara. |
checkPermissions |
Comprueba el estado de los permisos de la cámara (y opcionalmente del micrófono) sin mostrar el diálogo del sistema. |
requestPermissions |
Solicita permisos de cámara (y micrófono opcional). Si ya han sido concedidos o denegados, devuelve el estado actual sin preguntar. Cuando showSettingsAlert si es true y se deniegan los permisos, se mostrará una alerta específica de la plataforma para guiar al usuario a los ajustes de la app. |
getHorizontalFov |
Obtiene el campo de visión (FoV) horizontal de la cámara activa. Nota: En algunos dispositivos esto puede ser una estimación. |
getSupportedPictureSizes |
Obtiene los tamaños de imagen compatibles para todas las cámaras. |
setFlashMode |
Configura el modo de flash para la cámara activa. |
flip |
Cambia entre la cámara frontal y la trasera. |
setOpacity |
Establece la opacidad de la vista previa de la cámara. |
stopRecordVideo |
Detiene una grabación de video en curso. |
startRecordVideo |
Inicia la grabación de un video. |
setVideoQuality |
Configura la calidad de grabación de video para la sesión de cámara activa. |
getVideoQuality |
Obtiene la calidad de grabación de video actual. |
getSupportedVideoQualities |
Devuelve las calidades de video soportadas por la cámara activa. |
setVideoCodec |
Establece el codec de video usado al grabar. |
getVideoCodec |
Obtiene el codec de video actual usado para grabar. |
getSupportedVideoCodecs |
Devuelve los codecs de video soportados por la cámara activa. |
isVideoStabilizationSupported |
Comprueba si la cámara activa soporta estabilización de video. |
getSupportedVideoStabilizationModes |
Devuelve los modos de estabilización de video soportados por la cámara activa. |
getVideoStabilizationMode |
Obtiene el modo de estabilización de video actual. |
setVideoStabilizationMode |
Establece el modo de estabilización de video para la grabación. No se puede cambiar durante una grabación. También puedes pasar videoStabilizationMode en startRecordVideo() opciones. |
isRunning |
Comprueba si la vista previa de la cámara está en ejecución. |
getAvailableDevices |
Gets all available camera devices. |
getZoom |
Obtiene el estado actual del zoom, incluyendo min/max e info de la lente actual. |
getZoomButtonValues |
Devuelve los valores de los botones de zoom para cambiar rápido. - iOS/Android: incluye 0.5 si hay ultra gran angular; 1 y 2 si hay gran angular; 3 si hay teleobjetivo - Web: no soportado. |
setZoom |
Establece el nivel de zoom de la cámara. |
getFlashMode |
Obtiene el modo de flash actual. |
setDeviceId |
Cambia la cámara activa a la que tenga el deviceId. |
getDeviceId |
Obtiene el ID del dispositivo de cámara vinculado actualmente. En Android, si una petición de lente física recurre a una cámara lógica, devuelve el ID de la cámara lógica vinculada. |
getPreviewSize |
Obtiene el tamaño y la posición actuales de la vista previa. |
setPreviewSize |
Sets the preview size and position. |
setFocus |
Enfoca la cámara en un punto específico de la vista previa. |
deleteFile |
Elimina un archivo en la ruta absoluta indicada en el dispositivo. Úsalo para limpiar rápido las imágenes temporales creadas con storeToFile. En web, esto no está soportado y lanzará un error. |
getSafeAreaInsets |
Obtiene los safe area insets del dispositivo. Devuelve el inset del notch/recorte de cámara según la orientación y la orientación actual. En portrait: devuelve el inset superior (notch arriba). En landscape: devuelve el inset izquierdo (notch al lado). Se centra en el área de recorte (notch, punch hole, etc.) que tienen todos los móviles modernos. |
getOrientation |
Obtiene la orientación actual del dispositivo en un formato multiplataforma. |
getExposureModes |
Devuelve los modos de exposición compatibles con la cámara activa. Los modos pueden ser: 'locked', 'auto', 'continuous', 'custom'. |
getExposureMode |
Devuelve el modo de exposición actual. |
setExposureMode |
Establece el modo de exposición. |
getExposureCompensationRange |
Devuelve el rango de compensación de exposición (sesgo EV) compatible. |
getExposureCompensation |
Devuelve la compensación de exposición actual (sesgo EV). |
setExposureCompensation |
Establece la compensación de exposición (sesgo EV). El valor se ajustará al rango. |
getWhiteBalanceModes |
Devuelve los modos de balance de blancos compatibles con la cámara activa. Los modos pueden ser: 'AUTO', 'LOCK', 'CONTINUOUS'. CUSTOM no aparece en la lista hasta que se implemente el soporte manual. |
getWhiteBalanceMode |
Devuelve el modo de balance de blancos actual. |
setWhiteBalanceMode |
Establece el modo de balance de blancos. CONTINUOUS mantiene activo el balance de blancos automático (recomendado; evita tonos cálidos/amarillentos), LOCK congela las ganancias actuales, AUTO realiza un ajuste único. CUSTOM está reservado y será rechazado hasta que se implemente el soporte manual. |
getSupportedVideoFrameRates |
Lista las tasas de fotogramas de video compatibles con la cámara activa para el formato actual. Los valores compatibles dependen de la cámara, el lente y la calidad de video seleccionados. |
getVideoFrameRate |
Devuelve la tasa de fotogramas de video configurada para la cámara activa. En Android, la tasa de fotogramas de grabación real puede variar con poca luz o bajo presión térmica. |
setVideoFrameRate |
Establece la tasa de fotogramas (FPS) de la sesión de cámara activa. Se recomienda pasar frameRate a startRecordVideo() al iniciar una grabación. Rechaza los valores no compatibles con un error claro. |
Ejemplos
start()
Inicia la vista previa de la cámara.
import { CameraPreview } from '@capgo/camera-preview';
const result = await CameraPreview.start({ parent: 'parent' });
console.log(result);
stop()
Detiene la vista previa de la cámara.
import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.stop();
capture()
Captura una foto con la cámara.
import { CameraPreview } from '@capgo/camera-preview';
const result = await CameraPreview.capture({ height: 1920 });
console.log(result);
captureSample()
Captura un frame del stream de la vista previa de la cámara.
import { CameraPreview } from '@capgo/camera-preview';
const result = await CameraPreview.captureSample({
quality: 85,
mirrorFrontCamera: false,
});
console.log(result);
startBarcodeScanner()
Inicia el escaneo de códigos de barras en la vista previa de cámara activa.
import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.startBarcodeScanner();
stopBarcodeScanner()
Detiene el escaneo de códigos de barras sin detener la vista previa de la cámara.
import { CameraPreview } from '@capgo/camera-preview';
await CameraPreview.stopBarcodeScanner();
La tabla anterior enumera los 56 métodos principales. Los helpers de versión y listeners, así como el contrato completo de cada método, están documentados en la repositorio de GitHub.
Escuchar eventos
addListener devuelve un handle. Llama a handle.remove() cuando la pantalla se desmonte, o CameraPreview.removeAllListeners() para limpiar todos los listeners.
Referencia completa
Continuar desde Uso de @capgo/camera-preview
Si estás usando Uso de @capgo/camera-preview para planificar el comportamiento de la interfaz y medios nativos, conéctalo con @capgo/camera-preview para los detalles de implementación en @capgo/camera-preview, Primeros pasos para los detalles de implementación en Primeros pasos, Uso de @capgo/capacitor-live-activities para la capacidad nativa en Uso de @capgo/capacitor-live-activities, @capgo/capacitor-live-activities para el detalle de implementación en @capgo/capacitor-live-activities, y Uso de @capgo/capacitor-video-player para la capacidad nativa en Uso de @capgo/capacitor-video-player.