Column 차트

September 17, 2021 · View on GitHub

차트별로 사용할 수 있는 API는 이 가이드에서 다루지 않는다. 사용 가능한 API가 궁금하다면 API 가이드를 참고하자.

차트 생성하기

Column 차트의 생성 방법은 두 가지가 있다. 생성자 함수와 정적 함수를 통해 생성할 수 있다. 결과는 모두 차트의 인스턴스가 반환된다. 매개 변수는 차트가 그려지는 영역인 HTML 요소 el, 데이터값인 data, 옵션값 options가 객체로 들어간다. el 값은 차트의 컨테이너 영역이므로 차트 외에 다른 요소들이 포함되어 있으면 차트에 영향을 줄 수 있음으로 비어있는 HTML 요소를 사용하는 것을 권장한다.

import { ColumnChart } from '@toast-ui/chart';

const chart = new ColumnChart({el, data, options});

// 혹은

import Chart from '@toast-ui/chart';

const chart = Chart.columnChart({el, data, options});

기본 차트

데이터 타입

categories 값은 X축의 틱에 나타나며 series 값은 name과 data가 모두 작성된 데이터를 입력해야 한다. name은 각각의 시리즈를 구분할 목적으로 사용하는 유일한 id로 작성한다.

const data = {
  categories: ['Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Budget',
      data: [5000, 3000, 5000, 7000, 6000, 4000, 1000]
    },
    {
      name: 'Income',
      data: [8000, 4000, 7000, 2000, 6000, 3000, 5000]
    },
    {
      name: 'Expenses',
      data: [4000, 4000, 6000, 3000, 4000, 5000, 7000]
    },
    {
      name: 'Debt',
      data: [3000, 4000, 3000, 1000, 2000, 4000, 3000]
    }
  ]
}

image

range 차트

데이터 타입

기본 차트와 다른 점은 series data의 타입이다. data는 배열로 입력되며 범위의 시작과 끝을 숫자값으로 순서대로 입력한다.

const data = {
  categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Seoul',
      data: [
        [-8.3, 0.3],
        [-5.8, 3.1],
        [-0.6, 9.1],
        [5.8, 16.9],
        [11.5, 22.6],
        [16.6, 26.6],
        [21.2, 28.8],
        [21.8, 30.0],
        [15.8, 25.6],
        [8.3, 19.6],
        [1.4, 11.1],
        [-5.2, 3.2],
      ],
    },
    {
      name: 'Busan',
      data: [
        [0, 10],
        [3.5, 13.1],
        [5.6, 13.1],
        [10.8, 16.9],
        [11.5, 18.6],
        [13.6, 20.6],
        [15.2, 20.8],
        [21.8, 26.0],
        [17.8, 23.6],
        [11.3, 16.6],
        [4.4, 11.1],
        [3.2, 11.2],
      ],
    },
  ],
}

image

그룹형 스택 차트

stack 옵션을 통해 시리즈들이 쌓인 형태인 스택 차트를 만들 수 있다. 시리즈 데이터에 stackGroup 속성을 추가하면, 같은 stackGroup끼리 쌓인다.

const data = {
  categories: [
    '0 ~ 9',
    '10 ~ 19',
    '20 ~ 29',
    '30 ~ 39',
    '40 ~ 49',
    '50 ~ 59',
    '60 ~ 69',
    '70 ~ 79',
    '80 ~ 89',
    '90 ~ 99',
    '100 ~',
  ],
  series: [
    {
      name: 'Male - Seoul',
      data: [4007, 5067, 7221, 8358, 8500, 7730, 4962, 2670, 6700, 776, 131],
      stackGroup: 'Male',
    },
    {
      name: 'Female - Seoul',
      data: [3805, 4728, 7244, 8291, 8530, 8126, 5483, 3161, 1274, 2217, 377],
      stackGroup: 'Female',
    },
    {
      name: 'Male - Incheon',
      data: [1392, 1671, 2092, 2339, 2611, 2511, 1277, 6145, 1713, 1974, 194],
      stackGroup: 'Male',
    },
    {
      name: 'Female - Incheon',
      data: [1320, 1558, 1927, 2212, 2556, 2433, 1304, 8076, 3800, 6057, 523],
      stackGroup: 'Female',
    },
  ],
};

const options = {
  series: {
    stack: true
  }
};

group-stack

visible 옵션

각각의 series는 visible 옵션을 가질 수 있다. visible 옵션은 처음 차트가 그려졌을 때 시리즈를 나타낼지에 대한 여부를 결정한다. 기본값은 true이다. 기본 차트와 range, 그룹형 스택 차트 모두 사용하는 방법은 동일하다.

const data = {
  categories: ['Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Budget',
      data: [5000, 3000, 5000, 7000, 6000, 4000, 1000],
      visible: false
    },
    {
      name: 'Income',
      data: [8000, 4000, 7000, 2000, 6000, 3000, 5000]
    },
    {
      name: 'Expenses',
      data: [4000, 4000, 6000, 3000, 4000, 5000, 7000]
    },
    {
      name: 'Debt',
      data: [3000, 4000, 3000, 1000, 2000, 4000, 3000]
    }
  ]
}

위 옵션을 적용해 차트를 생성해보면 체크박스가 해제되어 생성되는 것을 확인할 수 있습니다.

image

colorByCategories 옵션

각각의 series는 colorByCategories 옵션을 가질 수 있다. colorByCategories 옵션은 차트의 막대 색을 카테고리 별로 다르게 칠할지 결정한다. 기본값은 false이다.

const data = {
  categories: ['Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  series: [
    {
      name: 'Budget',
      data: [5000, 3000, 5000, 7000, 6000, 4000, 1000],
      colorByCategories: true
    }
  ]
}

image

옵션

options는 객체로 작성한다.

type options = {
  chart?: {
    // ...
  },
  xAxis?: {
    // ...
  },
  yAxis?: {
    // ...
  },
  legend?: {
    // ...
  },
  exportMenu?: {
    // ...
  },
  tooltip?: {
    // ...
  },
  plot?: {
    // ...
  },
  responsive?: {
    // ...
  },
  theme?: {
    // 아래 테마 챕터에서 설명
  },
  series?: {
    stack?: boolean | {
      type: 'normal' | 'percent';
      connector?: boolean;
    };
    selectable?: boolean;
    eventDetectType?: 'point' | 'grouped';
    diverging?: boolean;
    dataLabels?: {
      visible?: boolean;
      anchor?: 'center' | 'start' | 'end' | 'auto';
      offsetX?: number;
      offsetY?: number;
      formatter?: (value) => string;
      stackTotal?: {
        visible?: boolean;
        formatter?: (value) => string;
      };
    };
  }
};

이 차트에서 사용할 수 있는 공통 옵션에 대해서는 이 가이드에서 다루지 않는다. 필요하다면 해당 옵션의 가이드를 참고하자. (링크: chart 옵션, 축, 범례, 내보내기, 툴팁, 플롯, responsive 옵션 )

stack

stack 옵션을 통해 시리즈들이 쌓인 형태인 스택 차트를 만들 수 있다. 스택 차트는 'normal' 타입과 'percent' 타입이 존재한다. stack.connector 옵션을 설정하면 카테고리 별 같은 시리즈에 대해 선을 이어 표현할 수 있다.

normal 타입

series.stack을 true로 설정하는 것은 stack.type을 'normal' 타입으로 설정한 것과 같다.

const options = {
  series: {
    stack: true
  }
}

// 혹은

const options = {
  series: {
    stack: {
      type: 'normal'
    }
  }
}

image

series.stack.connector옵션을 true로 설정한 경우 연결선을 표시할 수 있다.

const options = {
  series: {
    stack: {
      type: 'normal',
      connector: true
    }
  }
}

image

percent 타입

stack.type을 'percent'로 설정하면 카테고리 별 시리즈가 차지하는 비율을 백분율로 표시한다.

const options = {
  series: {
    stack: {
      type: 'percent'
    }
  }
}

image

connector 옵션을 true로 설정한 경우 연결선을 표시할 수 있다.

const options = {
  series: {
    stack: {
      type: 'percent',
      connector: true
    }
  }
}

image

selectable

해당 시리즈를 선택할 수 있다.

  • 기본값: false
const options = {
  series: {
    selectable: true
  }
};

image

selectable 옵션과 on API의 selectSeries, unselectSeries를 함께 사용할 경우 해당 시리즈에 대한 제어를 추가로 할 수 있다.

eventDetectType

마우스를 통해 시리즈 데이터를 선택하거나 탐지하는 방법을 정의한다.

타입설명
point개별 시리즈 영역에 마우스가 다가가야 탐지. 현재 마우스가 가리키고 있는 포인트를 기준으로 단 한 개만 탐지됨
groupedX축을 기준으로 값이 같은 모든 데이터가 탐지됨
  • 기본값: point

eventDetectType.point

eventDetectType을 'grouped'로 설정할 경우 X축을 기준으로 값이 같은 데이터가 모두 탐지된다.

const options = {
  series: {
    eventDetectType: 'grouped'
  }
};

eventDetectType.grouped

diverging

diverging 옵션을 사용하면 인구 분포 차트와 같이 양쪽으로 나누어진 분기 차트를 만들 수 있다. 분기 차트는 data.series의 첫 번째와 두 번째 요소를 사용한다.

  • 기본값: false
const data = {
    categories: [
    '100 ~',
    '90 ~ 99',
    '80 ~ 89',
    '70 ~ 79',
    '60 ~ 69',
    '50 ~ 59',
    '40 ~ 49',
    '30 ~ 39',
    '20 ~ 29',
    '10 ~ 19',
    '0 ~ 9',
  ],
  series: [
    {
      name: 'Male',
      data: [383, 3869, 39590, 136673, 248265, 419886, 451052, 391113, 352632, 296612, 236243],
    },
    {
      name: 'Female',
      data: [1255, 12846, 83976, 180790, 263033, 412847, 435981, 374321, 317092, 272438, 223251],
    },
  ],
};

const options = {
  series: {
    diverging: true
  }
};

diverging

dataLabels

데이터 라벨은 차트에서 시리즈에 대한 값을 표시한다. dataLabels 옵션은 다음과 같다.

type options = {
  ...
  series?: {
    dataLabels?: {
      visible?: boolean;
      offsetX?: number;
      offsetY?: number;
      formatter?: (value) => string;
      anchor: 'start' | 'center' | 'end' | 'auto';
      stackTotal?: {
        visible?: boolean;
        formatter?: (value) => string;
      };
    };
  };
};
이름타입설명
visibleboolean데이터 라벨 표시 여부
offsetXnumber데이터 라벨 위치 x 오프셋
offsetYnumber데이터 라벨 위치 y 오프셋
formatterfunction데이터 값을 매개변수로 넘겨받아 출력 형식 지정
anchor'start' | 'center' | 'end' | 'auto'데이터 라벨 위치 설정 (기본값: 'auto')
stackTotalobject스택 컬럼 차트에서 합계 값에 대한 라벨 설정
stackTotal.visibleboolean합계 라벨 표시 여부. 스택 차트일 경우 기본값은 true가 됨
stackTotal.formatterfunction합계 데이터 값을 매개변수로 넘겨받아 출력 형식 지정
// 기본
const options = {
  series: {
    dataLabels: { visible: true }
  }
};

image

// 스택 컬럼 차트
const options = {
  series: {
    stack: true,
    dataLabels: { visible: true }
  }
};

image

시리즈 theme

Column 차트에서 수정할 수 있는 시리즈 테마이다. 데이터 라벨 스타일은 값을 나타내는 기본 라벨을 포함하여, 스택 컬럼 차트일 경우 표시되는 합계 라벨에 대한 스타일링도 할 수 있다. 화살표가 있는 말풍선 스타일을 사용할 수 있다.

interface BoxChartSeriesTheme {
  barWidth?: number | string;
  areaOpacity?: number;
  colors?: string[];
  hover?: {
    color?: string;
    borderColor?: string;
    borderWidth?: number;
    shadowColor?: string;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowBlur?: number;
    groupedRect?: {
      color?: string;
      opacity?: number;
    };
  };
  select?: {
    color?: string;
    borderColor?: string;
    borderWidth?: number;
    areaOpacity?: number;
    shadowColor?: string;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowBlur?: number;
    groupedRect?: {
      color?: string;
      opacity?: number;
    };
    restSeries?: {
      areaOpacity?: number;
    };
  };
  connector?: {
    color?: string;
    lineWidth?: number;
    dashSegments?: number[];
  };
  dataLabels?: CommonDataLabelBubbleTheme & {
     stackTotal?: CommonDataLabelBubbleTheme;
  };
}

type CommonDataLabelBubbleTheme = {
  useSeriesColor?: boolean;
  lineWidth?: number;
  textStrokeColor?: string;
  shadowColor?: string;
  shadowBlur?: number;
  fontSize?: number;
  fontFamily?: string;
  fontWeight?: string | number;
  color?: string;
  textBubble?: {
    visible?: boolean;
    paddingX?: number;
    paddingY?: number;
    backgroundColor?: string;
    borderRadius?: number;
    borderColor?: string;
    borderWidth?: number;
    shadowColor?: string;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    shadowBlur?: number;
    arrow?: {
      visible?: boolean;
      width?: number;
      height?: number;
      direction?: 'top' | 'right' | 'bottom' | 'left';
    };
  };
};
이름타입설명
barWidthnumber | string시리즈 박스 너비
areaOpacitynumber모든 시리즈가 활성 되어 있을 때의 전체 영역 투명도
colorsstring[]시리즈의 색상
hoverobject데이터에 마우스를 올렸을 때 스타일
hover.groupRectobject옵션 series.eventDetectType: 'grouped'로 설정되어 있을 때, X축 기준으로 덮어지는 박스 영역의 스타일
selectobject옵션 series.selectable: true로 설정 되어 있을 때 시리즈가 선택 되면 적용되는 스타일
select.areaOpacitynumber선택된 시리즈의 영역 투명도
select.groupRectobject옵션 series.eventDetectType: 'grouped'로 설정되어 있을 때, X축 기준으로 선택되는 박스 영역의 스타일
select.restSeriesobject선택되지 않은 시리즈의 스타일
dataLabelsobject데이터 라벨 스타일
dataLabels.useSeriesColorboolean글자 색상을 시리즈 색상으로 사용할지 여부
dataLabels.lineWidthnumber텍스트 선 두께
dataLabels.textStrokeColorstring텍스트 선 색상
dataLabels.shadowColorstring텍스트 그림자 색상
dataLabels.shadowBlurnumber텍스트 그림자 Blur
dataLabels.fontSizenumber글자 크기
dataLabels.fontFamilystring폰트명
dataLabels.fontWeightstring글자 굵기
dataLabels.colorstring글자 색상, useSeriesColor: true로 설정한경우 이 옵션은 동작되지 않음
dataLabels.textBubbleobject말풍선 디자인 설정
dataLabels.textBubble.visibleboolean말풍선 디자인 사용 여부
dataLabels.textBubble.paddingXnumber수평 여백
dataLabels.textBubble.paddingYnumber수직 여백
dataLabels.textBubble.backgroundColorstring말풍선 배경색
dataLabels.textBubble.borderRadiusnumber말풍선 테두리의 둥근 모서리 값
dataLabels.textBubble.borderColorstring말풍선 테두리 색상
dataLabels.textBubble.borderWidthnumber말풍선 테두리 두께
dataLabels.textBubble.shadowColorstring말풍선 그림자 색상
dataLabels.textBubble.shadowOffsetXnumber말풍선 그림자 Offset X
dataLabels.textBubble.shadowOffsetYnumber말풍선 그림자 Offset Y
dataLabels.textBubble.shadowBlurnumber말풍선 그림자 Blur
dataLabels.textBubble.arrowobject말풍선 화살표 설정
dataLabels.textBubble.arrow.visibleboolean화살표 표시 여부
dataLabels.textBubble.arrow.widthnumber화살표 삼각형 너비
dataLabels.textBubble.arrow.heightnumber화살표 삼각형 높이
dataLabels.textBubble.arrow.direction'top' | 'right' | 'bottom' | 'left'화살표 방향
dataLabels.stackTotalobject스택 차트에서 합계 라벨 스타일. dataLabels에 적용할 수 있는 스타일 옵션 모두 사용 가능

테마는 옵션에서 theme 옵션을 지정하고 시리즈 테마는 theme.series로 설정한다. 아래 코드는 Column 시리즈의 색상과 너비를 바꾸고, 마우스를 올렸을 때 스타일을 변경한 옵션이다.

const options = {
  theme: {
    series: {
      barWidth: 5,
      colors: ['#EDAE49', '#D1495B', '#00798C', '#30638E'],
      hover: {
        color: '#00ff00',
        borderColor: '#73C8E7',
        borderWidth: 3,
        shadowColor: 'rgba(0, 0, 0, 0.7)',
        shadowOffsetX: 4,
        shadowOffsetY: 4,
        shadowBlur: 6,
      },
    }
  }
};

옵션에 대한 결과는 다음과 같다.

image

아래 코드는 데이터 라벨의 테마를 적용하여 말풍선으로 바꾸고 글자 스타일을 변경한 옵션이다.

const options = {
  series: {
    stack: true,
    dataLabels: { visible: true }
  },
  theme: {
    series: {
      dataLabels: {
        fontFamily: 'monaco',
        lineWidth: 2,
        textStrokeColor: '#ffffff',
        shadowColor: '#ffffff',
        shadowBlur: 4,
        stackTotal: {
          fontFamily: 'monaco',
          fontWeight: 14,
          color: '#ffffff',
          textBubble: {
            visible: true,
            paddingY: 6,
            borderWidth: 3,
            borderColor: '#00bcd4',
            borderRadius: 7,
            backgroundColor: '#041367',
            shadowOffsetX: 0,
            shadowOffsetY: 0,
            shadowBlur: 0,
            shadowColor: 'rgba(0, 0, 0, 0)'
          }
        }
      }
    }
  }
};

image