Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
172 lines (133 loc) · 5.51 KB

SETUP_GUIDE.md

File metadata and controls

172 lines (133 loc) · 5.51 KB
Raw

IntervalTimer - Xcode 配置与运行指南

iOS 16.0+ | SwiftUI | Swift 5.9+

一、创建 Xcode 项目

  1. 打开 Xcode，选择 File → New → Project
  2. 选择模板：iOS → App
  3. 填写项目信息： 
    Product Name:        IntervalTimer
Team:                （选择你的开发者账号）
Organization Identifier: com.yourname.intervaltimer
Interface:           SwiftUI
Language:            Swift
  4. Minimum Deployments 设置为 iOS 16.0
  5. 取消勾选 Include Tests（非必须）
  6. 选择保存路径，点击 Create

二、复制代码文件

将以下文件按目录结构复制到 Xcode 项目中：

IntervalTimer/
├── IntervalTimerApp.swift       ← 替换 Xcode 自动生成的同名文件
├── Info.plist                   ← 替换 Xcode 自动生成的同名文件
│
├── Models/（新建 Group）
│   ├── SystemSoundItem.swift
│   └── TimerConfig.swift
│
├── Services/（新建 Group）
│   ├── AudioService.swift
│   ├── NotificationService.swift
│   └── TimerService.swift
│
├── ViewModels/（新建 Group）
│   └── TimerViewModel.swift
│
└── Views/（新建 Group）
    ├── ContentView.swift        ← 替换 Xcode 自动生成的同名文件
    ├── SoundPickerView.swift
    ├── TimerSettingView.swift
    └── ControlPanelView.swift

在 Xcode 中新建 Group 的方法：

右键点击项目导航器中的 IntervalTimer 文件夹 → New Group → 输入名称

三、配置后台模式（必须）

步骤：

  1. 点击项目导航器顶部的 IntervalTimer（蓝色图标）
  2. 选择 TARGETS → IntervalTimer
  3. 点击 Signing & Capabilities 标签
  4. 点击左上角 + Capability
  5. 搜索并添加 Background Modes
  6. 在 Background Modes 中勾选：
    • ✅ Audio, AirPlay, and Picture in Picture
    • ✅ Background fetch

四、配置 Info.plist（必须）

使用提供的 Info.plist 文件替换，或手动添加以下键值：

Key Type Value
UIBackgroundModes Array audio, fetch
NSUserNotificationsUsageDescription String 需要通知权限以在后台定时提醒您
NSMicrophoneUsageDescription String 用于音频会话保活，支持后台声音播放
CFBundleDisplayName String 间隔计时器

手动添加方法：

  1. 右键 Info.plist → Open As → Source Code
  2. 在 <dict> 内添加对应的键值对

五、Signing 配置

  1. 在 Signing & Capabilities 中
  2. Team 选择你的 Apple Developer 账号
  3. Bundle Identifier 确保唯一（如 com.yourname.intervaltimer）
  4. 勾选 Automatically manage signing

⚠️ 若没有付费开发者账号，可使用免费账号，但只能在真机上运行 7 天后需重新签名

六、运行测试

模拟器运行（功能受限）：

Product → Run（⌘R）
  • 可测试 UI 布局、声音选择
  • ⚠️ 部分系统声音在模拟器中无声，建议真机测试

真机运行（推荐）：

  1. iPhone 连接 Mac（USB 或无线）
  2. iPhone 解锁，信任此电脑
  3. Xcode 顶部选择你的 iPhone 设备
  4. Product → Run（⌘R）

七、功能测试清单

测试项 测试方法 预期结果
通知权限 首次启动 弹出权限请求弹窗
参数设置 调整小时/分钟/秒数 Stepper 响应，数值变化
声音选择 点击声音选择行 进入列表页，可搜索/试听/选择
前台触发 设置 1 分钟，等待 1 分钟后播放声音，Z 秒后停止
立即静音 播放时点击静音 声音立即停止，计时继续
后台触发 开始后按 Home 键 1 分钟后收到通知
配置持久化 修改设置，杀死重启 设置仍然保留
重复触发 等待多次触发 每隔 X:Y 循环触发

八、常见问题

Q1: 声音没有播放？

  • 确认手机未静音（响铃/静音拨片）
  • 检查 Info.plist 中 UIBackgroundModes 是否包含 audio
  • 在设置 → 通知 → 间隔计时器 中确认通知已开启

Q2: 后台不触发？

  • 确认通知权限已授权（设置 → 通知 → 间隔计时器）
  • 确认 Background Modes 已在 Xcode 中正确配置
  • iOS 低电量模式可能延迟通知

Q3: 模拟器无声音？

  • 这是模拟器限制，建议使用真机测试
  • 部分 AudioToolbox 系统声音在模拟器上不支持

Q4: 编译报错 @MainActor 相关？

  • 确认 Xcode 版本 ≥ 14，Swift 版本 ≥ 5.7

九、项目文件总览

文件 说明
IntervalTimerApp.swift App 入口，通知代理注册
Info.plist 权限与后台模式配置
Models/TimerConfig.swift 用户配置模型，UserDefaults 持久化
Models/SystemSoundItem.swift 约 80 个系统声音数据，分 4 类
Services/AudioService.swift 播放系统声音，Z 秒后自动停止
Services/NotificationService.swift 本地通知注册与管理
Services/TimerService.swift 计时核心，前台/后台切换处理
ViewModels/TimerViewModel.swift 状态管理，连接 Service 与 View
Views/ContentView.swift 主页面
Views/TimerSettingView.swift X/Y/Z 参数设置 UI
Views/SoundPickerView.swift 声音选择列表（搜索+试听）
Views/ControlPanelView.swift 开始/停止/静音按钮

生成时间：2026-05-07