Tolan/frontend

Lyrria AI 英语语音助手 - 前端

🎯 项目简介

基于 React + TypeScript + Vite + Tailwind CSS 构建的现代化语音交互界面，完美支持各种屏幕尺寸和移动端浏览器。

---

✨ 技术栈

技术	版本	用途
React	18.2	UI 框架
TypeScript	5.3	类型系统
Vite	5.0	构建工具
Tailwind CSS	4.0	样式方案 ⭐
React Router	7.9	路由管理
Zustand	4.4	状态管理
Video.js	8.23	视频播放
Recorder Core	1.2	音频录制

---

🚀 快速开始

安装依赖

cd frontend
npm install

开发环境

npm run dev
# 访问 http://localhost:3000

生产构建

npm run build
npm run preview  # 预览构建结果

---

📱 浏览器兼容性

✅ 完全支持

• Chrome 90+ (Android/Windows/macOS)
• Safari 14+ (iOS 14+, macOS)
• Firefox 88+ (Android/Windows/macOS)
• Edge 90+ (Windows/Android)
• 夸克浏览器 (最新版)

⚠️ 降级支持

• Safari 13.1-14 (iOS 13): 部分 CSS 特性降级为固定值

🧪 测试设备

• ✅ iPhone SE / 11 / 14 Pro Max
• ✅ iPad / iPad Pro
• ✅ Samsung Galaxy S21
• ✅ Xiaomi 12
• ✅ 横屏/竖屏模式

---

🎨 响应式设计

移动端优先策略

项目采用 Tailwind CSS 实现完全响应式布局：

• 流式字体: clamp(24px, 6vw, 32px) 自动缩放
• 视口单位: 18vh、5vw 等相对单位
• 断点系统: sm:、md:、lg: 等前缀
• 混合布局: max(164px, 18vh) 确保最小值

示例:

<h1 className="text-fluid-2xl sm:text-3xl md:text-4xl">
  {/* 移动端 24-32px，平板 30px，桌面 36px */}
</h1>

---

📁 项目结构

frontend/
├── src/
│   ├── assets/          # 静态资源（图片、字体）
│   ├── pages/           # 页面组件
│   │   ├── WelcomePage.tsx       ✅ Tailwind
│   │   ├── LoadingPage.tsx       ✅ Tailwind
│   │   ├── GreetingPage.tsx      ✅ Tailwind
│   │   ├── VideoIntroPage.tsx    ⚠️ 待迁移
│   │   └── ChatBotPage.tsx       ⚠️ 待迁移
│   ├── components/      # 可复用组件（未来）
│   ├── store/           # Zustand 状态
│   ├── utils/           # 工具函数
│   ├── router/          # 路由配置
│   ├── index.css        # Tailwind 入口
│   └── main.tsx         # 应用入口
├── docs/                # 技术文档
│   ├── Tailwind_CSS迁移文档.md
│   └── Tailwind_快速参考.md
├── tailwind.config.js   # Tailwind 配置
├── postcss.config.js    # PostCSS 配置
├── vite.config.ts       # Vite 配置
└── package.json

---

🎯 页面流程

WelcomePage (欢迎页)
    ↓
LoadingPage (加载页)
    ↓
VideoIntroPage (视频介绍)
    ↓
GreetingPage (输入姓名)
    ↓
ChatBotPage (语音对话)

---

🛠️ 核心功能

1. 语音录制

import Recorder from 'recorder-core';

const recorder = new Recorder({
  type: 'pcm',
  sampleRate: 16000,
  bitRate: 16,
});

2. WebSocket 通信

import ReconnectingWebSocket from 'reconnecting-websocket';

const ws = new ReconnectingWebSocket('wss://backend/ws');
ws.send(JSON.stringify({ type: 'audio_chunk', data }));

3. 视频播放

import videojs from 'video.js';

const player = videojs(videoRef.current, {
  autoplay: true,
  controls: false,
  playsinline: true,
});

---

📖 样式开发指南

使用 Tailwind CSS

推荐写法:

<div className="w-full h-screen flex items-center justify-center bg-[#F5F5F5]">
  <div className="max-w-mobile p-4 rounded-xl shadow-lg">
    <h1 className="text-fluid-2xl font-semibold text-black">
      标题
    </h1>
  </div>
</div>

自定义值

<div className="top-[max(164px,18vh)]">
  {/* 方括号支持任意 CSS 值 */}
</div>

响应式

<div className="text-base sm:text-lg md:text-xl">
  {/* 移动端 16px，小屏 18px，中屏 20px */}
</div>

详细参考: Tailwind_快速参考.md

---

🔧 配置说明

环境变量 (.env)

# HTTPS 开关（开发环境）
VITE_ENABLE_HTTPS=false

# SSL 证书路径（可选）
VITE_SSL_KEYFILE=../ssl/key.pem
VITE_SSL_CERTFILE=../ssl/cert.pem

Tailwind 自定义

// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        'bg-main': '#E8E8E8',
        'accent': '#007AFF',
      },
      fontSize: {
        'fluid-2xl': 'clamp(24px, 6vw, 32px)',
      },
    },
  },
}

---

📊 性能指标

构建结果

• CSS 大小: 85KB → 20KB (gzip)
• JS 大小: 1.29MB → 405KB (gzip)
• 首屏加载: < 1s (4G 网络)

优化措施

• ✅ Vite 代码分割
• ✅ Tailwind JIT 编译
• ✅ 图片懒加载
• ✅ Tree-shaking 优化

---

🐛 常见问题

Q: 样式不生效？

检查 Tailwind 配置：

npm run build  # 查看是否有编译错误

Q: 移动端视口问题？

确保 index.html 包含：

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

Q: iOS 安全区域？

使用自定义类：

<div className="safe-top safe-bottom">
  {/* 自动避开刘海屏 */}
</div>

---

📚 文档

• Tailwind CSS 迁移文档
• Tailwind 快速参考
• 技术方案
• 更新日志

---

🤝 开发规范

组件规范

// ✅ 推荐
export const MyComponent: React.FC<Props> = ({ prop }) => {
  return (
    <div className="mobile-container">
      {/* 使用语义化类名 */}
    </div>
  );
};

// ❌ 避免
export const MyComponent = (props) => {
  return <div style={{ width: '100vw' }}>{/* 避免内联样式 */}</div>;
};

样式规范

• ✅ 优先使用 Tailwind 类名
• ✅ 复杂样式提取为组件
• ✅ 避免过长的 className（> 10 个类）
• ❌ 避免内联 style 属性

TypeScript 规范

• ✅ 所有函数添加类型注解
• ✅ 使用接口定义 Props
• ❌ 禁止使用 any 类型

---

🚀 后续计划

v2.1.0

• 迁移 VideoIntroPage 到 Tailwind
• 迁移 ChatBotPage 到 Tailwind
• 添加暗黑模式

v2.2.0

• 提取公共组件库
• 添加单元测试
• 国际化支持 (i18n)

---

📄 许可证

MIT License - 详见 LICENSE

---

👥 联系方式

如有问题，请联系开发团队或查看 项目文档

---

Built with ❤️ using React + Tailwind CSS