@xkit-yx/im-store-v2

v0.9.1

Published

19 days ago

云信即时通讯 store V2 版本

0High
0Medium
0Low

netease-yunxin

`@xkit-yx/im-store-v2`

基于 nim-web-sdk-ng 封装的网易云信 IM UI Kit 业务状态层。

这个包以 RootStore 为统一入口，内置了消息、会话、好友、群组、系统消息、在线状态、AI 用户、UI 视图状态等多个业务 store，适合在 Web IM、H5 IM、UniApp / 小程序 IM 场景中作为前端状态层直接使用。

能力概览

统一管理 IM 业务主状态，减少页面层直接拼装 SDK 数据
同时支持云端会话模式与本地会话模式
内置消息发送、历史消息、撤回、Pin、回复、收藏等消息能力
内置好友、黑名单、免打扰、系统消息、群组、群成员等常用业务能力
提供适合 UI 直接渲染的扩展类型，例如 V2NIMConversationForUI、V2NIMMessageForUI
支持 AI 用户、AI Bot、AI 代理请求相关状态管理
提供 TypeDoc API 文档，便于业务侧按类型和 store 能力接入

安装

npm install @xkit-yx/im-store-v2 nim-web-sdk-ng mobx

说明：

nim-web-sdk-ng 是对等依赖，需要由业务项目自行安装
当前包输出 esm、cjs 和类型声明

快速开始

1. 初始化 NIM SDK

先由业务项目完成 nim-web-sdk-ng 的初始化，然后将 SDK 实例交给 RootStore。

import { NIM } from "nim-web-sdk-ng/dist/esm/nim";
import { RootStore } from "@xkit-yx/im-store-v2";

const nim = NIM.getInstance({
  appkey: "your-appkey",
  debugLevel: "debug",
});

const rootStore = RootStore.getInstance(nim, {
  conversationLimit: 100,
  enableTeam: true,
  aiVisible: true,
});

2. 通过 `RootStore` 访问业务能力

await rootStore.friendStore.getFriendListActive();
await rootStore.teamStore.getJoinedTeamListActive();

const user = await rootStore.userStore.getUserActive("account-id");
const messages = rootStore.msgStore.getMsg("V2NIM_P2P-account-id");

更常见的调用方式是：

页面初始化后，等待 SDK 登录与同步
从 rootStore.xxxStore 读取状态或调用 ...Active 方法
页面销毁或账号切换时调用 rootStore.resetState() 或 rootStore.destroy()

核心入口

`RootStore`

RootStore 是整个业务层的统一入口，内部聚合了所有子 store。

常用字段：

connectStore：连接状态、登录状态、首轮数据同步
friendStore：好友列表、好友申请、好友资料
msgStore：消息发送、历史消息、回复、撤回、Pin、收藏
relationStore：黑名单、P2P 免打扰
conversationStore：云端会话模式下的会话列表与未读
localConversationStore：本地会话模式下的会话列表与未读
teamStore：群组资料、建群、退群、群设置
teamMemberStore：群成员列表、邀请成员、移除成员
sysMsgStore：好友申请、入群申请等系统消息
userStore：用户资料、当前登录用户资料
subscriptionStore：在线状态订阅
aiUserStore：AI 用户、AI Bot、AI 代理请求状态
uiStore：当前选中会话、联系人视图等纯 UI 状态
storageStore：文件上传能力

`RootStore.getInstance`

推荐通过单例工厂方法获取实例：

const rootStore = RootStore.getInstance(nim, localOptions, "Web");

适合：

应用生命周期内复用同一个 store 实例
多个页面 / 组件共享同一套 IM 业务状态

本地配置 `LocalOptions`

RootStore 初始化时支持传入 LocalOptions，用于调整 UI Kit 的业务行为。

常见配置示例：

const rootStore = RootStore.getInstance(nim, {
  addFriendNeedVerify: true,
  conversationLimit: 100,
  needMention: true,
  aiVisible: true,
  aiBotsVisible: true,
  p2pMsgReceiptVisible: false,
  teamMsgReceiptVisible: false,
  debug: "debug",
});

可控制的方向包括：

好友申请是否需要验证
会话列表拉取数量
群组相关默认策略
消息已读回执展示
AI 能力开关
调试日志等级

完整字段请参考 API 文档中的 LocalOptions。

类型导出

包对外导出了两类类型：

1. SDK 原始类型

例如：

V2NIMMessage
V2NIMUser
V2NIMFriend
V2NIMTeam
V2NIMTeamMember
V2NIMConversation
V2NIMLocalConversation

这些类型适合在业务代码里直接描述 SDK 原始对象。

2. UI Kit 扩展类型

例如：

V2NIMConversationForUI
V2NIMLocalConversationForUI
V2NIMMessageForUI
V2NIMFriendAddApplicationForUI
V2NIMTeamJoinActionInfoForUI

这些类型是在 SDK 原始对象基础上增加了更适合界面展示的扩展字段。

开发命令

# 开发构建
npm run dev

# 生产构建
npm run build

# ES5 构建
npm run build:es5

# 生成 API 文档
npm run docs:api

# 清理并重新生成 API 文档
npm run docs:api:clean

API 文档

本项目支持使用 TypeDoc 生成公开 API 的 HTML 文档。

生成命令：

npm run docs:api

生成结果默认输出到 docs/api/。

如果你已经在本地生成过文档，可以直接打开：

docs/api/index.html

文档说明：

左侧导航默认只展示主要业务 store
参数和返回值类型支持点击跳转
已隐藏源码 Defined in ... 信息，便于对外阅读

输出产物

构建后默认输出：

dist/index.esm.js
dist/index.cjs.js
dist/types/index.d.ts

同时包含面向不同运行环境的构建结果：

dist/uniapp/*
dist/wx/*

适用场景

这个包更适合以下项目使用：

基于网易云信 Web SDK 的聊天应用
需要将 SDK 原始事件整理成稳定业务状态的前端项目
需要把消息、会话、好友、群组、系统消息统一沉淀到一层 store 中的 UI Kit 工程

如果你的项目只需要非常轻量的 SDK 调用封装，而不需要完整业务状态层，这个包可能会偏重。

版本与依赖

包名：@xkit-yx/im-store-v2
当前版本：0.9.1
Peer Dependency：nim-web-sdk-ng ^10.x

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xkit-yx/im-store-v2

能力概览

安装

快速开始

1. 初始化 NIM SDK

2. 通过 RootStore 访问业务能力

核心入口

RootStore

RootStore.getInstance

本地配置 LocalOptions

推荐使用方式

消息能力

会话能力

联系人 / 群组能力

纯 UI 状态