环信鸿蒙版 UIKit 快速上手指南

news2025/7/16 11:45:02

环信鸿蒙版 UIKit 是专为 HarmonyOS 开发者设计的 IM UI 组件库，基于环信 IM SDK 开发，可帮助开发者快速集成即时通讯功能。

环信UIKit 的特点

ArkUI 声明式开发范式：采用高效简洁的声明式开发方式
状态管理 V2：支持深度观测和精准更新
组件导航：使用系统推荐的 Navigation 方式进行页面跳转

1. 使用 ArkUI 的声明式开发范式。

ArkUI 提供了两种开发范式：基于ArkTS的声明式开发范式和兼容JS的类Web开发范式。声明式开发范式具有高效简洁，内存占用少，性能更佳以及会作为鸿蒙主推的开发范式持续演进的特点。而类Web开发范式则是为了让Web前端开发者快速将已有的Web应用改造成方舟UI框架应用。基于以上原因，环信Chat UIKit 采用 ArkUI 的声明式开发范式。

2. 采用状态管理 V2 版本。

ArkUI 提供了两个版本的状态管理：状态管理V1和V2。状态管理 V1 版本是目前 ArkUI 的稳定版本，但是在使用上有如下限制：

状态变量不能独立于UI存在，同一个数据被多个视图代理时，在其中一个视图的更改不会通知其他视图更新。
只能感知对象属性第一层的变化，无法做到深度观测和深度监听。
在更改对象中属性以及更改数组中元素的场景下存在冗余更新的问题。
装饰器间配合使用限制多，不易用。组件中没有明确状态变量的输入与输出，不利于组件化。

而状态管理 V2 则增强了状态管理 V1 的能力，解决了状态管理 V1 版本的一些问题。状态管理 V2 版本的特点如下：

状态变量独立于UI，更改数据会触发相应视图的更新。
支持对象的深度观测和深度监听，且深度观测机制不影响观测性能。
支持对象中属性级精准更新及数组中元素的最小化更新。
装饰器易用性高、拓展性强，在组件中明确输入与输出，有利于组件化。

基于 V1 和 V2 版本的对比，结合 UIKit 聊天页面的复杂性，环信UIKit 采用了 V2 版本的状态管理。

3. 页面采用组件导航（Navigation）的方式。

组件导航（Navigation）是鸿蒙推荐的页面导航方式。UIKit 采用系统路由表的方式进行动态路由。应用只需要通过NavPathStack提供的路由方法，传入需要路由的页面配置名称，系统会完成路由跳转。

快速使用环信鸿蒙版 UIKit

前提条件

开始前，你需要满足以下的开发环境：

DevEco Studio NEXT Release（5.0.3.900）及以上；
HarmonyOS SDK API 12 及以上；
HarmonyOS NEXT.0.0.71 或以上版本的模拟器或者真机；
有效的环信即时通讯 IM 开发者账号和 App Key，请跳转到环信即时通讯云控制台

项目准备

下面介绍将单群聊 UIKit 引入项目中的必要环境配置。

打开 DevEco Studio，点击 Create Project。
在 Choose Your Ability Template 界面，选择 Application > Empty Ability，然后点击 Next。
在 Configure Your Project 界面，依次填入以下内容：
- Project name：你的 HarmonyOS 项目名称，如 HelloWorld。
- Bundle name：你的项目包的名称，如 com.hyphenate.helloworld。
- Save location：项目的存储路径。
- Compatible SDK：项目的支持的最低 API 等级，选择 5.0.0(12) 及以上。
- Module name：module的名称，默认为 entry。
点击 Finish。根据屏幕提示，安装所需插件。

注意：上述步骤使用的是 DevEco Studio 5.0.1 Release（5.0.5.315）版本。

在项目中引入 SDK 。

远程依赖

在项目根目录下执行如下命令：

ohpm install @easemob/chatuikit

说明一下：
上面的命令在根目录执行，会将 SDK 依赖添加到项目级别；在 Module 目录下，会将 SDK 依赖添加到对应的 Module 上。

源码依赖

从环信官网或从 GitHub 获取鸿蒙单群聊UIKit源码源码，按照下面的方式集成：

点击 Import，选择 Import Module，导入 chatuikit 模块。
在项目 Module 中引入 chatuikit 模块。

修改模块目录的 oh-package.json5 文件，在 dependencies 节点增加依赖声明。

"dependencies": {
    "@easemob/chatuikit": "file:./../chatuikit"
}

然后点击同步按钮，同步完成后，就可以在模块中使用 chatuikit 。

添加项目权限。

在模块的 module.json5 ，例如：HelloWorld 中 entry 模块的 module.json5 中，配置示例如下：

{
  module: {
    requestPermissions: [
      {
        name: "ohos.permission.GET_NETWORK_INFO",
      },
      {
        name: "ohos.permission.INTERNET",
      },
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "$string:record_permission_reason",
        'usedScene': {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      }
    ],
  },
}

需要在对应模块的 string.json 文件中增加如下：

{
    "name": "record_permission_reason",
    "value": "录制语音需要"
}

实现发送第一条单聊消息

下面我们一起来看看 UIKit 是如何发送第一条消息的。

创建快速开始页面及实现代码逻辑

打开 entry/src/main/ets/pages/Index.ets 文件，并替换为如下内容：

import { ChatPageParams, ChatUIKitClient, ChatClient, ChatError, ChatOptions, ConversationType } from '@easemob/chatuikit';
import { promptAction } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  pathStack: NavPathStack = new NavPathStack();
  private appKey: string = [项目的AppKey]; // 将[项目的AppKey]替换为项目的AppKey字符串
  private userId: string = '';
  private password: string = '';
  private peerId: string = '';

  private initSDK() {
    let options = new ChatOptions({
      appKey: this.appKey
    });
    options.setAutoLogin(false);
    let client = ChatClient.getInstance();
    client.init(getContext(), options);
    ChatUIKitClient.init(client);
  }

  private login() {
    if (!this.userId || !this.password) {
      promptAction.showToast({message: "UserId or password cannot be empty!"});
      return;
    }
    ChatUIKitClient.loginWithPassword(this.userId, this.password)
      .then(() => {
        promptAction.showToast({message: "Login successful!"});
      })
      .catch((e: ChatError) => {
        promptAction.showToast({message: "Login failed: "+e.description});
      })
  }

  private logout() {
    ChatUIKitClient.logout(false)
      .then(() => {
        promptAction.showToast({message: "Logout successful!"});
      })
  }

  private startChat() {
    if (!this.peerId) {
      promptAction.showToast({message: "Peer id cannot be empty!"});
      return;
    }
    this.pathStack.pushPath({name: 'ChatPage', param: {
      conversationId: this.peerId,
      conversationType: ConversationType.Chat
    } as ChatPageParams})
  }

  aboutToAppear(): void {
    this.initSDK();
  }

  build() {
    Navigation(this.pathStack) {
      Column() {
        TextInput({placeholder: 'UserId'})
          .commonStyle()
          .onChange(value => this.userId = value)

        TextInput({ placeholder: 'Password' })
          .commonStyle()
          .type(InputType.Password)
          .onChange(value => this.password = value)

        Button('Login')
          .commonStyle()
          .onClick(()=> {
            this.login();
          })

        Button('Logout')
          .commonStyle()
          .onClick(()=> {
            this.logout();
          })

        TextInput({placeholder: 'PeerId'})
          .commonStyle()
          .onChange(value => this.peerId = value)

        Button('Start Chat')
          .commonStyle()
          .onClick(()=> {
            this.startChat();
          })
      }
      .width('100%')
      .height('100%')
    }
  }

  @Styles
  commonStyle() {
    .width('80%')
    .margin({
      top: 20
    })
  }
}