npm - @yqzk/liveness-detection-web-component - Versions diffs - 1.0.0 - Mend

@yqzk/liveness-detection-web-component 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,30 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.0.0] - 2025-11-10
+### Added
+- 初始版本发布
+- 标准 Web Component 实现
+- 支持活体检测核心功能
+- 支持自定义主题和样式
+- 多语言支持（中文/英文）
+- TypeScript 类型定义
+- ES Module 和 UMD 格式支持
+- 完整的事件系统
+### Features
+- 实时人脸检测
+- 活体动作验证
+- 自动超时处理
+- 错误重试机制
+- 响应式设计
+### Documentation
+- 完整的 API 文档
+- 使用示例（HTML/React/Vue）
+- 浏览器兼容性说明

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Liaoning YQZK Team
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,350 @@
+# @liveness-detection/web-component
+活体检测 Web Component - 标准 Web 组件，可集成到任何前端框架。
+## 特性
+- 🎯 标准 Web Component，无框架依赖
+- 📦 支持 ES Module 和 UMD 格式
+- 🎨 样式内置，无需额外 CSS 文件
+- 📱 响应式设计，自适应各种屏幕
+- 🌐 完整的 TypeScript 类型支持
+- ⚡ 自动预热，快速启动
+## 安装
+```bash
+npm install @liveness-detection/web-component
+```
+## 快速开始
+### 在 HTML 中使用
+```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 '@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 中使用
+```tsx
+import { useEffect, useRef } from 'react';
+import '@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 中使用
+```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 '@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 格式（浏览器直接引入）
+```html
+<!DOCTYPE html>
+<html>
+<body>
+  <liveness-detector id="detector"></liveness-detector>
+  <!-- 直接引入 UMD 文件 -->
+  <script src="node_modules/@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 文档
+### 配置接口
+```typescript
+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)
+```typescript
+// 初始化检测器
+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 }` |
+### 类型定义
+```typescript
+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 变量覆盖：
+```css
+liveness-detector {
+  --ld-primary-color: #007bff;
+  --ld-border-radius: 8px;
+  /* 更多变量... */
+}
+```
+## 浏览器支持
+- Chrome >= 90
+- Firefox >= 88
+- Safari >= 14
+- Edge >= 90
+- 支持 Web Components 的现代浏览器
+## 许可证
+MIT License
+## 支持
+如有问题，请提交 [Issue](https://github.com/your-org/liveness-detection/issues)

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * 活体检测Web Component入口文件
+ * 导出所有公共API和类型定义
+ */
+export { LivenessDetector } from './LivenessDetector';
+export type { LivenessDetectorConfig, DetectionStartEvent, DetectionProgressEvent, DetectionCompleteEvent, DetectionErrorEvent } from './LivenessDetector';
+export { createLivenessDetector } from './utils/factory';
+export { validateConfig } from './utils/validation';
+export { DEFAULT_CONFIG } from './constants';
+export declare const VERSION: string;
+declare global {
+    interface HTMLElementTagNameMap {
+        'liveness-detector': import('./LivenessDetector').LivenessDetector;
+    }
+}