x-sccba

x-sccba — Vue 3 使用指南

基于 Element Plus 的增强组件库，提供丰富的业务组件与 AI 交互组件，完整支持 Vue 3 + Composition API。

目录

• 环境要求
• 安装依赖
• 快速上手
• 按需引入
• 组件列表
• Hooks
• ConfigProvider
• XEditor 富文本编辑器依赖
• 常见问题

环境要求

安装依赖

# 安装 Element Plus（必须，peerDependency 由使用者提供）
npm install element-plus

# 安装 Element Plus 图标（必须，peerDependency 由使用者提供）
npm install @element-plus/icons-vue

# 安装 x-sccba
npm install x-sccba

快速上手

main.ts

import { createApp } from 'vue';
import App from './App.vue';

// 1. 引入 Element Plus
import ElementPlus from 'element-plus';
import * as ElementPlusNS from 'element-plus';
import 'element-plus/dist/index.css';

// 2. 引入 x-sccba
import ElementPlusX from 'x-sccba';

const app = createApp(App);

// 3. 先注册 Element Plus
app.use(ElementPlus);

// 4. 再注册 x-sccba，并通过 { ui } 传入命名空间对象
//    注意：必须使用 import * as 的命名空间导入，不能传 default 导出
app.use(ElementPlusX, { ui: ElementPlusNS });

app.mount('#app');

为什么要传 ElementPlusNS？ x-sccba 内部通过 ui 对象按组件名动态查找 ElButton、ElInput 等， 必须传入含所有 El* 导出的命名空间对象（import * as）， 而非仅有 install/version 的 default 导出。

在组件中使用

<template>
  <XButton type="primary">点击</XButton>
  <XInput v-model="value" placeholder="请输入" />
  <XSender v-model="text" @submit="handleSubmit" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('');
const text = ref('');

function handleSubmit(val: string) {
  console.log('发送:', val);
}
</script>

按需引入

不使用全局注册，可直接按需导入组件：

import { XButton, XInput, XSender, XBubble } from 'x-sccba';

使用前仍需在入口文件完成 app.use(ElementPlusX, { ui: ElementPlusNS }) 注册， 以确保内部 UI 组件查找链正常工作。

组件列表

基础组件（Element Plus 增强封装）

数据展示

导航

反馈

布局

其他

AI 交互组件（x-sccba 特色）

业务组件

Hooks

所有 Hook 均可从 x-sccba 直接导入：

import {
  useMessage,
  useMessageBox,
  useNotification,
  useLoading,
  useLocale,
  useForwardProps,
  useOmitForwardProps
} from 'x-sccba';

useMessage

封装 ElMessage，统一默认配置：

const { message } = useMessage({ duration: 3000, showClose: true });

message.success('操作成功');
message.error('操作失败');
message.warning('警告');
message.info('提示');
message.closeAll();

useMessageBox

封装 ElMessageBox：

const { alert, confirm, prompt, close } = useMessageBox({
  confirmButtonText: '确定',
  cancelButtonText: '取消'
});

confirm('确定删除吗？')
  .then(() => {
    // 用户点击确定
  })
  .catch(() => {
    // 用户取消
  });

const { value } = await prompt('请输入名称', '新建');

useNotification

封装 ElNotification：

const { notification } = useNotification({
  duration: 4500,
  position: 'top-right'
});

notification.success('操作成功');
notification.error({ title: '错误', message: '详细信息' });
notification.closeAll();

useLoading

封装 ElLoading：

const { open, closeAll } = useLoading({
  text: '加载中...',
  background: 'rgba(0,0,0,0.7)'
});

const instance = open();
// 完成后关闭
instance.close();

// 或关闭全部
closeAll();

useLocale

获取当前国际化上下文（与 Element Plus locale 系统联动）：

const { t, lang } = useLocale();
console.log(lang.value); // 'zh-cn'
console.log(t('button.submit'));

useForwardProps / useOmitForwardProps

在封装组件时，精确转发父组件实际传入的 props，避免 Vue3 布尔值类型强制转换问题：

// 只转发父级实际传入的 props
const forwarded = useForwardProps(props);

// 转发时排除某些 props
const forwarded = useOmitForwardProps(props, [
  'modelValue',
  'onUpdate:modelValue'
]);

ConfigProvider

用于配置全局 Markdown 解析选项（自定义 markdown-it 实例或插件）：

<template>
  <ConfigProvider :md="customMd" :md-plugins="extraPlugins">
    <App />
  </ConfigProvider>
</template>

<script setup lang="ts">
import MarkdownIt from 'markdown-it';

const customMd = new MarkdownIt({ html: true, linkify: true });
const extraPlugins = [
  /* markdown-it 插件 */
];
</script>

XEditor 富文本编辑器依赖

XEditor 基于 Tiptap 构建，相关依赖以 optional peer 方式暴露，仅在 Vue3 项目使用 XEditor 时按需安装：

pnpm add @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/vue-3 \
  @tiptap/extension-underline @tiptap/extension-subscript @tiptap/extension-superscript \
  @tiptap/extension-link @tiptap/extension-image @tiptap/extension-text-align \
  @tiptap/extension-text-style @tiptap/extension-color @tiptap/extension-font-family \
  @tiptap/extension-table @tiptap/extension-table-row @tiptap/extension-table-cell \
  @tiptap/extension-table-header @tiptap/extension-placeholder \
  @tiptap/extension-character-count @tiptap/extension-task-list \
  @tiptap/extension-task-item @tiptap/extension-dropcursor dompurify

最简使用：

<template>
  <XEditor v-model="content" output="html" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const content = ref('');
</script>

XEditor 属性

常见问题

Q: 报错 [x-sccba] UI framework not provided

确认 app.use(ElementPlusX, { ui: ElementPlusNS }) 中 ui 使用的是 import * as ElementPlusNS from 'element-plus' 的命名空间导入，而不是 import ElementPlusNS from 'element-plus'。

Q: 组件样式缺失

确认已在入口引入 Element Plus 样式：

import 'element-plus/dist/index.css';

Q: TypeScript 类型提示缺失

确认 tsconfig.json 中包含 node_modules/x-sccba/types/index.d.ts，或添加：

{
  "compilerOptions": {
    "types": ["x-sccba"]
  }
}