桌面播放器卡片设计文档

概述

桌面播放器卡片是一个基于HarmonyOS Form Kit的系统级小组件，为TTMusic应用提供桌面快速控制功能。该卡片将利用现有的AvSessionController和ijkplayer播放器架构，通过FormExtensionAbility实现与主应用的数据同步和控制交互。当前应用使用ijkplayer作为播放内核，通过AvSessionController管理媒体会话，卡片将通过这个架构实现播放控制。

架构设计

整体架构

graph TB
    A[桌面卡片UI] --> B[FormExtensionAbility]
    B --> C[FormProvider]
    C --> D[CommonEvent通信]
    D --> E[LocalMusic组件]
    E --> F[ijkplayer播放内核]
    E --> G[AvSessionController]
    
    H[数据存储] --> C
    I[卡片配置] --> C
    
    J[系统通知栏] --> G
    K[媒体控制中心] --> G
    L[投播控制] --> G

核心组件

FormExtensionAbility: 卡片生命周期管理
FormProvider: 卡片数据提供者和业务逻辑处理
WidgetDataManager: 卡片数据管理和持久化
PlayerControlService: 播放控制服务接口
FormLayoutManager: 多尺寸布局管理器

组件设计

1. FormExtensionAbility

负责卡片的生命周期管理和系统交互。

主要职责：

处理卡片创建、更新、销毁事件
管理卡片实例和配置
处理用户交互事件路由
与主应用建立通信连接

关键接口：

interface FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData
  onUpdateForm(formId: string): void
  onRemoveForm(formId: string): void
  onFormEvent(formId: string, message: string): void
}

2. FormProvider

卡片的核心业务逻辑处理器。

主要职责：

管理播放状态数据
处理播放控制命令
同步主应用状态
格式化卡片显示数据

数据模型：

interface WidgetPlayState {
  isPlaying: boolean
  currentSong: SongInfo
  progress: PlayProgress
  playMode: PlayMode
  hasPlaylist: boolean
}

interface SongInfo {
  title: string
  artist: string
  album: string
  coverUrl: string
  duration: number
}

interface PlayProgress {
  currentTime: number
  totalTime: number
  percentage: number
}

3. PlayerControlService

与主应用播放器的通信接口。

主要功能：

发送播放控制命令
接收播放状态更新
处理歌曲切换事件
管理播放列表状态

通信机制：

使用CommonEvent进行应用间通信（发送控制命令到LocalMusic组件）
监听AvSessionController的媒体会话状态变化
通过Preferences持久化卡片状态和播放信息
利用现有的emitter事件机制（eventId: 2, 101, 333, 888等）

4. FormLayoutManager

多尺寸卡片布局管理。

支持的卡片尺寸：

小卡片 (2x1): 基本播放控制 + 歌曲名
中卡片 (4x2): 完整信息 + 播放控制 + 进度条
大卡片 (4x3): 专辑封面 + 完整信息 + 扩展控制

数据模型

卡片状态数据

interface WidgetData {
  // 播放状态
  playState: {
    isPlaying: boolean
    isPaused: boolean
    isLoading: boolean
  }
  
  // 当前歌曲信息
  currentSong: {
    id: string
    title: string
    artist: string
    album: string
    coverImagePath: string
    duration: number
  }
  
  // 播放进度
  progress: {
    currentPosition: number
    duration: number
    percentage: number
    currentTimeText: string
    totalTimeText: string
  }
  
  // 播放列表状态
  playlist: {
    hasNext: boolean
    hasPrevious: boolean
    currentIndex: number
    totalCount: number
  }
  
  // 卡片配置
  config: {
    size: WidgetSize
    theme: WidgetTheme
    showProgress: boolean
    showCover: boolean
  }
}

控制命令

enum WidgetCommand {
  PLAY_PAUSE = 'play_pause',
  NEXT_SONG = 'next_song',
  PREV_SONG = 'prev_song',
  SEEK_TO = 'seek_to',
  OPEN_APP = 'open_app',
  OPEN_PLAYER = 'open_player'
}

interface WidgetControlMessage {
  command: WidgetCommand
  params?: {
    position?: number
    songId?: string
  }
}

接口设计

与主应用通信接口

interface AppCommunicationService {
  // 发送控制命令到主应用
  sendControlCommand(command: WidgetCommand, params?: any): Promise<boolean>
  
  // 获取当前播放状态
  getCurrentPlayState(): Promise<WidgetData>
  
  // 注册状态变化监听
  registerStateListener(callback: (data: WidgetData) => void): void
  
  // 启动主应用
  launchMainApp(page?: string): Promise<boolean>
}

卡片数据管理接口

interface WidgetDataManager {
  // 保存卡片数据
  saveWidgetData(formId: string, data: WidgetData): Promise<void>
  
  // 获取卡片数据
  getWidgetData(formId: string): Promise<WidgetData>
  
  // 更新卡片显示
  updateWidget(formId: string, data: WidgetData): Promise<void>
  
  // 批量更新所有卡片
  updateAllWidgets(data: WidgetData): Promise<void>
}

错误处理

错误类型定义

enum WidgetErrorType {
  COMMUNICATION_ERROR = 'communication_error',
  DATA_SYNC_ERROR = 'data_sync_error',
  CONTROL_COMMAND_ERROR = 'control_command_error',
  LAYOUT_ERROR = 'layout_error'
}

interface WidgetError {
  type: WidgetErrorType
  message: string
  code: number
  timestamp: number
}

错误处理策略

通信错误: 显示离线状态，提供重连机制
数据同步错误: 使用缓存数据，后台重试同步
控制命令错误: 显示操作失败提示，记录错误日志
布局错误: 降级到基础布局，确保基本功能可用

测试策略

单元测试

FormProvider业务逻辑测试
数据模型转换测试
通信接口模拟测试
错误处理逻辑测试

集成测试

卡片与主应用通信测试
多卡片实例同步测试
系统媒体会话集成测试
不同尺寸布局适配测试

用户体验测试

卡片响应速度测试
状态同步准确性测试
多场景交互测试
异常情况恢复测试

性能优化

数据更新优化

使用增量更新减少数据传输
实现智能缓存机制
优化图片加载和缓存
控制更新频率避免过度刷新

内存管理

及时释放不用的资源
优化图片内存占用
控制卡片实例数量
实现内存泄漏监控

电量优化

减少不必要的后台活动
优化定时器使用
智能调整更新频率
配合系统省电模式

安全考虑

数据安全

敏感信息加密存储
验证通信数据完整性
防止恶意命令注入
限制卡片权限范围

隐私保护

最小化数据收集
用户授权机制
数据本地化处理
遵循隐私保护规范

design.md 6.7 KB History Raw