---
slug: "telegramharmony"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/forestbook/telegramharmony@main/README.md"
repo: "https://github.com/forestbook/telegramharmony"
source_file: "README.md"
branch: "main"
---
# Telegram for HarmonyOS NEXT

基于 HarmonyOS NEXT 的 Telegram 客户端，使用 ArkTS/ArkUI 开发，实现完整的 MTProto 2.0 协议。

## 功能特性

- ✅ 完整的 MTProto 2.0 协议实现 (Layer 214)
- ✅ 手机号登录/注册
- ✅ 聊天列表和消息
- ✅ 发送/接收文本消息
- ✅ 图片和视频的发送/接收/预览
- ✅ 语音消息
- ✅ 文件传输
- ✅ 跨数据中心文件下载
- ✅ 会话持久化

## 快速开始

### 1. 克隆仓库

```bash
git clone https://github.com/ForestBook/TelegramHarmony.git
cd TelegramHarmony
```

### 2. 配置 API 凭证 ⚠️ 重要

你需要获取自己的 Telegram API 凭证才能运行此应用。

1. 访问 [https://my.telegram.org/apps](https://my.telegram.org/apps)
2. 登录你的 Telegram 账号
3. 创建一个新应用，获取 `api_id` 和 `api_hash`
4. 复制凭证模板文件：

```bash
cp entry/src/main/ets/core/mtproto/ApiCredentials.template.ets \
   entry/src/main/ets/core/mtproto/ApiCredentials.ets
```

5. 编辑 `ApiCredentials.ets`，填入你的凭证：

```typescript
export const PROD_API_ID: number = 你的API_ID
export const PROD_API_HASH: string = '你的API_HASH'
```

### 3. 打开并运行

1. 启动 DevEco Studio 5.0+
2. 选择 "Open Project" 并选择 TelegramHarmony 目录
3. 同步项目依赖 (Sync Project)
4. 连接 HarmonyOS 设备或启动模拟器
5. 点击 Run 按钮

## 项目结构

```
TelegramHarmony/
├── AppScope/                    # 应用级配置
│   ├── app.json5               # 应用配置
│   └── resources/              # 应用级资源
│
├── entry/                       # 主入口模块
│   └── src/main/
│       ├── ets/
│       │   ├── entryability/   # 入口 Ability
│       │   ├── pages/          # 页面
│       │   │   ├── Index.ets           # 启动页
│       │   │   ├── LoginPage.ets       # 登录页
│       │   │   ├── VerifyCodePage.ets  # 验证码页
│       │   │   ├── ChatListPage.ets    # 聊天列表页
│       │   │   └── ChatPage.ets        # 聊天详情页
│       │   ├── viewmodel/      # 视图模型
│       │   │   ├── LoginViewModel.ets
│       │   │   ├── ChatListViewModel.ets
│       │   │   └── ChatViewModel.ets
│       │   ├── components/     # UI 组件
│       │   │   ├── Avatar.ets
│       │   │   ├── ChatListItemView.ets
│       │   │   ├── MessageBubble.ets
│       │   │   └── InputBar.ets
│       │   └── app/            # 应用状态
│       │       └── AppState.ets
│       └── resources/          # 模块资源
│
├── common/
│   └── signalkit/              # 响应式框架 (HAR)
│       └── src/main/ets/
│           ├── Signal.ets      # 信号类
│           ├── ValueSignal.ets # 值信号
│           └── Disposable.ets  # 资源管理
│
└── core/
    ├── models/                 # 数据模型 (HAR)
    │   └── src/main/ets/
    │       ├── Peer.ets        # 用户/群组模型
    │       ├── Message.ets     # 消息模型
    │       ├── ChatListItem.ets # 聊天列表项
    │       └── User.ets        # 当前用户模型
    │
    ├── services/               # 服务接口 (HAR)
    │   └── src/main/ets/
    │       ├── IAuthService.ets     # 认证服务接口
    │       ├── IMessageService.ets  # 消息服务接口
    │       ├── IChatListService.ets # 聊天列表服务接口
    │       └── ServiceLocator.ets   # 服务定位器
    │
    └── mock/                   # Mock 服务实现 (HAR)
        └── src/main/ets/
            ├── MockDataGenerator.ets   # 模拟数据生成
            ├── MockAuthService.ets     # 模拟认证服务
            ├── MockMessageService.ets  # 模拟消息服务
            └── MockChatListService.ets # 模拟聊天列表服务
```

## 安全说明

- `ApiCredentials.ets` 包含敏感信息，已添加到 `.gitignore`，**不会被提交到仓库**
- 请勿将 API 凭证提交到公开仓库
- 测试环境凭证是 Telegram 官方公开的，可以用于测试

## 技术栈

- **HarmonyOS NEXT API 12+**
- **ArkTS / ArkUI** 声明式 UI 框架
- **SignalKit** 响应式状态管理 (自研)
- **Service Locator** 依赖注入模式

## 开发要求

- DevEco Studio 5.0+
- HarmonyOS NEXT SDK (API 12)
- 真机或模拟器

## 构建运行

1. 使用 DevEco Studio 打开项目
2. 同步项目依赖 (Sync Project)
3. 选择目标设备
4. 点击运行

## 验证码

Mock 模式下固定验证码为：**12345**

## 架构说明

### 响应式框架

SignalKit 是基于 iOS Telegram 的 SwiftSignalKit 移植的响应式框架：

```typescript
// 创建信号
const signal = Signal.single('hello')

// 变换操作
signal
  .map(s => s.toUpperCase())
  .filter(s => s.length > 0)
  .start(
    (value) => console.log(value),
    (error) => console.error(error),
    () => console.log('completed')
  )
```

### 服务定位器

使用 ServiceLocator 模式实现依赖注入，便于在 Mock 和真实服务之间切换：

```typescript
// 注册服务
ServiceLocator.getInstance().register(ServiceType.Auth, new MockAuthService())

// 获取服务
const authService = getAuthService()
```

## 许可证

本项目仅供学习和研究目的。Telegram 是 Telegram Messenger Inc. 的商标。