velo-data-react-render

v0.0.3

Published

4 months ago

A powerful data visualization renderer for React, supporting charts, 3D effects, and rich UI components

0High
0Medium
0Low

uvdream

react visualization dashboard echarts threejs data-visualization charts renderer

VeloData React Renderer

一个强大的React大屏可视化渲染器组件

支持图表、3D效果、UI组件、装饰元素等50+组件类型

文档 | 示例 | VisualizationDashboard编辑器

✨ 特性

📊 17种图表组件 - 基于ECharts的折线图、柱状图、饼图、地图等
🎨 13种UI组件 - Ant Design组件封装,适配大屏主题
🌟 10种3D组件 - Three.js 3D地球、粒子系统、动画效果
🔲 布局组件 - 灵活的多栏布局系统
📡 数据源支持 - Mock数据和API接口,支持自动刷新
📱 响应式 - 自动缩放适配不同屏幕尺寸
🎭 主题系统 - 内置多种图表主题
⚡ 高性能 - 懒加载和优化的渲染性能
📦 TypeScript - 完整的类型定义

📦 安装

npm install velo-data-react-renderer
# 或
yarn add velo-data-react-renderer
# 或
pnpm add velo-data-react-renderer

🚀 快速开始

方式1: 直接传入JSON数据 (推荐)

最简单的使用方式 - 直接导入编辑器导出的JSON文件:

import { VeloRenderer } from 'velo-data-react-renderer'
import 'velo-data-react-renderer/dist/velo-data-react-renderer.css'
import dashboardData from './dashboard.json'

function App() {
  return <VeloRenderer data={dashboardData} />
}

JSON数据格式 (从VisualizationDashboard导出):

{
  "canvasConfig": {
    "width": 1920,
    "height": 1080,
    "backgroundColor": "#0a0e27",
    "name": "我的大屏"
  },
  "components": [
    {
      "id": "1",
      "type": "text",
      "name": "标题",
      "props": { "content": "数据大屏", "fontSize": 48 },
      "style": { "x": 100, "y": 50, "width": 400, "height": 80 },
      "visible": true,
      "locked": false
    }
  ]
}

方式2: 分别传入配置 (向后兼容)

如果需要动态构建配置:

import { VeloRenderer } from 'velo-data-react-renderer'
import 'velo-data-react-renderer/dist/velo-data-react-renderer.css'

function App() {
  const config = {
    width: 1920,
    height: 1080,
    backgroundColor: '#0a0e27',
    name: '我的大屏',
  }

  const components = [
    {
      id: '1',
      type: 'text',
      name: '标题',
      props: {
        content: '数据大屏',
        fontSize: 48,
        color: '#ffffff',
      },
      style: {
        x: 100,
        y: 50,
        width: 400,
        height: 80,
      },
      visible: true,
      locked: false,
    },
    {
      id: '2',
      type: 'singleLineChart',
      name: '折线图',
      props: {
        chartTitle: '销售趋势',
        xAxisData: ['1月', '2月', '3月', '4月', '5月'],
        seriesData: [
          {
            name: '销售额',
            data: [120, 200, 150, 80, 70],
          },
        ],
      },
      style: {
        x: 100,
        y: 150,
        width: 600,
        height: 400,
      },
      visible: true,
      locked: false,
    },
  ]

  return (
    <VeloRenderer
      config={config}
      components={components}
      autoScale={true}
    />
  )
}

使用API数据源

const components = [
  {
    id: '1',
    type: 'pieChart',
    name: '销售占比',
    props: {
      chartTitle: '产品销售占比',
      dataSource: {
        type: 'api',
        apiConfig: {
          url: 'https://api.example.com/sales',
          method: 'GET',
          refreshInterval: 30, // 30秒自动刷新
          dataPath: 'data.pieData', // 数据路径
        },
      },
    },
    style: {
      x: 100,
      y: 100,
      width: 500,
      height: 400,
    },
    visible: true,
    locked: false,
  },
]

使用VisualizationDashboard编辑器

最佳实践是使用 VisualizationDashboard编辑器可视化创建大屏,然后导出JSON配置:

import { VeloRenderer } from 'velo-data-react-renderer'
import  dashboardConfig from './dashboard-config.json'

function App() {
  return (
    <VeloRenderer
      config={dashboardConfig.canvasConfig}
      components={dashboardConfig.components}
      autoScale={true}
    />
  )
}

📚 API

VeloRenderer Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | config | CanvasConfig | (必需) | 画布配置 | | components | ComponentItem[] | (必需) | 组件列表 | | autoScale | boolean | true | 是否自动缩放适应屏幕 | | onComponentClick | (id: string) => void | - | 组件点击回调 | | className | string | '' | 自定义类名 | | style | React.CSSProperties | {} | 自定义样式 |

CanvasConfig

interface CanvasConfig {
  width: number                    // 画布宽度
  height: number                   // 画布高度
  backgroundColor: string          // 背景颜色
  name: string                     // 画布名称
  backgroundType?: 'color' | 'image'
  backgroundImage?: string         // 背景图片URL
  backgroundImageMode?: 'tile' | 'stretch' | 'cover' | 'contain' | 'center'
  backgroundImageOpacity?: number  // 背景图片透明度
  chartTheme?: {                   // 图表主题
    type: 'preset' | 'custom'
    presetName?: string
    customColors?: string[]
  }
}

ComponentItem

interface ComponentItem {
  id: string                       // 组件唯一ID
  type: ComponentType              // 组件类型
  name: string                     // 组件名称
  props: ComponentProps            // 组件属性
  style: ComponentStyle            // 组件样式
  visible: boolean                 // 是否可见
  locked: boolean                  // 是否锁定
  parentId?: string                // 父组件ID(布局嵌套)
  cellIndex?: number              // 所在单元格索引
  groupId?: string                // 组合ID
}

🎨 支持的组件类型

图表组件 (17种)

singleLineChart / doubleLineChart - 折线图
singleBarChart / doubleBarChart - 柱状图
horizontalBarChart - 横向柱状图
pieChart / halfPieChart - 饼图/半环形图
gaugeChart - 仪表盘
radarChart - 雷达图
scatterChart - 散点图
funnelChart - 漏斗图
wordCloudChart - 词云图
mapChart / cityMapChart - 地图
calendarChart - 日历热力图
treeChart - 树形图
sankeyChart - 桑基图

UI组件 (13种)

text - 文本
button - 按钮
input - 输入框
select - 选择器
switch - 开关
progress - 进度条
tag - 标签
badge - 徽标
avatar - 头像
card - 卡片
table - 表格
scrollRankList - 滚动排名列表
carouselList - 轮播列表

3D组件 (10种)

threeEarth - 3D地球
threeParticles - 粒子背景
threeCube - 3D魔方
threeDNA - DNA螺旋
threeWave - 3D波浪
threeTorus - 3D环形
threeGalaxy - 星系
threeTunnel - 时空隧道
threeMatrix - 矩阵雨
threePlasma - 等离子球

装饰组件

边框组件 (Border Box)

提供三种科技感边框样式:

borderBox1 - 四角装饰边框

{
  "type": "borderBox1",
  "props": {
    "glowColor": "#00d4ff",      // 边框发光颜色
    "cornerSize": 30,            // 角落装饰大小
    "animationDuration": 3000,   // 动画时长(毫秒)
    "content": "内容文本",        // 显示的文本
    "color": "#ffffff",          // 文字颜色
    "fontSize": 18               // 文字大小
  }
}

borderBox2 - 流光边框

{
  "type": "borderBox2",
  "props": {
    "glowColor": "#00ff88",
    "cornerSize": 30,
    "animationDuration": 4000,
    "content": "流光效果边框"
  }
}

borderBox3 - 双线科技边框

{
  "type": "borderBox3",
  "props": {
    "glowColor": "#ff6b6b",
    "cornerSize": 30,
    "animationDuration": 2500,
    "content": "双线边框"
  }
}

倒计时组件 (Flip Countdown)

翻牌式倒计时组件，支持两种模式:

目标时间模式

{
  "type": "flipCountdown",
  "props": {
    "countdownMode": "target",           // 模式: target(目标时间) 或 duration(时长)
    "targetDate": "2026-12-31T23:59:59", // 目标日期时间
    "showDays": true,                    // 显示天数
    "showHours": true,                   // 显示小时
    "showMinutes": true,                 // 显示分钟
    "showSeconds": true,                 // 显示秒数
    "cardWidth": 80,                     // 卡片宽度
    "cardHeight": 100,                   // 卡片高度
    "cardColorType": "gradient",         // 卡片颜色类型: solid(纯色) 或 gradient(渐变)
    "cardGradientStart": "#667eea",      // 渐变起始色
    "cardGradientEnd": "#764ba2",        // 渐变结束色
    "textColor": "#ffffff",              // 数字颜色
    "labelColor": "#8b95c9",             // 标签颜色
    "showLabels": true,                  // 显示标签(天/时/分/秒)
    "separator": ":"                     // 分隔符
  }
}

时长模式

{
  "type": "flipCountdown",
  "props": {
    "countdownMode": "duration",
    "countdownDuration": 86400,          // 倒计时时长(秒)
    "showDays": true,
    "showHours": true,
    "showMinutes": true,
    "showSeconds": false,
    "cardColorType": "solid",
    "cardSolidColor": "#1a1a2e",         // 纯色背景
    "textColor": "#00ff88",
    "separator": "-"
  }
}

其他装饰组件

gradientText - 渐变文字
futuristicTitle - 科技标题
fullscreenButton - 全屏按钮
customImageBorder - 自定义图片边框
decoration1/2 - 装饰元素

布局组件

layoutTwoColumn - 两栏布局
layoutThreeColumn - 三栏布局
layoutHeader - 头部布局
layoutSidebar - 侧栏布局

媒体组件

image - 图片
carousel - 轮播图

📖 组件使用示例

完整示例: 倒计时和边框组合

import { VeloRenderer } from 'velo-data-react-renderer'
import 'velo-data-react-renderer/dist/velo-data-react-renderer.css'

const dashboardData = {
  canvasConfig: {
    width: 1920,
    height: 1080,
    backgroundColor: '#0a0e27',
    name: '倒计时大屏'
  },
  components: [
    // 倒计时组件
    {
      id: 'countdown-1',
      type: 'flipCountdown',
      name: '新年倒计时',
      visible: true,
      locked: false,
      style: { x: 560, y: 100, width: 800, height: 200, zIndex: 1 },
      props: {
        countdownMode: 'target',
        targetDate: '2027-01-01T00:00:00',
        showDays: true,
        showHours: true,
        showMinutes: true,
        showSeconds: true,
        cardColorType: 'gradient',
        cardGradientStart: '#667eea',
        cardGradientEnd: '#764ba2',
        separator: ':'
      }
    },
    // 边框组件
    {
      id: 'border-1',
      type: 'borderBox1',
      name: '数据容器',
      visible: true,
      locked: false,
      style: { x: 100, y: 400, width: 500, height: 300, zIndex: 1 },
      props: {
        glowColor: '#00d4ff',
        cornerSize: 30,
        content: '实时数据监控',
        fontSize: 20
      }
    }
  ]
}

function App() {
  return <VeloRenderer data={dashboardData} />
}

查看更多示例: examples/CountdownBorderExample.tsx

🔧 高级用法

自定义组件点击事件

<VeloRenderer
  config={config}
  components={components}
  onComponentClick={(id) => {
    console.log('点击了组件:', id)
    // 处理点击事件,如跳转详情页
  }}
/>

禁用自动缩放

<VeloRenderer
  config={config}
  components={components}
  autoScale={false}
/>

自定义容器样式

<VeloRenderer
  config={config}
  components={components}
  className="my-dashboard"
  style={{
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
  }}
/>