itms-bi-components

v1.0.1

Published

2 months ago

XCMG ITMS BI Components

0High
0Medium
0Low

lawlight08

ITMS BI Components

XCMG ITMS BI 图表组件库，基于 Vue 3 + TypeScript + ECharts 构建的轻量级 BI 图表组件库。

特性

🚀 Vue 3 + TypeScript - 完整的类型支持
📦 按需引入 - 支持 tree-shaking
🎨 可定制主题 - 支持自定义颜色、尺寸等
📊 异步数据 - 支持直接传数据和异步请求
💅 SCSS Modules - 样式隔离，不影响全局
🔄 数据分页 - 柱状图支持数据分页展示
🌐 国际化 - 内置中英文，支持自定义语言包

安装

# npm
npm install itms-bi-components echarts vue-echarts element-plus plus-pro-components @element-plus/icons-vue sortablejs xlsx

# pnpm
pnpm add itms-bi-components echarts vue-echarts element-plus plus-pro-components @element-plus/icons-vue sortablejs xlsx

# yarn
yarn add itms-bi-components echarts vue-echarts element-plus plus-pro-components @element-plus/icons-vue sortablejs xlsx

依赖说明

本组件库依赖以下第三方库：

| 依赖 | 版本 | 说明 | 必需 | | --- | --- | --- | --- | | vue | ^3.5.30 | Vue 3 框架 | ✅ | | echarts | ^6.0.0 | 图表库 | ✅ | | vue-echarts | ^8.0.1 | Vue ECharts 组件 | ✅ | | element-plus | ^2.13.0 | Element Plus UI 组件库 | ✅ | | plus-pro-components | ^0.1.30 | Plus Pro 表格组件 | ✅ | | @element-plus/icons-vue | ^2.3.0 | Element Plus 图标库 | ✅ | | sortablejs | ^1.15.0 | 拖拽排序库 | ✅ | | xlsx | ^0.18.5 | Excel 导出库 | ✅ | | vxe-table | ^4.18.0 | 高性能表格组件 | ⭕ 可选 | | xe-utils | ^4.0.0 | VxeTable 工具库 | ⭕ 可选 |

使用方式

全局引入

import { createApp } from 'vue'
import App from './App.vue'
import ITMSBIComponents from 'itms-bi-components'
import 'itms-bi-components/style.css'

const app = createApp(App)
app.use(ITMSBIComponents)
app.mount('#app')

按需引入

<script setup lang="ts">
import { BaseRingChart, BaseBarChart } from 'itms-bi-components'
import 'itms-bi-components/style.css'
import type { ChartDataItem, BarChartData } from 'itms-bi-components'

const ringData: ChartDataItem[] = [
  { name: '已完成', value: 120 },
  { name: '进行中', value: 80 },
  { name: '待处理', value: 40 }
]

const barData: BarChartData = {
  categories: ['周一', '周二', '周三', '周四', '周五'],
  series: [
    { name: '销售额', data: [120, 200, 150, 80, 70] }
  ]
}
</script>

<template>
  <BaseRingChart :data="ringData" height="300px" />
  <BaseBarChart :data="barData" height="300px" />
</template>

国际化

组件库支持两种国际化配置方式：全局 API 模式 和 ConfigProvider 模式。

方式一：ConfigProvider 模式（推荐）

使用 ConfigProvider 组件在组件树级别配置国际化，支持响应式切换语言。

<script setup lang="ts">
import { ref } from 'vue'
import { ConfigProvider, BaseRingChart, BaseBarChart } from 'itms-bi-components'
import { zhCN, enUS, type Locale } from 'itms-bi-components'
import 'itms-bi-components/style.css'

const currentLocale = ref<Locale>(zhCN)

const switchLocale = () => {
  currentLocale.value = currentLocale.value.name === 'zh-CN' ? enUS : zhCN
}
</script>

<template>
  <button @click="switchLocale">
    切换语言 / Switch Language
  </button>
  
  <ConfigProvider :locale="currentLocale">
    <BaseRingChart :data="ringData" />
    <BaseBarChart :data="barData" />
  </ConfigProvider>
</template>

方式二：全局 API 模式

使用全局 API 设置语言，适用于不使用 ConfigProvider 的场景。

import { createApp } from 'vue'
import App from './App.vue'
import ITMSBIComponents, { setLocale, enUS } from 'itms-bi-components'
import 'itms-bi-components/style.css'

const app = createApp(App)
app.use(ITMSBIComponents)

// 切换为英文
setLocale(enUS)

全局 API 列表

| API | 说明 | 类型 | | --- | --- | --- | | setLocale | 设置当前语言包 | (locale: Locale) => void | | getLocale | 获取当前语言包 | () => Locale | | t | 获取指定 key 的翻译文本 | (key: keyof LocaleMessages) => string | | resetLocale | 重置为默认语言包（中文） | () => void | | useLocale | 获取 locale 上下文（优先从 ConfigProvider inject） | () => LocaleContext |

内置语言包

组件库内置以下语言包：

| 语言包 | 导入路径 | | --- | --- | | 中文（简体） | itms-bi-components 或 itms-bi-components/locale/lang/zh-CN | | English | itms-bi-components 或 itms-bi-components/locale/lang/en-US |

// 方式一：从主入口导入
import { zhCN, enUS } from 'itms-bi-components'

// 方式二：按需导入语言包（推荐，减少打包体积）
import zhCN from 'itms-bi-components/locale/lang/zh-CN'
import enUS from 'itms-bi-components/locale/lang/en-US'

自定义语言包

使用 defineLocale 创建自定义语言包：

import { defineLocale, ConfigProvider } from 'itms-bi-components'

// 创建日语语言包
const jaJP = defineLocale({
  loading: '読み込み中...',
  noData: 'データがありません',
  fetchError: 'データの取得に失敗しました'
}, 'ja-JP')

// 使用自定义语言包
<ConfigProvider :locale="jaJP">
  <BaseBarChart :data="chartData" />
</ConfigProvider>

语言包类型定义

// 翻译文本接口
interface LocaleMessages {
  loading: string      // 加载中
  noData: string       // 暂无数据
  fetchError: string   // 获取数据失败
  confirmOperation: string  // 确认执行此操作吗？
  prompt: string       // 提示
  more: string         // 更多
  action: string       // 操作
}

// 语言包类型
interface Locale {
  name: string              // 语言名称/代码，如 'zh-CN', 'en-US'
  messages: LocaleMessages  // 翻译文本
}

// Locale 上下文接口（useLocale 返回值）
interface LocaleContext {
  locale: Readonly<Ref<Locale>>              // 当前语言包
  t: (key: keyof LocaleMessages) => string   // 获取翻译文本
}

ConfigProvider 全局配置

ConfigProvider 组件用于在组件树级别配置国际化、字典组件等全局设置。

Props

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | locale | 语言包设置 | Locale | zhCN（中文） | | dictRender | 字典渲染配置 | DictRender | - |

字典渲染配置

当使用 ITMSTable 的 valueType: 'dict' 时，需要通过 ConfigProvider 提供字典渲染组件。

类型定义

// 字典组件属性配置
interface DictPropsConfig {
  /** 字典类型属性名，默认 'dictType' */
  dictTypeProp?: string
  /** 字典值属性名，默认 'value' */
  dictValueProp?: string
}

// 字典渲染配置
interface DictRender {
  /** 字典渲染组件 */
  component: Component
  /** 组件属性配置（可选） */
  propsConfig?: DictPropsConfig
}

示例

基础用法（使用默认属性名）

<script setup lang="ts">
import { defineComponent } from 'vue'
import { ConfigProvider, ITMSTable, type DictRender, type ITMSColumn } from 'itms-bi-components'

// 字典组件 - props 使用默认名称 dictType 和 value
const DictTag = defineComponent({
  props: ['dictType', 'value'],
  setup(props) {
    const dictMap: Record<string, Record<string, string>> = {
      status: { '1': '启用', '0': '禁用' },
      priority: { '1': '高', '2': '中', '3': '低' }
    }
    return () => <span>{dictMap[props.dictType]?.[props.value] ?? props.value}</span>
  }
})

const dictRender: DictRender = {
  component: DictTag
}

const columns: ITMSColumn[] = [
  { prop: 'name', label: '名称' },
  { prop: 'status', label: '状态', valueType: 'dict', dictType: 'status' },
  { prop: 'priority', label: '优先级', valueType: 'dict', dictType: 'priority' }
]
</script>

<template>
  <ConfigProvider :dictRender="dictRender">
    <ITMSTable :columns="columns" :data="tableData" />
  </ConfigProvider>
</template>

自定义属性名

如果字典组件的 props 名称与默认不同，可以通过 propsConfig 配置：

<script setup lang="ts">
import { defineComponent } from 'vue'
import { ConfigProvider, type DictRender } from 'itms-bi-components'

// 字典组件 - props 使用自定义名称
const DictTag = defineComponent({
  props: ['type', 'val'],  // 自定义属性名
  setup(props) {
    return () => <span>{getDictLabel(props.type, props.val)}</span>
  }
})

const dictRender: DictRender = {
  component: DictTag,
  propsConfig: {
    dictTypeProp: 'type',   // 映射 dictType -> type
    dictValueProp: 'val'    // 映射 value -> val
  }
}
</script>

<template>
  <ConfigProvider :dictRender="dictRender">
    <ITMSTable :columns="columns" :data="tableData" />
  </ConfigProvider>
</template>

组件

BaseRingChart 环形图

Props

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | data | 直接传入的数据 | ChartDataItem[] | [] | | requestFn | 请求数据的函数 | () => Promise<ChartDataItem[]> | - | | title | 图表标题 | string | '' | | width | 图表宽度 | string \| number | '100%' | | height | 图表高度 | string \| number | '300px' | | innerRadius | 环形图内半径 | string \| number | '40%' | | outerRadius | 环形图外半径 | string \| number | '55%' | | colors | 颜色列表 | string[] | 默认配色 | | showLegend | 是否显示图例 | boolean | true | | legendPosition | 图例位置 | 'left' \| 'right' \| 'top' \| 'bottom' | 'right' |

Events

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | itemClick | 点击数据块时触发 | RingChartClickEvent |

类型定义

// 数据项类型
interface ChartDataItem {
  name: string
  value: number
}

// 点击事件参数
interface RingChartClickEvent {
  name: string           // 数据项名称
  value: number          // 数据值
  percent: number        // 百分比
  seriesName: string     // 系列名称
  dataIndex: number      // 数据索引
  color: string          // 颜色
  data: ChartDataItem    // 原始数据项
}

示例

直接传数据

<BaseRingChart 
  :data="[
    { name: '已完成', value: 120 },
    { name: '进行中', value: 80 }
  ]" 
  title="任务状态分布"
  height="300px"
  :showLegend="true"
  legendPosition="bottom"
/>

异步请求数据

<script setup lang="ts">
import { BaseRingChart } from 'itms-bi-components'

const fetchData = async () => {
  const res = await fetch('/api/statistics')
  return res.json()
}
</script>

<template>
  <BaseRingChart 
    :requestFn="fetchData"
    title="任务统计"
    :colors="['#0158F0', '#F7B400', '#A77EFA']"
  />
</template>

监听点击事件

<script setup lang="ts">
import { BaseRingChart } from 'itms-bi-components'
import type { RingChartClickEvent } from 'itms-bi-components'

const handleClick = (event: RingChartClickEvent) => {
  console.log('点击了:', event.name, '值:', event.value, '占比:', event.percent + '%')
}
</script>

<template>
  <BaseRingChart 
    :data="chartData" 
    @itemClick="handleClick"
  />
</template>

BaseBarChart 柱状图

Props

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | data | 直接传入的数据 | BarChartData | { categories: [], series: [] } | | requestFn | 请求数据的函数 | () => Promise<BarChartData> | - | | title | 图表标题 | string | '' | | width | 图表宽度 | string \| number | '100%' | | height | 图表高度 | string \| number | '300px' | | colors | 颜色列表 | string[] | 默认配色 | | legendPosition | 图例位置（多系列时生效） | 'left' \| 'right' \| 'top' \| 'bottom' | 'top' | | barMaxWidth | 柱形最大宽度（px） | number | 12 | | showSplitLine | 是否显示网格线 | boolean | true | | maxLabelLength | X轴标签最大字数，超出显示省略号 | number | 6 | | pageSize | 每页显示类目数量，0 表示不分页 | number | 0 |

Events

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | itemClick | 点击柱形时触发 | BarChartClickEvent |

类型定义

// 系列数据项类型
interface BarSeriesItem {
  name: string      // 系列名称
  data: number[]    // 每个类目对应的值
}

// 柱状图数据类型
interface BarChartData {
  categories: string[]     // X轴类目列表
  series: BarSeriesItem[]  // 系列数据列表
}

// 点击事件参数
interface BarChartClickEvent {
  category: string      // 类目名称
  value: number         // 数据值
  seriesName: string    // 系列名称
  seriesIndex: number   // 系列索引
  dataIndex: number     // 数据索引
  color: string         // 颜色
}

示例

单系列柱状图

<script setup lang="ts">
import { BaseBarChart } from 'itms-bi-components'
import type { BarChartData } from 'itms-bi-components'

const chartData: BarChartData = {
  categories: ['一月', '二月', '三月', '四月', '五月'],
  series: [
    { name: '销售额', data: [120, 200, 150, 80, 70] }
  ]
}
</script>

<template>
  <BaseBarChart 
    :data="chartData"
    title="月度销售额"
    height="300px"
  />
</template>

多系列柱状图

<script setup lang="ts">
import { BaseBarChart } from 'itms-bi-components'
import type { BarChartData } from 'itms-bi-components'

const chartData: BarChartData = {
  categories: ['周一', '周二', '周三', '周四', '周五'],
  series: [
    { name: '销售额', data: [120, 200, 150, 80, 70] },
    { name: '利润', data: [60, 100, 75, 40, 35] }
  ]
}
</script>

<template>
  <BaseBarChart 
    :data="chartData"
    title="销售与利润对比"
    legendPosition="top"
    :colors="['#2f7afa', '#74E27D']"
  />
</template>

分页展示

<BaseBarChart 
  :data="chartData"
  title="大量数据分页展示"
  :pageSize="10"
  height="300px"
/>

异步请求数据

<script setup lang="ts">
import { BaseBarChart } from 'itms-bi-components'
import type { BarChartData } from 'itms-bi-components'

const fetchData = async (): Promise<BarChartData> => {
  const res = await fetch('/api/bar-data')
  return res.json()
}
</script>

<template>
  <BaseBarChart 
    :requestFn="fetchData"
    title="异步数据图表"
    :showSplitLine="false"
  />
</template>

监听点击事件

<script setup lang="ts">
import { BaseBarChart } from 'itms-bi-components'
import type { BarChartClickEvent } from 'itms-bi-components'

const handleClick = (event: BarChartClickEvent) => {
  console.log('点击了:', event.category, '系列:', event.seriesName, '值:', event.value)
}
</script>

<template>
  <BaseBarChart 
    :data="chartData"
    @itemClick="handleClick"
  />
</template>

HorizontalBarChart 横向柱状图

Props

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | data | 直接传入的数据 | HorizontalBarChartData | { categories: [], series: [] } | | requestFn | 请求数据的函数 | () => Promise<HorizontalBarChartData> | - | | title | 图表标题 | string | '' | | width | 图表宽度 | string \| number | '100%' | | height | 图表高度 | string \| number | '300px' | | colors | 颜色列表 | string[] | 默认配色 | | legendPosition | 图例位置（多系列时生效） | 'left' \| 'right' \| 'top' \| 'bottom' | 'top' | | barHeight | 柱形高度（px） | number | 6 | | showSplitLine | 是否显示网格线 | boolean | true | | maxLabelLength | Y轴标签最大字数，超出显示省略号 | number | 6 | | pageSize | 每页显示类目数量，0 表示不分页 | number | 0 | | truncateLabel | 是否截断过长的标签 | boolean | true | | formatLargeNumber | 是否格式化大数值（如 12345 → 12.3K） | boolean | true | | rightPadding | 右侧留白宽度（px） | number | 60 | | fontFamily | 自定义字体 | string | 'inherit' |

Events

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | itemClick | 点击柱形时触发 | HorizontalBarClickEvent |

类型定义

// 系列数据项类型
interface HorizontalSeriesItem {
  name: string      // 系列名称
  data: number[]    // 每个类目对应的值
}

// 横向柱状图数据类型
interface HorizontalBarChartData {
  categories: string[]        // Y轴类目列表
  series: HorizontalSeriesItem[]  // 系列数据列表
}

// 点击事件参数
interface HorizontalBarClickEvent {
  category: string      // 类目名称
  value: number         // 数据值
  seriesName: string    // 系列名称
  seriesIndex: number   // 系列索引
  dataIndex: number     // 数据索引
  color: string         // 颜色
}

示例

单系列横向柱状图

<script setup lang="ts">
import { HorizontalBarChart } from 'itms-bi-components'
import type { HorizontalBarChartData } from 'itms-bi-components'

const chartData: HorizontalBarChartData = {
  categories: ['一月', '二月', '三月', '四月', '五月'],
  series: [
    { name: '销售额', data: [120, 200, 150, 80, 70] }
  ]
}
</script>

<template>
  <HorizontalBarChart 
    :data="chartData"
    title="月度销售额"
    height="300px"
  />
</template>

多系列横向柱状图

<script setup lang="ts">
import { HorizontalBarChart } from 'itms-bi-components'
import type { HorizontalBarChartData } from 'itms-bi-components'

const chartData: HorizontalBarChartData = {
  categories: ['周一', '周二', '周三', '周四', '周五'],
  series: [
    { name: '销售额', data: [120, 200, 150, 80, 70] },
    { name: '利润', data: [60, 100, 75, 40, 35] }
  ]
}
</script>

<template>
  <HorizontalBarChart 
    :data="chartData"
    title="销售与利润对比"
    legendPosition="top"
    :colors="['#2f7afa', '#74E27D']"
  />
</template>

分页展示

<HorizontalBarChart 
  :data="chartData"
  title="大量数据分页展示"
  :pageSize="10"
  height="300px"
/>

异步请求数据

<script setup lang="ts">
import { HorizontalBarChart } from 'itms-bi-components'
import type { HorizontalBarChartData } from 'itms-bi-components'

const fetchData = async (): Promise<HorizontalBarChartData> => {
  const res = await fetch('/api/horizontal-bar-data')
  return res.json()
}
</script>

<template>
  <HorizontalBarChart 
    :requestFn="fetchData"
    title="异步数据图表"
    :showSplitLine="false"
  />
</template>

监听点击事件

<script setup lang="ts">
import { HorizontalBarChart } from 'itms-bi-components'
import type { HorizontalBarClickEvent } from 'itms-bi-components'

const handleClick = (event: HorizontalBarClickEvent) => {
  console.log('点击了:', event.category, '系列:', event.seriesName, '值:', event.value)
}
</script>

<template>
  <HorizontalBarChart 
    :data="chartData"
    @itemClick="handleClick"
  />
</template>

BaseDemoList 列表组件

Props

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | data | 直接传入的数据 | DemoListItem[] | [] | | requestFn | 请求数据的函数 | () => Promise<DemoListItem[]> | - | | height | 列表高度 | string \| number | '280px' | | labelMaxWidth | label 最大宽度 | string \| number | '200px' | | autoScroll | 是否自动滚动 | boolean | true | | scrollInterval | 自动滚动间隔（毫秒） | number | 3000 | | virtualScroll | 是否启用虚拟滚动（大数据量时建议开启） | boolean | false | | itemHeight | 列表项占用高度（虚拟滚动时需要固定值） | number | 46 |

Events

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | itemClick | 点击列表项时触发 | DemoListClickEvent | | dataLoaded | 数据加载完成时触发（仅当使用 requestFn 请求数据时） | DemoListItem[] |

类型定义

// 数据项类型
interface DemoListItem {
  label: string           // 展示内容
  value: string | number  // 右侧展示值
  prefixRender?: () => RenderResult  // 前缀渲染函数，不传默认为蓝色方块
  tagRender?: () => RenderResult     // 标签渲染函数，不传则不展示标签
}

// 点击事件参数
interface DemoListClickEvent {
  item: DemoListItem   // 数据项
  index: number        // 数据索引
}

// 渲染函数返回类型
type RenderResult = VNode | string | null | Component

示例

直接传数据

<script setup lang="ts">
import { BaseDemoList } from 'itms-bi-components'
import type { DemoListItem } from 'itms-bi-components'

const listData: DemoListItem[] = [
  { label: '任务A', value: 120 },
  { label: '任务B', value: 80 },
  { label: '任务C', value: 40 }
]
</script>

<template>
  <BaseDemoList 
    :data="listData"
    height="300px"
    :autoScroll="true"
  />
</template>

异步请求数据

<script setup lang="ts">
import { BaseDemoList } from 'itms-bi-components'
import type { DemoListItem } from 'itms-bi-components'

const fetchData = async (): Promise<DemoListItem[]> => {
  const res = await fetch('/api/list-data')
  return res.json()
}

const handleDataLoaded = (data: DemoListItem[]) => {
  console.log('数据加载完成:', data)
}
</script>

<template>
  <BaseDemoList 
    :requestFn="fetchData"
    height="280px"
    @dataLoaded="handleDataLoaded"
  />
</template>

自定义前缀和标签

<script setup lang="ts">
import { BaseDemoList } from 'itms-bi-components'
import type { DemoListItem } from 'itms-bi-components'

const listData: DemoListItem[] = [
  {
    label: '已完成任务',
    value: 120,
    prefixRender: () => <span style="color: #52c41a;">●</span>,
    tagRender: () => <span style="background: #52c41a; color: #fff; padding: 2px 6px; border-radius: 4px; font-size: 12px;">完成</span>
  },
  {
    label: '进行中任务',
    value: 80,
    prefixRender: () => <span style="color: #1890ff;">●</span>,
    tagRender: () => <span style="background: #1890ff; color: #fff; padding: 2px 6px; border-radius: 4px; font-size: 12px;">进行中</span>
  }
]
</script>

<template>
  <BaseDemoList 
    :data="listData"
    :autoScroll="false"
  />
</template>

虚拟滚动（大数据量）

<BaseDemoList 
  :requestFn="fetchLargeData"
  height="400px"
  :virtualScroll="true"
  :itemHeight="46"
  :autoScroll="false"
/>

监听点击事件

<script setup lang="ts">
import { BaseDemoList } from 'itms-bi-components'
import type { DemoListClickEvent } from 'itms-bi-components'

const handleItemClick = (event: DemoListClickEvent) => {
  console.log('点击了:', event.item.label, '值:', event.item.value, '索引:', event.index)
}
</script>

<template>
  <BaseDemoList 
    :data="listData"
    @itemClick="handleItemClick"
  />
</template>

ITMSTable 表格组件

基于 plus-pro-components 封装的高级表格组件，支持多级表头、百分比渲染、字典渲染、操作栏、导出等功能。

Props

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | columns | 列配置 | ITMSColumn[] | [] | | data | 表格数据 | RecordType[] | [] | | loadingStatus | 是否显示加载状态 | boolean | false | | error | 错误信息 | string | '' | | actionBar | 操作栏配置 | ActionBarProps \| false | - | | size | 表格尺寸 | 'large' \| 'default' \| 'small' | 'small' |

更多 Props 请参考 PlusTable 文档，所有属性均可透传。

Expose Methods

通过 ref 获取组件实例后可调用的方法：

| 方法名 | 说明 | 类型 | | --- | --- | --- | | tableInstance | 获取 PlusTable 实例 | () => any | | getSelectedRows | 获取当前选中的行数据 | () => T[] | | clearSelection | 清除选中状态 | () => void | | exportData | 导出当前表格所有数据 | (options?: ExportOptions) => void | | exportSelectedData | 导出选中的数据 | (options?: ExportOptions) => void |

类型定义

// 扩展的 valueType 类型
type ITMSTableValueType = TableValueType | 'percent' | 'dict'

// 扩展的列配置类型
interface ITMSPlusColumn {
  prop: string
  label: string
  valueType?: ITMSTableValueType | FormItemValueType
  /** 字典类型名称，valueType 为 'dict' 时必填 */
  dictType?: string
  /** 多级表头 */
  children?: ITMSPlusColumn[]
  // ... 继承 PlusColumn 其他属性
}

// 组件实例类型（支持泛型）
type ITMSTableInstance<T = RecordType> = {
  $: any
} & ITMSTableExpose<T>

// 暴露的方法类型
interface ITMSTableExpose<T = RecordType> {
  tableInstance: () => any
  getSelectedRows: () => T[]
  clearSelection: () => void
  exportData: (options?: ExportOptions) => void
  exportSelectedData: (options?: ExportOptions) => void
}

自定义 valueType

ITMSTable 扩展了 PlusTable 的 valueType，支持以下自定义类型：

| valueType | 说明 | 配置 | | --- | --- | --- | | percent | 百分比渲染（伪环形图 + 百分比文字） | 值需为 0-100 的数字 | | dict | 字典渲染 | 需配置 dictType 属性，并通过 ConfigProvider 提供字典组件 |

Events

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | clickAction | 操作栏按钮点击时触发（非二次确认时） | ButtonsCallBackParams | | clickActionConfirmCancel | 操作栏二次确认取消时触发 | ButtonsCallBackParams | | selection-change | 选择变化时触发 | T[] |

更多 Events 请参考 PlusTable 文档。

示例

基础用法

<script setup lang="ts">
import { ref } from 'vue'
import { ITMSTable, type ITMSColumn, type ITMSTableInstance } from 'itms-bi-components'

interface UserRow {
  id: number
  name: string
  age: number
  email: string
}

const tableRef = ref<ITMSTableInstance<UserRow> | null>(null)

const columns: ITMSColumn[] = [
  { prop: 'id', label: 'ID', width: 80 },
  { prop: 'name', label: '姓名', width: 120 },
  { prop: 'age', label: '年龄', width: 100 },
  { prop: 'email', label: '邮箱' }
]

const tableData: UserRow[] = [
  { id: 1, name: '张三', age: 28, email: '[email protected]' },
  { id: 2, name: '李四', age: 32, email: '[email protected]' }
]

// 获取选中数据
const getSelected = () => {
  const selected = tableRef.value?.getSelectedRows()
  console.log('选中的数据:', selected)
}
</script>

<template>
  <ITMSTable
    ref="tableRef"
    :columns="columns"
    :data="tableData"
    :isSelection="true"
  />
</template>

多级表头

<script setup lang="ts">
import { ITMSTable, type ITMSColumn } from 'itms-bi-components'

const columns: ITMSColumn[] = [
  { prop: 'name', label: '姓名', width: 120 },
  {
    label: '联系方式',
    children: [
      { prop: 'phone', label: '电话', width: 150 },
      { prop: 'email', label: '邮箱' }
    ]
  }
]
</script>

<template>
  <ITMSTable :columns="columns" :data="tableData" />
</template>

百分比渲染

<script setup lang="ts">
import { ITMSTable, type ITMSColumn } from 'itms-bi-components'

const columns: ITMSColumn[] = [
  { prop: 'name', label: '任务名称' },
  { prop: 'progress', label: '进度', valueType: 'percent', width: 150 }
]

const tableData = [
  { name: '任务A', progress: 75 },
  { name: '任务B', progress: 100 },
  { name: '任务C', progress: 30 }
]
</script>

<template>
  <ITMSTable :columns="columns" :data="tableData" />
</template>

字典渲染

需要配合 ConfigProvider 提供字典组件：

<script setup lang="ts">
import { defineComponent } from 'vue'
import { ITMSTable, ConfigProvider, type ITMSColumn, type DictRender } from 'itms-bi-components'

// 自定义字典组件
const DictTag = defineComponent({
  props: ['dictType', 'value'],
  setup(props) {
    // 根据字典类型和值获取显示文本
    const dictMap: Record<string, Record<string, string>> = {
      status: {
        '1': '启用',
        '0': '禁用'
      }
    }
    return () => <span>{dictMap[props.dictType]?.[props.value] ?? props.value}</span>
  }
})

const dictRender: DictRender = {
  component: DictTag
}

const columns: ITMSColumn[] = [
  { prop: 'name', label: '名称' },
  { prop: 'status', label: '状态', valueType: 'dict', dictType: 'status' }
]
</script>

<template>
  <ConfigProvider :dictRender="dictRender">
    <ITMSTable :columns="columns" :data="tableData" />
  </ConfigProvider>
</template>

操作栏配置

<script setup lang="ts">
import { ITMSTable, type ITMSColumn, type ActionBarProps } from 'itms-bi-components'

const columns: ITMSColumn[] = [
  { prop: 'name', label: '名称' },
  { prop: 'status', label: '状态' }
]

const actionBar: ActionBarProps = {
  label: '操作',
  width: 200,
  fixed: 'right',
  showNumber: 3,
  buttons: [
    { text: '编辑', onClick: (params) => console.log('编辑', params.row) },
    { text: '删除', confirm: true, onClick: (params) => console.log('删除', params.row) },
    { text: '查看', onClick: (params) => console.log('查看', params.row) }
  ]
}
</script>

<template>
  <ITMSTable :columns="columns" :data="tableData" :actionBar="actionBar" />
</template>

加载与错误状态

<template>
  <ITMSTable
    :columns="columns"
    :data="tableData"
    :loadingStatus="loading"
    :error="errorMsg"
  />
</template>

导出数据

<script setup lang="ts">
import { ref } from 'vue'
import { ITMSTable, type ITMSTableInstance, type ExportOptions } from 'itms-bi-components'

const tableRef = ref<ITMSTableInstance | null>(null)

const exportAll = () => {
  const options: ExportOptions = {
    filename: '导出数据',
    sheetName: '数据表'
  }
  tableRef.value?.exportData(options)
}

const exportSelected = () => {
  tableRef.value?.exportSelectedData({ filename: '选中数据' })
}
</script>

<template>
  <div>
    <button @click="exportAll">导出全部</button>
    <button @click="exportSelected">导出选中</button>
    <ITMSTable ref="tableRef" :columns="columns" :data="tableData" :isSelection="true" />
  </div>
</template>

BaseTable 基础表格组件

基于 vxe-table 封装的基础表格组件，适用于需要高性能表格的场景。

Props

| 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | columns | 表格列配置 | TableColumn[] | [] | | tableData | 表格数据 | TableData | [] | | border | 是否显示边框 | boolean | true | | stripe | 是否显示斑马纹 | boolean | false | | height | 表格高度 | number \| string | 'auto' | | loading | 是否显示加载状态 | boolean | false | | error | 错误信息 | string | '' |

类型定义

// 表格列配置
interface TableColumn {
  /** 表格对应列内容的字段名 */
  prop: string
  /** 表格表头显示的标题 */
  label: string
  /** 表格列宽 */
  width?: number | string
}

// 表格数据类型
type TableData = Record<string, unknown>[]

示例

基础用法

<script setup lang="ts">
import { BaseTable, type TableColumn, type TableData } from 'itms-bi-components'

const columns: TableColumn[] = [
  { prop: 'id', label: 'ID', width: 80 },
  { prop: 'name', label: '姓名', width: 120 },
  { prop: 'age', label: '年龄', width: 100 },
  { prop: 'email', label: '邮箱' }
]

const tableData: TableData = [
  { id: 1, name: '张三', age: 28, email: '[email protected]' },
  { id: 2, name: '李四', age: 32, email: '[email protected]' }
]
</script>

<template>
  <BaseTable
    :columns="columns"
    :tableData="tableData"
    height="400px"
    :stripe="true"
  />
</template>

加载与错误状态

<template>
  <BaseTable
    :columns="columns"
    :tableData="tableData"
    :loading="loading"
    :error="errorMsg"
  />
</template>

Excel 导出工具

组件库提供了 Excel 导出相关的工具函数，支持多级表头导出、列宽自适应等功能。

导出函数

| 函数名 | 说明 | 类型 | | --- | --- | --- | | exportTableData | 导出表格数据到 Excel 文件 | <T>(data: T[], columns, options?) => void | | exportSelectedData | 导出选中的数据到 Excel 文件 | <T>(selectedData: T[], columns, options?) => void | | getTableWorkbook | 获取表格数据的 Excel 工作簿对象 | <T>(data: T[], columns, options?) => WorkBook | | tableDataToCSV | 将表格数据转换为 CSV 格式字符串 | <T>(data: T[], columns, includeHeader?) => string |

类型定义

// 导出配置选项
interface ExportOptions {
  /** 文件名（不含扩展名） */
  filename?: string
  /** 工作表名称 */
  sheetName?: string
  /** 是否包含表头，默认 true */
  includeHeader?: boolean
}

// 列配置用于导出的简化结构
interface ExportColumn {
  /** 列字段名（叶子节点必须有） */
  prop?: string
  /** 列标题（用于表头） */
  label: string
  /** 子列配置（多级表头） */
  children?: ExportColumn[]
}

示例

基础导出

import { exportTableData, type ITMSColumn } from 'itms-bi-components'

const columns: ITMSColumn[] = [
  { prop: 'name', label: '姓名' },
  { prop: 'age', label: '年龄' },
  { prop: 'email', label: '邮箱' }
]

const data = [
  { name: '张三', age: 28, email: '[email protected]' },
  { name: '李四', age: 32, email: '[email protected]' }
]

// 导出数据
exportTableData(data, columns, {
  filename: '用户列表',
  sheetName: '用户数据'
})

多级表头导出

import { exportTableData, type ExportColumn } from 'itms-bi-components'

const columns: ExportColumn[] = [
  { prop: 'name', label: '姓名' },
  {
    label: '联系方式',
    children: [
      { prop: 'phone', label: '电话' },
      { prop: 'email', label: '邮箱' }
    ]
  }
]

exportTableData(data, columns, { filename: '多级表头' })

获取工作簿对象

import { getTableWorkbook } from 'itms-bi-components'

// 获取工作簿对象进行自定义处理
const workbook = getTableWorkbook(data, columns)
// 可以添加更多工作表或其他自定义操作

转换为 CSV

import { tableDataToCSV } from 'itms-bi-components'

const csvString = tableDataToCSV(data, columns, true)
console.log(csvString)

开发

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建组件库
pnpm build

# 预览构建结果
pnpm preview

技术栈

Vue 3 - 渐进式 JavaScript 框架
TypeScript - JavaScript 的超集
Vite - 下一代前端构建工具
ECharts - 开源可视化图表库
vue-echarts - Vue 的 ECharts 组件封装
SCSS - CSS 预处理器

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ITMS BI Components

特性

安装

依赖说明

使用方式

全局引入

按需引入

国际化

方式一：ConfigProvider 模式（推荐）

方式二：全局 API 模式

内置语言包

自定义语言包

语言包类型定义

ConfigProvider 全局配置

Props

字典渲染配置

类型定义

示例

组件

BaseRingChart 环形图

Props

Events

类型定义

示例

BaseBarChart 柱状图

Props

Events

类型定义

示例

HorizontalBarChart 横向柱状图

Props

Events

类型定义

示例

BaseDemoList 列表组件

Props

Events

类型定义

示例

ITMSTable 表格组件

Props

Expose Methods

类型定义

自定义 valueType

Events

示例

BaseTable 基础表格组件

Props

类型定义

示例

Excel 导出工具

导出函数

类型定义

示例

开发

技术栈

License