extension-camera

摄像头

Caffeine AI 的摄像头扩展。

概述

此技能通过预制的 React hook 提供网络摄像头访问。支持拍照、摄像头切换和错误处理。

前端

对于摄像头支持：

有一个预制的 React hook @caffeinelabs/camera/hooks/useCamera.ts，不可修改。

import { RefObject } from 'react';

export interface CameraConfig {
  // 摄像头朝向模式 - 'user' 为前置摄像头，'environment' 为后置摄像头
  facingMode?: 'user' | 'environment';
  // 理想的视频宽度和高度（像素）
  width?: number;
  height?: number;
  // 拍照图像质量（0-1，1 为最高质量）
  quality?: number;
  format?: 'image/jpeg' | 'image/png' | 'image/webp';
}

export interface CameraError {
  type: 'permission' | 'not-supported' | 'not-found' | 'unknown' | 'timeout';
  message: string;
}

export interface UseCameraReturn {
  // 摄像头是否当前处于活动状态并正在流式传输
  isActive: boolean;
  // 当前浏览器是否支持摄像头（检查中为 null）
  isSupported: boolean | null;
  // 当前错误状态（如果有）
  error: CameraError | null;
  // 摄像头是否正在初始化、启动、切换或停止
  isLoading: boolean;
  currentFacingMode: 'user' | 'environment';
  
  // 成功时返回 true
  startCamera: () => Promise<boolean>;
  stopCamera: () => Promise<void>;
  capturePhoto: () => Promise<File | null>;
  // 成功时返回 true
  switchCamera: () => (newFacingMode?: 'user' | 'environment') : Promise<boolean>;
  // 成功时返回 true
  retry: () => Promise<boolean>;
  
  // 附加到视频元素用于摄像头预览的 ref
  videoRef: RefObject<HTMLVideoElement>;
  // 用于拍照的 canvas 元素 ref（可隐藏）
  canvasRef: RefObject<HTMLCanvasElement>;
}

export declare function useCamera(config?: CameraConfig): UseCameraReturn;

使用示例：

import { useCamera } from '@caffeineai/camera';

function CameraComponent() {
    const { 
        isActive, 
        isSupported, 
        error, 
        isLoading,
        startCamera, 
        stopCamera, 
        capturePhoto,
        switchCamera,
        videoRef, 
        canvasRef 
    } = useCamera({ 
        autoStart: true,
        facingMode: 'environment' 
    });

    if (isSupported === false) {
        return <div>摄像头不受支持</div>;
    }

    return (
        <div>
            <video 
                ref={videoRef} 
                style={{ width: '100%', height: 'auto' }}
                playsInline
                muted
            />
            <canvas ref={canvasRef} style={{ display: 'none' }} />
            
            {error && <div>错误：{error.message}</div>}
            
            <div>
                <button onClick={startCamera} disabled={isLoading || isActive}>
                    启动摄像头
                </button>
                <button onClick={stopCamera} disabled={isLoading || !isActive}>
                    停止摄像头
                </button>
                <button onClick={switchCamera} disabled={isLoading || !isActive}>
                    切换摄像头
                </button>
                <button onClick={capturePhoto} disabled={!isActive}>
                    拍照
                </button>
            </div>
        </div>
    );
}

始终在摄像头预览上放置拍照按钮！
用户打开摄像头时始终显示摄像头预览
在桌面上，确保摄像头无法切换。只有 'environment' 模式有效。
在应用中正确显示摄像头错误消息。
在摄像头完全初始化并准备就绪之前，不要使摄像头按钮可点击。
确保摄像头预览具有明确的非零尺寸（固定高度、最小高度或宽高比包装器），以免因布局而折叠。
使预览在不同屏幕尺寸下响应（例如，width: 100% 配合稳定的宽高比）。