自定义组件

Web IMKit 允许你覆盖部分公开组件，以定制消息、输入框预览等 UI。本文介绍可覆盖组件范围、registerCustomElement 的调用方式，以及 5.42.0 起需要注意的 setup 入参变化。

组件分类

为了兼顾稳定性和定制能力，Web IMKit 将内部组件分为 Provider 组件和 Component 组件。

Component 组件为无状态组件，仅负责 UI 渲染，不负责数据管理。此类组件通过接收 props 外部输入以驱动 UI 渲染更新，但无法修改 props 数据本身。

Provider 组件为业务容器组件，内部包含响应式数据管理、交互事件分发等逻辑。此类组件是 SDK 内部实现的一部分，标签名通常以 -provider 结尾。

Web IMKit 仅允许覆盖公开的 Component 组件，用以深度定制开发。

5.42.0 破坏性变更 / 升级注意事项

• registerCustomElement 的 setup 入参从 { value: props } 调整为直接接收 props。已覆盖组件的业务需要将 props.value.xxx 更新为 props.xxx。
• HQ 语音消息组件 props 新增 position 字段。已覆盖该组件的业务建议适配该字段。
• 仅建议覆盖本文列出的公开可复写组件，不要依赖 Web IMKit 内部未公开组件名、Provider 或内部 props 结构。

registerCustomElement

Web IMKit 提供 registerCustomElement 接口，用于注册自定义组件并覆盖 SDK 内置组件。

提示

• 该接口仅限 ready 调用前有效。
• 由于自定义组件注册相对复杂，建议使用 TypeScript 进行业务开发，以获取更好的 IDE 语法提示支持和类型推导。
• Web IMKit 内部使用 Vue 作为 DOM 组件渲染引擎，因此自定义组件模板语法与 Vue 模板语法一致。

为了保障 Web IMKit 迭代升级过程中的兼容性，Web IMKit 仅允许覆盖部分公开组件。

当前版本开放以下组件供业务层覆盖：

组件	标签	说明
RCKitOverrideAbleComponent.HQVoiceMessageComponent	rc-hq-voice-message	HQ 语音消息组件。
RCKitOverrideAbleComponent.ReplyPreviewBarComponent	rc-reply-preview-bar	输入框回复预览栏组件。

参数说明

参数	类型	是否必传	说明
tag	RCKitOverrideAbleComponent	是	需要重写的组件标识，为 RCKitOverrideAbleComponent 枚举值。
options	IRCKitDefineCustomElementOptions	是	组件配置。

IRCKitDefineCustomElementOptions 说明

属性	类型	是否必传	说明
template	string	是	组件模板，模板语法使用 Vue 组件模板语法。
setup	(props: T, ctx: IRCKitComponentContext) => any	是	组件逻辑处理函数，props 为当前组件直接接收的属性对象。
styles	string[]	否	组件样式表。

setup 入参升级说明

5.42.0 起，setup 入参直接接收组件 props，不再包装在 value 字段中。升级时，请按以下规则调整：

TypeScript

// 旧写法
setup(props) {
  const value = props.value;
}

// 新写法
setup(props) {
  const value = props;
}

如果业务代码中仍使用 props.value.xxx 读取属性，需要改为 props.xxx。

代码示例

TypeScript

// 重写语音消息组件
kitApp.registerCustomElement(
  RCKitOverrideAbleComponent.HQVoiceMessageComponent,
  {
    setup(props, ctx) {
      return {
        value: props,
        position: props.position,
      };
    },
    template: `<button @click="value.toggle()">{{ value.playing ? '暂停' : '播放' }}</button><br/>
    playing: {{ value.playing }}<br/>
    progress: {{ value.progress }} / 100<br/>
    duration: {{ value.duration }}s<br/>
    position: {{ position }}<br/>`,
  }
);

回复预览栏组件

从 5.42.0 开始，Web IMKit 支持通过 RCKitOverrideAbleComponent.ReplyPreviewBarComponent 覆盖输入框中的回复预览栏。

IRCKitReplyPreviewBarComponentProps 包含以下字段：

字段	类型	说明
message	IRCKitCachedMessage	被回复的消息。
username	string	被回复消息的发送者名称。
previewText	string	回复预览文案。
thumbnail	string	预览缩略图地址，可选。
cancel	Function	取消当前回复状态的方法。

代码示例

TypeScript

kitApp.registerCustomElement(
  RCKitOverrideAbleComponent.ReplyPreviewBarComponent,
  {
    setup(props) {
      const onCancel = () => {
        props.cancel();
      };

      return {
        message: props.message,
        username: props.username,
        previewText: props.previewText,
        thumbnail: props.thumbnail,
        onCancel,
      };
    },
    template: `
    <div class="reply-preview-bar">
      <img v-if="thumbnail" :src="thumbnail" />
      <span>{{ username }}：{{ previewText }}</span>
      <button @click="onCancel">取消</button>
    </div>
  `,
  }
);

复用既有组件

Web IMKit 允许你在 template 模板中通过 <rc-origin> 标签复用被覆盖组件的原始实现。

代码示例

TypeScript

// 重写语音消息组件
kitApp.registerCustomElement(
  RCKitOverrideAbleComponent.HQVoiceMessageComponent,
  {
    setup(props, ctx) {
      const onClick = () => {
        console.log('点击了自定义测试按钮');
      };
      return { value: props, onClick };
    },
    // template 中通过 <rc-origin> 复用原组件。注意传递 value 属性。
    template: `
    <rc-origin :value="value"></rc-origin>
    <br/>
    <button @click="onClick">测试</button><br/>
  `,
  }
);