# qxx

**Repository Path**: Andy688/qxx

## Basic Information

- **Project Name**: qxx
- **Description**: 青签签应用是一个基于HarmonyOS的ArkTS应用，模拟申请、获取和管理青秀区文化签证的流程。该应用展示了如何在HarmonyOS环境下创建具有多页面流程的应用，实现表单提交、加载动画、结果展示和证书管理等功能。
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-05-15
- **Last Updated**: 2025-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鸿蒙应用开发文档

## 1. 项目概述

青签签应用是一个基于HarmonyOS的ArkTS应用，模拟申请、获取和管理青秀区文化签证的流程。该应用展示了如何在HarmonyOS环境下创建具有多页面流程的应用，实现表单提交、加载动画、结果展示和证书管理等功能。

## 效果展示

<div style="display: flex; justify-content: space-between; margin-bottom: 20px;">
    <img src="src/mockup.png" width="32%" alt="效果图1">
    <img src="src/mockup2.png" width="32%" alt="效果图2">
    <img src="src/mockup3.png" width="32%" alt="效果图3">
</div>

## 2. 技术架构

### 2.1 开发环境
- 开发框架：HarmonyOS/ArkTS
- IDE：DevEco Studio
- API版本：5.0.4(16)
- 构建工具：hvigor

### 2.2 项目结构
```
qxq/
├── entry/                        # 主模块
│   ├── src/main/
│   │   ├── ets/                  # 源代码目录
│   │   │   ├── api/              # API服务与工具类
│   │   │   ├── entryability/     # 应用入口
│   │   │   ├── pages/            # 页面组件
│   │   │   └── images/           # 图像资源
│   │   └── resources/            # 应用资源
│   └── build/                    # 构建输出
└── AppScope/                     # 应用作用域配置
```

### 2.3 核心模块
- **API模块**：提供应用的数据管理和业务逻辑
- **路由模块**：管理应用内页面跳转
- **页面模块**：提供用户界面和交互
- **资源模块**：管理应用资源（字符串、图像等）

## 3. API文档

### 3.1 API服务(`API.ets`)

主要负责应用程序的初始化和全局服务管理。

```typescript
class API {
  static getInstance(): API                // 获取API单例实例
  init(): void                             // 初始化API服务
}
```

### 3.2 路由管理器(`router.ets`)

管理应用内页面导航和路由跳转。

```typescript
enum RouteName {
  WELCOME,                                 // 欢迎页
  APPLICATION,                             // 申请表单页
  LOADING,                                 // 加载页
  APPROVAL,                                // 审批通过页
  REJECTION,                               // 拒绝页
  CERTIFICATE,                             // 证书页
  INDEX                                    // 索引页
}

class RouteManager {
  static push(url: string, params?: Object): void    // 导航到指定页面
  static pop(): void                                 // 返回上一页
  static randomApprovalOrRejection(): void           // 随机跳转到通过或拒绝页面
  static handleApplicationSubmit(                    // 处理申请表单提交
    formComplete: boolean, 
    callback: () => void, 
    userName?: string
  ): void
  static getParams(): Object                         // 获取当前页面的路由参数
}
```

### 3.3 用户数据服务(`UserDataService.ets`)

管理用户信息的存储和传递。

```typescript
class UserDataService {
  static getInstance(): UserDataService              // 获取UserDataService单例实例
  setUserName(name: string): void                    // 设置用户名
  getUserName(): string                              // 获取用户名
  generateCertificateNumber(): string                // 生成新的证书编号
  getCertificateNumber(): string                     // 获取证书编号
  recordCertificateDates(): void                     // 记录证书有效期
  getStartDate(): Date                               // 获取证书有效期起始日期
  getEndDate(): Date                                 // 获取证书有效期结束日期
}
```

## 4. 页面组件

### 4.1 页面流程图
```
Index → Welcome → Application → Loading → Approval/Rejection → Certificate
```

### 4.2 主要页面

| 页面 | 文件 | 说明 |
|-----|------|-----|
| 索引页 | Index.ets | 应用启动初始页面，会自动跳转至欢迎页 |
| 欢迎页 | Welcome.ets | 应用欢迎页面，展示应用简介及引导 |
| 申请表单 | Application.ets | 用户填写申请信息的表单页面 |
| 加载页 | Loading.ets | 提交申请后的加载动画页面 |
| 审批通过 | Approval.ets | 申请通过展示页面 |
| 拒绝页 | Rejection.ets | 申请被拒绝展示页面 |
| 证书页 | Certificate.ets | 显示用户证书详情及管理功能 |

## 5. 开发指南

### 5.1 新增页面流程

1. 在`entry/src/main/ets/pages/`目录下创建新页面组件
2. 在`main_pages.json`中注册页面组件
3. 在`RouteName`枚举中添加新页面的路由名称
4. 使用`RouteManager.push()`方法导航到新页面

### 5.2 数据流管理

- 使用`UserDataService`单例存储和传递用户数据
- 通过`RouteManager`的路由参数在页面间传递数据

### 5.3 路由配置要点

确保以下三处配置保持一致：
1. `main_pages.json`中的页面名称
2. `router.ets`中的`RouteName`枚举值
3. 页面组件文件名与路由名称一致

## 6. 功能模块

### 6.1 表单验证

在`Application.ets`中实现表单验证逻辑：
```typescript
validateForm(): boolean {
  // 验证各字段是否填写
  if (!this.name || !this.age || !this.gender || this.storeType === '请选择' || !this.understanding) {
    return false;
  }
  
  // 验证至少勾选一个文化活动
  if (!this.activities.some(activity => activity)) {
    return false;
  }
  
  return true;
}
```

### 6.2 证书管理

在`Certificate.ets`中实现证书显示和管理功能：
- 显示证书基本信息（持有人、编号、有效期等）
- 提供标签页切换功能（详情、使用记录、赞助）
- 集成网页浏览功能（内置WebView）

### 6.3 外部链接处理

使用内置WebView打开外部链接：
```typescript
openBrowser(url: string): void {
  this.currentUrl = url;
  this.showWebView = true;
  console.info('正在应用内打开URL: ' + url);
}
```

## 7. 构建与部署

### 7.1 构建应用

使用以下命令构建应用：
```bash
hvigor assembleHap
```

构建输出位置：
```
entry/build/default/outputs/default/entry-default-signed.hap
```

### 7.2 应用签名

在`build-profile.json5`中配置签名信息：
```json
"signingConfigs": [
  {
    "name": "default",
    "type": "HarmonyOS",
    "material": {
      "certpath": "<证书路径>.cer",
      "keyAlias": "debugKey",
      "keyPassword": "<密钥密码>",
      "profile": "<配置文件路径>.p7b",
      "signAlg": "SHA256withECDSA",
      "storeFile": "<密钥库路径>.p12",
      "storePassword": "<密钥库密码>"
    }
  }
]
```

### 7.3 安装部署

可通过以下方式安装应用：
- 通过DevEco Studio直接部署到设备
- 使用HDB工具命令：`hdc app install <hap文件路径>`
- 将HAP文件传输到设备后手动安装

## 8. 注意事项和最佳实践

1. **组件重用**：使用`@Builder`装饰器创建可重用的UI组件
2. **状态管理**：使用`@State`、`@Prop`等装饰器管理组件状态
3. **错误处理**：在网络请求和路由跳转中添加错误处理
4. **性能优化**：避免在UI线程中执行耗时操作
5. **样式统一**：保持一致的颜色方案和组件样式


## 9. 附录

### 9.1 相关资源

- [HarmonyOS开发文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/start-overview-0000001058499525)
- [ArkTS语言规范](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-overview-0000001281480778)

### 9.2 常见问题解答

1. **Q: 如何在不同页面间传递数据？**  
   A: 使用`UserDataService`单例存储数据或通过路由参数传递

2. **Q: 如何处理应用内的网页浏览？**  
   A: 使用内置的Web组件实现应用内浏览器功能

3. **Q: 应用签名失败怎么办？**  
   A: 检查`build-profile.json5`中的签名配置是否正确


   # 如果认可我，可以请我喝杯☕


<div style="display: flex; justify-content: space-between; margin-bottom: 20px;">
    <img src="src/wx.jpg" width="48%" alt="wx">
    <img src="src/zfb.jpg" width="48%" alt="zfb">
</div>