鸿蒙原生农历查询 (Lunar Calendar)

项目概述

简介

农历查询是一款简单实用的应用，可以帮助用户查询公历日期对应的农历信息、干支纪年、宜忌、吉凶、方位等传统历法信息。应用支持多平台部署，包括Android、iOS以及鸿蒙系统。

背景和动机

作为中华传统文化的重要组成部分，农历在我国有着深远的影响。为了传承和弘扬中华优秀传统文化，同时支持国产鸿蒙生态的发展，我投入了大量心血开发了这款应用。在开发过程中，我克服了诸多技术难题，特别是在适配鸿蒙系统方面付出了巨大努力。开源这个项目是希望能够为中国软件生态贡献一份力量，也期望更多开发者能够加入到支持国产操作系统的行列中来，共同推动技术创新和文化传承。

效果

功能特点

• 多样化信息展示：提供农历日期、干支纪年、生肖、星座、宜忌、方位等全面信息
• 分类标签页：通过标签页分类展示不同类型的信息，使界面更加清晰
• 方位指南针：直观展示方位信息，帮助用户理解传统方位概念
• 深色模式支持：支持浅色、深色和跟随系统三种主题模式
• 本地缓存功能：减少重复API请求，提高应用性能和离线使用体验
• 网络状态监测：实时检测网络连接状态，提供友好的错误提示
• 长按复制功能：支持长按复制信息内容，提高用户体验
• 多平台适配：支持Android、iOS和鸿蒙系统

安装与配置

环境要求

• Flutter SDK 3.21.0 或更高版本
• Dart SDK 3.0.0 或更高版本
• Android Studio / VS Code
• 对于鸿蒙开发：DevEco Studio

安装步骤

1. 克隆项目仓库

   git clone git@gitcode.com:nutpi/flutter_harmony_lunar.git
   

2. 进入项目目录

   cd flutter_harmony_lunar
   

3. 配置API密钥

   cp lib/config/api_config.template.dart lib/config/api_config.dart
   

   然后编辑 lib/config/api_config.dart 文件，将 YOUR_API_TOKEN_HERE 替换为您的实际API密钥。

4. 安装依赖

   flutter pub get
   

5. 运行应用

   flutter run
   

使用方法

基本操作

1. 启动应用后，默认显示当天的农历信息
2. 点击"选择日期"按钮可以选择任意日期查询对应的农历信息
3. 点击右上角的刷新图标可以强制刷新数据
4. 点击右上角的主题图标可以切换深色/浅色模式
5. 点击右上角的信息图标可以查看应用的关于页面
6. 在信息卡片上长按可以复制相应的内容

界面导航

• 基本信息：显示公历日期、农历日期、生肖、星座等基本信息
• 干支命理：显示年柱、月柱、日柱、时柱等干支信息
• 宜忌：显示当日宜忌事项和吉凶神信息
• 方位：显示财神、福神、喜神等方位信息和方位指南针

技术实现

架构设计

项目采用 Flutter 框架开发，使用分层架构设计，主要分为以下几个模块：

• 数据模型层：定义农历数据结构
• 服务层：处理API请求、数据解析和缓存
• UI层：实现用户交互界面
• 工具类：提供辅助功能

技术特点

• 本地缓存：使用SharedPreferences实现数据缓存，减少网络请求
• 网络监测：使用connectivity_plus监测网络状态变化
• 主题管理：支持深色模式和浅色模式，并保存用户偏好
• 响应式UI：使用Flutter的响应式UI框架，适配不同屏幕尺寸
• 错误处理：完善的错误处理机制，提供友好的用户提示
• API安全：将API密钥存储在单独的配置文件中，避免泄露

技术栈

• 前端框架：Flutter
• 状态管理：StatefulWidget
• 网络请求：http
• 本地存储：shared_preferences
• 国际化：intl + flutter_localizations
• 链接处理：url_launcher
• 网络监测：connectivity_plus
• 版本信息：package_info_plus

贡献指南

贡献流程

1. Fork 项目仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

代码规范

• 遵循 Flutter 官方推荐的代码风格
• 使用有意义的变量名和函数名
• 添加必要的注释
• 确保代码通过 lint 检查

许可证信息

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

维护与支持

维护者信息

• 作者：坚果派
• 公众号：nutpi
• 电话：17752170152
• 官网：https://www.nutpi.net/

问题反馈

如有问题或建议，请通过以下方式反馈：

• 在项目仓库创建 Issue
• 发送邮件至维护者
• 关注公众号"nutpi"并留言

相关资源

• Flutter 官方文档
• Dart 官方文档
• [鸿蒙开发文档](