更新记录

1.0.0（2025-06-22）

1.0.0

平台兼容性

uni-app(4.03)

uni-app x(4.03)

其他

LearningTimer.vue 组件使用文档

yuCloudTimer.vue 是一个专为 uni-app 设计的高精度、高自定义性的计时器组件。它不仅在视觉上精确复刻了设计稿，还在功能上提供了强大的灵活性，以满足各种业务场景的需求。 (请注意：此为示意图，实际效果取决于您的字体配置)

✨ 功能特性

• 高精度计时：计时逻辑基于 Date.now()，不受 setInterval 自身延迟的影响，确保了时间的绝对准确性。
• 生命周期感知：能自动监听 uni-app 的应用生命周期，当应用切换到后台时自动暂停计时，切换回前台时无缝续计。
• 自定义初始值：可以从外部传入一个初始秒数，让计时器从任意时间点开始。
• 动态重置：支持在运行时通过改变 prop 来动态重置计时器到新的时间点。
• 实时数据输出：通过事件 (emit) 每秒向父组件报告当前累计的总秒数，方便您进行存储、计算或与其他业务逻辑联动。
• 设计稿忠实还原：精确实现了 MasterGo 设计稿中的毛玻璃（Glassmorphism）背景、数字时钟字体效果和布局。

🚀 快速上手

在您的页面中引入并使用该组件。

<!-- /pages/study/index.vue -->
<template>
  <view class="container">
    <yuCloudTimer
      :initial-seconds="savedProgress"
      @update:time="handleTimeUpdate" 
    />
  </view>
</template>

<script setup>
import { ref } from 'vue';
import yuCloudTimer from '@/uni_modules/yuCloud-Timer/components/yuCloud-Timer/yuCloud-Timer.vue'; // 确保路径正确

const savedProgress = ref(300); // 模拟从 storage 或 API 加载的进度
const totalSeconds = ref(0);

// 该函数会每秒被调用一次
const handleTimeUpdate = (seconds) => {
  totalSeconds.value = seconds;

  // 例如：可以实现每10秒自动保存一次进度
  if (seconds > 0 && seconds % 10 === 0) {
    console.log(`正在保存当前进度: ${seconds} 秒`);
    // uni.setStorageSync('learning_progress', seconds);
  }
};
</script>

📋 API 文档

Props

Events

⚠️ 重要：字体配置 内部已添加

为了完美再现设计稿中的数字时钟效果，组件必须依赖特殊的 DS-Digital 字体。

请按照以下步骤配置字体：

1. 下载 DS-Digital 字体文件（支持 .ttf 或 .woff2 格式）。
2. 将字体文件放置到您项目的静态资源目录中，例如 /static/fonts/。
3. 打开 LearningTimer.vue 文件，修改 <style> 部分的 @font-face 规则，确保 src: url() 的路径指向您刚刚放置的字体文件。

代码示例：

/* LearningTimer.vue -> <style> */

@font-face {
  font-family: 'DS-Digital';
  /* 
    请将此路径修改为您项目中字体的实际路径！
    例如: /static/zt/DS-Digital.ttf
  */
  src: url('/static/zt/DS-Digital.ttf') format('truetype');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

响应式与复用性说明

• 屏幕尺寸：组件 UI 完全使用 rpx 单位和 Flexbox 布局，能够自动、等比例地适配从小型到大型的各类设备屏幕，不会出现布局错乱。
• 代码复用：组件被设计为一个高内聚、低耦合的独立模块，可通过 props 和 emits 与外部清晰地交互，可以在项目中任何需要的页面"即插即用"，无需担心副作用。