# ContactProject

**Repository Path**: juhetianxia321/contact-project

## Basic Information

- **Project Name**: ContactProject
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-16
- **Last Updated**: 2025-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 联系人管理Demo项目文档


## 一、项目概述

### 1.1 项目名称
ContactApp（联系人管理Demo）

### 1.2 项目目标
基于鸿蒙（HarmonyOS）API 12+及DevEco Studio 5.0，实现一套功能完整、性能优化的联系人管理应用。核心目标包括：
- 支持联系人全生命周期管理（新增、编辑、删除、查询）
- 实现拼音首字母分组展示，提升信息检索效率
- 优化列表渲染性能，通过组件复用和懒加载减少资源占用
- 提供流畅的交互体验（下拉刷新、滑动操作、振动反馈等）


### 1.3 技术栈
| 类别         | 具体信息                                  |
|--------------|-------------------------------------------|
| 开发语言     | ArkTS（鸿蒙声明式开发语言）               |
| 开发工具     | DevEco Studio 5.0                         |
| 目标平台     | 鸿蒙系统（API 12及以上）                  |
| UI框架       | ArkUI（含`List` `LazyForEach` `Navigation`等组件） |
| 状态管理     | `@State` `@Prop` `@ObjectLink` `@Link` `@Provide`等装饰器 |
| 核心特性     | 组件复用（`@Reusable`）、数据懒加载、自定义数据源 |


## 二、核心功能

### 2.1 联系人管理
- **新增联系人**：通过`AddContactComponent`弹窗录入信息（姓名、电话、邮箱等），自动生成唯一ID并归入对应拼音分组。
- **编辑联系人**：通过`EditContactComponent`修改已有联系人信息，实时同步至列表。
- **删除联系人**：支持滑动菜单删除或长按删除，自动处理空分组的移除。
- **查询功能**：通过顶部搜索框实时过滤联系人（支持姓名、电话、邮箱匹配）。


### 2.2 列表展示与交互
- **拼音分组**：基于`PinyinUtils`将联系人按姓名首字母分组（ # + A-Z），分组标题显示。
- **性能优化**：使用`LazyForEach`结合`ContactDataSource`实现列表项懒加载，`@Reusable`装饰器实现组件复用。
- **下拉刷新**：自定义刷新动画，支持“下拉刷新→释放刷新→同步中→完成”全状态反馈。
- **交互反馈**：长按联系人触发振动（`HapticUtil`），滑动列表项显示编辑/删除菜单。


## 三、项目结构

```
src/main/ets/
├── component/                  # 自定义组件
│   ├── ContactComponent.ets    # 联系人列表项组件（核心交互）
│   ├── AddContactComponent.ets # 新增联系人弹窗
│   ├── EditContactComponent.ets # 编辑联系人弹窗
│   └── ContactSectionHeader.ets # 分组标题组件
├── model/                      # 数据模型
│   └── ContactModel.ets        # 定义Contact（联系人）和GroupContact（分组）结构
├── services/                   # 业务逻辑
│   └── ContactService.ets      # 联系人数据处理（加载、分组、增删改查）
├── utils/                      # 工具类
│   ├── PinyinUtils.ets         # 拼音转换与分组键生成
│   ├── HapticUtil.ets          # 振动反馈工具
│   ├── RegExpUtils.ets         # 手机号/邮箱验证
│   └── JsonService.ets         # JSON文件读取
├── viewmodel/                  # 数据源
│   ├── BasicDataSource.ets     # 基础数据源抽象类
│   └── ContactDataSource.ets   # 联系人分组数据源实现
└── pages/                      # 页面组件
    └── Index.ets               # 主页面（联系人列表入口）
```


## 四、核心模块详解

### 4.1 数据模型（`ContactModel.ets`）
- **`Contact`类**：定义联系人核心字段（`id` `name` `phone` `email`等），支持自动生成ID和首字母提取。
- **`GroupContact`类**：封装分组信息，包含分组键（`groupKey`）和对应联系人数据源（`ContactDataSource<Contact>`）。


### 4.2 业务服务（`ContactService.ets`）
作为数据处理核心，提供以下功能：
- **数据加载**：通过`JsonService`从`rawfile`目录读取初始联系人数据，自动补全ID和首字母。
- **分组逻辑**：调用`PinyinUtils.getGroupKey()`生成分组键，通过`getGroupedContacts()`对联系人分组并排序（#分组置顶，字母分组按A-Z排序）。
- **增删改查**：实现`addContact()` `deleteContact()` `updateContact()`等方法，维护联系人数据一致性。


### 4.3 数据源（`ContactDataSource.ets`）
继承自`BasicDataSource`，实现`IDataSource`接口，支持：
- 数据增删改操作（`insetData()` `removeDataByIndex()`等）
- 数据变更通知（`notifyDataAdd()` `notifyDataChange()`等），确保UI实时更新
- 分组数据嵌套：`GroupContact`内部包含`ContactDataSource<Contact>`，支持二级懒加载


### 4.4 核心组件
1. **`ContactComponent`**：
    - 展示联系人头像（或首字母）、姓名等信息
    - 支持右滑显示编辑/删除菜单，长按触发振动反馈
    - 通过`@ObjectLink`与父组件数据双向绑定，确保修改实时同步

2. **`Index`页面**：
    - 集成搜索框、联系人列表、下拉刷新组件
    - 通过`LazyForEach`加载分组数据，实现列表滚动监听与刷新逻辑
    - 管理全局导航（`NavPathStack`）和页面状态（搜索文本、刷新状态等）


## 五、关键技术实现

### 5.1 列表性能优化
- **组件复用**：`ContactComponent`使用`@Reusable`装饰器，结合`aboutToReuse()`方法复用组件实例，减少创建销毁开销。
- **懒加载机制**：`LazyForEach`仅渲染可视区域内的列表项，通过`ContactDataSource`按需提供数据。
- **分组键生成**：`PinyinUtils.getGroupKey()`确保分组唯一且排序一致，避免重复计算。


### 5.2 数据同步策略
- 父组件通过`@ObjectLink`将`Contact`对象传递给`ContactComponent`，子组件修改后自动同步至父组件。
- 数据源变更时（如新增/删除联系人），`ContactDataSource`通过`notifyXXX`方法通知UI刷新，避免全量重绘。


### 5.3 下拉刷新实现
- 监听列表滚动事件（`onWillScroll`），根据滚动偏移量计算下拉距离，动态更新刷新状态文本。
- 通过`animateTo`实现刷新组件的平滑位移，模拟物理反馈效果。


## 六、使用指南

### 6.1 环境要求
- DevEco Studio 5.0 及以上
- 鸿蒙SDK API 12 及以上
- 鸿蒙系统设备或模拟器（API 12+）


### 6.2 部署步骤
1. 克隆项目到本地：
   ```bash
    git clone https://gitee.com/juhetianxia321/contact-project.git
   ```  
2. 在DevEco Studio中导入项目，等待依赖同步完成。
3. 连接设备或启动模拟器，点击运行按钮（▶️）编译部署。


### 6.3 功能操作
- **查看联系人**：默认按拼音分组展示，可通过右侧字母索引快速定位。
- **搜索联系人**：在顶部搜索框输入关键词，列表实时过滤结果。
- **新增联系人**：点击右上角“+”按钮，填写信息后保存。
- **编辑/删除**：右滑联系人项显示操作菜单，或长按触发更多选项。


## 七、待扩展功能（有时间了写）
1. 新增联系人头像上传功能（集成相册/相机权限）。
2. 支持联系人导入/导出（vCard格式）。
3. 增加联系人标签分类功能。
4. 新增联系人使用sqlite存入本地数据库

## 八、许可证
本项目基于 **Apache License Version 2.0** 开源，详见项目根目录`LICENSE`文件。