@wecode-team/im-widgets

React + 悟空 IM（wukongimjssdk）聊天 UI：访客 ChatLauncher、坐席 ChatConsole。（导出常量 IM_WS_ADDR / IM_HTTP_BASE）。仅需 import.meta.env.WE0_IM_ID 一个环境变量；组件 props 仅含 UI/交互。

安装

npm install @wecode-team/im-widgets
# or
pnpm add @wecode-team/im-widgets

react、react-dom（≥18）、wukongimjssdk（≥1.3）为 peerDependencies；npm 7+ 通常自动补齐，缺则 npm install wukongimjssdk（工程已有 React 时）。

集成与配置规范（We0）

在 .env / .env.local 中配置一个变量即可：

# .env.local
WE0_IM_ID=staff01

| 变量 | 必填 | 含义 | |------|------|------| | WE0_IM_ID | ✅ | 当前用户/坐席的身份标识；访客浮层与坐席工作台共用同一份配置 | | WE0_IM_SESSION_PEERS | 可选 | 逗号分隔的访客 uid，预置坐席左侧会话列表；不填时由消息自动发现 |

参考实现见 We0 仓库中的 im-widgets-website-demo（.env.example 与首页、/admin 用法）。

快速开始

# .env.local
WE0_IM_ID=staff01

访客浮层

import { ChatLauncher } from "@wecode-team/im-widgets";

<ChatLauncher title="在线咨询" connectOnOpen keepAlive />;

坐席工作台

import { ChatConsole } from "@wecode-team/im-widgets";

<ChatConsole minHeight={0} style={{ flex: 1, minHeight: 0 }} />;

导出 IM_WS_ADDR / IM_HTTP_BASE、readWe0ImLauncherConfig / readWe0ImConsoleConfig（原始 env 键，不含固定地址）、getResolvedLauncherDisplay / getResolvedConsoleDisplay、getOrCreateVisitorUid。

嵌入父级时父链需 minHeight: 0 + overflow: hidden，避免整页被撑高。

ChatLauncher

连接：WS IM_WS_ADDR；身份取自 WE0_IM_ID。

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | channelType | number | 1 | 频道类型，一般单聊 1 | | title | string | "在线咨询" | 浮层标题 | | placeholder | string | — | 输入框占位 | | offsetRight / offsetBottom | number | 24 | 距视口右下 px | | zIndex | number | 9999 | 层级 | | defaultOpen | boolean | false | 初始是否展开 | | connectOnOpen | boolean | true | 是否首次展开再连接 | | keepAlive | boolean | true | 关闭面板后是否保持连接 | | onError | (e: Error) => void | — | 连接/发送失败 | | maxInputChars | number | — | 输入最大字数，超出截断 |

内置：深浅色、连接状态、消息列表、链接/图片直链预览、输入框自动增高、Enter / Shift+Enter、发送/连接重试、未读角标、拖拽 FAB 调位（可记 localStorage）、Esc 关面板。

ChatConsole

连接：IM_WS_ADDR；历史等 HTTP：IM_HTTP_BASE；身份取自 WE0_IM_ID，会话预置可选 WE0_IM_SESSION_PEERS。

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | autoDiscoverSessions | boolean | true | 是否从消息自动补全左侧列表 | | channelType | number | 1 | 单聊 | | title | string | "客服工作台" | 顶栏标题 | | placeholder | string | — | 输入框 | | defaultPeerUid | string | — | 默认选中会话 | | minHeight | number | 520 | 嵌入传 0 配合父级 flex | | style | CSSProperties | — | 根容器，常设 flex:1、minHeight:0 | | onError | (e: Error) => void | — | — | | maxInputChars | number | — | — |

内置：会话排序/预览/未读、深浅色、连接与发送重试、无障碍、消息区吸底与「回到底部」等。

凭证 ImCredentials

type ImCredentials = { uid: string; token: string };

适配器与工具

默认使用 WuKongImAdapter（WKSDK.shared()）。可自实现 ImAdapter 换通道。

| 导出 | 说明 | |------|------| | IM_WS_ADDR / IM_HTTP_BASE | 固定 wss://im.we0.ai/ws 与 https://im.we0.ai | | getOrCreateVisitorUid | 与包内访客 uid 规则一致（同一页内缓存）；需在页面上展示与浮层同一 uid 时用 | | fetchChannelMessageHistory | HTTP 拉频道历史 | | wsAddrToHttpBase | wss:// → https:// 根 | | formatMessageTime / formatRelativeActivity | 时间展示 | | timeDividerLabel | 消息间分隔文案 | | getChatPalette | 主题色 | | LinkifiedText / isLikelyImageUrl | 链接与图片直链 |

类型：ChatLauncherProps、ChatConsoleProps、ImMessage、ImSessionItem、ImConnectConfig 等见 src/types.ts。

License

MIT