AI 组件库-MateChat 组件大全与主题定制

MateChat 组件大全与主题定制

一、组件概览

MateChat 的组件可以按"页面结构-消息渲染-交互输入-辅助扩展"四层来理解：

层	代表组件	作用	典型 Props / Slot
布局层	McLayout, McHeader, McLayoutContent, McLayoutSender	搭出「顶栏-内容-输入栏」三段式骨架	title, logoImg, slot operationArea 等
会话层	McBubble, McList, McMarkDown	把模型 / 用户输出以气泡、列表或富文本卡片形式呈现	content, align, avatarConfig, loading
输入层	McInput, McPrompt, McMention	文本录入、快捷提问、@-引用	maxLength, placeholder, @submitlist, direction, @itemClick 等
引导层	McIntroduction	欢迎 / 空态页	logoImg, title, subTitle, description, align, background

命名规律 ：所有组件均以 Mc 前缀开头（MateChat 缩写），便于与业务自有组件区分。

二、核心组件

1. Layout

用于对不同的模块进行排列布局

1.1. 引入

typescript 复制代码

import { McLayoutAside, McLayoutContent, McLayoutHeader, McLayout, McLayoutSender } from '@matechat/core';

1.2. 组件对象

McLayout
McLayoutContent
McLayoutSender
McLayoutAside
McLayoutHeader

提供「顶栏-内容-输入栏」三段式布局

Tips：McLayoutContent 自带 100% 高度，与 McLayoutSender 互不干涉，可放心让消息区滚动。

1.3. Demo

vue 复制代码

<template>
  <McLayout>
    <McLayoutHeader>
      <McHeader :logoImg="'/logo.svg'" :title="'MateChat'"></McHeader>
    </McLayoutHeader>
    <McLayoutContent style="margin: 16px 0;">
      <McBubble content="Hello MateChat" align="right"></McBubble>
      <McBubble content="Hello, what can I do for you?"></McBubble>
    </McLayoutContent>
    <McLayoutSender>
      <McInput :value="inputValue" :maxLength="2000" showCount></McInput>
    </McLayoutSender>
  </McLayout>
</template>

<script setup>
import { ref } from 'vue';

const msg = ref('组件demo');
const inputValue = ref('');
</script>

2. Bubble

用于承载对话内容的气泡组件

2.1. 引入

typescript 复制代码

import { McBubble } from '@matechat/core';

2.2. 参数

参数名	类型	默认值	说明
content	`string`	''	气泡显示内容
loading	`boolean`	false	是否显示 loading 态，显示 loading 时其他区域将不会显示
align	BubbleAlign + 'left' + 'right'	'left'	气泡对齐方式
avatarPosition	AvatarPosition + 'top' + 'side'	'side'	头像位置
variant	BubbleVariant + 'filled' + 'none' + 'bordered'	'filled'	气泡样式
avatarConfig	BubbleAvatar	--	头像配置

typescript 复制代码

interface BubbleAvatar {
  name?: string; // 头像内显示的名字
  gender?: 'male' | 'female'; // 根据性别头像背景色会有所不同
  width?: number; // 头像宽度
  height?: number; // 头像高度
  isRound?: boolean; // 是否是圆形头像
  imgSrc?: string; // 头像显示图片，imgSrc 优先级比 name 高
  displayName?: string; // 头像旁显示的名字，该属性仅当头像位于气泡上方时生效，如果希望当头像位于侧边时生效，我们推荐你通过 top 插槽来放置相关信息
}

2.3. Demo

vue 复制代码

<template>
  <McBubble :content="'Hello MateChat'" :avatarConfig="{ imgSrc: '/logo.svg' }">
    <template #top>
      <div class="bubble-top-area">
        <span>MateChat</span>
      </div>
    </template>
    <template #bottom>
      <div class="bubble-bottom-area">
        <i class="icon icon-copy-new"></i>
        <i class="icon icon-like"></i>
        <i class="icon icon-dislike"></i>
      </div>
    </template>
  </McBubble>
</template>

3. Prompt

用于展示一组预定义的问题或建议

3.1. 引入

typescript 复制代码

import { McPrompt } from '@matechat/core';

3.2. 参数

参数名	类型	默认值	说明
direction	ListDirection + vertical + horizontal	'vertical'	排列方式，水平或垂直
list	Prompt[]	[]	提示列表
variant	ListVariant + 'transparent' + 'filled' + 'bordered' + 'none'	'filled'	提示样式

typescript 复制代码

interface Prompt {
  value: string | number;
  label: string;
  iconConfig?: IconConfig;
  desc?: string;
}

interface IconConfig {
  name: string;
  size?: string;
  color?: string;
  component?: Component; // 支持传入自定义 vue 组件
}

3.3. Demo

vue 复制代码

<template>
  <div class="demo-container">
    <McPrompt :list="promptData"></McPrompt>
    <McPrompt :list="promptData" :direction="'horizontal'"></McPrompt>
  </div>
</template>

<script setup>
const promptData = [
  {
    value: 'quickSort',
    label: '帮我写一个快速排序',
    iconConfig: { name: 'icon-info-o', color: '#5e7ce0' },
    desc: '使用 js 实现一个快速排序',
  },
  {
    value: 'helpMd',
    label: '你可以帮我做些什么？',
    iconConfig: { name: 'icon-star', color: 'rgb(255, 215, 0)' },
    desc: '了解当前大模型可以帮你做的事',
  },
];
</script>

<style scoped lang="scss">
.demo-container {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
</style>

4. Input

用于对话的输入框组件

4.1. 引入

typescript 复制代码

import { McInput } from '@matechat/core';

4.2. 参数

| 参数名 | 类型 | 默认值 | 说明 |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|----------------------------|-----------------------|
| value | string | '' | 输入框的值 |
| placeholder | string | -- | 输入框占位文字 |
| disabled | boolean | false | 是否禁用输入框 |
| displayType | DisplayType + 'simple' + 'full' | 'full' | 输入框的形态 |
| loading | boolean | false | 是否发送中，为 true 时，点击发送按钮可暂停回答 |
| showCount | boolean | false | 是否显示字数统计 |
| maxLength | number | -- | 输入框的最大字数 |
| submitShortKey | SubmitShortKey ` | null` + 'shiftEnter' + 'enter' | 'enter' | 发送快捷键，null 表示不使用快捷键发送 |
| variant | InputVariant + 'bordered' + 'borderless' | 'bordered' | 输入框的形态 |
| sendBtnVariant | SendBtnVariant + 'simple' + 'full' | 'full' | 发送按钮的形态 |

4.3. Demo

vue 复制代码

<template>
  <McInput :value="inputValue" :maxLength="2000" :loading="loading" showCount @change="onInputChange" @submit="onSubmit" @cancel="onCancel">
  </McInput>
</template>

<script setup>
import { defineComponent, ref } from 'vue';

const inputValue = ref('');
const loading = ref(false);

const onInputChange = (e) => {
  console.log('input change---', e);
};
const onSubmit = (e) => {
  loading.value = true;
  console.log('input submit---', e);
};
const onCancel = () => {
  loading.value = false;
  console.log('input cancel');
};
</script>

5. MarkDown 卡片

用于显示 MarkDown 内容的卡片组件

5.1. 引入

typescript 复制代码

import { McMarkdownCard } from '@matechat/core';

5.2. 参数

参数名	类型	默认值	说明
content	`string`	''	MarkDown文本
theme	Theme + 'light' + 'dark'	'light'	MarkDown卡片主题
mdOptions	`object`	{}	设置 markdown 对字符串的处理方式，可参考markdown-it
mdPlugins	MdPlugin[]	[]	设置 markdown-it 插件
customXssRules	CustomXssRule[]	[]	自定义 xss 对某种 tag 的过滤方式，每条规则需要指定 tag, 并给出需要加入白名单的属性数组
enableThink	`boolean`	false	是否开启标签识别
thinkOptions	ThinkOptions	--	标签配置，自定义样式等
typing	`boolean`	false	开启打字机效果
typingOptions	TypingOptions	`{ step: 2, interval: 50, style: 'normal' }`	打字机效果配置

5.3. Demo

vue 复制代码

<template>
  <McMarkdownCard :content="content" :theme="theme"></McMarkdownCard>
</template>
<script setup>
import { ref, onMounted } from 'vue';
let themeService;
const theme = ref('light');
const content = ref(`
# 快速排序（Quick Sort）

### 介绍`)

三、按需引入与 Tree-Shaking

MateChat 本身提供 完整注册 与 按需引入 两种方式：

typescript 复制代码

// 方式一：一次性全局引入
import MateChat from '@matechat/core';
app.use(MateChat);

// 方式二：仅引入所需
import { McBubble, McInput } from '@matechat/core';
app.component('McBubble', McBubble);
app.component('McInput',  McInput);

推荐在生产环境使用方式二，配合 Vite + ESBuild 的 Tree-Shaking，可显著减小最终 bundle。

四、主题定制三步曲

MateChat 内置 DevUI 6.x 的主题系统，所有颜色、圆角、阴影都映射到 CSS 变量，默认提供 亮色 / 暗色 两套。你可以：

1. 选择内置暗色

typescript 复制代码

import 'vue-devui/style/theme/dark.css'

2. 覆盖单个变量（推荐）

css 复制代码

:root {
  --devui-brand:        #ff5722;  // 主品牌色
  --devui-primary-bg:   #fff7f5;  // 气泡背景
  --mc-bubble-radius:   12px;     // 自定义气泡圆角
}

3. 完全自定义主题文件

复制官方 light.css 为 my-brand.css
修改变量后全局引入
可按需切换：document.documentElement.setAttribute('data-theme','my-brand')

只要保持变量名不变，MateChat 的所有组件都会即时响应，无需额外配置。

五、实战建议

需求	官方推荐
长对话滚动性能	给 McLayoutContent 加 virtual-scroll（由业务实现），或在 500+ 条时裁剪历史
代码高亮洞察	在 McMarkDown 内部注入 highlight.js 自动扫描
多会话	用 Pinia/Zustand 保存多组 messages，每组挂一个 McLayout
"发送中" 动画	先 push loading:true 的空气泡，流式响应到达后再填充 content

六、总结

MateChat 组件层面 已经覆盖了 AI 聊天基本的 "布局-消息-输入-快捷操作-欢迎页" 闭环；
主题系统 继承 DevUI，改变量即可一键换肤；
官方还在演进 McMarkdown 富文档卡片 、文件/图片上传 等组件。