Introduction

VChart is a chart component library in the VisActor visualization system, based on vchart-svg-plugin, which can easily convert charts into SVG files.

🔨 Usage

📦 Installation

# npm
$ npm install @visactor/vchart-svg-plugin

# yarn
$ yarn add @visactor/vchart-svg-plugin

Usage Notes

• Animation: Disable animation (animation: false) when converting to ensure accurate SVG output

📊 A Simple Chart

import VChart from "@visactor/vchart";
import { convertVChartToSvg } from "@visactor/vchart-svg-plugin";

const spec = {
  type: "pie",
  data: [
    {
      id: "id0",
      values: [
        { type: "oxygen", value: "46.60" },
        { type: "silicon", value: "27.72" },
        { type: "aluminum", value: "8.13" },
        { type: "iron", value: "5" },
        { type: "calcium", value: "3.63" },
        { type: "sodium", value: "2.83" },
        { type: "potassium", value: "2.59" },
        { type: "others", value: "3.5" },
      ],
    },
  ],
  animation: false, // Note: Do not enable animation, otherwise you need to listen for animation end event before converting to SVG
  outerRadius: 0.8,
  valueField: "value",
  categoryField: "type",
  title: {
    visible: true,
    text: "Statistics of Surface Element Content",
  },
  legends: {
    visible: true,
    orient: "left",
  },
  label: {
    visible: true,
  },
  tooltip: {
    mark: {
      content: [
        {
          key: (datum) => datum["type"],
          value: (datum) => datum["value"] + "%",
        },
      ],
    },
  },
};

const vchart = new VChart(spec, {
  dom: "chart-container",
  animation: false, // Note: Do not enable animation, otherwise you need to listen for animation end event before converting to SVG
});
vchart.renderSync();

const svgContent = convertVChartToSvg(vchart);

render on node

const VChart = require("@visactor/vchart");
const Canvas = require("canvas");
const { convertVChartToSvg } = require("@visactor/vchart-svg-plugin");

const spec = {
  type: "pie",
  data: [
    {
      id: "id0",
      values: [
        { type: "oxygen", value: "46.60" },
        { type: "silicon", value: "27.72" },
        { type: "aluminum", value: "8.13" },
        { type: "iron", value: "5" },
        { type: "calcium", value: "3.63" },
        { type: "sodium", value: "2.83" },
        { type: "potassium", value: "2.59" },
        { type: "others", value: "3.5" },
      ],
    },
  ],
  animation: false, // Note: Do not enable animation, otherwise you need to listen for animation end event before converting to SVG
  outerRadius: 0.8,
  valueField: "value",
  categoryField: "type",
  title: {
    visible: true,
    text: "Statistics of Surface Element Content",
  },
  legends: {
    visible: true,
    orient: "left",
  },
  label: {
    visible: true,
  },
  tooltip: {
    mark: {
      content: [
        {
          key: (datum) => datum["type"],
          value: (datum) => datum["value"] + "%",
        },
      ],
    },
  },
};
const vchart = new VChart(spec, {
  // Declare the rendering environment used and pass the corresponding rendering environment parameters
  mode: "node",
  modeParams: Canvas,
  animation: false,
});
vchart.renderSync();

const svgContent = convertVChartToSvg(vchart);

�️ Development

Environment Setup

# Clone the repository
git clone https://github.com/visactor/vchart-svg-plugin.git
cd vchart-svg-plugin

# Install dependencies
yarn install

# Start development server
yarn dev

# Build for production
yarn build

# Run linting
yarn lint

Project Structure

vchart-svg-plugin/
├── src/                          # Source code
│   ├── svg/                      # SVG conversion modules
│   │   ├── arc.ts               # Arc shape conversion
│   │   ├── area.ts              # Area shape conversion
│   │   ├── convert.ts           # Main conversion logic
│   │   ├── graphic.ts           # Base graphic conversion
│   │   ├── group.ts             # Group element conversion
│   │   ├── line.ts              # Line shape conversion
│   │   ├── pattern.ts           # Pattern conversion
│   │   ├── polygon.ts           # Polygon shape conversion
│   │   ├── rect.ts              # Rectangle conversion
│   │   ├── shadow.ts            # Shadow effects
│   │   ├── symbol.ts            # Symbol conversion
│   │   └── util.ts              # Utility functions
│   └── index.ts                 # Main entry point
├── demo/                         # Demo application
│   ├── src/                     # Demo source code
│   ├── index.html               # Demo HTML
│   └── vite.config.ts           # Vite configuration
├── package.json                 # Project dependencies and scripts
├── rollup.config.js            # Rollup build configuration
├── tsconfig.json               # TypeScript configuration
└── README.md                   # Project documentation

Core Modules

SVG Conversion Modules

The plugin converts VChart rendered graphics to SVG through specialized modules:

• convert.ts: Main conversion entry point and orchestration
• graphic.ts: Base graphic element conversion logic
• arc.ts: Arc and pie chart segment conversion
• line.ts: Line and path element conversion
• rect.ts: Rectangle and rounded rectangle conversion
• area.ts: Area chart and polygon conversion
• symbol.ts: Symbol and marker conversion
• pattern.ts: Pattern and gradient conversion
• shadow.ts: Shadow effect conversion
• group.ts: Group element handling
• util.ts: Utility functions for SVG generation

Development Workflow

1. Local Development

   # Start the demo server
   yarn dev
   
   # The demo will be available at http://localhost:5173

2. Code Style

   • Use TypeScript for type safety
   • Follow ESLint configuration
   • Maintain consistent code formatting

3. Building

   # Build all formats (ESM, CJS, UMD)
   yarn build
   
   # Output will be in:
   # - esm/     (ES modules)
   # - cjs/     (CommonJS)
   # - umd/     (UMD bundle)

4. Testing

   • Run the demo to test changes
   • Verify SVG output quality
   • Test with different chart types

API Reference

Main Function

convertVChartToSvg(vchart: VChart): string

Converts a rendered VChart instance to SVG string.

Parameters:

• vchart: A rendered VChart instance

Returns:

• string: SVG content as string

• Node.js: For server-side rendering, use mode: "node" and provide canvas implementation
• Performance: Large charts may take longer to convert; consider using renderAsync() for complex visualizations

Environment Support

• Browser: Full support with DOM-based VChart
• Node.js: Supported with canvas backend (e.g., canvas package)
• SSR: Compatible with server-side rendering workflows

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly with the demo
5. Ensure code passes linting
6. Submit a pull request

For detailed contribution guidelines, see CONTRIBUTING.md

�🔗 Related Links

• Home
• VCharts Graph Examples
• VChart Graph Tutorial
• VChart Graph Configuration Options
• VChart API
• VGrammar
• VRender
• FAQ
• CodeSandbox Template for submitting bugs

🤝 Contribution

If you would like to contribute, please read the Code of Conduct and Contribution Guidelines.

Small streams make a river, and rivers flow into the sea!