桌面卡片

.kiro/specs/desktop-player-widget/tasks.md

@@ -7,7 +7,7 @@
   - _需求: 1.1, 6.1_
 
 - [ ] 2. 实现卡片数据管理
-- [ ] 2.1 创建卡片数据模型和管理器
+- [x] 2.1 创建卡片数据模型和管理器
   - 定义WidgetData接口和相关数据结构
   - 实现WidgetDataManager类处理数据持久化
   - 创建卡片状态缓存机制

entry/src/main/ets/common/widget/WidgetDataManager.ets

@@ -2,20 +2,33 @@ import formProvider from '@ohos.app.form.formProvider';
 import formBindingData from '@ohos.app.form.formBindingData';
 import preferences from '@ohos.data.preferences';
 import { hilog } from '@kit.PerformanceAnalysisKit';
-import { WidgetData, WidgetSize, WidgetTheme, FormattedWidgetData, PreferencesData } from './WidgetTypes';
+import { WidgetData, WidgetSize, WidgetTheme, FormattedWidgetData, PreferencesData, CacheStats } from './WidgetTypes';
 
 const TAG = 'WidgetDataManager';
 const WIDGET_PREFERENCES_NAME = 'widget_data_prefs';
+const CACHE_EXPIRY_TIME = 30 * 1000; // 30秒缓存过期时间
+
+/**
+ * 缓存项接口
+ */
+interface CacheItem {
+  data: WidgetData;
+  timestamp: number;
+  expiry: number;
+}
 
 /**
  * 卡片数据管理器
- * 负责卡片数据的持久化存储和更新
+ * 负责卡片数据的持久化存储、缓存和更新
  */
 export class WidgetDataManager {
   private preferencesStore: preferences.Preferences | null = null;
+  private dataCache: Map<string, CacheItem> = new Map();
+  private lastUpdateTime: number = 0;
 
   constructor() {
     this.initPreferences();
+    this.startCacheCleanup();
   }
 
   /**
@@ -226,4 +239,160 @@ export class WidgetDataManager {
     }
     return text.substring(0, maxLength - 1) + '…';
   }
+
+  /**
+   * 启动缓存清理定时器
+   */
+  private startCacheCleanup(): void {
+    setInterval(() => {
+      this.cleanExpiredCache();
+    }, 60 * 1000); // 每分钟清理一次过期缓存
+  }
+
+  /**
+   * 清理过期缓存
+   */
+  private cleanExpiredCache(): void {
+    const now = Date.now();
+    const expiredKeys: string[] = [];
+    
+    this.dataCache.forEach((item, key) => {
+      if (now > item.expiry) {
+        expiredKeys.push(key);
+      }
+    });
+    
+    expiredKeys.forEach(key => {
+      this.dataCache.delete(key);
+    });
+    
+    if (expiredKeys.length > 0) {
+      hilog.info(0x0000, TAG, `Cleaned ${expiredKeys.length} expired cache items`);
+    }
+  }
+
+  /**
+   * 从缓存获取数据
+   */
+  private getCachedData(formId: string): WidgetData | null {
+    const cacheKey = `cache_${formId}`;
+    const cacheItem = this.dataCache.get(cacheKey);
+    
+    if (cacheItem && Date.now() < cacheItem.expiry) {
+      hilog.info(0x0000, TAG, `Cache hit for form: ${formId}`);
+      return cacheItem.data;
+    }
+    
+    if (cacheItem) {
+      // 缓存已过期，删除
+      this.dataCache.delete(cacheKey);
+      hilog.info(0x0000, TAG, `Cache expired for form: ${formId}`);
+    }
+    
+    return null;
+  }
+
+  /**
+   * 设置缓存数据
+   */
+  private setCachedData(formId: string, data: WidgetData): void {
+    const cacheKey = `cache_${formId}`;
+    const now = Date.now();
+    
+    const cacheItem: CacheItem = {
+      data: data,
+      timestamp: now,
+      expiry: now + CACHE_EXPIRY_TIME
+    };
+    
+    this.dataCache.set(cacheKey, cacheItem);
+    hilog.info(0x0000, TAG, `Data cached for form: ${formId}`);
+  }
+
+  /**
+   * 获取卡片数据（带缓存）
+   */
+  async getWidgetDataWithCache(formId: string): Promise<WidgetData> {
+    // 先尝试从缓存获取
+    const cachedData = this.getCachedData(formId);
+    if (cachedData) {
+      return cachedData;
+    }
+    
+    // 缓存未命中，从持久化存储获取
+    const data = await this.getWidgetData(formId);
+    
+    // 设置缓存
+    this.setCachedData(formId, data);
+    
+    return data;
+  }
+
+  /**
+   * 更新卡片数据（带缓存）
+   */
+  async updateWidgetWithCache(formId: string, data: WidgetData): Promise<void> {
+    // 更新缓存
+    this.setCachedData(formId, data);
+    
+    // 更新卡片显示
+    await this.updateWidget(formId, data);
+  }
+
+  /**
+   * 清除指定卡片的缓存
+   */
+  clearWidgetCache(formId: string): void {
+    const cacheKey = `cache_${formId}`;
+    if (this.dataCache.has(cacheKey)) {
+      this.dataCache.delete(cacheKey);
+      hilog.info(0x0000, TAG, `Cache cleared for form: ${formId}`);
+    }
+  }
+
+  /**
+   * 清除所有缓存
+   */
+  clearAllCache(): void {
+    const cacheSize = this.dataCache.size;
+    this.dataCache.clear();
+    hilog.info(0x0000, TAG, `All cache cleared, ${cacheSize} items removed`);
+  }
+
+  /**
+   * 获取缓存统计信息
+   */
+  getCacheStats(): CacheStats {
+    const stats: CacheStats = {
+      size: this.dataCache.size,
+      hitRate: 0, // 可以在实际使用中统计命中率
+      lastUpdate: this.lastUpdateTime
+    };
+    return stats;
+  }
+
+  /**
+   * 预热缓存
+   */
+  async preloadCache(): Promise<void> {
+    try {
+      if (!this.preferencesStore) {
+        await this.initPreferences();
+      }
+      
+      const allKeys = await this.preferencesStore?.getAll();
+      const emptyPrefs: PreferencesData = {};
+      const widgetKeys = Object.keys(allKeys || emptyPrefs).filter(key => key.startsWith('widget_'));
+      
+      for (const key of widgetKeys) {
+        const formId = key.replace('widget_', '');
+        const data = await this.getWidgetData(formId);
+        this.setCachedData(formId, data);
+      }
+      
+      hilog.info(0x0000, TAG, `Cache preloaded for ${widgetKeys.length} widgets`);
+    } catch (error) {
+      hilog.error(0x0000, TAG, `Failed to preload cache: ${error}`);
+    }
+  }
 }

entry/src/main/ets/common/widget/WidgetDataManagerTest.ets

@@ -0,0 +1,286 @@
+import { hilog } from '@kit.PerformanceAnalysisKit';
+import { WidgetDataManager } from './WidgetDataManager';
+import { WidgetData, WidgetSize, WidgetTheme } from './WidgetTypes';
+
+const TAG = 'WidgetDataManagerTest';
+
+/**
+ * 卡片数据管理器测试类
+ * 用于验证数据模型和管理器的功能
+ */
+export class WidgetDataManagerTest {
+  private dataManager: WidgetDataManager;
+
+  constructor() {
+    this.dataManager = new WidgetDataManager();
+  }
+
+  /**
+   * 运行所有测试
+   */
+  async runAllTests(): Promise<boolean> {
+    hilog.info(0x0000, TAG, 'Starting WidgetDataManager tests...');
+    
+    try {
+      await this.testInitialData();
+      await this.testDataPersistence();
+      await this.testCacheOperations();
+      await this.testDataFormatting();
+      await this.testBatchOperations();
+      
+      hilog.info(0x0000, TAG, 'All tests passed successfully!');
+      return true;
+    } catch (error) {
+      hilog.error(0x0000, TAG, `Test failed: ${error}`);
+      return false;
+    }
+  }
+
+  /**
+   * 测试初始数据
+   */
+  private async testInitialData(): Promise<void> {
+    hilog.info(0x0000, TAG, 'Testing initial data...');
+    
+    const initialData = this.dataManager.getInitialWidgetData();
+    
+    // 验证初始数据结构
+    if (!initialData.playState || !initialData.currentSong || !initialData.progress) {
+      throw new Error('Initial data structure is incomplete');
+    }
+    
+    // 验证默认值
+    if (initialData.playState.isPlaying !== false) {
+      throw new Error('Initial play state should be false');
+    }
+    
+    if (initialData.currentSong.title !== '暂无播放') {
+      throw new Error('Initial song title should be "暂无播放"');
+    }
+    
+    hilog.info(0x0000, TAG, 'Initial data test passed');
+  }
+
+  /**
+   * 测试数据持久化
+   */
+  private async testDataPersistence(): Promise<void> {
+    hilog.info(0x0000, TAG, 'Testing data persistence...');
+    
+    const testFormId = 'test_form_001';
+    const testData: WidgetData = {
+      playState: {
+        isPlaying: true,
+        isPaused: false,
+        isLoading: false
+      },
+      currentSong: {
+        id: 'song_001',
+        title: '测试歌曲',
+        artist: '测试艺术家',
+        album: '测试专辑',
+        coverImagePath: '/test/cover.jpg',
+        duration: 240
+      },
+      progress: {
+        currentPosition: 60,
+        duration: 240,
+        percentage: 25,
+        currentTimeText: '01:00',
+        totalTimeText: '04:00'
+      },
+      playlist: {
+        hasNext: true,
+        hasPrevious: false,
+        currentIndex: 0,
+        totalCount: 10
+      },
+      config: {
+        size: WidgetSize.LARGE,
+        theme: WidgetTheme.LIGHT,
+        showProgress: true,
+        showCover: true
+      }
+    };
+    
+    // 保存数据
+    await this.dataManager.saveWidgetData(testFormId, testData);
+    
+    // 读取数据
+    const retrievedData = await this.dataManager.getWidgetData(testFormId);
+    
+    // 验证数据一致性
+    if (retrievedData.currentSong.title !== testData.currentSong.title) {
+      throw new Error('Data persistence failed: song title mismatch');
+    }
+    
+    if (retrievedData.playState.isPlaying !== testData.playState.isPlaying) {
+      throw new Error('Data persistence failed: play state mismatch');
+    }
+    
+    hilog.info(0x0000, TAG, 'Data persistence test passed');
+  }
+
+  /**
+   * 测试缓存操作
+   */
+  private async testCacheOperations(): Promise<void> {
+    hilog.info(0x0000, TAG, 'Testing cache operations...');
+    
+    const testFormId = 'test_form_cache';
+    const testData = this.dataManager.getInitialWidgetData();
+    testData.currentSong.title = '缓存测试歌曲';
+    
+    // 测试缓存设置和获取
+    await this.dataManager.updateWidgetWithCache(testFormId, testData);
+    const cachedData = await this.dataManager.getWidgetDataWithCache(testFormId);
+    
+    if (cachedData.currentSong.title !== testData.currentSong.title) {
+      throw new Error('Cache operation failed: data mismatch');
+    }
+    
+    // 测试缓存清理
+    this.dataManager.clearWidgetCache(testFormId);
+    
+    // 获取缓存统计
+    const stats = this.dataManager.getCacheStats();
+    if (typeof stats.size !== 'number') {
+      throw new Error('Cache stats invalid');
+    }
+    
+    hilog.info(0x0000, TAG, 'Cache operations test passed');
+  }
+
+  /**
+   * 测试数据格式化
+   */
+  private async testDataFormatting(): Promise<void> {
+    hilog.info(0x0000, TAG, 'Testing data formatting...');
+    
+    const testData: WidgetData = {
+      playState: {
+        isPlaying: true,
+        isPaused: false,
+        isLoading: false
+      },
+      currentSong: {
+        id: 'format_test',
+        title: '这是一个非常长的歌曲标题用来测试文本截断功能',
+        artist: '这是一个非常长的艺术家名称',
+        album: '专辑',
+        coverImagePath: '',
+        duration: 180
+      },
+      progress: {
+        currentPosition: 90,
+        duration: 180,
+        percentage: 50,
+        currentTimeText: '01:30',
+        totalTimeText: '03:00'
+      },
+      playlist: {
+        hasNext: true,
+        hasPrevious: true,
+        currentIndex: 5,
+        totalCount: 20
+      },
+      config: {
+        size: WidgetSize.MEDIUM,
+        theme: WidgetTheme.AUTO,
+        showProgress: true,
+        showCover: false
+      }
+    };
+    
+    // 这里我们无法直接测试私有方法formatDataForWidget
+    // 但可以通过updateWidget间接测试
+    const testFormId = 'format_test_form';
+    await this.dataManager.saveWidgetData(testFormId, testData);
+    
+    hilog.info(0x0000, TAG, 'Data formatting test passed');
+  }
+
+  /**
+   * 测试批量操作
+   */
+  private async testBatchOperations(): Promise<void> {
+    hilog.info(0x0000, TAG, 'Testing batch operations...');
+    
+    // 创建多个测试卡片
+    const testForms = ['batch_001', 'batch_002', 'batch_003'];
+    const testData = this.dataManager.getInitialWidgetData();
+    testData.currentSong.title = '批量测试歌曲';
+    
+    // 保存多个卡片数据
+    for (const formId of testForms) {
+      await this.dataManager.saveWidgetData(formId, testData);
+    }
+    
+    // 测试批量更新
+    testData.currentSong.title = '批量更新后的歌曲';
+    await this.dataManager.updateAllWidgets(testData);
+    
+    // 验证更新结果
+    for (const formId of testForms) {
+      const updatedData = await this.dataManager.getWidgetData(formId);
+      if (updatedData.currentSong.title !== testData.currentSong.title) {
+        throw new Error(`Batch update failed for form: ${formId}`);
+      }
+    }
+    
+    // 清理测试数据
+    for (const formId of testForms) {
+      await this.dataManager.removeWidgetData(formId);
+    }
+    
+    hilog.info(0x0000, TAG, 'Batch operations test passed');
+  }
+
+  /**
+   * 创建测试数据
+   */
+  createTestWidgetData(): WidgetData {
+    return {
+      playState: {
+        isPlaying: true,
+        isPaused: false,
+        isLoading: false
+      },
+      currentSong: {
+        id: 'test_song_123',
+        title: '测试歌曲标题',
+        artist: '测试艺术家',
+        album: '测试专辑',
+        coverImagePath: '/test/path/cover.jpg',
+        duration: 300
+      },
+      progress: {
+        currentPosition: 150,
+        duration: 300,
+        percentage: 50,
+        currentTimeText: '02:30',
+        totalTimeText: '05:00'
+      },
+      playlist: {
+        hasNext: true,
+        hasPrevious: true,
+        currentIndex: 2,
+        totalCount: 15
+      },
+      config: {
+        size: WidgetSize.LARGE,
+        theme: WidgetTheme.DARK,
+        showProgress: true,
+        showCover: true
+      }
+    };
+  }
+}
+
+/**
+ * 运行测试的便捷函数
+ */
+export async function runWidgetDataManagerTests(): Promise<boolean> {
+  const tester = new WidgetDataManagerTest();
+  return await tester.runAllTests();
+}

entry/src/main/ets/common/widget/WidgetTypes.ets

@@ -175,4 +175,28 @@ export interface FormattedWidgetData {
  * 偏好设置数据接口
  */
 export class PreferencesData {
+}
+
+/**
+ * 卡片操作数据接口
+ */
+export interface WidgetActionData {
+  action: string;
+  params: Record<string, Object>;
+}
+
+/**
+ * 缓存统计信息接口
+ */
+export interface CacheStats {
+  size: number;
+  hitRate: number;
+  lastUpdate: number;
+}
+
+/**
+ * 进度跳转参数接口
+ */
+export interface SeekParams {
+  percentage: number;
 }

entry/src/main/ets/common/widget/WidgetUtils.ets

@@ -0,0 +1,83 @@
+import { hilog } from '@kit.PerformanceAnalysisKit';
+import { WidgetActionData } from './WidgetTypes';
+
+const TAG = 'WidgetUtils';
+
+/**
+ * 卡片工具函数
+ */
+
+/**
+ * 向卡片发送操作事件
+ * @param context 卡片上下文
+ * @param data 事件数据
+ */
+export function postCardAction(context: Object, data: WidgetActionData): void {
+  try {
+    const message = JSON.stringify(data);
+    hilog.info(0x0000, TAG, `Posting card action: ${message}`);
+    
+    // 使用全局postCardAction函数发送卡片事件
+    // 这个函数在卡片运行时环境中可用
+    (globalThis as ESObject).postCardAction(context, message);
+  } catch (error) {
+    hilog.error(0x0000, TAG, `Failed to post card action: ${error}`);
+  }
+}
+
+/**
+ * 格式化时间显示
+ * @param seconds 秒数
+ * @returns 格式化的时间字符串 (mm:ss)
+ */
+export function formatTime(seconds: number): string {
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
+}
+
+/**
+ * 计算播放进度百分比
+ * @param current 当前位置
+ * @param total 总时长
+ * @returns 百分比 (0-100)
+ */
+export function calculatePercentage(current: number, total: number): number {
+  if (total <= 0) return 0;
+  return Math.min(100, Math.max(0, (current / total) * 100));
+}
+
+/**
+ * 截断文本
+ * @param text 原始文本
+ * @param maxLength 最大长度
+ * @returns 截断后的文本
+ */
+export function truncateText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return text.substring(0, maxLength - 1) + '…';
+}
+
+/**
+ * 验证卡片数据完整性
+ * @param data 卡片数据
+ * @returns 是否有效
+ */
+export function validateWidgetData(data: Record<string, Object>): boolean {
+  try {
+    // 检查必要字段
+    const requiredFields = ['playState', 'currentSong', 'progress', 'playlist', 'config'];
+    for (const field of requiredFields) {
+      if (!data[field]) {
+        hilog.warn(0x0000, TAG, `Missing required field: ${field}`);
+        return false;
+      }
+    }
+    return true;
+  } catch (error) {
+    hilog.error(0x0000, TAG, `Error validating widget data: ${error}`);
+    return false;
+  }
+}

entry/src/main/ets/common/widget/index.ets

@@ -0,0 +1,42 @@
+/**
+ * 卡片模块导出文件
+ * 统一导出所有卡片相关的类型、接口和工具
+ */
+
+// 数据类型和接口
+export {
+  WidgetSize,
+  WidgetTheme,
+  WidgetCommand,
+  WidgetErrorType,
+  type PlayState,
+  type SongInfo,
+  type PlayProgress,
+  type PlaylistState,
+  type WidgetConfig,
+  type WidgetData,
+  type WidgetControlParams,
+  type WidgetControlMessage,
+  type WidgetError,
+  type EventData,
+  type RequestData,
+  type FormattedWidgetData
+} from './WidgetTypes';
+
+// 数据管理器
+export { WidgetDataManager } from './WidgetDataManager';
+
+// 播放控制服务
+export { PlayerControlService } from './PlayerControlService';
+
+// 工具函数
+export {
+  postCardAction,
+  formatTime,
+  calculatePercentage,
+  truncateText,
+  validateWidgetData
+} from './WidgetUtils';
+
+// 测试工具
+export { WidgetDataManagerTest, runWidgetDataManagerTests } from './WidgetDataManagerTest';

entry/src/main/ets/widget/pages/PlayerWidgetLarge.ets

@@ -1,3 +1,6 @@
+import { postCardAction } from '../../common/widget/WidgetUtils';
+import { WidgetActionData, SeekParams } from '../../common/widget/WidgetTypes';
+
 /**
  * 大尺寸播放器卡片 (4x3)
  * 显示专辑封面、完整信息和扩展控制
@@ -184,10 +187,11 @@ struct PlayerWidgetLarge {
    * 处理控制操作
    */
   private handleControlAction(action: string): void {
-    postCardAction(this, {
+    const actionData: WidgetActionData = {
       action: action,
       params: {}
-    });
+    };
+    postCardAction(this, actionData);
   }
 
   /**
@@ -199,11 +203,13 @@ struct PlayerWidgetLarge {
     const progressWidth = event.target.area.width as number;
     const percentage = (clickX / progressWidth) * 100;
     
-    postCardAction(this, {
+    const seekParams: SeekParams = {
+      percentage: percentage
+    };
+    const seekData: WidgetActionData = {
       action: 'seek_to',
-      params: {
-        percentage: percentage
-      }
-    });
+      params: seekParams
+    };
+    postCardAction(this, seekData);
   }
 }

entry/src/main/ets/widget/pages/PlayerWidgetMedium.ets

@@ -1,3 +1,6 @@
+import { postCardAction } from '../../common/widget/WidgetUtils';
+import { WidgetActionData, SeekParams } from '../../common/widget/WidgetTypes';
+
 /**
  * 中等尺寸播放器卡片 (4x2)
  * 显示完整信息、播放控制和进度条
@@ -151,10 +154,11 @@ struct PlayerWidgetMedium {
    * 处理控制操作
    */
   private handleControlAction(action: string): void {
-    postCardAction(this, {
+    const actionData: WidgetActionData = {
       action: action,
       params: {}
-    });
+    };
+    postCardAction(this, actionData);
   }
 
   /**
@@ -166,11 +170,13 @@ struct PlayerWidgetMedium {
     const progressWidth = event.target.area.width as number;
     const percentage = (clickX / progressWidth) * 100;
     
-    postCardAction(this, {
+    const seekParams: SeekParams = {
+      percentage: percentage
+    };
+    const seekData: WidgetActionData = {
       action: 'seek_to',
-      params: {
-        percentage: percentage
-      }
-    });
+      params: seekParams
+    };
+    postCardAction(this, seekData);
   }
 }

entry/src/main/ets/widget/pages/PlayerWidgetSmall.ets

@@ -1,3 +1,6 @@
+import { postCardAction } from '../../common/widget/WidgetUtils';
+import { WidgetActionData } from '../../common/widget/WidgetTypes';
+
 /**
  * 小尺寸播放器卡片 (2x1)
  * 显示基本播放控制和歌曲名称
@@ -95,9 +98,10 @@ struct PlayerWidgetSmall {
    * 处理控制操作
    */
   private handleControlAction(action: string): void {
-    postCardAction(this, {
+    const actionData: WidgetActionData = {
       action: action,
       params: {}
-    });
+    };
+    postCardAction(this, actionData);
   }
 }