Bắt đầu nhanh

VSeed là một DSL (ngôn ngữ chuyên biệt theo miền) được chuẩn hóa cho lĩnh vực phân tích. Nhờ cách điều phối dữ liệu gọn gàng, việc trực quan hóa dữ liệu trở nên đơn giản.

Cài đặt

Cài đặt thư viện lõi vseed cùng các engine render nền tảng vchart và vtable.

npm

yarn

pnpm

bun

deno

npm install @visactor/vseed @visactor/vchart @visactor/vtable

Đăng ký

Đăng ký năng lực biểu đồ và theme tại điểm vào của ứng dụng (chỉ cần chạy một lần).

App.tsx

import { registerAll } from '@visactor/vseed'

// Đăng ký tất cả loại biểu đồ tích hợp sẵn và theme
registerAll()

Xây dựng

Dùng Builder để chuyển VSeed DSL thành cấu hình Spec có thể render.

logic.ts

import { VSeed, Builder } from '@visactor/vseed'

// 1. Định nghĩa ý định phân tích (DSL)
const vseed: VSeed = {
  chartType: 'line', // loại biểu đồ
  dataset: [
    // nguồn dữ liệu
    { date: '2019', profit: 10, sales: 100 },
    { date: '2020', profit: 30, sales: 200 },
    { date: '2021', profit: 30, sales: 300 },
    /* ... */
  ],
}

// 2. Sinh cấu hình render (Spec)
const spec = Builder.from(vseed).build()

Render

Truyền Spec đã sinh vào component VChart để render.

import { useRef, useEffect } from 'react'
import VChart from '@visactor/vchart'
import { registerAll, VSeed, Builder } from '@visactor/vseed'

registerAll()

const Demo = () => {
  const containerRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (!containerRef.current) return

    const vseed: VSeed = {
      chartType: 'line',
      dataset: [
        { date: '2019', profit: 10, sales: 100 },
        { date: '2020', profit: 30, sales: 200 },
        { date: '2021', profit: 30, sales: 300 },
        { date: '2022', profit: 50, sales: 400 },
        { date: '2023', profit: 40, sales: 500 },
      ],
    }

    const spec = Builder.from(vseed).build()
    const vchart = new VChart(spec, { dom: containerRef.current })

    vchart.renderSync()
    return () => vchart.release()
  }, [])

  return <div ref={containerRef} style={{ height: 300 }} />
}

export default Demo

Khái niệm cốt lõi

Triết lý thiết kế của VSeed là tách "muốn phân tích điều gì" (DSL) khỏi "vẽ biểu đồ như thế nào" (Spec).

1. VSeed DSL

Đối tượng cấu hình cốt lõi, tập trung vào dữ liệu và ngữ nghĩa nghiệp vụ. Bạn không cần quan tâm đến các chi tiết trực quan như trục hay bố cục chú giải. VSeed cung cấp sẵn các quy chuẩn trực quan theo từng loại biểu đồ.

const vseed: VSeed = {
  chartType: 'line',
  dataset: [
    { date: '2019', profit: 10, sales: 100 },
    { date: '2020', profit: 30, sales: 200 },
  ],
  dimensions: [{ id: 'date', alias: 'Ngày' }],
}

2. Builder

Engine chuyển đổi chịu trách nhiệm dịch DSL ngắn gọn thành VChart/VTable Spec chi tiết. Nó tích hợp nhiều xử lý dữ liệu và quy chuẩn trực quan.

// Mẫu Builder cho phép gọi theo chuỗi; trong tương lai sẽ hỗ trợ thêm nhiều bước xử lý trung gian
const spec = Builder.from(vseed).build()

Nâng cao: phân tích pivot

Sức mạnh của VSeed nằm ở phân tích đa chiều. Chỉ cần bổ sung định nghĩa Dimensions và Measures là có thể tạo các pivot chart hoặc biểu đồ kết hợp phức tạp.

import { useRef, useEffect } from 'react'
import VChart from '@visactor/vchart'
import { register, PivotChart } from '@visactor/vtable'
import { registerAll, VSeed, Builder, ColorIdEncoding } from '@visactor/vseed'

register.chartModule('vchart', VChart)
registerAll()

const Demo = () => {
  const containerRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (!containerRef.current) return

    const vseed: VSeed = {
      chartType: 'line',
      dataset: [
        { date: '2019', profit: 10, sales: 100 },
        { date: '2020', profit: 30, sales: 200 },
        { date: '2021', profit: 30, sales: 300 },
        { date: '2022', profit: 50, sales: 400 },
        { date: '2023', profit: 40, sales: 500 },
      ],
      // Định nghĩa chiều và chỉ số
      dimensions: [{ id: 'date', alias: 'Ngày' }],
      measures: [
        { id: 'profit', alias: 'Lợi nhuận', parentId: 'profit-group' },
        { id: 'sales', alias: 'Doanh số', parentId: 'sales-group' },
      ],
    }

    const spec = Builder.from(vseed).build()
    const tableInstance = new PivotChart(containerRef.current, spec)

    // Ví dụ: liên kết tương tác
    tableInstance.on('legend_item_click', (args) => {
      tableInstance.updateFilterRules([
        {
          filterKey: ColorIdEncoding,
          filteredValues: args.value,
        },
      ])
    })

    return () => tableInstance.release()
  }, [])

  return <div ref={containerRef} style={{ height: 300 }} />
}

export default Demo

#Bắt đầu nhanh

#Cài đặt

#Đăng ký

#Xây dựng

#Render

#Khái niệm cốt lõi

#1. VSeed DSL

#2. Builder

#Nâng cao: phân tích pivot