总览

VanCone Console Component 是为企业Web应用提供统一界面和交互风格的前端组件库，基于 Vue.js、Vite、ElementPlus 进行构建。相比基础组件库，Console Component 定义了一套新的 UI 风格，将基础组件组合成更加复杂的页面组件，并提供了低代码配置能力。

快速开始

安装依赖

# NPM
$ npm i @vancone/console-component --save

# Yarn
$ yarn add @vancone/console-component

加载样式

// main.ts

// 引入组件样式
import "element-plus/dist/index.css";
import '@vancone/console-component/style.css';

主界面

// App.vue
<template>
  <ConsoleApp title="Demo" helpDocUrl="https://docs.vancone.com/demo" />
</template>

<script setup lang="ts">
import { ConsoleApp } from 'vancone-console-component';
</script>

路由

// src/router/index.ts
import { DetailPage, NoPermission, TablePage } from '@vancone/console-component';


export const routes: Array<RouteRecordRaw> = [
  {
    path: '/:model?',
    name: 'ModelTable',
    component: TablePage,
    meta: {
      title: 'User',
      hidden: true,
      activeMenu: '{model}',
    }
  },
  {
    path: '/:model/detail',
    name: 'ModelDetail',
    component: DetailPage,
    meta: {
      title: 'User',
      hidden: true,
      activeMenu: '{model}',
    }
  },
  {
    path: '/no-permission',
    name: 'NoPermission',
    component: NoPermission,
    meta: {
      title: 'No Permission',
      hidden: true,
    }
  },
  ...
]

国际化

首先检查项目中是否已经引入 vue-i18n 依赖，如果没有需要先安装。

# NPM
$ npm i vue-i18n --save

# Yarn
$ yarn add vue-i18n

// src/main.ts
import { i18n } from '@vancone/console-component';
import '~/i18n/index';

app.use(i18n);

// src/i18n/index.ts
import { en, zh } from '@vancone/console-component';

import enJson from './langs/en.json';
import zhJson from './langs/zh.json';

Object.assign(en, enJson);
Object.assign(zh, zhJson);

低代码

// src/main.ts
import '~/config/index';

// src/config/index.ts
import { modelList, menuList, activeMenuMapping } from '@vancone/console-component';

import dataSourceModel from "./models/data-source";
import dataModelModel from "./models/data-model";
import agentModel from "./models/agent";

import assetSvg from '~/assets/svg/asset.svg';
import appSvg from '~/assets/svg/service.svg';

modelList.value = {
    'agent': agentModel,
    'data-asset': dataSourceModel,
    'data-source': dataSourceModel,
};

Object.assign(activeMenuMapping, {
    'data-source': 'data-asset',
    'data-model': 'data-asset',
});

menuList.value = [
    {
        path: '/data-asset',
        title: 'menu.dataAsset.dataAsset',
        icon: assetSvg,
    },
    {
        path: '/data-app',
        title: 'menu.dataService',
        icon: appSvg,
    },
];

基础组件

TableView 表格

基于 Element Plus 的低代码表格组件，支持数据展示、增删改查、导出、打印等功能。

基础用法

<script setup lang="ts">
import { reactive } from 'vue';
import TableView from 'vancone-console-web-component';

const model = reactive<DataModel>({
  api: '/api/data-sources',
  route: 'data-sources',
  tableConfig: {
    editPageRoutePath: '/data-sources/detail',
  },
  fields: [
    {
      prop: 'name',
      label: '数据源名称',
      tableColumn: { link: true }
    },
    {
      prop: 'type',
      label: '类型',
    },
    {
      prop: 'status',
      label: '状态',
    }
  ]
});
</script>

<template>
  <TableView :model="model" />
</template>

下拉列表

表格支持显示下拉字段的 label 值，使用 formItem.select 配置：

const model = reactive<DataModel>({
  api: '/api/data-sources',
  fields: [
    {
      prop: 'type',
      label: '数据源类型',
      formItem: {
        type: 'select',
        select: {
          options: [
            { label: 'MySQL', value: 'mysql' },
            { label: 'PostgreSQL', value: 'postgresql' },
            { label: 'MongoDB', value: 'mongodb' }
          ]
        }
      }
    }
  ]
});

路由跳转

支持两种路由跳转方式：

默认链接跳转

{
  prop: 'name',
  label: '名称',
  tableColumn: { link: true }  // 跳转到 /{route}/detail?id={id}
}

自定义路由跳转

{
  prop: 'name',
  label: '名称',
  tableColumn: {
    routerLink: '/custom/path/{id}'  // {id} 会被替换为实际 ID
  }
}

自定义操作列

const model = reactive<DataModel>({
  api: '/api/users',
  tableConfig: {
    operations: [
      {
        label: 'common.table.view',
        functions: {
          click: (index, row) => {
            console.log('查看', row.id);
          }
        }
      },
      {
        label: '启用',
        functions: {
          click: (index, row) => {
            // 启用操作
          }
        }
      }
    ]
  },
  fields: [...]
});

值转换显示

函数转换

{
  prop: 'status',
  label: '状态',
  tableColumn: {
    functions: {
      transformValue: (value) => {
        return value === 'active' ? '启用' : '禁用';
      }
    }
  }
}

映射转换

{
  prop: 'status',
  label: '状态',
  tableColumn: {
    transformValueMappings: [
      { value: 'active', label: '启用' },
      { value: 'inactive', label: '禁用' }
    ]
  }
}

显示选项配置

通过 tableConfig.display 控制表格显示元素：

const model = reactive<DataModel>({
  api: '/api/data',
  tableConfig: {
    display: {
      pane: false,          // 是否显示白色背景面板
      searchBox: false,    // 是否显示搜索框
      pagination: false,    // 是否显示分页
      advancedSearch: false, // 是否显示高级搜索按钮
      fileTaskButton: false  // 是否显示导入导出按钮
    }
  },
  fields: [...]
});

打印功能

点击工具栏的"打印"按钮，打印选中的行数据：

// 打印时表格会自动生成包含选中数据的 iframe

导出功能

点击导入导出下拉菜单中的"导出查询结果"：

const model = reactive<DataModel>({
  api: '/api/data',
  // 导出请求将发送到 {api}/export
});

只读模式

const model = reactive<DataModel>({
  api: '/api/data',
  tableConfig: {
    readOnly: true  // 隐藏创建、删除、编辑等操作按钮
  },
  fields: [...]
});

选择模式

const model = reactive<DataModel>({
  api: '/api/data',
  tableConfig: {
    selectMode: true  // 显示查看选中项的复选框
  },
  fields: [...]
});

自定义 CRUD 函数

const model = reactive<DataModel>({
  api: '/api/data',
  tableConfig: {
    functions: {
      create: () => {
        // 自定义创建逻辑
        dialogVisible.value = true;
      },
      delete: (index, row) => {
        // 自定义删除逻辑
      },
      batchDelete: (selectedItems) => {
        // 自定义批量删除逻辑
      }
    }
  },
  fields: [...]
});

标签类型

{
  prop: 'category',
  label: '分类',
  tableColumn: { type: 'tag' }  // 使用 el-tag 显示
}

分页配置

支持 [10, 20, 50, 100] 四种分页大小选择。

查询参数

const model = reactive<DataModel>({
  api: '/api/data',
  tableConfig: {
    queryParams: {
      status: 'active',
      type: 'mysql'
    }
  },
  fields: [...]
});

工具提示

const model = reactive<DataModel>({
  api: '/api/data',
  tableConfig: {
    tooltip: 'common.table.dataSourceTooltip'  // 在工具栏显示提示图标
  },
  fields: [...]
});

DataModel 属性

属性	描述	类型
api	查询、修改表格数据的 RESTful 风格 API	`string`
fields	表格的字段定义	`Array<Field>`
route	路由路径，用于生成默认详情页链接	`string`
tableConfig	表格配置	`TableConfig`
formConfig	表单配置	`FormConfig`
pageConfig	页面配置	`PageConfig`

TableConfig 属性

属性	描述	类型	默认值
selectMode	选择模式，显示查看选中项的复选框	`boolean`	false
readOnly	只读模式，隐藏创建、删除等操作按钮	`boolean`	false
creatable	是否显示创建按钮	`boolean`	true
updatable	是否显示编辑按钮	`boolean`	true
deletable	是否显示删除按钮	`boolean`	true
editPageRoutePath	编辑页面路由路径	`string` / `ComputedRef`
createPageRoutePath	创建页面路由路径	`string`
queryParams	额外的查询参数	`IAnyObject`
operations	自定义操作按钮	`Array<IOperationItem>`
labels	自定义按钮标签	`ILabel`
export	是否显示导出功能	`boolean`
tooltip	工具栏提示文本	`string`
functions	自定义 CRUD 函数	`Functions`
display	显示选项配置	`DisplayOptions`

DisplayOptions 属性

属性	描述	类型	默认值
pane	是否显示白色背景面板	`boolean`	true
searchBox	是否显示搜索框	`boolean`	true
pagination	是否显示分页	`boolean`	true
advancedSearch	是否显示高级搜索按钮	`boolean`	false
fileTaskButton	是否显示导入导出按钮	`boolean`	false

Field 属性

属性	描述	类型	默认值
prop	字段对应的 JSON key	`string`
label	表头显示名称，支持 `i18n(key)` 语法	`string`
visible	是否可见	`boolean`	true
value	字段值	`string`
formItem	表单配置	`FormItemConfig`
tableColumn	表格列配置	`TableColumnConfig`

TableColumnConfig 属性

属性	描述	类型	默认值
type	显示类型	`'tag'`
visible	在表格列中是否可见	`boolean`	true
link	是否为默认链接跳转	`boolean`	false
routerLink	自定义路由链接模板，`{id}` 会被替换	`string`
width	列宽度	`number`
transformValueMappings	值映射转换	`Array<{ value, label }>`
functions	自定义函数	`{ transformValue?: (value) => string }`

FormItemConfig 属性

属性	描述	类型	默认值
visible	在表单中是否可见	`boolean`	true
type	表单项类型	`'input' \\| 'select' \\| 'checkbox' \\| 'date' \\| ...`
placeholder	占位符文本	`string`
select	下拉框配置	`SelectConfig`
inputNumber	数字输入框配置	`InputNumberConfig`
required	是否必填	`boolean`
validationRule	验证规则	`Array<any>`
defaultValue	默认值	`any`
editable	是否可编辑（创建时）	`boolean`
updatable	是否可更新（编辑时）	`boolean`

SelectConfig 属性

属性	描述	类型
options	静态选项列表	`Array<{ label, value }>`
api	动态选项接口	`string`
queryParamName	查询参数名	`string`
queryParamValueField	查询参数值字段	`string`
labelMappingField	label 映射字段	`string`
valueMappingField	value 映射字段	`string`
viewModeLabelField	表格视图显示 label 的字段	`string`
allowCreate	是否允许创建新选项	`boolean`
useDatableDict	是否使用数据字典	`boolean`
dictId	数据字典 ID	`string`
multiple	是否多选	`boolean`

IOperationItem 属性

属性	描述	类型
label	按钮标签	`string` / `ComputedRef`
icon	按钮图标	`string`
functions	按钮函数	`{ transformLabel?, click? }`

ILabel 属性

属性	描述	类型	默认值
create	创建按钮自定义标签	`string`
delete	删除按钮自定义标签	`string`

组件暴露方法

方法	描述
refresh()	刷新表格数据
multipleSelection	当前选中的行数据
updateConfigAndRefresh	更新配置并刷新（已废弃）

TabCard 选项卡

TabCard 组件的作用与常见的 Tab 组件类似，主要用于页面中不同分类的数据表格的切换显示，支持展示不同分类的总数统计，需要搭配 Table 组件一起使用。

基础用法

<template>
  <TabCard :cards="cards" :tableRef="tableRef"/>
  <TableView ref="tableRef" :config="tableConfig" />
</template>

<script setup lang="ts">
import { computed, onMounted, reactive, ref } from "vue";
import { countData } from "~/api";
import TableView, { ITableConfig } from "~/components/common/TableView.vue";
import TabCard, { ICardConfig } from "~/components/common/TabCard.vue";

const tableRef = ref();

const firstTableConfig = reactive<ITableConfig>({
  // 此处省略 Table 配置
});

const secondTableConfig = reactive<ITableConfig>({
  // 此处省略 Table 配置
});

const tableConfig = reactive<ITableConfig>({...firstTableConfig});

const cards = reactive<Array<ICardConfig>>([
  {
    key: 'first',
    label: 'menu.first',
    icon: 'first-icon',
    tableConfig: firstTableConfig,
  },
  {
    key: 'second',
    label: 'menu.second',
    icon: 'second-icon',
    tableConfig: secondTableConfig,
  },
]);

onMounted(() => {
  countData().then(({ data }) => {
    let resultSet = data.data;
    for (var index in cards) {
      cards[index].count = resultSet[cards[index].key] ?? undefined;
    }
  })
})
</script>

TabCard 属性

属性	描述	类型	默认值
disable	是否禁用卡片	`boolean`	false
icon	卡片矢量图标名称，存放于 src/assets/svg 目录	`string`
key	卡片唯一标识符	`string`
label	卡片标题	`string`
tableConfig	点击卡片时要展示的表格配置	`ITableConfig`

Header 组件构成了应用界面顶部的标题栏，显示应用名称，为用户提供应用目录、消息中心、控制台入口、用户中心等功能。

Header组件

应用目录：为用户展示 VanCone 生态系统中的所有应用，方便用户快速跳转所需的应用。

消息中心：建设中。

用户菜单：组件最右侧展示用户头像，如果用户尚未设置头像，则会显示用户昵称的前两个字符。用户将光标悬停在头像上，将展示悬浮菜单，可以跳转用户中心、切换语言和退出登录。

基础用法

<template>
  <Header title="Example" helpDocUrl="https://vancone.com/" />
</template>

<script setup lang="ts">
import { Header } from '@vancone/console-component';
</script>

组件属性

属性	描述	类型	默认值
title	应用标题	`string`
helpDocUrl	帮助文档链接	`string`

低代码配置

Header 组件不支持低代码配置。

SvgIcon 图标

SvgIcon 用于加载 SVG 图标，会根据 name 字段的值去寻找项目中的 src/assets/svg 目录下的同名 SVG 文件。

基础用法

<template>
  <SvgIcon name="menu-grey" />
</template>

<script setup lang="ts">
import SvgIcon from '~/components/common/SvgIcon.vue';
</script>