extension-camera

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% 搭配穩定的長寬比）。