# HarmonyOS通用应用框架

**Repository Path**: chaoqun/ohapp

## Basic Information

- **Project Name**: HarmonyOS通用应用框架
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-06
- **Last Updated**: 2026-02-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS 通用应用框架

> 🚀 **快速构建高质量的HarmonyOS应用**

HarmonyOS通用应用框架是一个基于ArkTS语言开发的高质量、模块化的应用开发基础框架。它集成了现代化的应用架构设计，提供了丰富的通用功能模块，帮助开发者快速构建功能完整、性能优异的HarmonyOS应用。

## 🎯 应用介绍

**HarmonyOS通用应用框架** 是一个开箱即用的HarmonyOS应用开发解决方案，旨在为开发者提供：

- **快速启动** - 基于成熟的架构设计，快速开始新项目开发
- **模块化设计** - 清晰的代码组织结构，便于维护和扩展
- **生产就绪** - 包含权限管理、状态管理、数据持久化等企业级功能
- **最佳实践** - 遵循HarmonyOS开发规范和设计模式
- **多设备适配** - 支持手机、平板、车机等多种设备类型

无论您是HarmonyOS新手还是经验丰富的开发者，这个框架都能帮助您显著提升开发效率，专注于业务逻辑的实现。

## 🚀 特性

### 核心架构
- **模块化设计** - 清晰的服务层、组件层、工具层分离
- **响应式状态管理** - 基于ArkTS的AppStorageV2和PersistenceV2
- **生命周期管理** - 完整的应用生命周期管理机制
- **多设备适配** - 支持手机、平板、车机等多种设备类型

### 通用功能模块
- **使用时长追踪** - 自动记录用户使用时长和连续使用天数
- **会员奖励系统** - 基于连续使用的会员激励机制
- **权限管理** - 统一的权限请求和管理机制
- **通知系统** - 完整的通知权限管理和消息推送
- **颜色模式** - 支持深色/浅色模式切换
- **欢迎引导** - 美观的引导页面和用户引导流程

### 开发工具
- **窗口管理** - 智能窗口尺寸适配和断点管理
- **数据库服务** - 基于RelationalStore的数据持久化
- **工具类库** - 丰富的工具函数和辅助类
- **动画系统** - 流畅的页面切换和交互动画

## 📁 项目结构

```
entry/
├── src/main/
│   ├── ets/
│   │   ├── entryability/          # 应用入口能力
│   │   ├── pages/                 # 页面组件
│   │   ├── common/
│   │   │   ├── components/        # 通用组件
│   │   │   │   ├── welcome/       # 欢迎引导组件
│   │   │   │   ├── membership/    # 会员相关组件
│   │   │   │   └── common/        # 基础通用组件
│   │   │   ├── services/          # 业务服务层
│   │   │   │   ├── UsageTrackingService.ets      # 使用追踪服务
│   │   │   │   ├── MembershipRewardService.ets   # 会员奖励服务
│   │   │   │   ├── ContinuousUsageManager.ets    # 连续使用管理
│   │   │   │   └── PermissionService.ets         # 权限管理服务
│   │   │   ├── utils/             # 工具类
│   │   │   │   ├── WindowManager.ets             # 窗口管理
│   │   │   │   ├── DisplayManager.ets            # 显示管理
│   │   │   │   ├── ColorModeManager.ets          # 颜色模式管理
│   │   │   │   └── NotificationHelper.ets        # 通知助手
│   │   │   ├── models/            # 数据模型
│   │   │   ├── constants/         # 常量定义
│   │   │   └── interfaces/        # 接口定义
│   │   └── entrybackupability/    # 备份能力
│   └── resources/                 # 资源文件
└── oh-package.json5              # 模块依赖配置
```

## 🛠️ 快速开始

### 环境要求
- DevEco Studio 6.0+
- HarmonyOS SDK 6.0.0+
- Node.js 18+

### 安装步骤

1. **克隆项目**
   ```bash
   https://gitcode.com/Zhangzzzxy/ohapp.git
   cd ohapp
   ```

2. **使用DevEco Studio打开**
   

3. **配置应用信息**
   修改 `AppScope/app.json5` 中的应用信息：
   ```json5
   {
     "app": {
       "bundleName": "your.company.appname",
       "vendor": "your.company",
       "versionCode": 1000000,
       "versionName": "1.0.0",
       "icon": "$media:app_icon",
       "label": "$string:app_name"
     }
   }
   ```

4. **运行项目**
   - 在DevEco Studio中打开项目
   - 选择目标设备
   - 点击运行按钮

## 🏗️ 架构说明

### 核心架构图

```mermaid
graph TB
    A[UI Layer] --> B[Component Layer]
    B --> C[Service Layer]
    C --> D[Data Layer]
    
    A --> E[State Management]
    B --> F[Utils & Helpers]
    C --> G[External Services]
    
    subgraph "Service Layer"
        C1[UsageTrackingService]
        C2[MembershipService]
        C3[PermissionService]
        C4[NotificationService]
    end
    
    subgraph "State Management"
        E1[AppStorageV2]
        E2[PersistenceV2]
        E3[PreferenceKeys]
        E4[AppKeys]
    end
```

### 关键模块说明

#### 1. 状态管理
- **AppKeys** - 应用运行时状态管理
- **PreferenceKeys** - 用户偏好设置持久化
- **AppStorageV2** - 全局状态共享
- **PersistenceV2** - 数据持久化存储

#### 2. 服务层
- **UsageTrackingService** - 使用时长追踪
- **MembershipRewardService** - 会员奖励逻辑
- **ContinuousUsageManager** - 连续使用管理
- **PermissionService** - 权限管理
- **RelationalStoreService** - 数据库服务

#### 3. 工具层
- **WindowManager** - 窗口生命周期管理
- **DisplayManager** - 显示状态管理
- **ColorModeManager** - 颜色模式管理
- **NotificationHelper** - 通知权限管理

## 🔧 开发指南

### 添加新功能模块

1. **创建服务类**
   ```typescript
   // services/NewFeatureService.ets
   export class NewFeatureService {
     private static instance: NewFeatureService | null = null;
     
     public static getInstance(): NewFeatureService {
       if (!NewFeatureService.instance) {
         NewFeatureService.instance = new NewFeatureService();
       }
       return NewFeatureService.instance;
     }
     
     // 实现业务逻辑
   }
   ```

2. **添加状态管理**
   ```typescript
   // models/NewFeatureKeys.ets
   @ObservedV2
   export class NewFeatureKeys {
     @Track featureEnabled: boolean = false;
     @Track featureData: string = '';
   }
   ```

3. **创建UI组件**
   ```typescript
   // components/NewFeatureComponent.ets
   @ComponentV2
   export struct NewFeatureComponent {
     @Local nfk: NewFeatureKeys = AppStorageV2.connect(NewFeatureKeys)!;
     
     build() {
       // UI实现
     }
   }
   ```

### 自定义配置

修改 `DesignConstants.ets` 中的设计常量来自定义应用样式：

```typescript
export class DesignConstants {
  // 颜色配置
  public static readonly PRIMARY_COLOR: string = '#007DFF';
  public static readonly SECONDARY_COLOR: string = '#6C757D';
  
  // 间距配置
  public static readonly SPACING_SMALL: number = 8;
  public static readonly SPACING_MEDIUM: number = 16;
  public static readonly SPACING_LARGE: number = 24;
  
  // 字体配置
  public static readonly FONT_SIZE_TITLE: number = 24;
  public static readonly FONT_SIZE_BODY: number = 16;
}
```

## 📱 功能扩展

### 集成第三方服务

框架支持轻松集成各种第三方服务：

1. **网络请求** - 使用内置的HTTP客户端
2. **数据存储** - 基于RelationalStore的数据库
3. **推送服务** - 完整的通知系统
4. **位置服务** - 地理位置功能
5. **多媒体** - 音频、视频处理

## 🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

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

### 开发规范
- 遵循 ArkTS 编码规范
- 使用有意义的变量和函数名
- 添加必要的注释和文档
- 确保代码通过类型检查

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持

如果您在使用过程中遇到问题：

1. 查看 [Issues](https://github.com/your-username/harmonyos-app-framework/issues) 页面
2. 创建新的 Issue 描述问题
3. 提供详细的错误信息和复现步骤

## 🔄 更新日志

### v1.0.0
- 初始版本发布
- 完整的应用框架架构
- 基础功能模块实现

---

**开始构建您的下一个HarmonyOS应用吧！** 🎉