集成源码 - IM 即时通讯 UIKit

更新时间： 2025/09/03 16:04:52

IM HTML5 Demo （简称 IM H5 Demo）是基于网易云信 IM UIKit（NEUIKit）打造的一款 Demo，托管在 GitHub 开源代码仓库 nim-uikit-H5。该 Demo 提供了一些通用的功能，包含会话、聊天、群组等，您可以基于源码搭建您的即时通讯业务逻辑。

效果预览

IM H5 Demo 的部分界面效果如下：

前提条件

开始跑通 Demo 之前，请确保您已完成了以下操作：

在网易云信控制台上创建应用，并获取 App Key。
注册 IM 账号，获取账号 ID 和 token。
在网易云信控制台上，为应用开通 消息漫游 开关。开启步骤请参考《控制台文档》配置应用。

调整本地开发环境，并满足如下要求：

配置项	要求
集成开发环境	vuecli/vite
Vue.js 版本	Vue 3
开发语言	TypeScript
Node.js 版本	v16 及以上
JavaScript 包管理器	NPM（版本请与 Node.js 版本匹配）

第一步：创建项目

您可以使用 vuecli 或者 vite 创建项目，详细步骤请参考 Vue 官网文档。

如果您已创建项目，请忽略本步骤。

第二步：下载组件

运行以下命令将 NEUIKit GitHub 源码项目 nim-uikit-H5 下载到您的项目中：

Bash# 找桌面任意目录，clone 组件项目
git clone https://github.com/netease-kit/nim-uikit-H5.git

在 clone 下的组件项目中找到 NEUIKit 文件夹，将该文件夹复制到您的项目的 components 目录下，例如：

执行以下命令安装 NEUIKit 需要的依赖。

Bashnpm i nim-web-sdk-ng@10.8.30 @xkit-yx/im-store-v2@0.7.2 @xkit-yx/utils@0.7.2 dayjs@1.11.7 mobx@6.6.1 mitt@3.0.1 --save

依赖	说明
`nim-web-sdk-ng`	网易云信 NIM SDK，提供了一整套即时通讯基础能力。
`@xkit-yx/im-store-v2`	store 用于全局状态管理，基于 MobX 和 NIM SDK 封装的全局上下文对象，它提供了数据和 UI 之间的双向绑定能力。包含多个子模块，每个子模块负责管理不同的数据领域，如会话、消息、联系人、群组等。通过 store，您可以方便地获取数据、响应数据变化，并更新 UI。更多 store 相关信息。请参见全局上下文。
`@xkit-yx/utils`	项目中的工具库，提供 `getFileType`、`parseFileSize` 等函数。

下载成功后，可根据您的业务需求对源码进行修改，具体的目录结构请参考工程结构。

第三步：集成并初始化组件

在您的项目 App.vue 文件中引入 NEUIKit 组件，参考以下代码初始化 nim 和 store。

TypeScript<script lang="ts">
import { V2NIMConst } from "nim-web-sdk-ng/dist/esm/nim";
import RootStore from "@xkit-yx/im-store-v2";
import V2NIM from "nim-web-sdk-ng/dist/v2/NIM_BROWSER_SDK";
import type { V2NIMMessage } from "nim-web-sdk-ng/dist/esm/nim/src/V2NIMMessageService";
import { getCurrentInstance } from "vue";

export default {
  name: "App",
  methods: {
    initIMUiKit(opts: { account: string; token: string }) {
      const init = () => {
        //初始化nim 
        const nim = V2NIM.getInstance(
          {
            appkey: "your appkey",
            needReconnect: true,
            debugLevel: "debug",
            apiVersion: "v2",
            enableV2CloudConversation: true,
          },
          {
            V2NIMLoginServiceConfig: {
              lbsUrls: ["https://lbs.netease.im/lbs/webconf.jsp"],
              linkUrl: "weblink.netease.im",
            },
          }
        );
        // 初始化store
        const store = new RootStore(
          // @ts-ignore
          //参数一：NIMSDK，必填
          nim,
          //参数二：本地化配置，必填，详细参数说明请参考全局上下文的底部常见问题
          {
            // 添加好友是否需要验证
            addFriendNeedVerify: false,
            // 是否需要显示 p2p 消息、p2p会话列表消息已读未读，默认 false
            p2pMsgReceiptVisible: true,
            // 是否需要显示群组消息已读未读，默认 false
            teamMsgReceiptVisible: true,
            // 群组被邀请模式，默认需要验证
            teamAgreeMode:
              V2NIMConst.V2NIMTeamAgreeMode.V2NIM_TEAM_AGREE_MODE_NO_AUTH,
            // 发送消息前回调, 可对消息体进行修改，添加自定义参数
            sendMsgBefore: async (options: {
              msg: V2NIMMessage;
              conversationId: string;
              serverExtension?: Record<string, unknown>;
            }) => {
              return { ...options };
            },
          },
          //参数三：平台，可选
          "H5"
        );
        return {
          nim,
          store,
        };
      };

      const { nim, store } = init();
      const app = getCurrentInstance();

      // 将nim和store 挂载，供组件内部访问
      if (app) {
        app.appContext.app.config.globalProperties.$NIM = nim;
        app.appContext.app.config.globalProperties.$UIKitStore = store;
      }

      nim.V2NIMLoginService.login(opts.account, opts.token).then(() => {
        // IM 登录成功后跳转到会话页面
        this.$router.push("/conversation");
        this.showUiKit = true;
      });
    },
  },
  mounted() {
    this.initIMUiKit({
        account: 'xxx',
        token: 'xxxx'    
    });
  },
};
</script>

第四步：配置路由

在项目的路由文件配置您需要的页面，并将路由同步至 /NEUIKit/utils/uikitRouter.ts。（因为 UIKit 内部也需要根据路由跳转。）

以下以配置聊天页面为例，在项目的路由配置文件中添加聊天页面的路由，并创建聊天页面，在页面中引入 NEUIKit 的 chat 组件。

在您项目的 router.ts 文件中引入需要的路由。

import { createRouter, createWebHashHistory } from "vue-router";

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    {
      path: '/NEUIKit/chat',
      name: "Chat",
      component: () => import("../views/chat/ChatPage.vue"),
    },
  ],
});

export default router;

在您创建的 ChatPage.vue 文件中的更新路由：

<template>
  <Chat></Chat>
</template>

<script lang="ts" setup>
import Chat from "@/components/NEUIKit/Chat/index.vue";
</script>

<style scoped></style>

将路由同步至 /NEUIKit/utils/uikitRouter.ts 文件。

export const neUiKitRouterPath = {
  chat: "/chat",
};

完整路由可参考 demo 中的 router.ts。

import { createRouter, createWebHashHistory } from "vue-router";
import { neUiKitRouterPath } from "@/components/NEUIKit/utils/uikitRouter";

// 创建路由实例
const router = createRouter({
  // 使用 hash 模式的路由
  history: createWebHashHistory(),
  routes: [
    {
      // 根路径重定向到会话列表页面
      path: "/",
      redirect: neUiKitRouterPath.conversation,
    },
    {
      // 聊天页面路由
      path: neUiKitRouterPath.chat,
      name: "Chat",
      component: () => import("../views/chat/ChatPage.vue"),
    },
    {
      // 消息已读信息页面路由
      path: neUiKitRouterPath.messageReadInfo,
      name: "MessageReadInfo",
      component: () => import("../views/chat/MessageReadInfoPage.vue"),
    },
    {
      // 单聊设置页面路由
      path: neUiKitRouterPath.p2pSetting,
      name: "P2pSetting",
      component: () => import("../views/chat/P2pSettingPage.vue"),
    },
    {
      // 会话列表页面路由
      path: neUiKitRouterPath.conversation,
      name: "Conversation",
      component: () => import("../views/conversation/ConversationPage.vue"),
    },
    {
      // 会话搜索页面路由
      path: neUiKitRouterPath.conversationSearch,
      name: "ConversationSearch",
      component: () =>
        import("../views/conversation/ConversationSearchPage.vue"),
    },
    {
      // 通讯录页面路由
      path: neUiKitRouterPath.contacts,
      name: "Contacts",
      component: () => import("../views/contacts/ContactsPage.vue"),
    },
    {
      // 黑名单列表页面路由
      path: neUiKitRouterPath.blacklist,
      name: "Blacklist",
      component: () => import("../views/contacts/BlackListPage.vue"),
    },
    {
      // 验证消息列表页面路由
      path: neUiKitRouterPath.validlist,
      name: "ValidList",
      component: () => import("../views/contacts/ValidListPage.vue"),
    },
    {
      // 群组列表页面路由
      path: neUiKitRouterPath.teamlist,
      name: "TeamList",
      component: () => import("../views/contacts/TeamListPage.vue"),
    },
    {
      // 个人中心页面路由
      path: neUiKitRouterPath.my,
      name: "My",
      component: () => import("../views/user/MyPage.vue"),
    },
    {
      // 用户设置页面路由
      path: neUiKitRouterPath.userSetting,
      name: "UserSetting",
      component: () => import("../views/user/SettingPage.vue"),
    },
    {
      // 我的详情页面路由
      path: neUiKitRouterPath.myDetail,
      name: "MyDetail",
      component: () => import("../views/user/MyDetailPage.vue"),
    },
    {
      // 我的详情编辑页面路由
      path: neUiKitRouterPath.myDetailEdit,
      name: "MyDetailEdit",
      component: () => import("../views/user/MyDetailEditPage.vue"),
    },
    {
      // 关于网易云信页面路由
      path: neUiKitRouterPath.aboutNetease,
      name: "AboutNetease",
      component: () => import("../views/user/AboutNeteasePage.vue"),
    },
    {
      // 好友名片页面路由
      path: neUiKitRouterPath.friendCard,
      name: "FriendCard",
      component: () => import("../views/friend/FriendCardPage.vue"),
    },
    {
      // 添加好友页面路由
      path: neUiKitRouterPath.addFriend,
      name: "AddFriend",
      component: () => import("../views/friend/AddFriendPage.vue"),
    },
    {
      // 好友信息编辑页面路由
      path: neUiKitRouterPath.friendInfoEdit,
      name: "FriendInfoEdit",
      component: () => import("../views/friend/FriendInfoEditPage.vue"),
    },
    {
      // 创建群组页面路由
      path: "/team/create",
      name: "TeamCreate",
      component: () => import("../views/team/TeamCreatePage.vue"),
    },
    {
      // 群组设置页面路由
      path: neUiKitRouterPath.teamSetting,
      name: "TeamSetting",
      component: () => import("../views/team/TeamSetPage.vue"),
    },
    {
      // 群组成员管理页面路由
      path: neUiKitRouterPath.teamMember,
      name: "TeamMMember",
      component: () => import("../views/team/TeamMemberPage.vue"),
    },
    {
      // 群组信息编辑页面路由
      path: neUiKitRouterPath.teamInfoEdit,
      name: "TeamInfoEdit",
      component: () => import("../views/team/TeamInfoEditPage.vue"),
    },
    {
      // 群组头像编辑页面路由
      path: neUiKitRouterPath.teamAvatarEdit,
      name: "TeamAvatarEdit",
      component: () => import("../views/team/TeamAvatarEditPage.vue"),
    },
    {
      // 群组介绍编辑页面路由
      path: neUiKitRouterPath.teamIntroduceEdit,
      name: "TeamNameEdit",
      component: () => import("../views/team/TeamIntroduceEditPage.vue"),
    },
    {
      // 添加群成员页面路由
      path: neUiKitRouterPath.teamAdd,
      name: "TeamAdd",
      component: () => import("../views/team/TeamAddPage.vue"),
    },
    {
      // 群昵称设置页面路由
      path: neUiKitRouterPath.teamNick,
      name: "TeamNick",
      component: () => import("../views/team/TeamNickPage.vue"),
    },
    {
      // 登录页面路由
      path: neUiKitRouterPath.login,
      name: "Login",
      component: () => import("../views/login/LoginPage.vue"),
    },
  ],
});

export default router;

第五步：运行项目

通过 npm run start，或者您项目的自定义运行命令，根据您的业务需求，在合适的时机展示聊天页面。

自定义开发

API 参考

IM H5 Demo 基于 UIKitStore 开发，相关 API 详情请参考 UIKitStore。

此文档是否对你有帮助？

有帮助

去反馈

效果预览
前提条件
第一步：创建项目
第二步：下载组件
第三步：集成并初始化组件
第四步：配置路由
第五步：运行项目
自定义开发
API 参考