Telegram for HarmonyOS NEXT

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

功能特性

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

快速开始

1. 克隆仓库

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

2. 配置 API 凭证 ⚠️ 重要

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

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

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

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

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 移植的响应式框架：

// 创建信号
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 和真实服务之间切换：

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

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

许可证

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