From 1fcc3dbbc038004ee0b206cdca4d6530b0c10689 Mon Sep 17 00:00:00 2001 From: v504 Date: Wed, 20 Aug 2025 13:49:43 +0800 Subject: [PATCH] Refactor README.md to streamline project overview and features; remove outdated documentation files; enhance structure and clarity for better user guidance; update project features and technology stack sections. --- README.md | 111 +++---- docs/CAMERA_PERMISSION_README.md | 289 ++++++++++++++++++ docs/README.md | 163 ++++++++++ {MyQrCode => docs}/README_Logger.md | 0 {MyQrCode => docs}/README_Multilingual.md | 0 {MyQrCode => docs}/REFACTOR_README.md | 0 .../RESCAN_BUTTON_FIX_README.md | 0 .../SCANNING_ISSUE_FIX_README.md | 0 {MyQrCode => docs}/TOUCH_FIX_README.md | 0 9 files changed, 493 insertions(+), 70 deletions(-) create mode 100644 docs/CAMERA_PERMISSION_README.md create mode 100644 docs/README.md rename {MyQrCode => docs}/README_Logger.md (100%) rename {MyQrCode => docs}/README_Multilingual.md (100%) rename {MyQrCode => docs}/REFACTOR_README.md (100%) rename {MyQrCode => docs}/RESCAN_BUTTON_FIX_README.md (100%) rename {MyQrCode => docs}/SCANNING_ISSUE_FIX_README.md (100%) rename {MyQrCode => docs}/TOUCH_FIX_README.md (100%) diff --git a/README.md b/README.md index 6773d32..a5da03e 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,61 @@ -# MyQrCode - SwiftUI 版本 +# MyQrCode -## 项目概述 +## 📱 项目简介 -这是一个使用 SwiftUI 构建的条码扫描器应用，支持二维码和多种条形码格式，已经从原来的 UIKit 版本完全转换为 SwiftUI。 +MyQrCode 是一个功能完整的二维码和条形码扫描应用，采用 SwiftUI 和 AVFoundation 技术栈开发。 -## 主要变化 +## ⭐ 主要特性 -### 从 UIKit 转换为 SwiftUI +- **多格式支持**: QR码、条形码等多种格式 +- **多码识别**: 同时识别多个条码并允许用户选择 +- **微信风格界面**: 暂停预览和用户选择功能 +- **多样化扫描线**: 5种不同风格的扫描线动画 +- **多语言支持**: 中英文双语界面 +- **权限管理**: 完整的相机权限管理 +- **日志系统**: 详细的调试和监控日志 -- **ScannerViewController.swift** → **ScannerView.swift** - - 使用 `@StateObject` 管理扫描器状态 - - 使用 `UIViewRepresentable` 包装相机预览层 - - 采用 MVVM 架构模式 +## 🚀 快速开始 -### 新特性 +1. 克隆项目到本地 +2. 使用 Xcode 15+ 打开项目 +3. 在真机上运行和测试 +4. 确保在 Info.plist 中添加相机权限描述 -1. **现代化的 UI 设计** - - 扫描框覆盖层，提供视觉引导 - - 美观的按钮和文本样式 - - 响应式布局 +## 🛠️ 技术栈 -2. **改进的状态管理** - - 使用 `@Published` 属性包装器 - - 通过通知中心传递扫描结果 - - 更好的错误处理 +- **UI框架**: SwiftUI +- **相机功能**: AVFoundation +- **架构模式**: MVVM +- **状态管理**: Combine + @Published +- **最低版本**: iOS 15.0+ -3. **用户体验优化** - - 扫描成功后的震动反馈 - - 清晰的扫描指导文本 - - 优雅的模态展示 +## 📚 详细文档 -4. **多格式条码支持** - - 二维码 (QR Code) - - EAN-8 和 EAN-13 条形码 - - Code 128 和 Code 39 条形码 - - UPC-E 条形码 - - PDF417 和 Aztec 码 +项目的详细文档和开发说明请查看： -5. **微信风格扫描界面** - - 扫描线动画效果 - - 检测到条码时短暂暂停预览 - - 条码位置中心点标记（绿色圆圈） - - 点击标记直接选择条码 - - 支持重新扫描 +**[📖 完整项目文档](docs/README.md)** -## 文件结构 +包含以下内容： +- 🚀 核心功能实现说明 +- 🔧 问题修复文档 +- 📱 架构设计说明 +- 🧪 测试指南 +- 🛠️ 开发工具配置 + +## 📂 项目结构 ``` MyQrCode/ -├── ScannerView.swift # 新的 SwiftUI 扫描器视图 -├── ContentView.swift # 更新的主内容视图 -├── MyQrCodeApp.swift # 应用入口点 -└── ...其他文件 +├── MyQrCode/ # 应用主目录 +├── docs/ # 📚 项目文档 +├── MyQrCodeTests/ # 🧪 测试文件 +└── README.md # 📖 项目说明 ``` -## 使用方法 - -1. 启动应用后，点击"开始扫描"按钮 -2. 将二维码或条形码放入扫描框内 -3. 扫描成功后： - - 短暂暂停预览并显示条码覆盖层 - - 在相机预览上显示条码位置标记（绿色圆圈） -4. 在预览暂停时： - - 在相机预览上显示条码位置标记（绿色圆圈） - - 单个条码：1秒后自动显示结果 - - 多个条码：点击绿色标记选择要解码的条码 - - 点击"重新扫描"继续扫描 -5. 单个条码自动选择，多个条码手动选择 -6. 可以重复扫描新的条码 - -## 技术特点 - -- **SwiftUI**: 现代化的声明式 UI 框架 -- **AVFoundation**: 相机和条码扫描功能 -- **MVVM 架构**: 清晰的代码分离和状态管理 -- **通知中心**: 组件间的松耦合通信 - -## 兼容性 +## 🤝 贡献 -- iOS 14.0+ -- Xcode 12.0+ -- Swift 5.3+ +欢迎提交 Issue 和 Pull Request 来帮助改进项目！ -## 注意事项 +## 📄 许可证 -- 需要在真机上测试相机功能 -- 确保在 Info.plist 中添加相机权限描述 -- 扫描器支持屏幕旋转和尺寸变化 -- 条码位置标记会自动适应屏幕变化 \ No newline at end of file +此项目遵循 MIT 许可证。 \ No newline at end of file diff --git a/docs/CAMERA_PERMISSION_README.md b/docs/CAMERA_PERMISSION_README.md new file mode 100644 index 0000000..05185ec --- /dev/null +++ b/docs/CAMERA_PERMISSION_README.md @@ -0,0 +1,289 @@ +# 相机授权功能实现说明 + +## 🎯 功能概述 + +为 MyQrCode 应用添加了完整的相机权限管理功能，包括权限检查、权限请求、权限状态显示和用户引导。 + +## 🔧 技术实现 + +### 1. **权限状态管理** + +在 `ScannerViewModel` 中添加了权限相关的状态： + +```swift +@Published var cameraAuthorizationStatus: AVAuthorizationStatus = .notDetermined +@Published var showPermissionAlert = false +``` + +### 2. **权限检查流程** + +#### **初始化时权限检查** +```swift +override init() { + super.init() + checkCameraPermission() // 替换原来的 setupCaptureSession() +} +``` + +#### **权限状态检查方法** +```swift +private func checkCameraPermission() { + switch AVCaptureDevice.authorizationStatus(for: .video) { + case .authorized: + // 已授权，设置相机会话 + setupCaptureSession() + + case .notDetermined: + // 未确定，请求权限 + requestCameraPermission() + + case .denied, .restricted: + // 被拒绝或受限，显示权限提示 + showPermissionAlert = true + + @unknown default: + // 未知状态 + break + } +} +``` + +### 3. **权限请求处理** + +#### **自动权限请求** +```swift +private func requestCameraPermission() { + AVCaptureDevice.requestAccess(for: .video) { [weak self] granted in + DispatchQueue.main.async { + if granted { + self?.cameraAuthorizationStatus = .authorized + self?.setupCaptureSession() + } else { + self?.cameraAuthorizationStatus = .denied + self?.showPermissionAlert = true + } + } + } +} +``` + +#### **手动权限刷新** +```swift +func refreshCameraPermission() { + checkCameraPermission() +} +``` + +### 4. **设置页面跳转** + +```swift +func openSettings() { + if let settingsUrl = URL(string: UIApplication.openSettingsURLString) { + UIApplication.shared.open(settingsUrl) { success in + // 处理跳转结果 + } + } +} +``` + +## 📱 用户界面 + +### 1. **权限状态视图** + +创建了 `CameraPermissionView` 来显示不同权限状态下的UI： + +#### **未确定状态** +- 显示相机图标和说明文字 +- 提供"授予相机权限"按钮 +- 点击后自动请求权限 + +#### **被拒绝状态** +- 显示权限被拒绝的说明 +- 提供"打开设置"按钮 +- 引导用户到系统设置中手动开启 + +#### **受限状态** +- 显示权限受限的说明 +- 提供相应的解决方案 + +### 2. **UI 组件结构** + +```swift +struct CameraPermissionView: View { + let authorizationStatus: AVAuthorizationStatus + let onRequestPermission: () -> Void + let onOpenSettings: () -> Void + + var body: some View { + VStack(spacing: 30) { + // 相机图标 + Image(systemName: "camera.fill") + + // 标题和描述 + Text("camera_permission_title".localized) + Text(getDescriptionText()) + + // 操作按钮 + VStack(spacing: 15) { + if authorizationStatus == .notDetermined { + // 请求权限按钮 + } else if authorizationStatus == .denied || authorizationStatus == .restricted { + // 打开设置按钮 + } + } + } + } +} +``` + +### 3. **权限状态集成** + +在 `ScannerView` 中根据权限状态显示不同的UI： + +```swift +var body: some View { + ZStack { + if scannerViewModel.cameraAuthorizationStatus == .authorized { + // 相机预览和扫描UI + CameraPreviewView(...) + ScanningOverlayView(...) + // ... 其他扫描相关组件 + } else { + // 权限相关UI + CameraPermissionView(...) + } + } +} +``` + +## 🌐 多语言支持 + +### 1. **英文本地化** + +```strings +"camera_permission_title" = "Camera Permission Required"; +"camera_permission_description" = "This app needs access to your camera to scan QR codes and barcodes. Please grant camera permission to continue."; +"camera_permission_denied" = "Camera access has been denied. Please enable camera permission in Settings to use the scanner."; +"request_camera_permission" = "Grant Camera Access"; +"open_settings" = "Open Settings"; +``` + +### 2. **中文本地化** + +```strings +"camera_permission_title" = "需要相机权限"; +"camera_permission_description" = "此应用需要访问您的相机来扫描二维码和条形码。请授予相机权限以继续使用。"; +"camera_permission_denied" = "相机访问被拒绝。请在设置中启用相机权限以使用扫描器。"; +"request_camera_permission" = "授予相机权限"; +"open_settings" = "打开设置"; +``` + +## 🔄 权限状态监听 + +### 1. **自动状态更新** + +```swift +.onReceive(scannerViewModel.$cameraAuthorizationStatus) { status in + if status == .authorized { + logInfo("🎯 相机权限已授权，启动扫描", className: "ScannerView") + scannerViewModel.startScanning() + } +} +``` + +### 2. **扫描控制** + +```swift +.onAppear { + // 只有在相机权限已授权时才启动扫描 + if scannerViewModel.cameraAuthorizationStatus == .authorized { + scannerViewModel.startScanning() + } +} +``` + +## 📋 权限状态类型 + +### 1. **AVAuthorizationStatus 枚举** + +- **`.notDetermined`**: 用户尚未做出选择 +- **`.authorized`**: 用户已授权访问相机 +- **`.denied`**: 用户拒绝访问相机 +- **`.restricted`**: 相机访问受限（如家长控制） + +### 2. **状态转换流程** + +``` +notDetermined → 请求权限 → authorized/denied +denied → 用户手动开启 → authorized +restricted → 需要管理员操作 → authorized +``` + +## 🧪 测试场景 + +### 1. **首次安装** +- 应用启动时自动请求权限 +- 用户可以选择允许或拒绝 + +### 2. **权限被拒绝** +- 显示权限被拒绝的说明 +- 提供打开设置的按钮 +- 用户可以从设置中重新开启 + +### 3. **权限恢复** +- 用户从设置返回后自动检测权限状态 +- 权限恢复后自动启动扫描功能 + +### 4. **权限受限** +- 显示相应的说明和解决方案 +- 引导用户联系管理员或检查设备设置 + +## 🔒 隐私和安全 + +### 1. **最小权限原则** +- 只请求必要的相机权限 +- 不收集或存储相机数据 +- 权限仅用于扫描功能 + +### 2. **用户控制** +- 用户可以随时在设置中关闭权限 +- 应用会优雅地处理权限变化 +- 提供清晰的权限说明 + +### 3. **错误处理** +- 权限被拒绝时提供友好的错误信息 +- 引导用户解决问题的方法 +- 不会因为权限问题导致应用崩溃 + +## 🚀 部署说明 + +### 1. **Info.plist 配置** +确保在 `Info.plist` 中添加相机权限描述： + +```xml +NSCameraUsageDescription +此应用需要访问相机来扫描二维码和条形码 +``` + +### 2. **权限测试** +- 在真机上测试权限流程 +- 验证不同权限状态下的UI显示 +- 测试权限恢复后的功能 + +### 3. **用户体验** +- 权限请求时机合理 +- 错误信息清晰易懂 +- 操作流程简单直观 + +## 📊 功能特性总结 + +- ✅ **自动权限检查**: 应用启动时自动检查相机权限 +- ✅ **智能权限请求**: 只在必要时请求权限 +- ✅ **友好错误提示**: 权限被拒绝时提供清晰的说明 +- ✅ **设置页面跳转**: 一键跳转到系统设置 +- ✅ **状态自动更新**: 权限状态变化时自动更新UI +- ✅ **多语言支持**: 支持中英文界面 +- ✅ **优雅降级**: 无权限时显示相应的提示界面 +- ✅ **权限恢复**: 权限恢复后自动启动扫描功能 + +通过这些功能，用户可以获得完整的相机权限管理体验，确保应用能够正常使用相机功能，同时尊重用户的隐私选择。 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1c13874 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,163 @@ +# MyQrCode 项目文档 + +欢迎来到 MyQrCode 项目文档！这里包含了项目开发过程中的所有重要文档和说明。 + +## 📚 文档索引 + +### 🚀 核心功能文档 + +1. **[相机授权功能实现说明](CAMERA_PERMISSION_README.md)** + - 完整的相机权限管理功能 + - 权限检查、请求、状态显示和用户引导 + - 多语言支持的权限界面 + +2. **[重构说明文档](REFACTOR_README.md)** + - ScannerView 代码重构详细说明 + - 组件化拆分和模块化设计 + - 架构优化和代码组织 + +3. **[多语言支持实现说明](README_Multilingual.md)** + - 中英文双语支持 + - 本地化字符串管理 + - 语言切换功能 + +4. **[日志系统实现说明](README_Logger.md)** + - 自定义日志系统 + - 多级别日志管理 + - 调试和监控功能 + +### 🔧 问题修复文档 + +1. **[触摸选择点响应问题修复说明](TOUCH_FIX_README.md)** + - 触摸区域优化 + - 事件处理改进 + - 用户交互体验提升 + +2. **[重新扫描后无法扫描问题修复说明](SCANNING_ISSUE_FIX_README.md)** + - 会话状态管理修复 + - 扫描重启逻辑优化 + - 错误处理机制 + +3. **[重新扫描按钮修复说明](RESCAN_BUTTON_FIX_README.md)** + - 按钮位置重新设计 + - 功能失效问题修复 + - 用户体验优化 + +## 📱 项目概述 + +MyQrCode 是一个功能完整的二维码和条形码扫描应用，采用 SwiftUI 和 AVFoundation 技术栈开发。 + +### 🌟 主要特性 + +- **多格式支持**: 支持 QR 码、条形码等多种格式 +- **多码识别**: 同时识别多个条码并允许用户选择 +- **微信风格界面**: 暂停预览和用户选择功能 +- **多样化扫描线**: 5种不同风格的扫描线动画 +- **多语言支持**: 中英文双语界面 +- **权限管理**: 完整的相机权限管理 +- **日志系统**: 详细的调试和监控日志 + +### 🏗️ 技术架构 + +- **UI框架**: SwiftUI +- **相机功能**: AVFoundation +- **架构模式**: MVVM +- **状态管理**: Combine + @Published +- **本地化**: .lproj 文件 +- **日志**: 自定义 Logger 系统 + +### 📦 项目结构 + +``` +MyQrCode/ +├── MyQrCode/ # 应用主目录 +│ ├── ScannerView.swift # 主扫描视图（重构后） +│ ├── ContentView.swift # 应用入口视图 +│ ├── Logger.swift # 日志系统 +│ ├── MyQrCodeApp.swift # 应用入口 +│ ├── en.lproj/ # 英文本地化 +│ ├── zh-Hans.lproj/ # 中文本地化 +│ └── Assets.xcassets/ # 应用资源 +├── docs/ # 项目文档 +└── README.md # 项目主文档 +``` + +## 🚦 开发历程 + +### 阶段 1: 基础功能实现 +- 基本的二维码扫描功能 +- SwiftUI 界面搭建 +- AVFoundation 集成 + +### 阶段 2: 功能增强 +- 多码识别和选择 +- 微信风格的用户界面 +- 扫描线动画效果 + +### 阶段 3: 用户体验优化 +- 触摸交互优化 +- 权限管理完善 +- 多语言支持 + +### 阶段 4: 代码质量提升 +- 代码重构和模块化 +- 日志系统集成 +- 问题修复和优化 + +## 🧪 测试指南 + +### 基本功能测试 +1. 单个二维码扫描 +2. 多个二维码识别和选择 +3. 不同格式的条码扫描 + +### 权限测试 +1. 首次安装权限请求 +2. 权限拒绝后的处理 +3. 权限恢复功能 + +### 用户体验测试 +1. 触摸选择响应 +2. 重新扫描功能 +3. 语言切换功能 + +### 兼容性测试 +1. 不同 iOS 版本 +2. 不同设备尺寸 +3. 横竖屏切换 + +## 🛠️ 开发工具和环境 + +- **开发环境**: Xcode 15+ +- **最低iOS版本**: iOS 15.0 +- **开发语言**: Swift 5.9+ +- **UI框架**: SwiftUI +- **相机框架**: AVFoundation +- **依赖管理**: Swift Package Manager + +## 📋 TODO 和未来计划 + +- [ ] 添加扫描历史记录 +- [ ] 支持生成二维码功能 +- [ ] 添加更多扫描线样式 +- [ ] 优化相机性能 +- [ ] 添加扫描音效 +- [ ] 支持批量扫描 + +## 🤝 贡献指南 + +1. 代码规范遵循 Swift 官方指南 +2. 新功能需要添加相应的文档 +3. 重要变更需要更新测试用例 +4. 提交前需要通过所有测试 + +## 📞 联系信息 + +如果您在使用过程中遇到问题，请通过以下方式联系： + +- 项目仓库: [GitHub Issues] +- 开发者邮箱: [开发者邮箱] + +--- + +最后更新: 2025年8月20日 \ No newline at end of file diff --git a/MyQrCode/README_Logger.md b/docs/README_Logger.md similarity index 100% rename from MyQrCode/README_Logger.md rename to docs/README_Logger.md diff --git a/MyQrCode/README_Multilingual.md b/docs/README_Multilingual.md similarity index 100% rename from MyQrCode/README_Multilingual.md rename to docs/README_Multilingual.md diff --git a/MyQrCode/REFACTOR_README.md b/docs/REFACTOR_README.md similarity index 100% rename from MyQrCode/REFACTOR_README.md rename to docs/REFACTOR_README.md diff --git a/MyQrCode/RESCAN_BUTTON_FIX_README.md b/docs/RESCAN_BUTTON_FIX_README.md similarity index 100% rename from MyQrCode/RESCAN_BUTTON_FIX_README.md rename to docs/RESCAN_BUTTON_FIX_README.md diff --git a/MyQrCode/SCANNING_ISSUE_FIX_README.md b/docs/SCANNING_ISSUE_FIX_README.md similarity index 100% rename from MyQrCode/SCANNING_ISSUE_FIX_README.md rename to docs/SCANNING_ISSUE_FIX_README.md diff --git a/MyQrCode/TOUCH_FIX_README.md b/docs/TOUCH_FIX_README.md similarity index 100% rename from MyQrCode/TOUCH_FIX_README.md rename to docs/TOUCH_FIX_README.md