Tham chiếu kỹ thuật — Data Visualization Pro

Tổng quan kiến trúc

Plugin Pro chủ yếu hoạt động ở phía client — đăng ký thêm các loại biểu đồ ECharts vào hệ thống chart renderer. Phía server là plugin rỗng (không thêm API hay collection mới) vì toàn bộ logic truy vấn dữ liệu đã được xử lý bởi plugin data-visualization cơ bản.

Danh sách Chart Types

Plugin đăng ký các chart type sau vào hệ thống:

Chart Class	Tên	Series Type	Tùy chọn riêng
`Line`	Line	`line`	`smooth`
`Column`	Column	`bar`	`isStack`
`Bar`	Bar (ngang)	`bar` (rotated)	`isStack`
`DivergingBar`	Diverging Bar	`bar` (dual)	—
`Pie`	Pie	`pie`	—
`Area`	Area	`line` + `areaStyle`	`smooth`, `isStack`
`Scatter`	Scatter	`scatter`	—
`Funnel`	Funnel	`funnel`	—
`Radar`	Radar	`radar`	—
`Treemap`	Treemap	`treemap`	—
`WordCloud`	Word Cloud	`wordCloud`	—

EChart Base Class

Tất cả biểu đồ Pro đều kế thừa từ class EChart, cung cấp:

Phương thức chính

Phương thức	Mô tả
`init(fields, { measures, dimensions })`	Tự động suy luận xField, yField, seriesField từ dữ liệu
`getProps({ data, general, advanced, fieldProps })`	Tạo ECharts option từ cấu hình và dữ liệu
`getBasicOptions({ general })`	Trả về option cơ bản (grid, animation, size, theme)
`getLegendOptions(config)`	Tạo cấu hình legend
`getLabelOptions(config)`	Tạo cấu hình label
`getReference()`	Trả về link tham chiếu đến tài liệu ECharts

Static Methods

Phương thức	Mô tả
`EChart.registerTheme(name, theme, mode)`	Đăng ký theme mới (light hoặc dark)

Thuộc tính cấu hình

typescript

// Mỗi EChart type có các config sau:
config: [
  'xField',            // Trường trục X
  'seriesField',       // Trường phân nhóm
  'size',              // Kích thước
  'lightTheme',        // Theme sáng
  'darkTheme',         // Theme tối
  'showLegend',        // Hiển thị chú giải
  'legendOrient',      // Hướng chú giải
  'legendPosition',    // Vị trí chú giải
  'labelType',         // Kiểu nhãn
  'padding',           // Khoảng cách lề
  'splitLine',         // Đường chia lưới
  'markLine',          // Đường tham chiếu
  'xAxisTitle',        // Tiêu đề trục X
  'yAxisTitle',        // Tiêu đề trục Y
  'xAxisLabelRotate',  // Xoay nhãn trục X
]

Dataset và Transform

Plugin sử dụng ECharts dataset API với custom transform:

typescript

dataset: [
  {
    dimensions: [xField, ...yFields],
    source: data,  // dữ liệu từ query
  },
  {
    transform: [
      {
        type: 'data-visualization:transform',
        config: { fieldProps },
      },
      {
        type: 'data-visualization:toSeries',
        config: { xField, yField, seriesField },
      },
    ],
  },
]

Transform	Mô tả
`data-visualization:transform`	Chuyển đổi dữ liệu theo field props (format, label)
`data-visualization:toSeries`	Chuyển đổi dữ liệu sang dạng series (pivot bởi seriesField)

Theme System

Đăng ký theme

typescript

// Đăng ký theme light
EChart.registerTheme('myTheme', themeObject, 'light');

// Đăng ký theme dark
EChart.registerTheme('myDarkTheme', themeObject, 'dark');

Danh sách theme có sẵn

Chế độ	Theme
Light	`default`, `light`, `walden`, `vintage`, `westeros`, `essos`, `infographic`, `macarons`, `roma`, `shine`, `wonderland`
Dark	`dark`, `defaultDark`, `chalk`, `halloween`, `purple-passion`

Tạo Chart Type tùy chỉnh

Bạn có thể tạo chart type mới bằng cách instantiate EChart:

typescript

import { EChart } from '@digiforce-nc/plugin-data-visualization-pro/client';

const myChart = new EChart({
  name: 'my-custom-chart',
  title: 'Custom Chart',
  series: { type: 'bar', itemStyle: { borderRadius: [4, 4, 0, 0] } },
  config: ['smooth', 'isStack'],
});

Hoặc kế thừa class EChart để override phương thức getProps() cho logic phức tạp hơn.

Tích hợp với Plugin Cơ bản

Plugin Pro không thay thế mà bổ sung vào plugin cơ bản:

Thành phần	Cơ bản	Pro
Query API	`charts:queryData`	Dùng lại từ cơ bản
Cache	Memory cache	Dùng lại từ cơ bản
ACL	`loggedIn`	Dùng lại từ cơ bản
Renderer	G2Plot	ECharts (bổ sung)
Chart Types	Bar, Line, Pie, Area, Table	+ Scatter, Funnel, Radar, Treemap, WordCloud, DivergingBar
Themes	Mặc định	13 themes (9 light + 4 dark)

Giới hạn kỹ thuật

Giới hạn	Chi tiết
Server-side rendering	Không hỗ trợ — biểu đồ chỉ render phía client
Export	Cần `html2canvas` hoặc ECharts built-in export
Responsive	ECharts tự handle resize, nhưng cần cấu hình `size` phù hợp
Real-time data	Không hỗ trợ WebSocket — cần dùng polling hoặc cache refresh