# VeilTimeAndroid

**Repository Path**: Ez17Code/veil-time-android

## Basic Information

- **Project Name**: VeilTimeAndroid
- **Description**: **VeilTime 系列的 Android 移动端 — 悬浮时钟 & 桌面 Widget**

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# VeilTime Android (轻纱时钟)

**VeilTime 系列的 Android 移动端 — 悬浮时钟 & 桌面 Widget**

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Kotlin](https://img.shields.io/badge/Kotlin-1.9-7F52FF.svg)](https://kotlinlang.org/)
[![Platform](https://img.shields.io/badge/platform-Android%208.0+-3DDC84.svg)](https://developer.android.com/)
[![API](https://img.shields.io/badge/API-26+-3DDC84.svg)]()

[功能特性](#-核心特性) • [快速开始](#-快速开始) • [姐妹项目](#-姐妹项目)

</div>

---

## 简介

VeilTime Android 是 [VeilTime（轻纱时钟）](https://gitee.com/Ez17Code/VeilTime-open-source) 的 Android 移动端实现。延续"纯净、沉浸、不打扰"的设计理念，为 Android 用户提供悬浮时钟和桌面 Widget 两种使用方式。

## 核心特性

### 悬浮时钟
- **极致沉浸**：纯透明悬浮窗，无边框无背景，如轻纱般融入屏幕
- **自由拖拽**：长按 5 秒进入设置，支持全屏拖拽定位，上下边界限位防脱
- **农历显示**：原生 Kotlin 算法，支持 1900-2050 年精确农历日期
- **整点报时**：准点发出轻柔提示音，优雅提醒时间流逝
- **开机自启**：支持开机自动启动，无需手动操作

### 桌面 Widget
- **圆形模拟时钟**：经典表盘设计，刻度线 + 分钟数字，时针/分针/秒针分色显示
- **四种尺寸**：1x1 / 2x2 / 3x3 / 4x4，适配不同桌面布局
- **智能高刷**：常态 1 分钟刷新省电，点击激活 60 秒每秒高刷（秒针实时转动）
- **调试覆盖**：高刷模式下显示 HH:MM:SS 时间戳，便于状态确认

### 省电优化
- **混合刷新策略**：Widget 默认低频更新（1 分钟），仅在用户交互时短暂高刷
- **前台 Service**：高刷期间使用前台 Service + Handler，替代被系统限频的 AlarmManager
- **自动停止**：60 秒高刷到期后自动停止 Service，零额外功耗

## 快速开始

### 环境要求
- Android Studio Hedgehog (2023.1.1) 或更高版本
- Android SDK 34
- Gradle 8.6+

### 构建运行

```bash
# 克隆仓库
git clone git@gitee.com:Ez17Code/veil-time-android.git
cd veil-time-android

# Android Studio 打开项目，或命令行构建
./gradlew assembleDebug

# 安装到设备
adb install app/build/outputs/apk/debug/app-arm64-v8a-debug.apk
```

### 权限说明

| 权限 | 用途 |
|------|------|
| `SYSTEM_ALERT_WINDOW` | 悬浮窗显示 |
| `FOREGROUND_SERVICE` | 前台服务（高刷 Widget） |
| `USE_EXACT_ALARM` | 整点报时（时钟类应用专属） |
| `RECEIVE_BOOT_COMPLETED` | 开机自启 |
| `VIBRATE` | 提示音/震动反馈 |

## 项目结构

```
app/src/main/java/com/anonym/floatingclock/
├── MainActivity.kt              # 主设置界面
├── FloatingClockService.kt      # 悬浮窗前台服务
├── ClockWindowPositioner.kt     # 悬浮窗位置限位
├── ClockTouchHandler.kt         # 触摸手势处理
├── HourlyChimeReceiver.kt       # 整点报时
├── BootReceiver.kt              # 开机自启
└── widget/
    ├── ClockWidgetRenderer.kt   # Widget 表盘渲染
    ├── ClockWidgetBoostService.kt # 高刷前台 Service
    ├── ClockWidgetProvider*.kt   # 4 种尺寸 Provider
    ├── LunarCalendarCalculator.kt # 农历算法
    └── ...
```

## 姐妹项目

VeilTime 是一个跨平台时钟系列：

| 平台 | 仓库 | 技术栈 |
|------|------|--------|
| Windows 桌面 | [VeilTime-open-source](https://gitee.com/Ez17Code/VeilTime-open-source) | C# + Avalonia UI |
| Android 移动 | [veil-time-android](https://gitee.com/Ez17Code/veil-time-android) | Kotlin + Android SDK |

## 许可证

本项目基于 [MIT License](LICENSE) 开源。