antbms-battery-pack

v0.0.2-beta3

Published

6 months ago

A dynamic battery pack visualization component based on zrender

0High
0Medium
0Low

limin.incontent

battery visualization zrender antbms

AntBMS Battery Pack Visualization

基于TypeScript和ZRender的电池包可视化组件，用于动态展示电池组状态，支持H5和UniApp多平台环境。现已支持Vue 3集成。

功能特点

🔋 电池可视化：直观展示电池组状态、电压和温度
🔄 实时更新：支持动态更新电池状态和数据
⚡ 均衡状态：可视化展示主动/被动均衡状态
📱 跨平台：同时支持H5和UniApp环境
🎨 自定义样式：支持自定义电池布局、颜色和样式
📏 自适应：自动适应容器大小
🖱️ 交互体验：支持鼠标/触摸交互查看详细信息
📦 TypeScript：使用TypeScript开发，提供完整类型定义
⚛️ Vue 3支持：可以作为Vue 3组件使用

安装

方法一：使用npm安装

npm install antbms-battery-pack --save

方法二：直接使用打包文件（不发布到npm）

如果你想在不发布到npm的情况下使用这个组件，可以按照以下步骤操作：

克隆或下载本项目

git clone https://github.com/Observe-secretly/antbms-battery-pack.git
# 或者直接下载ZIP文件

安装依赖并构建库文件

cd antbms-battery-pack
npm install
npm run build:lib

将生成的库文件复制到你的项目中

# 生成的文件位于lib/battery-pack.js

在你的项目中引入这个文件

<!-- 在HTML中引入 -->
<script src="path/to/battery-pack.js"></script>

或者在模块化项目中：

// 作为模块导入
import BatteryPack from 'path/to/battery-pack.js';

使用方法

在Vue 3中使用

<template>
  <div class="container">
    <div class="controls">
      <button @click="updateRandomData">更新随机数据</button>
      <button @click="togglePassiveBalancing">切换被动均衡</button>
      <button @click="toggleActiveBalancing">切换主动均衡</button>
      <button @click="resetBatteryPack">重置</button>
    </div>
    <div id="battery-container" ref="batteryContainer"></div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { createBatteryPack } from 'antbms-battery-pack';

const batteryContainer = ref<HTMLElement | null>(null);
let batteryPack: any = null;

// 生成随机电池数据
function generateRandomData(count = 18, passiveBalancing = false, activeBalancing = false) {
  const data = [];
  for (let i = 1; i <= count; i++) {
    // 生成3.0V到4.2V之间的随机电压
    const voltage = (3.0 + Math.random() * 1.2).toFixed(3);
    // 生成20°C到40°C之间的随机温度
    const temperature = (20 + Math.random() * 20).toFixed(1);
    
    data.push({
      id: i,
      voltage: `${voltage}V`,
      temperature: `${temperature}°C`,
      status: Number(voltage) < 3.2 ? 'danger' : Number(voltage) < 3.5 ? 'warning' : 'normal',
      passiveBalance: passiveBalancing && i % 3 === 0, // 每3个电池启用被动均衡
      activeBalance: activeBalancing && i % 5 === 0  // 每5个电池启用主动均衡
    });
  }
  return data;
}

// 更新随机数据
function updateRandomData() {
  if (batteryPack) {
    const randomData = generateRandomData(18, Math.random() > 0.5, Math.random() > 0.7);
    batteryPack.updateData(randomData);
  }
}

// 切换被动均衡
function togglePassiveBalancing() {
  if (batteryPack) {
    const data = generateRandomData(18, true, false);
    batteryPack.updateData(data);
  }
}

// 切换主动均衡
function toggleActiveBalancing() {
  if (batteryPack) {
    const data = generateRandomData(18, false, true);
    batteryPack.updateData(data);
  }
}



onMounted(() => {
  if (batteryContainer.value) {
    // 初始化电池包可视化
    batteryPack = createBatteryPack(batteryContainer.value, {
      padding: 20,
      batteryWidth: 60,
      batteryHeight: 100,
      colors: {
        normal: '#5C8AF0',
        warning: '#f5a742',
        danger: '#f54242',
        passive_balancing: '#ABF04B', // 被动均衡颜色使用绿色
        active_balance_line: '#5C8AF0'
      }
    });

    // 初始数据
    const initialData = generateRandomData(18, false, false);
    batteryPack.updateData(initialData);
  }
});
</script>

<style>
.container {
  max-width: 1000px;
  margin: 0 auto;
}
#battery-container {
  border: 1px solid #ccc;
  margin: 20px auto;
  width: 100%;
  max-width: 1200px;
  height: 600px;
  position: relative;
}
.controls {
  margin-top: 20px;
}
button {
  padding: 8px 16px;
  margin-right: 10px;
  cursor: pointer;
}
</style>

在普通H5环境中使用

<div id="battery-container" style="width: 800px; height: 400px;"></div>

<script>
  import { createBatteryPack } from 'antbms-battery-pack';
  
  // 初始化电池包可视化
  const container = document.getElementById('battery-container');
  const batteryPack = createBatteryPack(container, {
    padding: 20,
    batteryWidth: 60,
    batteryHeight: 100,
    colors: {
      normal: '#5C8AF0',
      warning: '#f5a742',
      danger: '#f54242'
    }
  });
  
  // 更新电池数据
  const batteryData = [
    { id: 1, voltage: '3.299V', temperature: '25.0°C', status: 'normal' },
    { id: 2, voltage: '3.299V', temperature: '25.2°C', status: 'normal' },
    { id: 3, voltage: '3.300V', temperature: '25.1°C', status: 'normal', passiveBalance: true },
    // ... 更多电池数据
  ];
  
  batteryPack.updateData(batteryData);
</script>

在UniApp环境中使用

<template>
  <view class="battery-container">
    <canvas 
      canvas-id="batteryCanvas" 
      id="batteryCanvas"
      @touchstart="handleTouchStart"
      @touchmove="handleTouchMove"
      @touchend="handleTouchEnd"
    ></canvas>
  </view>
</template>

<script>
import { UniBatteryPackRefactored } from 'antbms-battery-pack';

export default {
  data() {
    return {
      batteryPack: null
    };
  },
  onReady() {
    // 创建电池包实例
    this.batteryPack = new UniBatteryPackRefactored('batteryCanvas', {
      padding: 20,
      batteryWidth: 60,
      batteryHeight: 100,
      colors: {
        normal: '#5C8AF0',
        warning: '#f5a742',
        danger: '#f54242'
      }
    });
    
    // 更新电池数据
    this.batteryPack.updateData(this.generateBatteryData());
  },
  methods: {
    // 触摸事件处理
    handleTouchStart(e) {
      if (this.batteryPack) {
        this.batteryPack.handleTouchStart(e);
      }
    },
    handleTouchMove(e) {
      if (this.batteryPack) {
        this.batteryPack.handleTouchMove(e);
      }
    },
    handleTouchEnd(e) {
      if (this.batteryPack) {
        this.batteryPack.handleTouchEnd(e);
      }
    },
    // 生成电池数据
    generateBatteryData() {
      // 返回电池数据数组
      const data = [];
      for (let i = 1; i <= 18; i++) {
        const voltage = (3.0 + Math.random() * 1.2).toFixed(3);
        const temperature = (20 + Math.random() * 20).toFixed(1);
        
        data.push({
          id: i,
          voltage: `${voltage}V`,
          temperature: `${temperature}°C`,
          status: Number(voltage) < 3.2 ? 'danger' : Number(voltage) < 3.5 ? 'warning' : 'normal'
        });
      }
      return data;
    }
  },
  onUnload() {
    // 销毁电池包实例
    if (this.batteryPack) {
      this.batteryPack.destroy();
    }
  }
};
</script>

<style>
.battery-container {
  width: 100%;
  height: 400px;
}
</style>

配置选项

interface BatteryPackOptions {
  // 布局配置
  padding?: number;         // 内边距，默认20
  batteryWidth?: number;    // 电池宽度，默认60
  batteryHeight?: number;   // 电池高度，默认100
  batteryGap?: number;      // 电池间距，默认20
  batteryHeadHeight?: number; // 电池头高度，默认10
  
  // 颜色配置
  colors?: {
    normal?: string;          // 正常状态颜色，默认'#4e8df5'
    warning?: string;         // 警告状态颜色，默认'#f5a742'
    danger?: string;          // 危险状态颜色，默认'#f54242'
    passive_balancing?: string; // 被动均衡颜色，默认'#ABF04B'
    active_balance_line?: string; // 主动均衡线颜色，默认'#5C8AF0'
  };
  
  // 动画配置
  animationDuration?: number; // 动画持续时间，默认500ms
  
  // 交互配置
  showTooltip?: boolean;     // 是否显示提示框，默认true
  
  // 调试配置
  isDebug?: boolean;         // 是否显示调试网格，默认false
}

电池数据格式

interface BatteryData {
  id: number;              // 电池ID
  voltage: string;         // 电池电压，如'3.299V'
  temperature?: string;    // 电池温度，如'25.0°C'
  status?: 'normal' | 'warning' | 'danger'; // 电池状态
  passiveBalance?: boolean; // 被动均衡状态
  activeBalance?: {        // 主动均衡数据（可选）
    type: 'battery_to_pack' | 'pack_to_battery'; // 均衡类型
    batteryIds: number[];  // 参与均衡的电池ID
    isActive: boolean;     // 是否正在进行主动均衡
  };
}

API方法

工厂函数

// 创建适合当前平台的电池包组件实例
import { createBatteryPack } from 'antbms-battery-pack';

// H5环境：container为DOM元素或元素ID
// UniApp环境：container为Canvas的ID
const batteryPack = createBatteryPack(container, options);

平台检测

import { platform, getPlatform } from 'antbms-battery-pack';

// 使用平台信息单例
console.log(platform.type);      // 'h5' 或 'uni' 或 'unknown'
console.log(platform.isH5);      // true 或 false
console.log(platform.isUniApp);  // true 或 false

// 或者重新获取平台信息
const platformInfo = getPlatform();

组件实例方法

// 更新电池数据
batteryPack.updateData(batteryData);

// 销毁组件
batteryPack.destroy();

UniApp特有方法

// 处理触摸事件（仅UniApp环境）
uniBatteryPack.handleTouchStart(e);
uniBatteryPack.handleTouchMove(e);
uniBatteryPack.handleTouchEnd(e);

开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

浏览器兼容性

支持所有现代浏览器（Chrome、Firefox、Safari、Edge等）
不支持IE11及以下版本

依赖

ZRender - 轻量级的Canvas类库
Vue 3 - 渐进式JavaScript框架（可选）

版本

当前版本：0.0.1-beta3

许可证

MIT