@zeewain/3d-avatar-sdk 1.2.1 → 1.2.2

package/dist/examples/test-vue2/src/components/UnityPreview.vue

@@ -0,0 +1,201 @@
+<template>
+  <el-card class="unity-preview" shadow="hover">
+    <div slot="header" class="card-header">
+      <span>Unity 预览</span>
+      <el-tag v-if="sdkStatus.unityLoaded" type="success" size="mini">已加载</el-tag>
+      <el-tag v-else type="info" size="mini">未加载</el-tag>
+    </div>
+
+    <div class="unity-container-wrapper">
+      <div id="unity-container" class="unity-container">
+        <div v-if="!sdkStatus.unityLoaded" class="unity-tip">
+          <i class="el-icon-monitor"></i>
+          <p>Unity 内容将在此处加载...</p>
+        </div>
+      </div>
+    </div>
+
+    <div class="unity-controls">
+      <el-button-group>
+        <el-button
+          type="warning"
+          size="small"
+          icon="el-icon-close"
+          :disabled="!sdkStatus.avatarLoaded"
+          @click="handleUnloadAvatar"
+        >
+          卸载Avatar
+        </el-button>
+        <el-button
+          type="danger"
+          size="small"
+          icon="el-icon-delete"
+          :disabled="!sdkStatus.unityLoaded"
+          @click="handleDestroySDK"
+        >
+          销毁实例
+        </el-button>
+      </el-button-group>
+    </div>
+
+    <!-- 加载进度显示 -->
+    <div v-if="loadingProgress > 0 && loadingProgress < 1" class="loading-progress">
+      <el-progress
+        :percentage="Math.round(loadingProgress * 100)"
+        :stroke-width="6"
+        text-inside
+      />
+      <p class="progress-text">Unity 加载中，请稍候...</p>
+    </div>
+  </el-card>
+</template>
+
+<script>
+export default {
+  name: 'UnityPreview',
+  props: {
+    sdkStatus: {
+      type: Object,
+      required: true,
+      default: () => ({
+        unityLoaded: false,
+        avatarLoaded: false
+      })
+    },
+    loadingProgress: {
+      type: Number,
+      default: 0
+    }
+  },
+  methods: {
+    handleUnloadAvatar () {
+      this.$emit('unload-avatar')
+    },
+
+    handleDestroySDK () {
+      this.$emit('destroy-sdk')
+    }
+  }
+}
+</script>
+
+<style lang="scss" scoped>
+// Unity预览
+.unity-preview {
+  position: relative;
+  display: flex;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  flex-direction: column;
+
+  .card-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    font-weight: 600;
+  }
+
+  :deep(.el-card__body) {
+    display: flex;
+    width: 100%;
+    height: 100%;
+    flex-direction: column;
+    box-sizing: border-box;
+  }
+
+  .unity-container-wrapper {
+    position: relative;
+    width: 100%;
+    max-height: 600px; // 添加最大高度限制
+    margin-bottom: 15px;
+    overflow: hidden; // 防止内容溢出
+    flex: 1;
+  }
+
+  .unity-container {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    max-height: 100%; // 确保不超过父容器
+    overflow: hidden;
+    background-color: #000;
+    border-radius: 4px;
+  }
+
+  .unity-tip {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    color: white; // 确保在黑色背景上文字可见
+    text-align: center;
+    transform: translate(-50%, -50%);
+
+    i {
+      margin-bottom: 10px;
+      font-size: 48px;
+    }
+
+    p {
+      margin: 0;
+      font-size: 14px;
+    }
+  }
+
+  .unity-controls {
+    display: flex;
+    justify-content: center;
+    padding-top: 10px;
+  }
+
+  .loading-progress {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    width: 80%;
+    transform: translate(-50%, -50%);
+    text-align: center;
+    z-index: 10;
+
+    .progress-text {
+      color: white;
+      margin-top: 10px;
+      font-size: 14px;
+    }
+  }
+}
+
+// 移动端优化
+@media screen and (width <= 768px) {
+  .unity-preview {
+    .unity-container-wrapper {
+      height: 250px;
+      max-height: 250px; // 确保移动端不会超过设定高度
+      flex: none;
+      overflow: hidden; // 防止内容溢出
+    }
+
+    .unity-controls {
+      .el-button-group {
+        display: flex;
+        flex-direction: column;
+
+        .el-button {
+          margin: 2px 0;
+        }
+      }
+    }
+  }
+}
+
+// 平板端优化
+@media screen and (width <= 992px) and (width > 768px) {
+  .unity-preview {
+    .unity-container-wrapper {
+      height: 300px; // 平板端适中高度
+      max-height: 300px; // 确保平板端不会超过设定高度
+      overflow: hidden; // 防止内容溢出
+    }
+  }
+}
+</style>

package/dist/examples/test-vue2/src/main.js

@@ -0,0 +1,16 @@
+import Vue from 'vue'
+import App from './App.vue'
+
+// 引入Element-UI
+import ElementUI from 'element-ui'
+import 'element-ui/lib/theme-chalk/index.css'
+
+// 使用Element-UI
+Vue.use(ElementUI)
+
+// 关闭生产提示
+Vue.config.productionTip = false
+
+new Vue({
+  render: h => h(App)
+}).$mount('#app')

package/dist/examples/test-vue2/vue.config.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Vue CLI 配置文件
+ * @description 支持本地开发和npm包两种模式的动态配置
+ */
+
+const { defineConfig } = require('@vue/cli-service')
+const path = require('path')
+
+// 检查是否使用本地开发版本（通过环境变量控制）
+const useLocalSDK = process.env.VUE_APP_USE_LOCAL_SDK === 'true'
+const localSDKPath = path.resolve(__dirname, '../../dist')
+
+console.log('🔧 Vue 配置信息:')
+console.log(`   - 使用本地 SDK: ${useLocalSDK ? '✅ 是' : '❌ 否'}`)
+if (useLocalSDK) {
+  console.log(`   - 本地 SDK 路径: ${localSDKPath}`)
+  console.log('   - 运行模式: 开发模式')
+} else {
+  console.log('   - 运行模式: npm包模式')
+}
+
+module.exports = defineConfig({
+  transpileDependencies: true,
+  publicPath: process.env.NODE_ENV === 'production' ? './' : '/',
+  devServer: {
+    port: 8080,
+    host: 'localhost',
+    open: true
+  },
+  configureWebpack: {
+    resolve: {
+      alias: {
+        '@': require('path').resolve(__dirname, 'src'),
+        // 如果启用本地开发模式，将 SDK 指向本地构建版本
+        ...(useLocalSDK && {
+          '@zeewain/3d-avatar-sdk': path.resolve(localSDKPath, 'index.esm.js')
+        })
+      }
+    }
+  }
+})

package/dist/examples/test-vue3/.eslintrc

@@ -0,0 +1,3 @@
+{
+    "extends": "@cyril_m"
+}

package/dist/examples/test-vue3/.stylelintignore

@@ -0,0 +1,3 @@
+dist*/
+node_modules/
+src/assets/sprites/

package/dist/examples/test-vue3/.stylelintrc

@@ -0,0 +1,48 @@
+{
+  "extends": [
+    "stylelint-config-standard",
+    "stylelint-config-standard-scss",
+    "stylelint-config-standard-vue/scss"
+  ],
+  "plugins": [
+    "stylelint-scss"
+  ],
+  "customSyntax": "postcss-html",
+  "rules": {
+    "indentation": 2,
+    "rule-empty-line-before": "never",
+    "at-rule-empty-line-before": "never",
+    "at-rule-no-unknown": null,
+    "no-descending-specificity": null,
+    "selector-pseudo-class-no-unknown": null,
+    "property-no-unknown": null,
+    "font-family-no-missing-generic-family-keyword": null,
+    "selector-id-pattern": null,
+    "selector-class-pattern": null,
+    "scss/no-global-function-names": null,
+    "scss/at-import-partial-extension": null,
+    "function-no-unknown": [
+      true,
+      {
+        "ignoreFunctions": [
+          "v-bind",
+          "map-get",
+          "lighten",
+          "darken",
+          "themed"
+        ]
+      }
+    ],
+    "property-no-vendor-prefix": [
+      true,
+      {
+        "ignoreProperties": [
+          "mask-image"
+        ]
+      }
+    ],
+    "max-line-length": null,
+    "no-empty-source": null,
+    "color-function-notation": null
+  }
+}

package/dist/examples/test-vue3/README.md

@@ -0,0 +1,236 @@
+# ZEE 3D Avatar SDK - Vue3 测试项目
+
+## 📋 项目概述
+
+这是一个基于 Vue3 + TypeScript + Vite + Element Plus 技术栈的 ZEE 3D Avatar SDK 测试项目，展示了如何在现代 Vue3 应用中集成和使用最新的统一架构 SDK。
+
+## ✨ 技术栈
+
+- **Vue 3.4+** - 渐进式 JavaScript 框架
+- **TypeScript** - JavaScript 的超集，提供类型安全
+- **Vite 5.0+** - 下一代前端构建工具
+- **Element Plus** - 基于 Vue3 的组件库
+- **Sass/SCSS** - CSS 预处理器
+- **ESLint + Prettier** - 代码规范和格式化
+- **Stylelint** - CSS 代码规范
+
+## 🚀 核心特性
+
+### SDK 统一架构
+- **单一入口**：使用 `ZEEAvatarSDK` 统一类管理所有功能
+- **一步初始化**：`initializeAvatar()` 方法统一完成 Unity 初始化和数字人加载
+- **多实例支持**：支持同页面多个独立 SDK 实例
+- **完整类型支持**：TypeScript 类型定义，智能提示
+
+### 功能模块
+- **全局配置管理** - Token 和 Avatar 编码配置
+- **Avatar 初始化** - 统一的数字人初始化流程
+- **动作控制** - 播放动作、获取当前动作信息
+- **智能播报** - 文本转语音、音频播报、播报控制
+- **镜头控制** - 全身、半身、面部镜头切换
+- **实时日志** - 操作日志记录和显示
+- **响应式布局** - 支持 PC 和移动端适配
+
+## 📦 安装和运行
+
+### 环境要求
+- Node.js 18.0+
+- pnpm 8.0+
+
+### 安装依赖
+```bash
+cd examples/test-vue3
+pnpm install
+```
+
+### 开发模式
+```bash
+# 使用本地 SDK 源码（推荐）
+pnpm run dev
+
+# 使用 npm 包版本
+pnpm run dev:npm
+```
+
+### 构建项目
+```bash
+pnpm run build
+```
+
+### 预览构建结果
+```bash
+pnpm run preview
+```
+
+## 🛠️ 开发命令
+
+### 代码检查和格式化
+```bash
+# ESLint 检查
+pnpm run lint:js
+
+# Stylelint 检查
+pnpm run lint:css
+
+# 修复 ESLint 问题
+pnpm run lint:fix
+
+# 修复 Stylelint 问题
+pnpm run lint:css-fix
+
+# 检查和修复所有问题
+pnpm run lint:all-fix
+```
+
+### TypeScript 类型检查
+```bash
+pnpm run type-check
+```
+
+## 📁 项目结构
+
+```
+examples/test-vue3/
+├── public/                 # 静态资源
+│   ├── index.html         # HTML 模板
+│   └── assets/            # Unity 构建文件（自动复制）
+├── src/                   # 源代码
+│   ├── components/        # Vue 组件
+│   │   ├── GlobalConfig.vue      # 全局配置组件
+│   │   ├── InitApi.vue          # 初始化 API 组件
+│   │   ├── MotionControlApi.vue # 动作控制 API 组件
+│   │   ├── BroadcastApi.vue     # 播报 API 组件
+│   │   ├── CameraApi.vue        # 镜头控制 API 组件
+│   │   ├── UnityPreview.vue     # Unity 预览组件
+│   │   ├── LogPanel.vue         # 日志面板组件
+│   │   └── InfoCards.vue        # 信息卡片组件
+│   ├── styles/            # 样式文件
+│   │   └── global.scss    # 全局样式
+│   ├── types/             # TypeScript 类型定义
+│   │   └── index.ts       # 类型定义文件
+│   ├── App.vue            # 根组件
+│   └── main.ts            # 应用入口
+├── setup.js               # 项目设置脚本
+├── vite.config.ts         # Vite 配置
+├── tsconfig.json          # TypeScript 配置
+├── package.json           # 项目配置
+└── README.md             # 项目说明
+```
+
+## 🔧 核心组件说明
+
+### App.vue
+主应用组件，使用 Vue3 Composition API 和 TypeScript：
+- 统一的 SDK 实例管理
+- 响应式布局适配
+- 全局状态管理
+- 事件处理和错误管理
+
+### GlobalConfig.vue
+全局配置组件：
+- Token 和 Avatar 编码配置
+- 本地存储管理
+- 配置验证和应用
+
+### InitApi.vue
+初始化 API 组件：
+- 使用统一的 `initializeAvatar()` 方法
+- 自动完成 Unity 初始化和数字人加载
+- 进度显示和状态管理
+
+### MotionControlApi.vue
+动作控制 API 组件：
+- 播放指定动作
+- 获取当前动作信息
+- 动作状态管理
+
+### BroadcastApi.vue
+播报 API 组件：
+- 文本转语音播报
+- 音频文件播报
+- 播报控制（暂停、恢复、停止）
+
+### CameraApi.vue
+镜头控制 API 组件：
+- 全身、半身、面部镜头切换
+- 实时镜头状态显示
+
+### UnityPreview.vue
+Unity 预览组件：
+- Unity 容器管理
+- 加载进度显示
+- 资源管理操作
+
+### LogPanel.vue
+日志面板组件：
+- 实时日志显示
+- 日志类型区分
+- 日志清理功能
+
+## 🎯 使用示例
+
+### 基础使用
+```typescript
+import { ZEEAvatarSDK, AvatarCameraType, BroadcastType } from '@zeewain/3d-avatar-sdk'
+
+// 创建 SDK 实例
+const sdk = new ZEEAvatarSDK({
+  loaderUrl: './assets/Build/webgl.loader.js',
+  dataUrl: './assets/Build/webgl.data.unityweb',
+  frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
+  codeUrl: './assets/Build/webgl.wasm.unityweb',
+  containerId: 'unity-container',
+  token: 'your-token',
+  env: 'prod'
+})
+
+// 初始化数字人
+await sdk.initializeAvatar('avatar001', AvatarCameraType.WHOLE)
+
+// 播放动作
+await sdk.playMotion('wave_hand')
+
+// 文本播报
+await sdk.startBroadcast({
+  type: BroadcastType.TEXT,
+  humanCode: 'avatar001',
+  text: '欢迎使用 ZEE 3D Avatar SDK',
+  voiceCode: 'VOICE001',
+  volume: 1.0,
+  speed: 1.0,
+  isSubtitle: false
+})
+```
+
+### 错误处理
+```typescript
+try {
+  await sdk.initializeAvatar('avatar001')
+} catch (error) {
+  if (error instanceof SDKError) {
+    console.error('SDK错误:', error.message, '错误码:', error.code)
+  } else {
+    console.error('系统错误:', error)
+  }
+}
+```
+
+## 🔍 开发调试
+
+### 浏览器开发者工具
+- 打开浏览器开发者工具
+- 查看 Console 面板的日志输出
+- 检查 Network 面板的网络请求
+- 使用 Vue DevTools 调试组件状态
+
+### 日志系统
+项目内置了完整的日志系统：
+- 实时显示操作日志
+- 按类型区分日志级别
+- 支持日志清理和导出
+
+### 常见问题
+1. **Unity 无法加载**：检查 assets 目录是否包含 Unity 构建文件
+2. **Token 认证失败**：确认 Token 配置正确且有效
+3. **播报无声音**：检查音量设置和浏览器音频策略
+4. **类型错误**：确保使用正确的 TypeScript 类型定义

package/dist/examples/test-vue3/env.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, any>
+  export default component
+}
+

package/dist/examples/test-vue3/index.html

@@ -0,0 +1,95 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ZEE 3D Avatar SDK - Vue3 测试项目</title>
+    <meta name="description" content="ZEE 3D Avatar SDK Vue3 + TypeScript + Vite 测试项目" />
+    <meta name="keywords" content="ZEE, 3D, Avatar, SDK, Vue3, TypeScript, Vite" />
+    <meta name="author" content="ZEEWain" />
+    <!-- 样式重置 -->
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      
+      html, body {
+        height: 100%;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+          'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+          sans-serif;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+      
+      #app {
+        height: 100%;
+      }
+      
+      /* 加载动画 */
+      .loading-container {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        background: #f5f5f5;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 9999;
+      }
+      
+      .loading-spinner {
+        width: 40px;
+        height: 40px;
+        border: 4px solid #e0e0e0;
+        border-top: 4px solid #409eff;
+        border-radius: 50%;
+        animation: spin 1s linear infinite;
+      }
+      
+      @keyframes spin {
+        0% { transform: rotate(0deg); }
+        100% { transform: rotate(360deg); }
+      }
+      
+      .loading-text {
+        margin-top: 16px;
+        color: #666;
+        font-size: 14px;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app">
+      <!-- 初始加载动画 -->
+      <div class="loading-container" id="initial-loading">
+        <div>
+          <div class="loading-spinner"></div>
+          <div class="loading-text">加载中...</div>
+        </div>
+      </div>
+    </div>
+    
+    <script type="module" src="/src/main.ts"></script>
+    
+    <!-- 移除初始加载动画 -->
+    <script>
+      window.addEventListener('load', () => {
+        setTimeout(() => {
+          const loading = document.getElementById('initial-loading');
+          if (loading) {
+            loading.style.opacity = '0';
+            loading.style.transition = 'opacity 0.3s ease';
+            setTimeout(() => {
+              loading.remove();
+            }, 300);
+          }
+        }, 500);
+      });
+    </script>
+  </body>
+</html>