ChannelSwitcher 频道切换器

Web IMKit 的超级群频道切换器：横向 chip 列表展示「群级消息 + 频道」，支持选中、创建、加入、离开；可直接使用，也可由 ChatView 通过 showChannelSwitcher 自动挂载。

运行时组件（非 IDL 契约）

本组件由 SDK 运行时直接提供，不是 IDL 契约组件：IMKit 契约（sdk-imkit）只声明 10 个契约组件（ConversationListView / ChatView / MessageBubble / MessageInput / Avatar / UnreadBadge / TimeSeparator / MessageStatusIndicator / Theme / IMKitFacade），不包含当前版本频道 UI 组件；因此下面的 props/事件以各端实际实现为准，跨端命名不保证一致。

导入与最小示例​

JavaScript
import { ChannelSwitcher, Theme } from '@ni-paas/im-web-kit';
import { createClient, ConversationType } from '@ni-paas/im-web';

const client = createClient({ appkey, serverUrl });
await client.connect(token);
const listed = await client.listSupergroupChannels('g_1001');

const switcher = new ChannelSwitcher({
  channels: listed.data.channels,      // SupergroupChannel[]
  channelId: 'ch_news',                // 空串 = 群级消息
  groupId: 'g_1001',
  currentUserId: me,
  locale: 'zh-CN',
  theme: new Theme({ mode: "dark" }),
  showGroupLevel: true,
  allowCreate: true,
  allowJoin: true,
  allowLeave: true,
  onSelect: (channelId) => chatView.update({ channelId }),
});
switcher.mount(document.getElementById("channels"));

Props​

Prop类型默认说明
channelsSupergroupChannel[][]频道数组（宿主用 listSupergroupChannels 拉取；private 频道已由服务端按可见性过滤）
channelIdstring''当前频道；空串/缺省 = 群级消息
groupIdstring''超级群 ID（create 事件 payload 用）
currentUserIdstring''用于判断「已加入」（也可由 channel.joined / userIds 推导）
locale'zh-CN' | 'en''zh-CN'组件内文案语言
themeTheme | nullnull传入后应用 9 个 token；深色由 Theme 设置 data-imkit-theme
showGroupLevelbooleantrue是否显示「群级消息」chip
allowCreate / allowJoin / allowLeavebooleantrue是否显示创建/加入/退出操作
onSelect / onCreate / onJoin / onLeavefunctionnull与同名事件等价的回调

事件​

事件载荷触发
select{ channelId, channel }点击频道 chip 或「群级消息」；channel=null 表示群级
create{ groupId }点击「+ 新建频道」（不内置表单，由宿主创建后更新 channels）
join{ channelId, channel }点击未加入频道的「加入」
leave{ channelId, channel }点击已加入频道的「退出」

主题 token（9 个）​

Token用途
--imkit-background容器背景
--imkit-surfacechip / 计数徽标 / 按钮背景
--imkit-text主文本；深色下选中 chip 文本
--imkit-text-secondary标题、计数、空态
--imkit-primary创建按钮、选中边框、join 按钮
--imkit-mention创建按钮 hover
--imkit-bubble-mine选中 chip 背景
--imkit-bubble-other选中 chip 文本（浅色）
--imkit-dangerprivate 类型标识、退出按钮

ChatView 集成​

JavaScript
new ChatView({
  lib: client,
  conversationType: ConversationType.SUPER_GROUP,
  targetId: 'g_1001',
  channelId: 'ch_news',
  showChannelSwitcher: true,   // 在消息流顶部挂载 ChannelSwitcher
  showChannelCreate: true,
  showChannelJoin: true,
  showChannelLeave: true,
  channels: listed.data.channels,
  groupId: 'g_1001',
});

ChatView 会把 channels/channelId/groupId/currentUserId/locale/theme 投影给内部的 ChannelSwitcher；默认 showChannelSwitcher=false，不改变既有布局。

无障碍与测试​

  • 容器 role="region" + aria-label；chip 容器 role="tablist"，chip 为 role="tab" 且带 aria-selected。
  • 稳定钩子：data-channel-switcher、data-channel-id、data-channel-type、data-channel-selected、data-channel-action（select/create/join/leave）、data-channel-members；ChatView 挂载时 #chat-channel-switcher。
  • 本地化：locale=en* 切换英文文案（Channels/Group messages/Join/Leave…）。

限制​

  • 创建频道不内置表单：create 只发事件，宿主负责调用 createSupergroupChannel 并刷新 channels。
  • 不提供频道成员管理（成员增删用 Server API）。
  • 频道级未读/回执未拆分；切换频道后未读仍按群会话统计。

相关链接​