Heatmap 차트

January 26, 2021 · View on GitHub

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

차트 생성하기

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

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

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

// 혹은

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

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

기본 차트

데이터 타입

데이터는 series 값과 categories 값을 받는다. categories는 X축과 Y축에 들어갈 라벨 정보를 입력 받으며 series는 각 x, y 축에 맞는 데이터를 숫자 값이 들어간 배열로 입력한다.

const data = {
  categories: {
    x: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
    y: ['Seoul', 'Seattle', 'Sydney', 'Moscow', 'Jungfrau'],
  },
  series: [
    [-3.5, -1.1, 4.0, 11.3, 17.5, 21.5, 24.9, 25.2, 20.4, 13.9, 6.6, -0.6],
    [3.8, 5.6, 7.0, 9.1, 12.4, 15.3, 17.5, 17.8, 15.0, 10.6, 6.4, 3.7],
    [22.1, 22.0, 20.9, 18.3, 15.2, 12.8, 11.8, 13.0, 15.2, 17.6, 19.4, 21.2],
    [-10.3, -9.1, -4.1, 4.4, 12.2, 16.3, 18.5, 16.7, 10.9, 4.2, -2.0, -7.5],
    [-13.2, -13.7, -13.1, -10.3, -6.1, -3.2, 0.0, -0.1, -1.8, -4.5, -9.0, -10.9],
  ],
}

image

옵션

options는 객체로 작성한다.

type options = {
  chart?: {
    //...
  }
  xAxis?: {
    //...
  }
  yAxis?: {
    //...
  }
  legend?: {
    //...
  }
  exportMenu?: {
    //...
  }
  tooltip?: {
    //...
  }
  responsive?: {
    //...
  }
  theme?: {
    // 아래 테마 챕터에서 설명
  }
  series?: {
    selectable?: boolean;
    shift?: boolean;
    dataLabels?: {
      visible?: boolean;
      offsetX?: number;
      offsetY?: number;
      formatter?: (value) => string;
    }
  }
}

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

selectable

image

  • 기본값: false

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

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

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

dataLabels

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

type options = {
  ...
  series?: {
    dataLabels?: {
      visible?: boolean;
      offsetX?: number;
      offsetY?: number;
      formatter?: (value) => string;
    }
  }
};
이름타입설명
visibleboolean데이터 라벨 표시 여부
offsetXnumber데이터 라벨 위치 x 오프셋
offsetYnumber데이터 라벨 위치 y 오프셋
formatterfunction데이터 값을 매개변수로 넘겨받아 출력 형식 지정
// 기본
const options = {
  series: {
    dataLabels: { visible: true }
  }
};

image

시리즈 theme

Heatmap 차트에서 수정할 수 있는 시리즈 테마이다. 데이터 라벨 테마는 화살표가 없는 말풍선 스타일을 사용할 수 있다.

interface HeatmapChartSeriesTheme {
  startColor: string;
  endColor: string;
  borderColor?: string;
  borderWidth?: number;
  select?: {
    color?: string;
    borderColor?: string;
    borderWidth?: number;
  };
  hover?: {
    color?: string;
    borderColor?: string;
    borderWidth?: number;
  };
  dataLabels?: {
    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;
    };
  };
}
이름타입설명
startColorstring값의 색상 기준이 되는 시작값
endColorstring값의 색상 기준이 되는 끝값
borderColorstring시리즈의 테두리 색상
borderWidthnumber시리즈의 테두리 너비
selectobject옵션 series.selectable: true로 설정 되어 있을 때 시리즈가 선택 되면 적용되는 스타일
hoverobject데이터에 마우스를 올렸을 때 스타일
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

startColor와 endColor

값의 기준이 되는 색상 값이다. startColor와 endColor 색상 값을 기준으로 입력받은 data의 색상이 결정된다.

간단한 예시로 startColor를 #4A76B2,

image

endColor를 #221271로 지정하면 colorValue가 높을 수록 endColor에 가까운 색깔을 가질 것이다.

image

const options = {
  theme: {
    series: {
      startColor: '#4A76B2',
      endColor: '#221271'
    }
  }
}

image

데이터 라벨의 테마를 적용하여 말풍선으로 바꾸고 글자 색상을 변경한 옵션은 아래와 같다.

const options = {
  series: {
    dataLabels: { visible: true }
  },
  theme: {
    series: {
      dataLabels: {
        fontFamily: 'monaco',
        fontSize: 9,
        fontWeight: '600',
        useSeriesColor: true,
        textBubble: {
          visible: true,
          backgroundColor: '#333333',
          paddingX: 1,
          paddingY: 1,
          borderRadius: 5
        }
      }
    }
  }
};

image