跳到主要内容
新版 Web IMKit SDKWeb IMKit SDK 从 5.36.0 版本开始升级了 UI 和 SDK 结构。如果您集成的版本低于 5.36.0，请参考旧版 Web IMKit 文档。

输入菜单

Web IMKit 输入组件内置了基础输入菜单，除了发送文本消息外，还可以通过菜单触发表情、图片、文件、拍照等能力。

当前 SDK 默认未内置语音消息、小视频消息等入口。如果业务需要，可以通过自定义输入菜单扩展这些能力，并在点击事件中接入自己的上传、预览或发送流程。

提示

Web IMKit 目前有以下限制：

  • 图片、文件大小上限为 100 MB。
  • GIF 文件大小上限为 2 MB。超出限制后，GIF 文件将作为普通文件消息发送。
  • 支持发送时长不超过 2 分钟的小视频。

默认菜单​

每个菜单项都有一个独立的 ID 标识，通过 RCKitInputMenuID 枚举定义。同时，每个菜单项通过 order 属性计算在输入组件中的布局位置。

当前默认输入菜单使用了 4 个内置菜单 ID：

菜单 IDorder功能说明
RCKitInputMenuID.EMOJI0打开表情面板。
RCKitInputMenuID.IMAGES1选择本地图片以发送图片消息。最多可同时选择 100 张图片，且单张图片要求不超过 100 MB。
RCKitInputMenuID.FILES2选择本地文件并发送。最多可同时选择 100 个文件，每个文件要求不超过 100 MB。
注意：被选中的文件会根据文件类型分别以不同类型消息进行发送。
RCKitInputMenuID.PHOTO3启动默认摄像头并拍摄，并将照片以图片消息发送。暂不支持指定摄像头。

其中 PHOTO 菜单仅在以下条件下显示：

  • 当前页面运行在 https:、file: 或 localhost 环境
  • 当前设备不是移动端

输入菜单配置​

通过 setInputMenu() 可以整体替换输入菜单配置；通过 cloneInputMenu() 可以先读取当前菜单，再基于现有配置进行调整。

请在 ready() 前完成输入菜单配置。

当前菜单配置类型如下：

typescript
import type { IRCKitInputMenu, IRCKitInputMenuItem } from '@rongcloud/im-kit';

const menu: IRCKitInputMenu = {
  items: [],
};

每个菜单项 IRCKitInputMenuItem 支持以下字段：

  • id：菜单项唯一 ID，同时也会作为多语言文案 Key 使用
  • order：排序值，值越小越靠前
  • icon：菜单图标
  • hoverIcon：鼠标悬停时的图标，可选
  • filter：菜单显示过滤函数，可选
  • submenu：二级菜单项列表，可选

自定义输入菜单​

推荐做法是先通过 cloneInputMenu() 获取默认菜单，再保留需要复用的内置项，最后通过 setInputMenu() 设置新的菜单结构。

下面示例演示：

  • 保留默认 EMOJI
  • 新增一个自定义一级菜单
  • 将其他默认菜单项收纳到该菜单的二级菜单中
  • 额外增加一个“发送视频”的自定义二级菜单项
typescript
import {
  RCKitEvents,
  RCKitInputMenuID,
  type IRCKitInputMenu,
} from '@rongcloud/im-kit';

const defaultMenu = kitApp.cloneInputMenu();
const menu: IRCKitInputMenu = { items: [] };

const emojiItem = defaultMenu.items.find(item => item.id === RCKitInputMenuID.EMOJI);
const otherItems = defaultMenu.items.filter(item => item.id !== RCKitInputMenuID.EMOJI);

if (emojiItem) {
  menu.items.push(emojiItem);
}

menu.items.push({
  id: 'input.menu.item.more',
  icon: '/icons/more.svg',
  order: 1,
  submenu: [
    ...otherItems,
    {
      id: 'input.menu.item.video',
      icon: '/icons/video.svg',
      order: 100,
    },
  ],
});

kitApp.setInputMenu(menu);

kitApp.addEventListener(RCKitEvents.INPUT_MENU_ITEM_CLICK, (evt) => {
  if (evt.data.id === 'input.menu.item.video') {
    // 这里接入业务自己的视频选择、上传或发送逻辑
  }
});

自定义菜单文案​

自定义菜单的文案不是直接配置在菜单项里的，而是通过菜单项 id 从语言包中读取。

因此，为了让自定义菜单显示正确的文字，需要为对应 id 注册多语言文案：

typescript
const zh = kitApp.cloneLanguageEntries('zh_CN')!;
zh['input.menu.item.more'] = '更多';
zh['input.menu.item.video'] = '发送视频';
kitApp.registerLanguagePack('zh_CN', zh);

如果你的应用支持英文、繁体中文等其他语言，也需要同步注册对应语言包。

二级菜单说明​

当菜单项存在 submenu 且 submenu.length > 0 时，点击该菜单项不会直接执行动作，而是会打开一个二级菜单。

二级菜单中的菜单项仍然遵循同样的配置规则：

  • 内置菜单 ID 仍由 SDK 处理，例如 IMAGES、FILES
  • 自定义菜单 ID 会派发 RCKitEvents.INPUT_MENU_ITEM_CLICK 事件，由业务自行处理

使用建议​

  • 如果只是调整默认菜单顺序，直接修改 cloneInputMenu() 返回结果中的 order 即可
  • 如果希望把多个能力收纳到同一个入口下，可以使用 submenu
  • 如果某个菜单只应在特定会话中显示，可以使用 filter
  • 如果要扩展视频、卡片、业务表单等能力，建议使用自定义菜单 ID，并在事件监听中完成后续处理
最后于 更新