VChart, as a powerful chart library, also has strong layout capabilities, with built-in compact layout mode, grid layout, and support for custom layout capabilities.

Layout Elements

In VChart, not all chart components participate in the layout, such as tooltip and crosshairs, which do not participate in the layout. Currently, the parts that participate in the layout in VChart are: title, legend, axes, region, datazoom, scrollBar.

However, the layout logic in VChart is not implemented according to module types. VChart has a comprehensive extension mechanism, so there may be a variety of extended components, and these components may also need to participate in the layout. Therefore, the concept of layout elements was used in the design of layout capabilities.

Basic Concepts

Layout elements are not equivalent to chart modules; they are independent abstract elements used by the layout system. The chart layout module only lays out the layout elements, ignoring what the actual components of the chart are.

The chart module participates in the layout by holding a layout element and communicating with the layout element.

Layout Element Attributes

Layout elements have several important attributes:

• Layout Type: Built-in placeholder layouts provide different layout logic to elements through the layout type.

export type ILayoutType =
  | 'region-relative' // 轴，datazoom这样需要与region贴合，有布局关联的元素, 独立占位，不重合
  | 'region-relative-overlap' // 与上面的布局逻辑一致，但是同位置的元素会重叠在一起
  | 'region' // 一般只给region元素使用
  | 'normal' // 普通布局元素，比如标题。
  | 'absolute' // 想要多个元素在同一行布局，比如想并排布局多个图例
  | 'normal-inline'; // 绝对定位元素，使用空间信息配置，基于画布左上角进行定位布局    

• Spatial information: Supports attributes such as x, y, lef, top, right, bottom, width, height, etc. However, in different layout logics, only some attributes will take effect. For example, in grid layout, the elements within the cell x, y will not be affected by the configured x, y.

Layout Logic

VChart has two built-in layout logics and supports custom layouts.

Placeholder Layout

This is the most commonly used layout logic. As shown in the figure below.

By placing elements into canvas placeholders one by one, a compact layout is eventually formed.

Grid Layout

Grid layout divides the canvas into a grid of n rows by m columns according to row and column information, and then places chart elements into the cells.

For example, the following example on the official website is a grid layout of 2 columns, 4 rows.

Parameter Definition of Grid Layout

// 网格布局的类型定义
export interface IGridLayoutSpec extends ILayoutSpecBase {
  /**
   * 设置布局类型为grid布局
   */
  type: 'grid';
  /**
   * grid布局的总列数
   */
  col: number;
  /**
   * grid布局的总行数
   */
  row: number;
  /**
   * 可选配置，指定某几列的宽度
   */
  colWidth?: {
    /**
     * 指定列数，序号从 0 开始
     */
    index: number;
    /**
     * 设置指定列的宽度，单位为像素
     */
    size: number | ((maxSize: number) => number);
  }[];
  /**
   * 可选配置，指定某几行的高度
   */
  rowHeight?: {
    /**
     * 指定行数，序号从 0 开始
     */
    index: number;
    /**
     * 设置指定行的高度，单位为像素
     */
    size: number | ((maxSize: number) => number);
  }[];
  /**
   *
   * 指定所有图表元素所在位置，图表元素的位置起点和占几行几列，可以占多行多列
   * 图表元素位置允许配置重叠。
   */
  elements: ElementSpec[];
}

网格单元格内模块位置设置
export type ElementSpec = (
  | {
      /**
       * 组件对应的spec key，如'legends'表示图例
       */
      modelKey: string;
      /**
       * 组件对应的序号
       */
      modelIndex: number;
    }
  | {
      /**
       * 组件对应的id
       */
      modelId: string;
    }
) & {
  /**
   * 组件在grid布局中所在的列。从左向右，从 0 开始计数
   */
  col: number;
  /**
   * 组件在grid布局中所在的列跨度，即占了几列，默认值为1
   */
  colSpan?: number;
  /**
   * 组件在grid布局中所在的行。从上向下，从 0 开始计数。
   */
  row: number;
  /**
   * 组件在grid布局中所在的行跨度，即占了几行，默认值为1
   */
  rowSpan?: number;
};    

Custom Layout

VChart also provides custom layout capabilities, allowing users to freely set spatial properties for all layout elements.

For example, this example on the official website.

Draw 12 pies at the twelve positions of the clock. No additional attribute configuration is needed for these pie charts, and the layout logic is only about 10 lines.

const vchart = new VChart(spec, {
  dom: CONTAINER_ID,
  // 通过 option 传入自定义布局
  layout: (chart, item, chartLayoutRect, chartViewBox) => {
    /**
     * chart 是图表对象
     * item 是参与布局的图表模块
     * chartLayoutRect 是图表减去padding后的可用布局空间
     * chartViewBox 是图表在画布中的位置，包含图表的padding。
     */
    const radius = Math.min(chartLayoutRect.width / 2, chartLayoutRect.height / 2);
    const center = { x: chartLayoutRect.width / 2, y: chartLayoutRect.height / 2 };
    const regionSize = radius * 0.2;
    const regionPosRadius = radius - regionSize * 0.5 * 1.415;
    // 使用布局元素的属性和提供的方法完成布局
    item.forEach((i, index) => {
      const angle = (index / 12) * Math.PI * 2;
      // 请在布局完成后务必调用
      i.setLayoutStartPosition({
        x: center.x + Math.sin(angle) * regionPosRadius - regionSize * 0.5,
        y: center.y + Math.cos(angle) * regionPosRadius - regionSize * 0.5
      });
      i.setLayoutRect({ width: regionSize, height: regionSize });
      i.updateLayoutAttribute && i.updateLayoutAttribute();
    });
  }
});    

This document was revised and organized by the following person

玄魂