@yqzk/liveness-detection-web-component

v1.0.4

Published

a day ago

活体检测Web Component - 标准Web组件，可集成到任何前端框架

Downloads

218

0High
0Medium
0Low

chrisandy

liveness-detection web-component face-detection biometric authentication custom-element

@yqzk/liveness-detection-web-component

活体检测 Web Component - 标准 Web 组件，可集成到任何前端框架。

特性

标准 Web Component，无框架依赖
支持 ES Module 和 UMD 格式
样式内置，无需额外 CSS 文件
响应式设计，自适应各种屏幕
完整的 TypeScript 类型支持
自动预热，快速启动

安装

npm i @yqzk/liveness-detection-web-component

快速开始

在 HTML 中使用

<!DOCTYPE html>
<html>
<body>
  <!-- 1. 添加组件标签 -->
  <liveness-detector 
    api-endpoint="https://your-api.com"
    theme="light"
    language="zh">
  </liveness-detector>

  <!-- 2. 导入并使用 -->
  <script type="module">
    import '@yqzk/liveness-detection-web-component';
    
    const detector = document.querySelector('liveness-detector');
    
    // 初始化配置
    await detector.init({
      apiEndpoint: 'https://your-api.com',
      timeout: 60000
    });
    
    // 监听事件
    detector.addEventListener('detectionComplete', (e) => {
      console.log('检测成功:', e.detail);
    });
    
    detector.addEventListener('detectionError', (e) => {
      console.error('检测失败:', e.detail);
    });
    
    // 开始检测
    const result = await detector.detect();
  </script>
</body>
</html>

在 React 中使用

import { useEffect, useRef } from 'react';
import '@yqzk/liveness-detection-web-component';

function App() {
  const detectorRef = useRef<any>(null);

  useEffect(() => {
    const detector = detectorRef.current;
    
    // 初始化
    detector.init({
      apiEndpoint: 'https://your-api.com',
      timeout: 60000,
      theme: 'light'
    });
    
    // 监听事件
    const handleComplete = (e: CustomEvent) => {
      console.log('检测成功:', e.detail);
    };
    
    const handleError = (e: CustomEvent) => {
      console.error('检测失败:', e.detail);
    };
    
    detector.addEventListener('detectionComplete', handleComplete);
    detector.addEventListener('detectionError', handleError);
    
    return () => {
      detector.removeEventListener('detectionComplete', handleComplete);
      detector.removeEventListener('detectionError', handleError);
    };
  }, []);
  
  const startDetection = async () => {
    try {
      const result = await detectorRef.current.detect();
      console.log('检测结果:', result);
    } catch (error) {
      console.error('检测失败:', error);
    }
  };

  return (
    <div>
      <liveness-detector
        ref={detectorRef}
        api-endpoint="https://your-api.com"
        theme="light"
        language="zh"
      />
      <button onClick={startDetection}>开始检测</button>
    </div>
  );
}

在 Vue 中使用

<template>
  <div>
    <liveness-detector
      ref="detectorRef"
      api-endpoint="https://your-api.com"
      theme="light"
      language="zh"
      @detectionComplete="handleComplete"
      @detectionError="handleError"
    />
    <button @click="startDetection">开始检测</button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import '@yqzk/liveness-detection-web-component';

const detectorRef = ref<any>(null);

onMounted(async () => {
  // 初始化
  await detectorRef.value.init({
    apiEndpoint: 'https://your-api.com',
    timeout: 60000,
    theme: 'light'
  });
});

const handleComplete = (e: CustomEvent) => {
  console.log('检测成功:', e.detail);
};

const handleError = (e: CustomEvent) => {
  console.error('检测失败:', e.detail);
};

const startDetection = async () => {
  try {
    const result = await detectorRef.value.detect();
    console.log('检测结果:', result);
  } catch (error) {
    console.error('检测失败:', error);
  }
};
</script>

使用 UMD 格式（浏览器直接引入）

<!DOCTYPE html>
<html>
<body>
  <liveness-detector id="detector"></liveness-detector>

  <!-- 直接引入 UMD 文件 -->
  <script src="node_modules/@yqzk/liveness-detection-web-component/dist/index.umd.cjs"></script>
  
  <script>
    const detector = document.getElementById('detector');
    
    // 初始化
    detector.init({
      apiEndpoint: 'https://your-api.com'
    }).then(() => {
      console.log('初始化完成');
      
      // 开始检测
      return detector.detect();
    }).then(result => {
      console.log('检测成功:', result);
    }).catch(error => {
      console.error('检测失败:', error);
    });
  </script>
</body>
</html>

API 文档

配置接口

interface LivenessDetectorConfig {
  apiEndpoint: string;           // API 服务地址（必填）
  timeout?: number;               // 超时时间（毫秒），默认 60000
  retryCount?: number;            // 重试次数，默认 3
  modalMode?: boolean;            // 是否使用模态框模式
  theme?: 'light' | 'dark' | 'auto'; // 主题，默认 'auto'
  language?: string;              // 语言，默认 'zh-CN'
  enableFrameStorage?: boolean;   // 是否启用帧存储
  cameraConfig?: {
    width?: number;               // 摄像头宽度
    height?: number;              // 摄像头高度
    facingMode?: 'user' | 'environment'; // 摄像头方向
  };
  uiConfig?: {
    showProgress?: boolean;       // 是否显示进度
    showInstructions?: boolean;   // 是否显示指引
    enableSound?: boolean;        // 是否启用声音
  };
}

HTML 属性 (Attributes)

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | api-endpoint | string | 是 | API 服务地址 | | modal-mode | boolean | 否 | 是否使用模态框模式 | | theme | 'light' | 'dark' | 'auto' | 否 | 主题模式，默认 'auto' | | language | string | 否 | 语言，默认 'zh-CN' | | timeout | number | 否 | 超时时间（毫秒），默认 60000 | | retry-count | number | 否 | 重试次数，默认 3 |

方法 (Methods)

// 初始化检测器
await detector.init(config?: Partial<LivenessDetectorConfig>): Promise<void>

// 开始检测（返回检测结果）
await detector.detect(): Promise<DetectionResult>

// 停止检测
await detector.stop(): Promise<void>

// 反初始化（清理资源）
await detector.deinit(): Promise<void>

// 获取当前状态
detector.getStatus(): {
  initialized: boolean;
  detecting: boolean;
  sessionId: string | null;
  phase?: DetectionPhase;
  progress?: number;
}

事件 (Events)

| 事件名 | 说明 | 事件详情类型 | |--------|------|-------------| | initialized | 初始化完成 | { config: LivenessDetectorConfig } | | detectionStart | 检测开始 | DetectionStartEvent | | detectionProgress | 检测进度更新 | DetectionProgressEvent | | detectionComplete | 检测完成 | DetectionCompleteEvent | | detectionError | 检测错误 | DetectionErrorEvent | | detectionStopped | 检测停止 | { sessionId: string } |

类型定义

interface DetectionResult {
  success: boolean;
  confidence: number;
  timestamp: number;
  sessionId: string;
  // ... 更多字段
}

interface DetectionStartEvent {
  sessionId: string;
  config: DetectionConfig;
}

interface DetectionProgressEvent {
  sessionId: string;
  phase: DetectionPhase;
  progress: number;
  currentAction?: string;
  timeRemaining?: number;
}

interface DetectionCompleteEvent {
  sessionId: string;
  result: DetectionResult;
  duration: number;
}

interface DetectionErrorEvent {
  sessionId: string;
  error: string;
  code?: string;
  recoverable?: boolean;
}

样式说明

无需额外 CSS 文件！

样式已经内置在 JavaScript 中，通过 Shadow DOM 自动注入。组件会自动：

适配浅色/深色主题
响应式布局
继承父元素的 CSS 变量

如需自定义样式，可以通过 CSS 变量覆盖：

liveness-detector {
  --ld-primary-color: #007bff;
  --ld-border-radius: 8px;
  /* 更多变量... */
}

浏览器支持

Chrome >= 90
Firefox >= 88
Safari >= 14
Edge >= 90
支持 Web Components 的现代浏览器

许可证

MIT License

支持

如有问题，请提交问题到 [email protected]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@yqzk/liveness-detection-web-component

特性

安装

快速开始

在 HTML 中使用

在 React 中使用

在 Vue 中使用

使用 UMD 格式（浏览器直接引入）

API 文档

配置接口

HTML 属性 (Attributes)

方法 (Methods)

事件 (Events)

类型定义

样式说明

浏览器支持

许可证

支持