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) |
| 动画与 H5 | animation(开关 / 强度 / 波纹)、h5(安全区 / 键盘 / 下拉刷新) |
| 数据源接管 | dataSource(薄别名,4.0.0 移除)、sdkConfig.repositories(推荐,六域数据入口) |
| 能力查询 | useUIKit().capabilities(SDK 客观能力矩阵) |
| 通知 | notification(页内弹窗 / 浏览器通知 / 触发模式 / 权限)、noticeConfig(系统通知文案与过滤) |
| 日志 | logger(IndexedDB 落库 / SDK 日志收集 / 级别 / 保留策略) |
最小接入
组件以 EmUIKitProvider 为名导出,全局注册后作为应用根容器使用:
<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 后再初始化:
<EmUIKitProvider :auto-init="false" :app-key="appKey">
<EmChatContainer />
</EmUIKitProvider>说明
EmUIKitProvider 不对外 emit 事件(无 ready 等);初始化完成状态可通过 useUIKitProvider()(composable 层)获取与手动触发 init()。
Token 过期回调
<EmUIKitProvider
app-key="your-app-key"
:on-token-will-expire="refreshToken"
:on-token-expired="handleTokenExpired"
>
<EmChatContainer />
</EmUIKitProvider>数据源接管(dataSource)
业务自有后端时,通过 dataSource 接管数据获取(不传走 SDK 默认实现):
const dataSource = {
// 拉取联系人列表
fetchContacts: async () => ({ list: myContacts, hasMore: false }),
// 订阅在线状态(返回后由 UIKit 管理)
subscribePresence: async (userIds) => { /* ... */ },
// 服务端按手机号/邮箱搜索用户
searchUsers: async (keyword) => mySearchUsers(keyword),
}<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 包取出实例显式传入
adapterprop,连接生命周期(login / logout)归业务全权负责——useClient().login()/useClient().logout()不会转发到 adapter,业务直接调用自己持有的adapter.login(user, token)/adapter.logout()
import { Websdk5Adapter } from '@easemob-community/uikit-sdk-websdk5'
const adapter = new Websdk5Adapter()
// 业务侧自行登录:await adapter.login(userId, token)<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 翻译结果:
<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(业务开关)取交集决定能力入口的展示:
import { useUIKit } from '@easemob-community/uikit-im'
const { capabilities } = useUIKit()
if (capabilities.combineMessage) {
// 当前 adapter 背后的 SDK 支持合并消息,可展示合并转发入口
}非 Vue 上下文(定时任务、主进程等)可用 core 的模块级 getUIKitAdapter()(@easemob-community/uikit-core)读取当前装配的适配器实例,Provider 未挂载或已卸载时返回 null。
通知与日志
<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
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| appKey | string | — | 环信应用标识 AppKey(orgName#appName),由环信控制台创建应用获取;与 appId 二选一 |
| appId | string | — | 环信应用 App ID(SDK 5.1+;与 appKey 二选一,appId 模式经 DNSConfig 解析,不可配固定 serverUrls;webim4 / SDK 4.x 不支持) |
| adapter | SdkAdapter | — | 注入的中立 SDK 适配器(SdkAdapter)。传入后业务全权管理其生命周期(D122 注入模式); 不传时使用注册表默认适配器——由 import '@easemob-community/uikit-im/websdk5' 子路径入口自注册(UIKit 全权管理);4.x 接入方改为 import webim4 adapter 并显式传本 prop。 |
| sdkConfig | Omit<CoreUIKitInitConfig, 'appKey' | 'appId'> | — | SDK 客户端配置(除 appKey/appId 外的 SDK 初始化字段,如 debug / enableSyncData / loginTimeoutMs 等),与 appKey/appId 合并后透传给 adapter |
| autoInit | boolean | true | 是否自动初始化 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 英文 |
| animation | AnimationConfig | — | 全局动画配置:enabled 总开关 / level 强度(subtle|normal|expressive)/ ripple 波纹,挂载时应用一次 |
| h5 | H5AdaptationConfig | — | H5 适配配置:安全区、键盘适配、下拉刷新等。 默认 safeArea=true, keyboardAdapt=true, pullRefresh='auto'。 |
| enableContact | boolean | true | 是否启用好友体系(默认 true) |
| contactFetchMode | ContactFetchMode | 'page' | 联系人拉取模式(默认 'page') - 'page': 目前 SDK 未暴露分页游标接口,实际按全量返回处理 - 'all': 一次性全量拉取 |
| enableBlocklist | boolean | true | 是否启用黑名单(默认 true) |
| enablePresence | boolean | true | 是否启用在线状态(默认 true;presence 订阅会带来额外查询/订阅请求, 低频场景可显式关闭) |
| enableGroup | boolean | true | 是否启用群组体系(默认 true) |
| enableUserInfo | boolean | true | 是否启用用户资料(昵称/头像等)展示与拉取(默认 true) |
| enableUserInfoSubscription | boolean | true | 是否启用陌生人用户资料变更订阅(默认 true)。 若服务端未开通该能力,会提示用户开通并自动熔断后续订阅。 |
| enableDraft | boolean | true | 是否启用会话列表草稿显示(默认 true) |
| enableAtMe | boolean | true | 是否启用 @我提示(默认 true) |
| enableTyping | boolean | true | 是否启用对方正在输入提示(默认 true) |
| enableReadReceipt | boolean | true | 是否启用消息已读回执(默认 true)。 关闭后接收方不再发送消息级已读回执,UIKit 也不展示已读状态 (单聊已读 icon、群已读数/已读详情);不影响本机未读数同步。 |
| filterBlockedContacts | boolean | true | 好友列表是否过滤掉已拉黑用户(默认 true;仅联系人子视图/好友列表生效,选人弹窗不受影响) |
| showNicknameInSingleChat | boolean | false | 单聊消息列表是否展示对方昵称(默认 false,微信风格默认隐藏) |
| showNicknameInGroupChat | boolean | true | 群聊消息列表是否展示发送者昵称(默认 true) |
| dataSource | UIKitDataSource | — | 业务接管数据源,不传走 SDK 默认 |
| noticeConfig | NoticeConfig | — | 系统通知自定义配置:renderText 自定义文案(俏皮/严肃话术等)、 filter 条件隐藏、disabledEvents 直接禁用某类事件。默认全开,按内置多语言文案展示。 支持响应式对象,运行时变更即刻生效。 System notice customization: renderText to rewrite the copy, filter to hide conditionally, disabledEvents to disable certain event types. |
| enableToast | boolean | true | 是否启用内置 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
全局主题配置:预设 / 模式 / 品牌色 / 间距 / 圆角 / 字号 / 密度 / 气泡与背景色,挂载时应用
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| preset | ThemePreset | — | 预设主题档位:'default' | 'business' | 'fresh',应用后单项配置可继续覆盖 |
| mode | 'light' | 'dark' | 'auto' | — | 主题模式:'light' | 'dark' | 'auto'(跟随系统) |
| primaryColor | PrimaryColorInput | — | 品牌主色:色相数字(0-360,默认 203,保留当前 S/L) 或完整 HSL 对象 |
| gap | number | — | 容器间距(px),默认 8,最小 0 |
| shape | 'ground' | 'square' | — | 组件圆角模式:'ground' 圆角(默认)| 'square' 直角 |
| fontSize | ThemeFontSize | — | 字号:'normal' | 'large' | 'xlarge' 或具体缩放倍数 |
| density | Density | — | 密度:compact 紧凑 / normal 标准 / comfortable 宽松 |
| bubbleColor | string | { self?: string, other?: string } | — | 气泡颜色:传字符串时同时设置自己/对方;传对象可分别设置 |
| chatBg | string | — | 聊天背景:支持颜色 / 渐变 / url(...) 图片 |
| inputBg | string | — | 输入区背景 |
| hoverColor | string | — | 自定义 hover 背景色(任意 CSS 颜色值)。单值同时作用于浅色与深色模式; 不配置时走内置浅/深默认(--uikit-bg-hover)。 Custom hover background color; applies to both light and dark modes. |
| activeColor | string | — | 自定义 active(选中项)背景色。单值同时作用于浅色与深色模式; 不配置时走内置 rgba(primary-rgb, α) 跟随品牌主色。 Custom active background color; applies to both light and dark modes. |
| iconMutedColor | string | — | 自定义弱化/占位图标色。单值同时作用于浅色与深色模式; 不配置时走内置浅/深默认(--uikit-icon-muted)。 Custom muted icon color; applies to both light and dark modes. |
| headerBorder | boolean | — | 全局 header 底部分隔线开关(会话/通讯录/聊天/抽屉/弹窗 header 的 1px 底线),默认 false 关闭。 Global header bottom divider toggle (conversation/contact/chat/drawer/modal headers). Default false. |
| messageChipBg | boolean | — | 消息辅助信息胶囊背景开关(时间分割线 / 通知事件 / 没有更多历史消息的气泡底胶囊),默认 true 开启。 Toggle for the capsule background of auxiliary message tips (time dividers / notice events / no-more-history). Default true. |
notification
消息通知配置(默认全开,触发模式 background)。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| enable | boolean | — | 总开关(默认 true) |
| browser | boolean | — | 浏览器系统通知(默认 true) |
| inApp | boolean | — | 页内右上角弹窗(默认 true) |
| autoRequestPermission | boolean | — | 首次通知时自动请求浏览器通知权限(默认 true) |
| triggerMode | NotificationTriggerMode | — | 触发模式:'background' 仅页面隐藏时(默认)| 'always' 非当前会话即触发 |
| navigateOnClick | boolean | — | 点击通知时跳转对应会话(默认 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 本地落库,用于问题排查)。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| enabled | boolean | — | 是否持久化 UIKit 日志(默认 true) / Persist UIKit logs (default true) |
| collectSdkLog | boolean | — | 是否同时收集 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). |
| maxEntries | number | — | 最大保留条数(默认 5000) / Max retained entries (default 5000) |
| retentionDays | number | — | 保留天数(默认 7) / Retention days (default 7) |
