CLAUDE.md

always response 中文

本文件为 Claude Code (claude.ai/code) 在此代码库中工作提供指导。

项目概述

TTMusic 是基于 OpenHarmony ArkTS 开发的功能丰富的音乐播放器应用，支持本地和网络音频播放，集成了 ijkplayer 进行媒体处理。

构建命令

依赖管理

# 安装依赖
ohpm install

# 更新特定依赖
ohpm update @ohos/ijkplayer

运行测试

当前项目没有正式的单元测试。测试通过手动设备测试和 DevEco Studio 的内置调试工具进行。

架构概览

模块结构

TTMusic/
├── entry/                  # 主应用模块
│   ├── src/main/ets/
│   │   ├── pages/         # 应用页面 (SplashIndex, MainIndex 等)
│   │   ├── view/          # 可复用UI组件 (LocalMusic, TitleBar 等)
│   │   ├── viewmodel/     # 数据模型和业务逻辑
│   │   ├── common/        # 工具类、常量和共享代码
│   │   ├── controller/    # 控制层 (AvSessionController, KnockController)
│   │   └── dialog/        # 对话框组件
├── ijkplayer/             # 基于 FFmpeg 的媒体播放器原生模块
├── lib/                   # 共享库 (歌词解析等)
└── hvigor/               # 构建配置

核心组件

核心播放器架构:

LocalMusic.ets - 主音乐播放器界面和播放控制
IjkMediaPlayer - 使用 FFmpeg 的原生媒体播放器后端
AvSessionController.ets - 用于系统集成的音频会话管理
PlayerModel.ets - 可观察的播放器状态模型

导航和UI:

MainIndex.ets - 主标签导航 (当前已禁用标签，简化版)
SplashIndex.ets - 应用初始化和加载页面
PlaylistDetailPage.ets - 播放列表管理和详情视图

数据管理:

MediaTable.ets & PlaylistTable.ets - 媒体和播放列表的数据库操作
ConfigManager.ets - 基于API的远程配置系统
GlobalContext.ets - 应用级状态管理

数据库架构

使用关系数据库 (RDB) 用于:

媒体文件元数据和索引
播放列表管理
用户偏好设置

配置系统

通过 ConfigManager.ets 进行远程配置管理:

从 https://pay.ss5.xyz/switches/lists 获取设置
支持 boolean、number、string 和 JSON 类型
与 AppStorage 集成以实现响应式UI更新

关键技术模式

ArkTS 特定注意事项

禁止解构赋值: 使用传统循环而不是 for (const [key, value] of Object.entries(obj))
需要空值安全: 在对象方法调用前总是检查 null/undefined
禁止计算属性名: 使用 obj[key] = value 而不是 {[key]: value}
显式错误类型: 使用 catch (e: Error) 而不是 catch (e)
基于Promise的异步: 数据库操作使用 .then()/.catch() 而不是 async/await

状态管理

@State 用于组件本地状态
@StorageProp/@StorageLink 用于 AppStorage 集成
@Observed 类用于复杂数据模型
通过 GlobalContext 单例进行全局状态管理

音频播放集成

// 标准播放器初始化模式
const player = IjkMediaPlayer.getInstance();
player.setDataSource(audioUrl);
player.prepareAsync();
player.setOnCompletionListener(this.handleCompletion.bind(this));

主题系统

多个内置主题 (默认、暮色、森林、珊瑚、极夜) 支持:

通过 AppStorage 进行动态颜色切换
基于资源的颜色定义 ($r('app.color.brand'))
明暗模式支持

开发指南

文件组织

pages/ 目录中的页面使用 @Entry 装饰器
view/ 目录中的可复用组件
viewmodel/ 中的业务逻辑，使用适当的模型类
common/util/ 中按功能组织的工具类

代码风格

类名使用 PascalCase (例如 MediaTable)
方法名使用 camelCase (例如 queryByParentPath)
常量使用 UPPER_SNAKE_CASE (例如 DB_COLUMNS.FILE_PATH)
私有属性使用 _camelCase 前缀

错误处理

在 catch 块中总是使用显式的 Error 类型
使用项目的 Logger 工具记录错误
通过 ToastUtil 显示用户友好的消息
正确处理数据库 Promise 拒绝

API 集成

使用 NetAxiosUtil 进行 HTTP 请求
通过 ConfigManager 进行远程配置
正确的 JSON 解析和错误处理
在 CommonConstants 中定义的 API 端点

常见开发任务

添加新音乐格式

更新 CommonConstants.REAL_MUSIC_FORMAT 数组
确认 ijkplayer 支持该格式
使用实际媒体文件测试

实现新主题

在 AppTheme.ets 中添加颜色定义
在设置中更新主题选择UI
在所有使用主题颜色的组件中测试

数据库模式更新

在相应的 Table 类中修改表创建
在 onCreate 回调中添加版本升级逻辑
处理现有数据的迁移

添加新对话框组件

在 dialog/ 目录中创建，遵循现有模式
使用 @pura/harmony-dialog 保持样式一致性
与父页面状态管理集成

重要依赖

@ohos/ijkplayer - 媒体播放引擎 (基于FFmpeg)
@pura/harmony-utils - 工具函数和助手
@pura/harmony-dialog - 对话框管理系统
@seagazer/cclyric - 歌词解析和显示
@chinalike/popup - 弹窗和模态框组件

测试和调试

使用 DevEco Studio 的内置调试工具
使用 common/util/Logger.ets 中的 Logger.info()、Logger.error() 记录日志
在实际设备上测试音频功能
通过日志输出检查数据库操作

平台特定注意事项

需要 OpenHarmony API 12 (5.0.0(12)) 或更高版本
支持手机、平板和 2in1 设备
通过 audioPlayback 后台模式启用后台音频播放
在 module.json5 中配置音频/视频文件类型的文件关联
日志都需要加上一个前缀：“heanup”
禁止使用unknown和any类型

CLAUDE.md 5.8 KB Historia Czysty