@cimom/vben-effects-plugins

该包提供了多个第三方库的集成插件，每个插件都包含了可重用的逻辑、配置和组件，方便在项目中进行统一管理和调用。通过子路径导出的方式，允许应用按需引入所需的插件，避免不必要的打包体积增加。

安装

# 进入目标应用目录，例如 apps/xxxx-app
# cd apps/xxxx-app
pnpm add @cimom/vben-effects-plugins

引入方式

所有的第三方插件都必须以 subpath 形式引入，例如：

// 引入 ECharts 插件
import { useEcharts, EchartsUI } from '@cimom/vben-effects-plugins/echarts';

// 引入 Motion 动画插件
import { Motion, MotionDirective } from '@cimom/vben-effects-plugins/motion';

// 引入 VXE Table 插件
import {
  VbenVxeGrid,
  setupVbenVxeTable,
} from '@cimom/vben-effects-plugins/vxe-table';

这样做的好处是，应用可以自行选择是否使用插件，而不会因为插件的引入及副作用而导致打包体积增大，只引入需要的插件即可。

可用插件

ECharts 图表插件

ECharts 是一个功能强大的交互式图表库，该插件提供了对 ECharts 的封装，使其更容易在 Vue 项目中使用。

基本使用

<template>
  <div class="chart-container" style="height: 400px;">
    <EchartsUI ref="chartRef" :loading="loading" />
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { useEcharts, EchartsUI } from '@cimom/vben-effects-plugins/echarts';

const chartRef = ref<InstanceType<typeof EchartsUI>>();
const loading = ref(false);

// 使用 useEcharts 钩子函数
const { setOptions, getInstance, resize } = useEcharts(chartRef);

onMounted(() => {
  // 设置图表配置
  setOptions({
    title: {
      text: '示例图表',
    },
    tooltip: {
      trigger: 'axis',
    },
    xAxis: {
      type: 'category',
      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    },
    yAxis: {
      type: 'value',
    },
    series: [
      {
        data: [150, 230, 224, 218, 135, 147, 260],
        type: 'line',
      },
    ],
  });
});

// 获取 ECharts 实例进行高级操作
function doSomethingWithChart() {
  const chartInstance = getInstance();
  if (chartInstance) {
    // 可以直接操作 ECharts 实例
    chartInstance.dispatchAction({
      type: 'highlight',
      seriesIndex: 0,
      dataIndex: 1,
    });
  }
}

// 手动调整图表大小
function handleResize() {
  resize();
}
</script>

API 参考

useEcharts 钩子函数

function useEcharts(chartRef: Ref<typeof EchartsUI | undefined>) {
  // 返回值
  return {
    // 设置图表配置选项
    setOptions: (options: EChartsOption, clear?: boolean) => void,
    // 获取 ECharts 实例
    getInstance: () => echarts.ECharts | null,
    // 手动调整图表大小
    resize: () => void,
    // 更新图表主题
    updateTheme: (theme?: 'light' | 'dark' | null) => void,
    // 清空图表
    clear: () => void,
    // 销毁图表实例
    dispose: () => void
  };
}

EchartsUI 组件属性

| 属性 | 类型 | 默认值 | 说明 | | ---------------- | --------------------------- | ------- | ---------------- | | loading | boolean | false | 是否显示加载状态 | | loadingOptions | object | {} | 加载状态配置选项 | | theme | 'light' \| 'dark' \| null | null | 图表主题 | | autoresize | boolean | true | 是否自动调整大小 |

Motion 动画插件

基于 @vueuse/motion 的动画插件，提供了丰富的动画效果和简单的 API，用于创建流畅的界面过渡和交互动画。

基本使用

<template>
  <div>
    <!-- 使用动画组件 -->
    <Motion :initial="{ opacity: 0, y: 100 }" :enter="{ opacity: 1, y: 0 }">
      <div class="animated-box">渐入动画元素</div>
    </Motion>

    <!-- 使用动画指令 -->
    <div
      v-motion="{ initial: { opacity: 0 }, enter: { opacity: 1 } }"
      class="animated-text"
    >
      渐变文本
    </div>

    <!-- 使用动画组 -->
    <MotionGroup tag="ul" :delay="100">
      <li
        v-for="i in 5"
        :key="i"
        v-motion="{ initial: { x: -100 }, enter: { x: 0 } }"
      >
        列表项 {{ i }}
      </li>
    </MotionGroup>
  </div>
</template>

<script setup lang="ts">
import {
  Motion,
  MotionDirective,
  MotionGroup,
} from '@cimom/vben-effects-plugins/motion';

// 注册动画指令
const vMotion = MotionDirective;
</script>

全局注册

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { MotionPlugin } from '@cimom/vben-effects-plugins/motion';

const app = createApp(App);

// 注册动画插件
app.use(MotionPlugin);

app.mount('#app');

API 参考

Motion 组件属性

| 属性 | 类型 | 默认值 | 说明 | | ---------- | ---------------- | --------------- | -------------------- | | initial | MotionVariants | {} | 初始状态 | | enter | MotionVariants | {} | 进入状态 | | leave | MotionVariants | {} | 离开状态 | | visible | MotionVariants | {} | 可见状态 | | delay | number | 0 | 动画延迟（毫秒） | | duration | number | 150 | 动画持续时间（毫秒） | | easing | string | 'ease-in-out' | 动画缓动函数 |

MotionVariants 类型

interface MotionVariants {
  opacity?: number;
  x?: number | string;
  y?: number | string;
  z?: number | string;
  scale?: number;
  scaleX?: number;
  scaleY?: number;
  rotate?: number | string;
  rotateX?: number | string;
  rotateY?: number | string;
  rotateZ?: number | string;
  skewX?: number | string;
  skewY?: number | string;
  // 其他 CSS 变换属性...
}

VXE Table 插件

VXE Table 是一个功能强大的表格组件，该插件提供了对 VXE Table 的封装，使其更容易在项目中使用。

基本使用

<template>
  <div>
    <VbenVxeGrid
      ref="gridRef"
      v-bind="gridOptions"
      @page-change="handlePageChange"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, reactive, onMounted } from 'vue';
import { VbenVxeGrid, useVxeGrid } from '@cimom/vben-effects-plugins/vxe-table';
import type { VxeGridInstance } from 'vxe-table';

const gridRef = ref<VxeGridInstance>();

// 使用 useVxeGrid 钩子函数
const { gridOptions, setData, getSelectRecords, clearSelection } = useVxeGrid({
  columns: [
    { field: 'id', title: 'ID', width: 80 },
    { field: 'name', title: '姓名', minWidth: 120 },
    { field: 'age', title: '年龄', width: 80 },
    { field: 'address', title: '地址', minWidth: 200 },
  ],
  toolbarConfig: {
    buttons: [
      { code: 'add', name: '新增' },
      { code: 'edit', name: '编辑' },
      { code: 'delete', name: '删除' },
    ],
  },
  pagerConfig: {
    pageSize: 10,
    pageSizes: [10, 20, 50, 100],
  },
});

// 加载数据
onMounted(async () => {
  const data = await fetchData();
  setData(data);
});

// 处理页面变化
function handlePageChange({ currentPage, pageSize }) {
  // 重新加载数据
  fetchData(currentPage, pageSize).then((data) => {
    setData(data);
  });
}

// 模拟获取数据
async function fetchData(page = 1, pageSize = 10) {
  // 实际项目中这里会调用 API
  return Array.from({ length: 100 })
    .map((_, index) => ({
      id: index + 1,
      name: `用户${index + 1}`,
      age: Math.floor(Math.random() * 50) + 18,
      address: `地址信息 ${index + 1}`,
    }))
    .slice((page - 1) * pageSize, page * pageSize);
}

// 获取选中记录
function getSelected() {
  const records = getSelectRecords();
  console.log('选中记录:', records);
}

// 清除选择
function clearSelected() {
  clearSelection();
}
</script>

全局注册

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { setupVbenVxeTable } from '@cimom/vben-effects-plugins/vxe-table';

const app = createApp(App);

// 注册 VXE Table
setupVbenVxeTable();

app.mount('#app');

API 参考

useVxeGrid 钩子函数

function useVxeGrid(options: VxeTableGridOptions) {
  // 返回值
  return {
    // 表格配置选项
    gridOptions: Ref<VxeGridProps>,
    // 设置表格数据
    setData: (data: any[]) => void,
    // 获取选中记录
    getSelectRecords: () => any[],
    // 清除选择
    clearSelection: () => void,
    // 刷新表格
    reloadData: (data?: any[]) => void,
    // 设置加载状态
    setLoading: (loading: boolean) => void
  };
}

VbenVxeGrid 组件属性

组件继承了 VXE Table 的 Grid 组件的所有属性，详细属性请参考 VXE Table 官方文档。

高级用法

自定义 ECharts 主题

import { useEcharts } from '@cimom/vben-effects-plugins/echarts';
import { usePreferences } from '@cimom/vben-preferences';

// 创建自定义主题钩子
export function useCustomEcharts(chartRef) {
  const { preferences } = usePreferences();
  const { setOptions, updateTheme, resize } = useEcharts(chartRef);

  // 监听主题变化
  watch(
    () => preferences.theme,
    (theme) => {
      // 更新图表主题
      updateTheme(theme === 'dark' ? 'dark' : 'light');
    },
    { immediate: true },
  );

  return {
    setOptions,
    updateTheme,
    resize,
  };
}

组合使用多个插件

<template>
  <div>
    <Motion :initial="{ opacity: 0 }" :enter="{ opacity: 1 }">
      <div class="chart-container" style="height: 400px;">
        <EchartsUI ref="chartRef" :loading="loading" />
      </div>
    </Motion>

    <Motion
      :initial="{ y: 50, opacity: 0 }"
      :enter="{ y: 0, opacity: 1 }"
      :delay="300"
    >
      <VbenVxeGrid ref="gridRef" v-bind="gridOptions" />
    </Motion>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { Motion } from '@cimom/vben-effects-plugins/motion';
import { EchartsUI, useEcharts } from '@cimom/vben-effects-plugins/echarts';
import { VbenVxeGrid, useVxeGrid } from '@cimom/vben-effects-plugins/vxe-table';

// 图表相关
const chartRef = ref();
const loading = ref(false);
const { setOptions } = useEcharts(chartRef);

// 表格相关
const gridRef = ref();
const { gridOptions, setData } = useVxeGrid({
  // 表格配置...
});

onMounted(async () => {
  // 初始化图表
  setOptions({
    // 图表配置...
  });

  // 加载表格数据
  const data = await fetchData();
  setData(data);
});

// 模拟获取数据
async function fetchData() {
  // 实际项目中这里会调用 API
  return [];
}
</script>

注意事项

1. 插件以子路径形式导出，确保按照正确的路径导入所需的插件。
2. 某些插件（如 VXE Table）需要全局注册，确保在应用入口文件中正确设置。
3. 使用 ECharts 时，建议监听窗口大小变化并调用 resize 方法以保持图表响应式。
4. 动画插件可能会在某些低性能设备上影响性能，可以考虑根据设备性能动态启用或禁用动画。

常见问题

ECharts 图表不显示或显示异常

确保容器元素具有明确的宽高，并且在组件挂载后设置图表配置：

<template>
  <div class="chart-container" style="height: 400px; width: 100%;">
    <EchartsUI ref="chartRef" />
  </div>
</template>

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

onMounted(() => {
  // 确保在组件挂载后设置配置
  setOptions({
    // 图表配置...
  });
});
</script>

VXE Table 样式问题

确保已正确导入 VXE Table 的样式文件：

// main.ts
import 'vxe-table/lib/style.css';

动画不生效

确保正确设置了动画属性，并且元素在初始状态下是可见的：

<Motion
  :initial="{ opacity: 0, y: 50 }"
  :enter="{ opacity: 1, y: 0, transition: { duration: 500 } }"
>
  <div>动画元素</div>
</Motion>