MeetingKit 提供了灵活的界面定制能力,允许第三方开发者根据业务需求显示或隐藏特定功能、自定义底部工具栏按钮以及重写部分界面样式。本文档详细介绍了主要的界面定制方式。
能力 | 方法说明 | 调用时机 | 备注 |
| 显示或隐藏会中功能模块(聊天、白板、录制等) |
| - |
| 配置呼叫页背景音乐(音源、音量、是否播放) |
| v4.0.10+;替代 |
| 控制设置侧栏 Tab 及页内细项显隐 |
| v4.0.10+ |
| 定制会议信息/邀请界面、标签页 |
| v4.0.10+ |
| 设置主题色与亮暗模式 |
| v4.0.10+;替代会中换肤用的 |
| 设置 MeetingKit 界面语言( |
| - |
| 自定义会中底部工具栏按钮(增删改、排序) | 渲染 | - |
| 在用户手势后解锁浏览器远端音频播放 | 用户触发入会的点击/触摸等手势回调中, | - |
使用示例
import { uiMeetingKit } from '@xylink/meetingkit';
// 1. 界面定制(createClient 前)
uiMeetingKit.setFeatureVisible({ enableIM: false });
uiMeetingKit.setBgmAudioConfig({ play: false });
uiMeetingKit.setSettingConfig({ settingMenu: { hotkey: false } });
uiMeetingKit.setTheme({ colorPrimary: '#49A681' });
uiMeetingKit.setUiConfig({ tabTitle: '我的会议' });
uiMeetingKit.setLocale('zh_CN');
// 2. 创建客户端
await uiMeetingKit.createClient({ /* clientId, clientSecret, extId, server, meetingControlUrl */ });
// 3. 渲染 XYMeetingKitComp(makeCall 前),定制底部按钮
//
// 4. 登录 → 用户手势触发入会时:playAudio(推荐)→ makeCall
await uiMeetingKit.getClient()?.loginExternalAccount({ extUserId: '…', displayName: '…' });
await uiMeetingKit.getClient()?.playAudio();
await uiMeetingKit.makeCall({ confNumber: '…', displayName: '…' });通过 setFeatureVisible 方法可以动态显示或隐藏特定功能模块。
使用示例
提示
请在 uiMeetingKit.createClient() 之前调用此方法
import { uiMeetingKit } from '@xylink/meetingkit';
uiMeetingKit.setFeatureVisible({
enableIM: false // 隐藏聊天功能
});
支持隐藏的功能键名
功能键名 | 说明 | 默认值 | 备注 |
enablePip | 画中画 | true | |
enableFullScreen | 全屏 | true | v4.0.10+ |
enableVirtualBackground | 虚拟背景 | false | |
enableIM | 聊天 | true | 公有云暂不支持,需手动设置为false |
enableWhiteboard | 白板 | true | |
enableAnnotation | 批注 | true | |
enableVersionInfo | 显示版本信息 | true | v4.0.10+ 废弃,由 |
enableShareContent | 分享内容 | true | |
enableInvite | 邀请 | true | |
enableConferenceLink | 会议链接 | true | |
enableTranscription | 文字转写 | true | v4.0.10+ , 仅 PC 展示;需会议侧开通转写能力 |
enableMultiLayoutPolling | 多画面 / 轮询 | true | v4.0.10+ |
enableConflictContent | 是否允许共享屏幕抢占 | true | v4.0.10+ |
enableMeetingRecord | 会中「录制」按钮 | true | v4.0.10+ |
enablePageLeaveConfirm | 关闭页面前确认 | true | v4.0.10+ |
enableBgmAudio | 呼叫页背景音乐 | true | v4.0.10+ |
MeetingKit 提供会中底部工具栏(Footer)的自定义能力,可通过 footerCustomButtons 增删改默认按钮、调整排序与显隐,或接入业务自定义操作。
1. 添加新功能按钮 - 扩展会议功能,集成业务特定操作
2. 修改现有按钮 - 调整默认按钮的行为、样式或显示条件
3. 隐藏不需要的按钮 - 简化界面,聚焦核心功能
4. 重新排序按钮 - 根据使用频率和重要性调整按钮位置
5. 条件性显示 - 基于用户角色、会议状态等条件动态显示/隐藏按钮
通过向 XYMeetingKitComp 组件的 footerCustomButtons 参数传递配置数组,即可实现底部按钮的自定义配置(当前仅支持PC端)。
1、了解默认按钮配置
2、键名使用原则
import { XYMeetingKitComp } from '@xylink/meetingkit';
<XYMeetingKitComp
visible={visible}
footerCustomButtons={[]}
/>
export interface XYCustomButtonConfig {
key: string; // 按钮唯一标识符(必需),使用已存在的 key 值会覆盖默认按钮配置
label?: string | ReactNode; // 按钮显示文字
icon?: string | ReactNode; // 按钮图标
position?: XYButtonPosition; // 按钮位置:'left' | 'middle' | 'right'
className?: string; // 自定义CSS类名
order?: number; // 显示顺序(数值越小越靠前)
show?: boolean; // 为 false 时从对应区域移除该按钮
priority?: XYButtonPriority; // 隐藏优先级:MUST_SHOW | HIGH | MEDIUM | LOW
defaultHidden?: boolean; // 是否默认隐藏在"更多"菜单中
closeParentDialog?: boolean; // 点击后是否关闭父级弹窗
popover?: XYPopoverProps; // 气泡弹窗配置
onClick?: (context?: any) => void | Promise<void>; // 点击回调函数, 原内置交互逻辑不再执行
component?: React.ComponentType<any>; // 自定义React组件
}
1、左侧区域按钮
左侧区域放置最核心的会议控制功能,这些按钮通常具有最高优先级
lable | 键名(key) | 顺序(order) | 显示条件(show) |
静音/取消静音 |
| 1 | 始终显示 |
开启视频/关闭视频 |
| 2 | 始终显示 |
2、中间区域按钮
中间区域包含主要的会议功能和工具按钮,按优先级和功能分组
lable | 键名 (key) | 顺序(order) | 隐藏优先级(priority) | 显示条件(show) |
共享 |
| 1 | HIGH | 非移动端 |
会议录制 |
| 2 | MEDIUM | 非移动端 |
邀请 |
| 3 | LOW | 非移动端 |
参会者(主持会议) |
| 4 | HIGH | 始终显示 |
窗口布局 |
| 5 | MEDIUM | 非移动端 |
开启字幕 |
| 6 | LOW | 非移动端 |
白板 |
| 7 | MEDIUM | 非移动端 |
批注 |
| 8 | LOW | 非移动端 |
聊天 |
| 9 | MEDIUM | 非移动端 |
设置 |
| 10 | LOW | 非移动端 |
3、右侧区域按钮
右侧区域放置重要的操作按钮,通常是会议的关键操作
lable | 键名 (key) | 顺序(order) | 显示条件(show) |
结束 |
| 1 | 非移动端 |
添加自定义按钮
import { XYMeetingKitComp } from '@xylink/meetingkit';
const customButtons = [
{
key: 'customer-support',
label: '客服支持',
icon: <SupportIcon />,
position: XYButtonPosition.MIDDLE,
order: -1,
priority: XYButtonPriority.MEDIUM,
onClick:()=>{}
},
{
key: 'feedback',
label: '反馈',
icon: <FeedbackIcon />,
position: XYButtonPosition.MIDDLE,
order: -1,
priority: XYButtonPriority.LOW,
className: 'custom-feedback-btn',
onClick: ()=>{}
}
];
<XYMeetingKitComp
footerCustomButtons={customButtons}
// 其他配置...
/>
默认按钮 | 自定义按钮 |
|
|
通过 setUiConfig 定制会议室顶部小「i」信息区、邀请弹层、浏览器标签页及云录制提示语。
提示
请在 uiMeetingKit.createClient() 之前调用此方法
使用示例
import { uiMeetingKit } from '@xylink/meetingkit';
uiMeetingKit.setUiConfig({
tabTitle: '我的会议',
tabIcon: 'https://your.cdn/favicon.ico',
logoUrl: 'https://your.cdn/logo.png',
meetingInfoUi: {
conferenceLink: {
label: '入会链接',
value: 'https://example.com/join/xxx',
copyText: 'https://example.com/join/xxx',
},
},
inviteUi: {
headline: { value: '邀请您加入会议' },
conferenceNumber: { label: '会议号', show: true },
hardwareSectionLabel: '客户端与终端入会方式',
phoneDial: { value: '400-xxx-xxxx' },
showCopyInviteButton: true,
},
recordUi: {
cloudRecordCompleteTip: '云录制已完成,请在录制中心查看',
},
});常用字段
字段 | 说明 |
tabTitle | 浏览器标签页标题 |
tabIcon | 浏览器标签页图标 |
logoUrl | 设置-关于页等企业 Logo |
meetingInfoUi.password | 会中顶部会议信息-小「i」内会议密码行 |
meetingInfoUi.conferenceLink | 会中顶部会议信息-小「i」内会议链接文案 |
inviteUi.headline | 邀请弹框-标题 |
inviteUi.conferenceNumber | 邀请弹框-会议号标签 |
inviteUi.password | 邀请弹框-会议密码行 |
inviteUi.conferenceLink | 邀请弹框-会议链接行 |
inviteUi.phoneDial | 邀请弹框-电话入会号码 |
inviteUi.hardwareSectionLabel | 邀请弹框-「软件客户端和硬件终端入会」区块标题 |
inviteUi.showCopyInviteButton | 邀请弹框- 是否显示「复制邀请文本」 |
recordUi.cloudRecordCompleteTip | 云录制结束后的提示语 |
会中顶部会议信息 | 邀请弹框 |
|
|
通过 setSettingConfig 控制会中「设置」弹框的 Tab 及页内细项。
提示
使用示例
uiMeetingKit.setSettingConfig({
appearanceMode: 'light', // 'light' | 'dark' | 'system'
settingMenu: {
about: {
showVersionLog: false, // 隐藏版本日志
showSdkDriverLine: false, // 隐藏 SDK 驱动说明
// showLogo: false, // 可选,隐藏 Logo
},
feedback: {
showDownloadLog: false, // 隐藏「下载日志」
showDebug: false, // 隐藏「调试模式」
},
hotkey: false, // 隐藏「快捷键」Tab
common: {
appearanceSetting: true,
speakerName: true,
isLowResolution: true,
},
},
});settingMenu Tab
Tab 键名 | 说明 | 默认 |
common | 通用 | 显示 |
device | 设备 | 显示 |
hotkey | 快捷键 | 显示 |
feedback | 反馈 | 显示 |
about | 关于 | 显示 |
server | 服务器 | 显示 |
通用 Tab 细项(settingMenu.common 传对象时)
字段 | 说明 | 默认 |
appearanceSetting | 外观设置(普通/深色/跟随系统) | true |
speakerName | 正在讲话人 | true |
isLowResolution | 节能模式 | true |
localHide | 隐藏本地画面 | true |
inFullScreen | 全屏加入会议 | true |
关于页细项
字段 | 说明 | 默认 |
showLogo | 是否显示Logo(可通过 | true |
showVersionLog | 是否显示版本日志入口 | true |
showSdkDriverLine | 是否显示 SDK 驱动说明 | true |
反馈页细项
字段 | 说明 | 默认 |
showDownloadLog | 是否显示「下载日志」 | true |
showDebug | 是否显示「调试模式」 | true |
设置弹框 |
|
通过调用setLocale设置MeetingKit国际化语言
import { uiMeetingKit } from '@xylink/meetingkit';
// 设置界面语言为英文
uiMeetingKit.setLocale('en-US');
// 设置界面语言为中文
uiMeetingKit.setLocale('zh-CN');
// 设置界面语言为繁体
uiMeetingKit.setLocale('zh_TW');
英文 | 繁体 |
|
|
MeetingKit 支持通过 setTheme 自定义会中界面主题色,并同步至 IM、会控等内嵌页面。
提示
1、useTheme方法从v4.0.10+已移除,建议更换成setTheme方法
2、首次设置请在uiMeetingKit.createClient()之前调用,避免首帧默认主题色。
1. 基础主题设置
只需配置主色调colorPrimary,即可实现整体主题色更换。
import { uiMeetingKit } from '@xylink/meetingkit';
uiMeetingKit.setTheme({
colorPrimary: '#49A681',
displayMode: 'light', // 'light' | 'dark' | 'system'
});
2.完整主题配置
如需精细控制各个UI元素,可详细配置所有颜色变量。通过 cssVariables 覆盖设计 token(键名去掉 CSS 前缀 --xy-,如 B1、Tag1_bg)。完整品牌色键列表见导出常MEETING_KIT_BRAND_TOKEN_KEYS。
uiMeetingKit.setTheme({
cssVariables: {
B1: '#49A681',
B2: '#3E8C6D',
Tag1_text: '#49A681',
Tag1_bg: '#E2F1EB',
},
displayMode: 'light', // 'light' | 'dark' | 'system'
});
动态切换
入会前或会中均可再次调用 setTheme 更新主题。
MeetingKit支持通过主题配置来自定义界面外观,包括背景色、字体颜色、图标颜色等。
默认主题色 | 自定义主题色 |
|
|
方式一:全局关闭(推荐)
await uiMeetingKit.setFeatureVisible({ enableBgmAudio: false });
方式二:自定义音源与音量
uiMeetingKit.setBgmAudioConfig({
src: 'https://your.cdn/hold-music.mp3',
loop: true,
volume: 0.3,
play: false,
});
主持人在会中通过参会者侧栏 「更多」→「专业会控」 可在新窗口打开专业会控。业务侧需提供与主会中页同源的壳页,并完成下方接入。仅使用侧栏会控时可跳过本节。
meetingControlUrl 在 v4.0.9 及此前已支持;壳页组件 XYMeetingControlHostComp 为 v4.0.10+。
1. createClient 配置壳页地址
await uiMeetingKit.createClient({
clientId: '…',
clientSecret: '…',
extId: '…',
server: 'https://…',
meetingControlUrl: `${window.location.origin}${window.location.pathname}#/host`
});meetingControlUrl 为本应用内的壳页路由,非会控服务 URL。
setTheme 可同步至专业会控窗口。2. 注册壳页路由
import { XYMeetingControlHostComp } from '@xylink/meetingkit';
export function MeetingHostRoute() {
return (
preloadHidden
getDocumentTitle={() => '专业会控'}
iframeTitle="专业会控"
onMissingUrl={() => {
window.location.href = '/';
}}
/>
);
} 壳页无需再次 createClient,须在用户已入会且主会中页已完成初始化的同一浏览器环境中打开。
提示
专业会控在新窗口加载,与会中页不共享内存中的 Client。壳页需调用一次 createClient(可用与主页相同的 clientId / clientSecret / extId,不必入会),否则无法实现换肤。
浏览器限制:远端音频需在用户手势后才能播放。请在已渲染 XYMeetingKitComp 的前提下,于用户触发入会的手势操作中(如点击入会按钮、确认入会弹窗)调用相关音频播放接口,以满足浏览器自动播放策略。
await uiMeetingKit.getClient()?.playAudio();
await uiMeetingKit.makeCall({ confNumber: '…', displayName: '…' });