跳到正文

Provider 全局配置(EmUIKitProvider) ​

EmUIKitProvider 是 UIKit 的顶级容器组件:所有组件(会话列表、聊天、通讯录、群组、原子组件)都必须在它内部渲染。它负责:

  • SDK 连接与登录:用 appKey / appId(二选一;appId 为 SDK 5.1+ 能力,仅 websdk5)创建环信 SDK Client 并初始化 Domain/事件管线
  • 功能开关(features):好友体系、在线状态、群组、用户资料、草稿、@我、正在输入等模块的启停(运行时切换即时生效)
  • 全局主题 / 国际化 / 动画 / H5 适配:一套配置作用于全部组件
  • 数据源接管(dataSource):业务侧完全接管联系人/群组/在线状态/用户资料等数据获取
  • 通知与日志:页内通知 / 浏览器系统通知 / 系统通知文案定制 / IndexedDB 日志持久化

功能范围总览 ​

能力域相关配置
连接与登录appKey / appId(二选一)、sdkConfig、autoInit、adapter(注入模式)、onTokenWillExpire、onTokenExpired
功能开关enableContact、contactFetchMode、enableBlocklist、enablePresence、enableGroup、enableUserInfo、enableUserInfoSubscription、enableDraft、enableAtMe、enableTyping、filterBlockedContacts、showNicknameInSingleChat、showNicknameInGroupChat、enableToast
主题theme(模式 / 品牌色 / 间距 / 圆角 / 字号 / 密度 / 气泡与背景色)
国际化locale(zh-CN / en)
动画与 H5animation(开关 / 强度 / 波纹)、h5(安全区 / 键盘 / 下拉刷新)
数据源接管dataSource(薄别名,4.0.0 移除)、sdkConfig.repositories(推荐,六域数据入口)
能力查询useUIKit().capabilities(SDK 客观能力矩阵)
通知notification(页内弹窗 / 浏览器通知 / 触发模式 / 权限)、noticeConfig(系统通知文案与过滤)
日志logger(IndexedDB 落库 / SDK 日志收集 / 级别 / 保留策略)

最小接入 ​

组件以 EmUIKitProvider 为名导出,全局注册后作为应用根容器使用:

vue
<script setup lang="ts">
import { createPinia } from 'pinia'
// UIKit 需要 pinia 实例(组件内部 store 依赖)
</script>

<template>
  <EmUIKitProvider app-key="your-app-key">
    <!-- 业务容器 / 组件都放在 Provider 内 -->
    <EmChatContainer />
  </EmUIKitProvider>
</template>

依赖说明

  • EmUIKitProvider 不自带 pinia:项目需自行 app.use(createPinia())(文档站演示、在线演练场中由运行环境注入)。
  • 未配置 appKey / appId 时 Provider 仍会创建上下文,但 client 无法完成登录。

常见配置 ​

延迟初始化(autoInit) ​

autoInit=false 时不自动建立 SDK 连接,适合等待登录态 / 异步获取 token 后再初始化:

vue
<EmUIKitProvider :auto-init="false" :app-key="appKey">
  <EmChatContainer />
</EmUIKitProvider>

说明

EmUIKitProvider 不对外 emit 事件(无 ready 等);初始化完成状态可通过 useUIKitProvider()(composable 层)获取与手动触发 init()。

Token 过期回调 ​

vue
<EmUIKitProvider
  app-key="your-app-key"
  :on-token-will-expire="refreshToken"
  :on-token-expired="handleTokenExpired"
>
  <EmChatContainer />
</EmUIKitProvider>

数据源接管(dataSource) ​

业务自有后端时,通过 dataSource 接管数据获取(不传走 SDK 默认实现):

ts
const dataSource = {
  // 拉取联系人列表
  fetchContacts: async () => ({ list: myContacts, hasMore: false }),
  // 订阅在线状态(返回后由 UIKit 管理)
  subscribePresence: async (userIds) => { /* ... */ },
  // 服务端按手机号/邮箱搜索用户
  searchUsers: async (keyword) => mySearchUsers(keyword),
}
vue
<EmUIKitProvider app-key="your-app-key" :data-source="dataSource">
  <EmChatContainer />
</EmUIKitProvider>

SDK 适配器注入(adapter) ​

Provider 需要一个 SDK 适配器(SdkAdapter,对接具体版本的环信 SDK)才能工作,两种装配方式二选一:

  • 内置模式(默认,推荐):入口文件 import '@easemob-community/uikit-im/websdk5'(4.x 用 @easemob-community/uikit-im/webim4),import 副作用把对应 adapter 注册为默认适配器,Provider 不传 adapter 时自动使用,UIKit 全权管理连接生命周期(init / login / logout)
  • 注入模式:业务从 adapter 包取出实例显式传入 adapter prop,连接生命周期(login / logout)归业务全权负责——useClient().login() / useClient().logout() 不会转发到 adapter,业务直接调用自己持有的 adapter.login(user, token) / adapter.logout()
ts
import { Websdk5Adapter } from '@easemob-community/uikit-sdk-websdk5'

const adapter = new Websdk5Adapter()
// 业务侧自行登录:await adapter.login(userId, token)
vue
<EmUIKitProvider :adapter="adapter" app-key="your-app-key">
  <EmChatContainer />
</EmUIKitProvider>

数据入口接管(sdkConfig.repositories) ​

dataSource prop 已收口为 repository 注入的薄别名(装配时逐项翻译,保留至 4.0.0 移除)。新接入推荐经 sdkConfig.repositories 按域整体接管数据读路径——message / conversation / contact / group / presence / userInfo 六域均为可选的部分方法覆盖,显式 repositories 优先于 dataSource 翻译结果:

vue
<EmUIKitProvider
  app-key="your-app-key"
  :sdk-config="{
    repositories: {
      conversation: { fetchConversations: myFetchConversations },
      contact: { fetchContacts: myFetchContacts, fetchBlocklist: myFetchBlocklist },
      userInfo: { fetchUserInfos: myFetchUserInfos },
    },
  }"
>
  <EmChatContainer />
</EmUIKitProvider>

写路径旁路落库(Electron 本地库 SQLite 场景)另见 sdkConfig.persistence 钩子,详见 进阶指南 - 旁路持久化。

能力查询(capabilities) ​

不同 SDK 版本的能力差异由 adapter 如实上报到 useUIKit().capabilities(combineMessage / pinnedMessage / streamingMessage / groupReadReceipt 四个能力位,adapter 未上报时缺省全 true),与 features(业务开关)取交集决定能力入口的展示:

ts
import { useUIKit } from '@easemob-community/uikit-im'

const { capabilities } = useUIKit()

if (capabilities.combineMessage) {
  // 当前 adapter 背后的 SDK 支持合并消息,可展示合并转发入口
}

非 Vue 上下文(定时任务、主进程等)可用 core 的模块级 getUIKitAdapter()(@easemob-community/uikit-core)读取当前装配的适配器实例,Provider 未挂载或已卸载时返回 null。

通知与日志 ​

vue
<EmUIKitProvider
  app-key="your-app-key"
  :notification="{
    browser: true,            // 浏览器系统通知
    inApp: true,              // 页内右上角弹窗
    triggerMode: 'background',// 仅页面隐藏时触发
    onNotify: (item, channel) => playRingtone(), // 送达回调(自定义铃声等,见 Notification 指南)
  }"
  :logger="{
    enabled: true,            // IndexedDB 持久化
    collectSdkLog: false,     // 默认不收集 SDK 日志
    uikitLevel: 'info',       // 生产建议 info
    maxEntries: 5000,
    retentionDays: 7,
  }"
>
  <EmChatContainer />
</EmUIKitProvider>

更多能力(主题定制、系统通知文案、H5 适配、日志导出)见对应指南页。

API ​

UikitProvider API ​

Props ​

属性类型默认值说明
appKeystring—环信应用标识 AppKey(orgName#appName),由环信控制台创建应用获取;与 appId 二选一
appIdstring—环信应用 App ID(SDK 5.1+;与 appKey 二选一,appId 模式经 DNSConfig 解析,不可配固定 serverUrls;webim4 / SDK 4.x 不支持)
adapterSdkAdapter—注入的中立 SDK 适配器(SdkAdapter)。传入后业务全权管理其生命周期(D122 注入模式);
不传时使用注册表默认适配器——由 import '@easemob-community/uikit-im/websdk5' 子路径入口
自注册(UIKit 全权管理);4.x 接入方改为 import webim4 adapter 并显式传本 prop。
sdkConfigOmit<CoreUIKitInitConfig, 'appKey' | 'appId'>—SDK 客户端配置(除 appKey/appId 外的 SDK 初始化字段,如 debug / enableSyncData / loginTimeoutMs 等),与 appKey/appId 合并后透传给 adapter
autoInitbooleantrue是否自动初始化 SDK 连接(默认 true):false 时延迟初始化,待业务调用 useClient().init(config) 传入 appKey 后创建
theme{ preset?: ThemePreset, mode?: 'light' | 'dark' | 'auto', primaryColor?: PrimaryColorInput, gap?: number, shape?: 'ground' | 'square', fontSize?: ThemeFontSize, density?: Density, bubbleColor?: string | { self?: string, other?: string }, chatBg?: string, inputBg?: string, hoverColor?: string, activeColor?: string, iconMutedColor?: string, headerBorder?: boolean, messageChipBg?: boolean }—全局主题配置:预设 / 模式 / 品牌色 / 间距 / 圆角 / 字号 / 密度 / 气泡与背景色,挂载时应用
locale'zh-CN' | 'en''zh-CN'界面语言:zh-CN 中文(默认) / en 英文
animationAnimationConfig—全局动画配置:enabled 总开关 / level 强度(subtle|normal|expressive)/ ripple 波纹,挂载时应用一次
h5H5AdaptationConfig—H5 适配配置:安全区、键盘适配、下拉刷新等。
默认 safeArea=true, keyboardAdapt=true, pullRefresh='auto'。
enableContactbooleantrue是否启用好友体系(默认 true)
contactFetchModeContactFetchMode'page'联系人拉取模式(默认 'page')
- 'page': 目前 SDK 未暴露分页游标接口,实际按全量返回处理
- 'all': 一次性全量拉取
enableBlocklistbooleantrue是否启用黑名单(默认 true)
enablePresencebooleantrue是否启用在线状态(默认 true;presence 订阅会带来额外查询/订阅请求,
低频场景可显式关闭)
enableGroupbooleantrue是否启用群组体系(默认 true)
enableUserInfobooleantrue是否启用用户资料(昵称/头像等)展示与拉取(默认 true)
enableUserInfoSubscriptionbooleantrue是否启用陌生人用户资料变更订阅(默认 true)。
若服务端未开通该能力,会提示用户开通并自动熔断后续订阅。
enableDraftbooleantrue是否启用会话列表草稿显示(默认 true)
enableAtMebooleantrue是否启用 @我提示(默认 true)
enableTypingbooleantrue是否启用对方正在输入提示(默认 true)
enableReadReceiptbooleantrue是否启用消息已读回执(默认 true)。
关闭后接收方不再发送消息级已读回执,UIKit 也不展示已读状态
(单聊已读 icon、群已读数/已读详情);不影响本机未读数同步。
filterBlockedContactsbooleantrue好友列表是否过滤掉已拉黑用户(默认 true;仅联系人子视图/好友列表生效,选人弹窗不受影响)
showNicknameInSingleChatbooleanfalse单聊消息列表是否展示对方昵称(默认 false,微信风格默认隐藏)
showNicknameInGroupChatbooleantrue群聊消息列表是否展示发送者昵称(默认 true)
dataSourceUIKitDataSource—业务接管数据源,不传走 SDK 默认
noticeConfigNoticeConfig—系统通知自定义配置:renderText 自定义文案(俏皮/严肃话术等)、
filter 条件隐藏、disabledEvents 直接禁用某类事件。默认全开,按内置多语言文案展示。
支持响应式对象,运行时变更即刻生效。
System notice customization: renderText to rewrite the copy, filter to hide
conditionally, disabledEvents to disable certain event types.
enableToastbooleantrue是否启用内置 Toast 提示(默认 true)。
关闭后仍可通过 useToast() 获取状态并自行渲染提示组件。
notification{ enable?: boolean, browser?: boolean, inApp?: boolean, autoRequestPermission?: boolean, triggerMode?: NotificationTriggerMode, navigateOnClick?: boolean, onNotify?: (item: Omit<NotificationItem, 'id' | 'unreadCount'>, channel: NotificationChannel) => void }—消息通知配置(默认全开,触发模式 background)。
关闭后仍可通过 useNotification() 获取状态并自行渲染通知组件。
onTokenWillExpire() => void—Token 即将过期回调,业务可在此刷新 token
onTokenExpired() => void—Token 已过期回调,业务可在此重新登录或提示用户
logger{ enabled?: boolean, collectSdkLog?: boolean, uikitLevel?: 'debug' | 'info' | 'warn' | 'error', sdkLevel?: 'debug' | 'warn' | 'error', maxEntries?: number, retentionDays?: number }—日志持久化配置(IndexedDB 本地落库,用于问题排查)。
Log persistence config (IndexedDB, for troubleshooting).

theme ​

全局主题配置:预设 / 模式 / 品牌色 / 间距 / 圆角 / 字号 / 密度 / 气泡与背景色,挂载时应用

属性类型默认值说明
presetThemePreset—预设主题档位:'default' | 'business' | 'fresh',应用后单项配置可继续覆盖
mode'light' | 'dark' | 'auto'—主题模式:'light' | 'dark' | 'auto'(跟随系统)
primaryColorPrimaryColorInput—品牌主色:色相数字(0-360,默认 203,保留当前 S/L) 或完整 HSL 对象
gapnumber—容器间距(px),默认 8,最小 0
shape'ground' | 'square'—组件圆角模式:'ground' 圆角(默认)| 'square' 直角
fontSizeThemeFontSize—字号:'normal' | 'large' | 'xlarge' 或具体缩放倍数
densityDensity—密度:compact 紧凑 / normal 标准 / comfortable 宽松
bubbleColorstring | { self?: string, other?: string }—气泡颜色:传字符串时同时设置自己/对方;传对象可分别设置
chatBgstring—聊天背景:支持颜色 / 渐变 / url(...) 图片
inputBgstring—输入区背景
hoverColorstring—自定义 hover 背景色(任意 CSS 颜色值)。单值同时作用于浅色与深色模式;
不配置时走内置浅/深默认(--uikit-bg-hover)。
Custom hover background color; applies to both light and dark modes.
activeColorstring—自定义 active(选中项)背景色。单值同时作用于浅色与深色模式;
不配置时走内置 rgba(primary-rgb, α) 跟随品牌主色。
Custom active background color; applies to both light and dark modes.
iconMutedColorstring—自定义弱化/占位图标色。单值同时作用于浅色与深色模式;
不配置时走内置浅/深默认(--uikit-icon-muted)。
Custom muted icon color; applies to both light and dark modes.
headerBorderboolean—全局 header 底部分隔线开关(会话/通讯录/聊天/抽屉/弹窗 header 的 1px 底线),默认 false 关闭。
Global header bottom divider toggle (conversation/contact/chat/drawer/modal headers). Default false.
messageChipBgboolean—消息辅助信息胶囊背景开关(时间分割线 / 通知事件 / 没有更多历史消息的气泡底胶囊),默认 true 开启。
Toggle for the capsule background of auxiliary message tips (time dividers / notice events / no-more-history). Default true.

notification ​

消息通知配置(默认全开,触发模式 background)。

属性类型默认值说明
enableboolean—总开关(默认 true)
browserboolean—浏览器系统通知(默认 true)
inAppboolean—页内右上角弹窗(默认 true)
autoRequestPermissionboolean—首次通知时自动请求浏览器通知权限(默认 true)
triggerModeNotificationTriggerMode—触发模式:'background' 仅页面隐藏时(默认)| 'always' 非当前会话即触发
navigateOnClickboolean—点击通知时跳转对应会话(默认 true)
onNotify(item: Omit<NotificationItem, 'id' | 'unreadCount'>, channel: NotificationChannel) => void—通知送达回调:判定链命中且通知实际投递(浏览器通知发出成功 / 页内弹窗入列)时触发,
channel 为实际投递通道。可用于播放自定义铃声、对接自定义通知服务等;
音频资源与浏览器 autoplay 解锁策略由业务侧负责(UIKit 不内置铃声)。
Notification delivery callback, fired when a notification is actually delivered
('browser' on system notification success / 'in-app' on in-app toast queued).
Use it to play custom sounds or hook custom notification services.

logger ​

日志持久化配置(IndexedDB 本地落库,用于问题排查)。

属性类型默认值说明
enabledboolean—是否持久化 UIKit 日志(默认 true) / Persist UIKit logs (default true)
collectSdkLogboolean—是否同时收集 SDK 日志(默认 false) / Also collect SDK logs (default false)
uikitLevel'debug' | 'info' | 'warn' | 'error'—UIKit 层收集级别(默认 'info'),低于该级别直接丢弃。
生产建议 'info',排查时临时调 'debug'。
UIKit collect level (default 'info'); use 'debug' temporarily for troubleshooting.
sdkLevel'debug' | 'warn' | 'error'—SDK 层收集级别(默认 'warn',SDK 无 info 级)。
DEBUG 含心跳等高频日志,生产建议 'warn'。
SDK collect level (default 'warn'; SDK has no info level).
maxEntriesnumber—最大保留条数(默认 5000) / Max retained entries (default 5000)
retentionDaysnumber—保留天数(默认 7) / Retention days (default 7)